> For AI agents: the complete documentation index is available at https://react-native-swipe-deck.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-swipe-deck.pages.dev/ko/llms-full.txt.

# API 레퍼런스

## 주요 export

```ts
export {
  SwipeDeckActionMotion,
  SwipeDeckMotion,
  createSwipeDeck,
  SwipeDeck,
  SwipeDeckUndoMotion,
} from '@react-native-motion-kit/swipe-deck';
```

[Source 보기](https://github.com/react-native-motion-kit/react-native-swipe-deck/blob/main/src/index.tsx)

## `createSwipeDeck<T>(config?)`

Typed deck family를 만듭니다.

```tsx
const ProfileDeck = createSwipeDeck<Profile>({
  motion: SwipeDeckMotion.tinder(),
});
```

반환되는 instance는 다음을 포함합니다.

- `Root`
- `Card`
- `useDeckState`
- `useDeckActions`
- `useDeckInteraction`
- `useDeckEvent`
- `useDeckEventListener`

## `SwipeDeck.Root` props

[Source 보기](https://github.com/react-native-motion-kit/react-native-swipe-deck/blob/main/src/types.ts)

| Prop                | Type                                 | 설명                                          |
| ------------------- | ------------------------------------ | ------------------------------------------- |
| `id`                | `string`                             | Factory-scoped deck namespace입니다.           |
| `data`              | `readonly T[]`                       | Deck이 렌더링할 ordered item입니다.                 |
| `getKey`            | `(item: T, index: number) => string` | 필수 stable item key입니다.                      |
| `initialIndex`      | `number`                             | 초기 active item index입니다.                    |
| `disabled`          | `boolean`                            | accepted action과 gesture를 비활성화합니다.          |
| `allowedDirections` | `AllowedDirections`                  | 허용할 dismiss direction을 제한합니다.               |
| `swipeThreshold`    | `SwipeThreshold`                     | Root-level dismiss threshold override입니다.   |
| `velocityThreshold` | `number`                             | Root-level flick threshold override입니다.     |
| `motion`            | `SwipeDeckMotionPreset`              | Gesture-driven motion preset입니다.            |
| `actionMotion`      | `SwipeDeckActionMotionRecipe`        | Programmatic swipe motion recipe입니다.        |
| `undoMotion`        | `SwipeDeckUndoMotionRecipe`          | Programmatic undo restore motion recipe입니다. |
| `undoEnabled`       | `boolean`                            | Undo history tracking을 활성화합니다.              |
| `visibleCardCount`  | `number`                             | Forward mounted card의 최대 budget입니다.         |
| `containerStyle`    | `StyleProp<ViewStyle>`               | Deck container에 적용할 style입니다.               |
| `children`          | `ReactNode`                          | Matching `SwipeDeck.Card`를 포함해야 합니다.        |

```ts
type AllowedDirections = readonly ('left' | 'right' | 'up')[];
type SwipeThreshold = number | ((layout: SwipeDeckLayout) => number);
```

Static `SwipeDeck.Root`는 `id`를 제외한 같은 props를 받습니다.

전체 id contract는 [Multi-Instance Management](https://react-native-swipe-deck.pages.dev/ko/guide/usage/multi-instance-management.md)를 참고하세요.

`id`는 item key가 아닙니다. `"nearby"`, `"recommended"` 같은 안정적인 deck namespace나, 화면이
mount되어 있는 동안 변하지 않는 navigation route key를 사용하세요. 해당 id를 retain하는 committed
Root 또는 public hook consumer가 하나 이상 mount되어 있는 동안 identity가 안정적으로 유지됩니다.
마지막 cleanup과 deferred eviction 이후 같은 id를 다시 사용하면 새 action과 interaction shared value를
받습니다. Item id, timestamp, mounted lifecycle 중에 바뀌는 값에서 id를 만들지 마세요. 같은 factory의
Root 두 개가 동시에 mount되려면 여전히 서로 다른 id가 필요합니다.

## `SwipeDeck.Card` props

| Prop          | Type                                                 | 설명                                         |
| ------------- | ---------------------------------------------------- | ------------------------------------------ |
| `interactive` | `boolean \| ((info: SwipeRenderInfo<T>) => boolean)` | Active card 안의 touchable children을 활성화합니다. |
| `style`       | `StyleProp<ViewStyle>`                               | Absolute card container에 적용됩니다.            |
| `children`    | `(info: SwipeRenderInfo<T>) => ReactNode`            | Bounded window의 item 하나를 렌더링합니다.           |

`SwipeRenderInfo<T>`는 `item`, `index`, `offset`, `role`, `isActive`를 포함합니다.

## State와 Actions

```ts
type SwipeDeckState = {
  activeIndex: number;
  count: number;
  isCompleted: boolean;
  canSwipe: boolean;
  canUndo: boolean;
};

type SwipeDeckActions = {
  swipeLeft: SwipeDeckAction;
  swipeRight: SwipeDeckAction;
  swipeUp: SwipeDeckAction;
  undo: SwipeDeckUndoAction;
};
```

Programmatic action은 action이 받아들여졌는지 알려주는 `boolean`을 반환합니다.

## Interaction

```ts
type SwipeDeckInteractionPhase = 'idle' | 'dragging' | 'dismissing' | 'undoing';
```

`SwipeDirection`은 `'left' | 'right' | 'up'`입니다. `allowedDirections`를 생략하면 left와
right만 허용되고 upward dismiss는 opt-in입니다.

`useDeckInteraction()`은 `progress`, `signedProgress`, `direction`, `intentDirection`,
`dismissDirection`, `translationX`, `translationY`, `isDragging`, `phase` Reanimated shared value를
반환합니다. `intentDirection`은 overlay용 policy-filtered live semantic source이며 `'left'`,
`'right'`, `'up'`, `null`이 될 수 있습니다. Centered upward gesture만 internal up cone에 들어가고,
일반적인 upper-left/upper-right diagonal은 horizontal intent로 남습니다. 해당 raw horizontal winner가
허용되지 않으면 `intentDirection`, `progress`, `signedProgress`는 neutral이고 card translation은 손가락을
그대로 따릅니다. `signedProgress`와 numeric `direction`은 horizontal-only라 upward intent/dismiss 중에는
`0`입니다. `dismissDirection`은 dismiss가 accepted된 뒤 `'left'`, `'right'`, `'up'`, `null`이 될 수
있습니다.

## Events

```ts
type SwipeDeckEventMap<T> = {
  swipe: SwipeEvent<T>;
  undo: UndoEvent<T>;
  indexChange: { index: number };
  endReached: true;
};
```

최신 event snapshot에는 `useDeckEvent`를, imperative subscription에는 `useDeckEventListener`를
사용하세요.

## Motion Helpers

- `SwipeDeckMotion.tinder(options?)`
- `SwipeDeckActionMotion.direct(options?)`
- `SwipeDeckActionMotion.springboard(options?)`
- `SwipeDeckUndoMotion.spring(options?)`
- `SwipeDeckUndoMotion.timing(options?)`

동작 세부 사항은 이 reference보다 guide page를 먼저 참고하는 것을 권장합니다.