> 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.

# 기본 사용법

## Factory API

Factory API가 기본 API입니다. Deck state, action, event, interaction shared value,
또는 여러 named instance가 필요하다면 factory API를 사용하세요.

```tsx
import { createSwipeDeck } from '@react-native-motion-kit/swipe-deck';

const ProfileDeck = createSwipeDeck<Profile>();

function Screen() {
  return (
    <ProfileDeck.Root data={profiles} getKey={(item) => item.id}>
      <ProfileDeck.Card>{({ item }) => <ProfileCard profile={item} />}</ProfileDeck.Card>
    </ProfileDeck.Root>
  );
}
```

Factory는 `Root`, `Card`, hook이 같은 item type을 공유하도록 해 JSX에서 generic을
반복하지 않아도 됩니다.

## Card Render Info

`Card`는 mounted item마다 render info를 받습니다.

| Field      | 의미                                                    |
| ---------- | ----------------------------------------------------- |
| `item`     | 사용자의 `data` 배열에 있는 item입니다.                           |
| `index`    | `data` 안에서의 item index입니다.                            |
| `offset`   | active item으로부터의 card offset입니다.                      |
| `role`     | active card는 `'current'`, buffered card는 `'next'`입니다. |
| `isActive` | active card에서만 `true`입니다.                             |

```tsx
<ProfileDeck.Card>
  {({ item, role, isActive }) => <ProfileCard profile={item} role={role} active={isActive} />}
</ProfileDeck.Card>
```

## Interactive Card Content

Card는 기본적으로 non-interactive입니다. 그래야 deck이 swipe gesture를 안전하게 소유할 수 있습니다.
Active card 안에 CTA button이나 link 같은 touchable children이 있다면 `interactive`를 사용하세요.

```tsx
<ProfileDeck.Card interactive>
  {({ item }) => <AdCard ad={item} onPressCta={() => openAd(item)} />}
</ProfileDeck.Card>
```

일부 item에서만 touchable children을 열어야 한다면 predicate form을 사용하세요.

```tsx
<ProfileDeck.Card interactive={({ item }) => item.type === 'ad'}>
  {({ item }) => <SwipeVoteCard item={item} />}
</ProfileDeck.Card>
```

`interactive`는 active card에만 적용됩니다. 뒤쪽 card는 계속 non-interactive입니다.
Card 내부 carousel이나 scroll view처럼 더 깊은 nested gesture 조정은 raw `pointerEvents`를
노출하기보다 별도의 gesture-coordination API로 다루는 것이 좋습니다.

## Allowed Directions

`allowedDirections`는 dismiss로 받아들일 방향을 제한합니다.

```tsx
<ProfileDeck.Root
  data={profiles}
  getKey={(item) => item.id}
  allowedDirections={['left', 'right', 'up']}
>
  <ProfileDeck.Card>{({ item }) => <ProfileCard profile={item} />}</ProfileDeck.Card>
</ProfileDeck.Root>
```

- 생략하면 left와 right를 허용합니다.
- upward dismiss는 `'up'`을 명시적으로 포함해야 합니다.
- gesture up은 기본값인 `SwipeDeckMotion.tinder({ drag: { mode: 'free' } })`에서 동작합니다.
- `drag.mode: 'horizontal'`은 gesture up만 거절하며 `actions.swipeUp()`은 막지 않습니다.
- `[]`는 drag는 허용하지만 모든 dismiss release와 programmatic swipe action을 거절합니다.

## Static API

Card rendering만 필요하고 factory hook이 필요 없다면 static API를 사용할 수 있습니다.

```tsx
import { SwipeDeck } from '@react-native-motion-kit/swipe-deck';

function InlineDeck() {
  return (
    <SwipeDeck.Root data={profiles} getKey={(item) => item.id}>
      <SwipeDeck.Card<Profile>>{({ item }) => <ProfileCard profile={item} />}</SwipeDeck.Card>
    </SwipeDeck.Root>
  );
}
```

Static `Root`는 `id`를 받지 않습니다. Static `Root`와 `Card`는 factory처럼 item type을
함께 고정하지 않으므로, typed render prop이 필요하면 `Card`에 item type을 직접 넘기세요.