diff --git a/README.ko.md b/README.ko.md index 797fc51..aaf6a03 100644 --- a/README.ko.md +++ b/README.ko.md @@ -1,23 +1,47 @@ -# @react-native-motion-kit/swipe-deck +# React Native Swipe Deck -[English](README.md) +> [English](./README.md) | 한국어
- React Native Motion Kit logo + React Native Motion Kit 로고
-Reanimated, Worklets, Gesture Handler 기반의 고성능 React Native용 Tinder 스타일 -swipe deck / swipe card 라이브러리입니다. +## 개요 -## 특징 +React Native에서 Tinder 스타일 card stack을 만들 때 gesture state, programmatic action, animation state, commit event를 매 화면마다 직접 연결하고 있나요? -- **작은 render window**: 현재 카드와 bounded forward stack만 mount합니다. -- **Item-keyed rendering**: promoted card가 React Native view identity를 유지합니다. -- **Typed compound API**: `createSwipeDeck()`로 typed deck family를 만듭니다. -- **Deck hooks**: state, action, event, animated overlay를 같은 factory에서 다룹니다. -- **Motion recipes**: gesture motion, programmatic action, undo restore를 따로 조정합니다. +`@react-native-motion-kit/swipe-deck`는 React Native용 고성능 swipe deck 라이브러리입니다. +Reanimated, Worklets, Gesture Handler를 기반으로 card stack, like/pass button, progress 기반 overlay, undo flow, 여러 독립 deck instance를 typed compound API로 다룰 수 있습니다. -## 설치 +### 주요 기능 + +- 🤌 **Gesture 중심 Deck UX** - Tinder 스타일 card stack에 맞춰 drag, flick, threshold, direction control을 조정합니다 +- 🏎️ **고성능 애니메이션** - React Native Reanimated와 Worklets 기반으로 UI thread에서 부드러운 card motion을 만듭니다 +- 🪟 **Bounded Render Window** - 전체 데이터가 아니라 active card와 작은 forward stack만 mount합니다 +- 🧬 **Item-Stable Promotion** - 안정적인 item key로 promoted card가 React Native view identity를 유지합니다 +- 🧠 **Typed Compound API** - Root, Card, hook, action, event를 하나의 typed deck family로 묶습니다 +- 🎛️ **외부 제어 API** - button이나 다른 UI에서 swipeLeft, swipeRight, undo를 programmatic하게 실행합니다 +- 🎨 **Motion Recipes** - gesture motion, programmatic action, undo restore를 각각 독립적으로 조정합니다 +- 🧩 **Multi-Instance Management** - 안정적인 factory-scoped id로 여러 deck root를 독립적으로 관리합니다 +- ↩️ **Undo Support** - action-safe undo motion과 LIFO history로 back-swipe UX를 opt-in으로 제공합니다 +- 🪄 **쉬운 API** - Root와 Card로 시작하고 control이나 event가 필요할 때만 hook을 추가합니다 + +## 빠른 시작 + +### 📚 문서 + +전체 문서는 여기에서 확인할 수 있습니다: + +### 예제 & 데모 + +- [📁 예제 프로젝트](https://github.com/react-native-motion-kit/react-native-swipe-deck/tree/main/example) - 다양한 use case를 담은 실제 구현 코드입니다 + +### 🤖 AI + +- [llms.txt](https://react-native-swipe-deck.pages.dev/ko/llms.txt): 모든 문서 페이지의 제목, 링크, 간단한 설명을 담은 structured index 파일입니다. +- [llms-full.txt](https://react-native-swipe-deck.pages.dev/ko/llms-full.txt): 모든 문서 페이지의 전체 내용을 하나로 합친 full-content 파일입니다. + +### 설치 ```sh npm install @react-native-motion-kit/swipe-deck react-native-gesture-handler react-native-reanimated react-native-worklets @@ -26,15 +50,16 @@ npm install @react-native-motion-kit/swipe-deck react-native-gesture-handler rea 사용 중인 React Native 또는 Expo 버전에 맞춰 Reanimated/Worklets 설정을 완료하세요. Babel 설정에서는 `react-native-worklets/plugin`을 마지막 Babel plugin으로 추가해야 합니다. -## 빠른 시작 +### 기본 사용법 ```tsx -import { Text, View } from 'react-native'; +import { Pressable, Text, View } from 'react-native'; import { createSwipeDeck, SwipeDeckMotion } from '@react-native-motion-kit/swipe-deck'; type Profile = { id: string; name: string; + bio: string; }; const ProfileDeck = createSwipeDeck({ @@ -45,38 +70,49 @@ function ProfileCard({ profile }: { profile: Profile }) { return ( {profile.name} + {profile.bio} ); } -export function ProfileDeckScreen({ profiles }: { profiles: Profile[] }) { +function ProfileDeckControls() { + const { activeIndex, count, canSwipe } = ProfileDeck.useDeckState(); + const { swipeLeft, swipeRight } = ProfileDeck.useDeckActions(); + const current = activeIndex >= 0 ? activeIndex + 1 : 0; + return ( - item.id} visibleCardCount={3}> - {({ item }) => } - + + {`${current} / ${count}`} + + Nope + + + Like + + ); } -``` - -Control, animated overlay, commit event가 필요하다면 같은 factory Root 주변에서 -`ProfileDeck.useDeckState()`, `ProfileDeck.useDeckActions()`, -`ProfileDeck.useDeckInteraction()`, `ProfileDeck.useDeckEvent()`, -`ProfileDeck.useDeckEventListener()`를 사용하세요. -## 문서 +export function ProfileDeckScreen({ profiles }: { profiles: Profile[] }) { + return ( + + item.id} visibleCardCount={3}> + {({ item }) => } + -공개 사이트를 준비하는 동안 전체 가이드는 이 저장소의 `docs/` 아래에서 관리합니다. + + + ); +} +``` -- [개요](docs/docs/1.x/ko/guide/getting-started/overview.mdx) -- [빠른 시작](docs/docs/1.x/ko/guide/getting-started/quick-start.mdx) -- [API 레퍼런스](docs/docs/1.x/ko/guide/usage/api-reference.mdx) -- [AI 사용 가이드](docs/docs/1.x/ko/guide/getting-started/ai.mdx) +Control, animated overlay, commit event가 필요하다면 `Root`와 같은 `ProfileDeck` factory에서 제공하는 hook을 사용하세요: +`ProfileDeck.useDeckState()`, `ProfileDeck.useDeckActions()`, `ProfileDeck.useDeckInteraction()`, `ProfileDeck.useDeckEvent()`, `ProfileDeck.useDeckEventListener()`. -AI가 읽기 좋은 문서는 docs build 시 생성됩니다. +## 기여 -- [llms.txt](docs/doc_build/ko/llms.txt) -- [llms-full.txt](docs/doc_build/ko/llms-full.txt) +프로젝트 기여 방법과 개발 환경 설정은 [Contributing Guide](CONTRIBUTING.md)를 참고하세요. ## 라이선스 -MIT +[MIT](./LICENSE) diff --git a/README.md b/README.md index a5ad9fb..1179f2d 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,46 @@ -# @react-native-motion-kit/swipe-deck +# React Native Swipe Deck -[한국어](README.ko.md) +> English | [한국어](./README.ko.md)
React Native Motion Kit logo
-High-performance Tinder-style swipe deck and swipe cards for React Native, -powered by Reanimated, Worklets, and Gesture Handler. +## Overview -## Highlights +Need Tinder-style cards without hand-wiring gesture state, programmatic actions, animation state, and committed events on every screen? -- **Small render window**: mounts only the active card and a bounded forward stack. -- **Item-keyed rendering**: promoted cards keep their React Native view identity. -- **Typed compound API**: create one typed deck family with `createSwipeDeck()`. -- **Deck hooks**: read state, run actions, subscribe to events, and drive animated overlays. -- **Motion recipes**: tune gesture motion, programmatic actions, and undo restores separately. +`@react-native-motion-kit/swipe-deck` is a high-performance swipe deck library for React Native. It is built on Reanimated, Worklets, and Gesture Handler, with a typed compound API for card stacks, like/pass buttons, progress-driven overlays, undo flows, and multiple independent deck instances. -## Installation +### Key Features + +- 🤌 **Gesture-First Deck UX** - Drag, flick, threshold, and direction controls tuned for Tinder-style card stacks +- 🏎️ **High-Performance Animations** - Smooth UI-thread card motion powered by React Native Reanimated and Worklets +- 🪟 **Bounded Render Window** - Mount only the active card and a small forward stack instead of the whole data set +- 🧬 **Item-Stable Promotion** - Stable item keys let promoted cards keep their React Native view identity +- 🧠 **Typed Compound API** - Create one typed deck family with Root, Card, hooks, actions, and events +- 🎛️ **External Control API** - Trigger swipeLeft, swipeRight, and undo from buttons or other UI components +- 🎨 **Motion Recipes** - Tune gesture motion, programmatic actions, and undo restores independently +- 🧩 **Multi-Instance Management** - Manage multiple deck roots independently with stable factory-scoped IDs +- ↩️ **Undo Support** - Opt into back-swipe UX with action-safe undo motion and LIFO history +- 🪄 **Easy-to-Use API** - Start with Root and Card, then add hooks only when controls or events need them + +## Quick Start + +### 📚 Documentation + +Full documentation is available at: + +### Examples & Demo + +- [📁 Example Project](https://github.com/react-native-motion-kit/react-native-swipe-deck/tree/main/example) - Real implementation code with various use cases + +### 🤖 AI + +- [llms.txt](https://react-native-swipe-deck.pages.dev/llms.txt): A structured index file containing the titles, links, and brief descriptions of all documentation pages. +- [llms-full.txt](https://react-native-swipe-deck.pages.dev/llms-full.txt): A full-content file that concatenates the complete content of every documentation page into a single file. + +### Installation ```sh npm install @react-native-motion-kit/swipe-deck react-native-gesture-handler react-native-reanimated react-native-worklets @@ -26,15 +49,16 @@ npm install @react-native-motion-kit/swipe-deck react-native-gesture-handler rea Then follow the Reanimated/Worklets setup for your React Native or Expo version. Make sure `react-native-worklets/plugin` is the last Babel plugin. -## Quick Start +### Basic Usage ```tsx -import { Text, View } from 'react-native'; +import { Pressable, Text, View } from 'react-native'; import { createSwipeDeck, SwipeDeckMotion } from '@react-native-motion-kit/swipe-deck'; type Profile = { id: string; name: string; + bio: string; }; const ProfileDeck = createSwipeDeck({ @@ -45,39 +69,48 @@ function ProfileCard({ profile }: { profile: Profile }) { return ( {profile.name} + {profile.bio} ); } -export function ProfileDeckScreen({ profiles }: { profiles: Profile[] }) { +function ProfileDeckControls() { + const { activeIndex, count, canSwipe } = ProfileDeck.useDeckState(); + const { swipeLeft, swipeRight } = ProfileDeck.useDeckActions(); + const current = activeIndex >= 0 ? activeIndex + 1 : 0; + return ( - item.id} visibleCardCount={3}> - {({ item }) => } - + + {`${current} / ${count}`} + + Nope + + + Like + + ); } -``` - -Use `ProfileDeck.useDeckState()`, `ProfileDeck.useDeckActions()`, -`ProfileDeck.useDeckInteraction()`, `ProfileDeck.useDeckEvent()`, and -`ProfileDeck.useDeckEventListener()` around the same factory Root when you need -controls, animated overlays, or committed model events. -## Docs +export function ProfileDeckScreen({ profiles }: { profiles: Profile[] }) { + return ( + + item.id} visibleCardCount={3}> + {({ item }) => } + -Full guides are maintained in this repository under `docs/` while the public -site is being prepared. + + + ); +} +``` -- [Overview](docs/docs/1.x/en/guide/getting-started/overview.mdx) -- [Quick Start](docs/docs/1.x/en/guide/getting-started/quick-start.mdx) -- [API Reference](docs/docs/1.x/en/guide/usage/api-reference.mdx) -- [AI Usage Guide](docs/docs/1.x/en/guide/getting-started/ai.mdx) +Use hooks from the same `ProfileDeck` factory as the `Root` when you need controls, animated overlays, or committed model events: `ProfileDeck.useDeckState()`, `ProfileDeck.useDeckActions()`, `ProfileDeck.useDeckInteraction()`, `ProfileDeck.useDeckEvent()`, and `ProfileDeck.useDeckEventListener()`. -AI-readable docs are generated during the docs build: +## Contributing -- [llms.txt](docs/doc_build/llms.txt) -- [llms-full.txt](docs/doc_build/llms-full.txt) +For details on how to contribute to the project and set up the development environment, please refer to the [Contributing Guide](CONTRIBUTING.md). ## License -MIT +[MIT](./LICENSE) diff --git a/docs/docs/1.x/en/guide/getting-started/ai.mdx b/docs/docs/1.x/en/guide/getting-started/ai.mdx index ac99258..046ba73 100644 --- a/docs/docs/1.x/en/guide/getting-started/ai.mdx +++ b/docs/docs/1.x/en/guide/getting-started/ai.mdx @@ -12,11 +12,11 @@ This site publishes Markdown files for AI tools during `rspress build`. - [`/llms-full.txt`](/llms-full.txt): full English documentation in one Markdown file. Use this when the agent has enough context budget and should understand the whole API surface. -- [`/ko/llms.txt`](/ko/llms.txt) and - [`/ko/llms-full.txt`](/ko/llms-full.txt): Korean equivalents. -Before the public docs URL is available, build locally and read the generated -files from `docs/doc_build/`. +Public URLs: + +- [`https://react-native-swipe-deck.pages.dev/llms.txt`](https://react-native-swipe-deck.pages.dev/llms.txt) +- [`https://react-native-swipe-deck.pages.dev/llms-full.txt`](https://react-native-swipe-deck.pages.dev/llms-full.txt) ## Recommended Prompt diff --git a/docs/docs/1.x/en/guide/getting-started/installation.mdx b/docs/docs/1.x/en/guide/getting-started/installation.mdx index 5bfa73e..0673508 100644 --- a/docs/docs/1.x/en/guide/getting-started/installation.mdx +++ b/docs/docs/1.x/en/guide/getting-started/installation.mdx @@ -1,16 +1,10 @@ -# Installation +import { PackageManagerTabs } from '@rspress/core/theme'; -Install the package and its React Native gesture/animation peer dependencies: +# Installation -```sh -npm install @react-native-motion-kit/swipe-deck react-native-gesture-handler react-native-reanimated react-native-worklets -``` +Install the package and its required React Native gesture/animation peer dependencies: -You can use your package manager of choice. For Yarn: - -```sh -yarn add @react-native-motion-kit/swipe-deck react-native-gesture-handler react-native-reanimated react-native-worklets -``` + ## Minimum Versions @@ -24,9 +18,13 @@ yarn add @react-native-motion-kit/swipe-deck react-native-gesture-handler react- ## React Native Setup -Follow the Reanimated and Worklets setup instructions for your React Native or -Expo version. In Babel config, make sure `react-native-worklets/plugin` is the -last Babel plugin. +Follow the official setup guides for your React Native or Expo version: + +- [React Native Reanimated getting started](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) +- [React Native Gesture Handler installation](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation) + +In Babel config, make sure `react-native-worklets/plugin` is the last Babel +plugin. ```js title="babel.config.js" module.exports = { diff --git a/docs/docs/1.x/en/guide/getting-started/quick-start.mdx b/docs/docs/1.x/en/guide/getting-started/quick-start.mdx index 857c5b3..7f0c327 100644 --- a/docs/docs/1.x/en/guide/getting-started/quick-start.mdx +++ b/docs/docs/1.x/en/guide/getting-started/quick-start.mdx @@ -3,6 +3,11 @@ Create one typed deck family for your item type. `Root`, `Card`, hooks, actions, and events from that factory share the same registry namespace. +## Examples & Demo + +[📁 Example Project](https://github.com/react-native-motion-kit/react-native-swipe-deck/tree/main/example) - +Real implementation code with various use cases. + ```tsx import { Text, View } from 'react-native'; import { createSwipeDeck, SwipeDeckMotion } from '@react-native-motion-kit/swipe-deck'; diff --git a/docs/docs/1.x/ko/guide/getting-started/ai.mdx b/docs/docs/1.x/ko/guide/getting-started/ai.mdx index c4c18b4..904154f 100644 --- a/docs/docs/1.x/ko/guide/getting-started/ai.mdx +++ b/docs/docs/1.x/ko/guide/getting-started/ai.mdx @@ -13,8 +13,12 @@ AI assistant에게 코드를 생성하게 할 때 아래 규칙을 함께 전달 파일입니다. Agent의 context budget이 충분하고 전체 API를 이해해야 할 때 사용하세요. - [`/llms.txt`](/llms.txt)와 [`/llms-full.txt`](/llms-full.txt): English equivalents. -공개 문서 URL이 생기기 전에는 로컬에서 build한 뒤 `docs/doc_build/` 아래의 파일을 -사용하세요. +공개 URL: + +- [`https://react-native-swipe-deck.pages.dev/ko/llms.txt`](https://react-native-swipe-deck.pages.dev/ko/llms.txt) +- [`https://react-native-swipe-deck.pages.dev/ko/llms-full.txt`](https://react-native-swipe-deck.pages.dev/ko/llms-full.txt) +- [`https://react-native-swipe-deck.pages.dev/llms.txt`](https://react-native-swipe-deck.pages.dev/llms.txt) +- [`https://react-native-swipe-deck.pages.dev/llms-full.txt`](https://react-native-swipe-deck.pages.dev/llms-full.txt) ## 추천 프롬프트 diff --git a/docs/docs/1.x/ko/guide/getting-started/installation.mdx b/docs/docs/1.x/ko/guide/getting-started/installation.mdx index 9822f0c..d06c6d0 100644 --- a/docs/docs/1.x/ko/guide/getting-started/installation.mdx +++ b/docs/docs/1.x/ko/guide/getting-started/installation.mdx @@ -1,16 +1,10 @@ -# 설치 +import { PackageManagerTabs } from '@rspress/core/theme'; -패키지와 React Native gesture/animation peer dependency를 설치합니다. +# 설치 -```sh -npm install @react-native-motion-kit/swipe-deck react-native-gesture-handler react-native-reanimated react-native-worklets -``` +패키지와 필수 React Native gesture/animation peer dependency를 함께 설치합니다. -Yarn을 사용한다면: - -```sh -yarn add @react-native-motion-kit/swipe-deck react-native-gesture-handler react-native-reanimated react-native-worklets -``` + ## 최소 지원 버전 @@ -24,7 +18,11 @@ yarn add @react-native-motion-kit/swipe-deck react-native-gesture-handler react- ## React Native 설정 -사용 중인 React Native 또는 Expo 버전에 맞춰 Reanimated와 Worklets 설정을 완료하세요. +사용 중인 React Native 또는 Expo 버전에 맞춰 공식 setup guide를 확인하세요. + +- [React Native Reanimated getting started](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) +- [React Native Gesture Handler installation](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation) + Babel 설정에서는 `react-native-worklets/plugin`을 마지막 Babel plugin으로 추가해야 합니다. ```js title="babel.config.js" diff --git a/docs/docs/1.x/ko/guide/getting-started/quick-start.mdx b/docs/docs/1.x/ko/guide/getting-started/quick-start.mdx index 4b70cf7..5ffc522 100644 --- a/docs/docs/1.x/ko/guide/getting-started/quick-start.mdx +++ b/docs/docs/1.x/ko/guide/getting-started/quick-start.mdx @@ -3,6 +3,11 @@ Item type에 맞는 typed deck family를 하나 만드세요. 같은 factory의 `Root`, `Card`, hook, action, event가 같은 registry namespace를 공유합니다. +## 예제 & 데모 + +[📁 예제 프로젝트](https://github.com/react-native-motion-kit/react-native-swipe-deck/tree/main/example) - +다양한 use case를 담은 실제 구현 코드입니다. + ```tsx import { Text, View } from 'react-native'; import { createSwipeDeck, SwipeDeckMotion } from '@react-native-motion-kit/swipe-deck'; diff --git a/docs/theme/index.tsx b/docs/theme/index.tsx index a2a6f08..b97968c 100644 --- a/docs/theme/index.tsx +++ b/docs/theme/index.tsx @@ -8,12 +8,6 @@ import { useEffect } from 'react'; const GUIDE_SECTION_NAMES = new Set(['getting-started', 'usage']); const INSTALL_PACKAGES = '@react-native-motion-kit/swipe-deck'; -const INSTALL_COMMANDS = { - npm: `npm install ${INSTALL_PACKAGES}`, - yarn: `yarn add ${INSTALL_PACKAGES}`, - pnpm: `pnpm add ${INSTALL_PACKAGES}`, - bun: `bun add ${INSTALL_PACKAGES}`, -}; function getGuideRedirectPath(pathname: string) { const parts = pathname.split('/').filter(Boolean); @@ -49,7 +43,7 @@ function HomeLayout() { - + } /> diff --git a/package.json b/package.json index aa428a9..3e164bf 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,7 @@ "tinder-swipe", "worklets" ], - "homepage": "https://github.com/react-native-motion-kit/react-native-swipe-deck#readme", + "homepage": "https://react-native-swipe-deck.pages.dev", "bugs": { "url": "https://github.com/react-native-motion-kit/react-native-swipe-deck/issues" },