@retray-dev/ui-kit 1.0.0 → 1.6.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference
+# @retray-dev/ui-kit — Component Reference (v1.6.0)
 
 This file is the AI reference for this package. It is shipped inside the npm package so consuming projects can import it into their `CLAUDE.md` with:
 
@@ -11,22 +11,37 @@ This file is the AI reference for this package. It is shipped inside the npm pac
 
 ## Setup (Required)
 
-Wrap your app root with both providers. `ThemeProvider` enables theming; `ToastProvider` enables the toast notification system.
+Wrap your app root with all required providers in this exact order:
 
 ```tsx
-import { ThemeProvider, ToastProvider } from '@retray-dev/ui-kit'
+import { SafeAreaProvider, initialWindowMetrics } from 'react-native-safe-area-context'
+import { GestureHandlerRootView } from 'react-native-gesture-handler'
+import { ThemeProvider, BottomSheetModalProvider, ToastProvider } from '@retray-dev/ui-kit'
 
-export default function RootLayout({ children }) {
+export default function App() {
   return (
-    <ThemeProvider colorScheme="system">
-      <ToastProvider>
-        {children}
-      </ToastProvider>
-    </ThemeProvider>
+    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+      <GestureHandlerRootView style={{ flex: 1 }}>
+        <ThemeProvider colorScheme="system">
+          <BottomSheetModalProvider>
+            <ToastProvider>
+              {/* your app */}
+            </ToastProvider>
+          </BottomSheetModalProvider>
+        </ThemeProvider>
+      </GestureHandlerRootView>
+    </SafeAreaProvider>
   )
 }
 ```
 
+**Provider order is mandatory:**
+- `SafeAreaProvider` must be outermost — required by `useSafeAreaInsets` in `ToastProvider`
+- `initialMetrics={initialWindowMetrics}` is required on Android to avoid a "No safe area value available" crash on first render
+- `GestureHandlerRootView` must wrap everything — required by `@gorhom/bottom-sheet`
+- `BottomSheetModalProvider` must be inside `GestureHandlerRootView`
+- `ToastProvider` must be inside `SafeAreaProvider`
+
 ### ThemeProvider Props
 
 | Prop | Type | Default | Notes |
@@ -59,7 +74,7 @@ function MyComponent() {
 
 ## Theme Tokens
 
-All 18 tokens are available via `useTheme().colors`.
+All 20 tokens are available via `useTheme().colors`.
 
 | Token | Light | Dark | Semantic Role |
 |-------|-------|------|---------------|
@@ -72,7 +87,7 @@ All 18 tokens are available via `useTheme().colors`.
 | `secondary` | `#f5f5f5` | `#2a2a2a` | Secondary surfaces |
 | `secondaryForeground` | `#1a1a1a` | `#fafafa` | Text on secondary |
 | `muted` | `#f5f5f5` | `#2a2a2a` | Muted backgrounds, skeleton fills, track fills |
-| `mutedForeground` | `#737373` | `#a3a3a3` | Placeholder text, helper text, captions |
+| `mutedForeground` | `#646464` | `#a3a3a3` | Placeholder text, helper text, captions (WCAG AA ≥4.5:1) |
 | `accent` | `#f5f5f5` | `#2a2a2a` | Hover / pressed state fills |
 | `accentForeground` | `#1a1a1a` | `#fafafa` | Text on accent |
 | `destructive` | `#ef4444` | `#dc2626` | Error / danger / delete actions |
@@ -80,6 +95,8 @@ All 18 tokens are available via `useTheme().colors`.
 | `border` | `#e5e5e5` | `#2a2a2a` | Borders and dividers |
 | `input` | `#e5e5e5` | `#2a2a2a` | Input field border color |
 | `ring` | `#a3a3a3` | `#d4d4d4` | Focus ring color |
+| `success` | `#16a34a` | `#22c55e` | Success state (Toast success variant) |
+| `successForeground` | `#ffffff` | `#ffffff` | Text on success background |
 
 ---
 
@@ -91,12 +108,12 @@ All 18 tokens are available via `useTheme().colors`.
 
 **Import:** `import { Text } from '@retray-dev/ui-kit'`
 **When to use:** All text in the app. Replaces React Native's `Text` with semantic variants.
-**Extends:** `TextProps` from React Native.
+**Extends:** `TextProps` from React Native — all native props pass through.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | variant | `'h1' \| 'h2' \| 'h3' \| 'body' \| 'caption' \| 'label'` | `'body'` | Sets font size, weight, and line height |
-| color | `string` | — | Override the color. Defaults to `foreground`, except `caption` which defaults to `mutedForeground` |
+| color | `string` | — | Override the color. Defaults to `foreground`, except `caption` which uses `mutedForeground` |
 
 **Sizes:**
 - `h1`: 32px / 700 weight
@@ -127,22 +144,27 @@ All 18 tokens are available via `useTheme().colors`.
 | label | `string` | required | Button text |
 | variant | `'primary' \| 'secondary' \| 'outline' \| 'ghost'` | `'primary'` | Visual style |
 | size | `'sm' \| 'md' \| 'lg'` | `'md'` | — |
-| loading | `boolean` | `false` | Replaces label with spinner and forces disabled |
-| fullWidth | `boolean` | `false` | Stretches to container width |
+| loading | `boolean` | `false` | Replaces label with a spinner and forces disabled state |
+| fullWidth | `boolean` | `false` | Stretches to container width (`alignSelf: 'stretch'`) |
 | disabled | `boolean` | — | Reduces opacity to 0.45 |
+| icon | `React.ReactNode` | — | Icon rendered alongside the label |
+| iconPosition | `'left' \| 'right'` | `'left'` | Side the icon appears on |
 
 **Variants:**
 - `primary`: filled with `primary` token — main actions
 - `secondary`: filled with `secondary` token — less prominent actions
-- `outline`: transparent with `border` — alternative/secondary without fill
+- `outline`: transparent with `border` — alternative without fill
 - `ghost`: fully transparent — in-context or low-emphasis actions
 
+**Animations:** Scale springs to 0.97 on `onPressIn`, back to 1.0 on `onPressOut`.
+
 **Example:**
 ```tsx
 <Button label="Save changes" onPress={handleSave} />
 <Button label="Cancel" variant="ghost" onPress={onCancel} />
 <Button label="Delete" variant="outline" size="sm" />
 <Button label="Submitting..." loading fullWidth />
+<Button label="Share" icon={<ShareIcon size={16} />} iconPosition="right" />
 ```
 
 ---
@@ -151,13 +173,15 @@ All 18 tokens are available via `useTheme().colors`.
 
 **Import:** `import { Input } from '@retray-dev/ui-kit'`
 **When to use:** Single-line text entry. Includes built-in label, error, and hint support.
-**Extends:** `TextInputProps` from React Native.
+**Extends:** `TextInputProps` from React Native — all native props pass through.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | label | `string` | — | Label above the input |
-| error | `string` | — | Shows error text below; turns border red |
-| hint | `string` | — | Helper text below (hidden when error is set) |
+| error | `string` | — | Shows error text below; turns border red (`destructive` token) |
+| hint | `string` | — | Helper text below (hidden when `error` is set) |
+
+**Border colors:** `destructive` when `error` is set, `ring` when focused, `border` otherwise.
 
 **Example:**
 ```tsx
@@ -168,18 +192,62 @@ All 18 tokens are available via `useTheme().colors`.
 
 ---
 
+### CurrencyInput
+
+**Import:** `import { CurrencyInput } from '@retray-dev/ui-kit'`
+**When to use:** Monetary or numeric inputs that need thousands formatting while typing. Wraps `Input` — shares the same visual design, label, error, and hint behavior.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `string` | — | Controlled display value (includes prefix, e.g. `'$1,234'`) |
+| onChangeText | `(formatted: string) => void` | — | Called with the formatted display string |
+| onChangeValue | `(raw: number) => void` | — | Called with the parsed number (no separators, no prefix) |
+| prefix | `string` | `'$'` | Symbol prepended to the formatted value |
+| thousandsSeparator | `'.' \| ','` | `'.'` | Character used to separate groups of three digits |
+| label | `string` | — | Label above the input |
+| error | `string` | — | Error text below; turns border red |
+| hint | `string` | — | Helper text below (hidden when `error` is set) |
+| placeholder | `string` | `'$0'` | Defaults to `prefix + '0'` |
+| editable | `boolean` | — | Pass `false` to disable editing |
+| containerStyle | `ViewStyle` | — | Style for the outer container |
+
+**Example:**
+```tsx
+const [display, setDisplay] = useState('')
+const [amount, setAmount] = useState(0)
+
+<CurrencyInput
+  label="Amount"
+  value={display}
+  onChangeText={setDisplay}
+  onChangeValue={setAmount}
+  hint={`Parsed: ${amount}`}
+/>
+
+// European format (dot as thousands separator)
+<CurrencyInput
+  prefix="€"
+  thousandsSeparator="."
+  value={display}
+  onChangeText={setDisplay}
+  onChangeValue={setAmount}
+/>
+```
+
+---
+
 ### Textarea
 
 **Import:** `import { Textarea } from '@retray-dev/ui-kit'`
-**When to use:** Multi-line text entry. Same API as Input plus `rows`.
-**Extends:** `TextInputProps` from React Native.
+**When to use:** Multi-line text entry. Same API as `Input` plus `rows`.
+**Extends:** `TextInputProps` from React Native — all native props pass through.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | label | `string` | — | Label above |
 | error | `string` | — | Error text below; red border |
 | hint | `string` | — | Helper text below |
-| rows | `number` | `4` | Sets minimum height (each row ≈ 24px) |
+| rows | `number` | `4` | Sets `minHeight` (each row ≈ 28px) |
 
 **Example:**
 ```tsx
@@ -197,6 +265,7 @@ All 18 tokens are available via `useTheme().colors`.
 |------|------|---------|-------|
 | label | `string` | required | — |
 | variant | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | — |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -216,8 +285,9 @@ All 18 tokens are available via `useTheme().colors`.
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | src | `string` | — | Image URI |
-| fallback | `string` | — | Text for fallback (first 2 chars shown, uppercased) |
-| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | sm=24, md=32, lg=48, xl=64 |
+| fallback | `string` | — | Text shown when image fails or `src` is absent — first 2 chars, uppercased |
+| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | sm=24, md=32, lg=48, xl=64 (diameter in pt) |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -234,7 +304,8 @@ All 18 tokens are available via `useTheme().colors`.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical requires a parent with defined height |
+| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical requires a parent with a defined height |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -251,11 +322,12 @@ All 18 tokens are available via `useTheme().colors`.
 ### Spinner
 
 **Import:** `import { Spinner } from '@retray-dev/ui-kit'`
-**When to use:** Loading state indicator.
+**When to use:** Loading state indicator. Wraps React Native's `ActivityIndicator`.
+**Extends:** `ActivityIndicatorProps` (except `size`).
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | sm/md map to RN `'small'`, lg maps to `'large'` |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | `sm`/`md` map to RN `'small'`, `lg` maps to `'large'` |
 | color | `string` | `primary` token | Override spinner color |
 
 **Example:**
@@ -269,13 +341,14 @@ All 18 tokens are available via `useTheme().colors`.
 ### Skeleton
 
 **Import:** `import { Skeleton } from '@retray-dev/ui-kit'`
-**When to use:** Placeholder while content is loading. Pulses with animation.
+**When to use:** Placeholder while content is loading. Pulses with a looping opacity animation.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | width | `number \| string` | `'100%'` | — |
 | height | `number` | `16` | — |
 | borderRadius | `number` | `6` | — |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -294,6 +367,9 @@ All 18 tokens are available via `useTheme().colors`.
 |------|------|---------|-------|
 | value | `number` | `0` | Current value |
 | max | `number` | `100` | Maximum value |
+| style | `ViewStyle` | — | — |
+
+**Animation:** Spring-animates the fill width on `value` changes (JS thread — `useNativeDriver: false`). Uses `onLayout` to capture track pixel width and interpolates to pixels (cannot animate `width: '%'`).
 
 **Example:**
 ```tsx
@@ -326,21 +402,26 @@ All sub-components accept a `style` prop for overrides.
 </Card>
 ```
 
-**Notes:** `CardHeader` and `CardContent` have `padding: 24`. `CardFooter` has `paddingTop: 0` so it connects naturally to `CardContent`.
+**Notes:**
+- `CardHeader` and `CardContent` have `padding: 24`
+- `CardFooter` has `paddingTop: 0` so it connects naturally to `CardContent`
+- `CardTitle`: 18px / 600 weight, `cardForeground` color
+- `CardDescription`: 14px, `mutedForeground` color
 
 ---
 
 ### Alert
 
 **Import:** `import { Alert } from '@retray-dev/ui-kit'`
-**When to use:** Inline feedback messages (info, success, warning, error). Not for toasts.
+**When to use:** Inline feedback messages (info, success, warning, error). Not for transient toasts.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | title | `string` | — | Bold heading |
 | description | `string` | — | Detail text |
-| variant | `'default' \| 'destructive'` | `'default'` | `destructive` turns border and text red |
-| icon | `ReactNode` | — | Icon placed to the left |
+| variant | `'default' \| 'destructive'` | `'default'` | `destructive` turns border and text to `destructive` token |
+| icon | `ReactNode` | — | Icon placed to the left of the text content |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -359,8 +440,9 @@ All sub-components accept a `style` prop for overrides.
 |------|------|---------|-------|
 | title | `string` | required | — |
 | description | `string` | — | — |
-| icon | `ReactNode` | — | Shown in a muted square above the text |
+| icon | `ReactNode` | — | Shown in a 48×48 muted square above the text |
 | action | `ReactNode` | — | Usually a `Button`, placed below the text |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -383,6 +465,7 @@ All sub-components accept a `style` prop for overrides.
 | onCheckedChange | `(checked: boolean) => void` | — | — |
 | label | `string` | — | Text to the right of the box |
 | disabled | `boolean` | — | — |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -395,13 +478,18 @@ const [accepted, setAccepted] = useState(false)
 ### Switch
 
 **Import:** `import { Switch } from '@retray-dev/ui-kit'`
-**When to use:** Binary on/off settings. Animated thumb.
+**When to use:** Binary on/off settings.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | checked | `boolean` | `false` | — |
 | onCheckedChange | `(checked: boolean) => void` | — | — |
-| disabled | `boolean` | — | — |
+| disabled | `boolean` | — | Reduces opacity to 0.45 |
+| style | `ViewStyle` | — | — |
+
+**Dimensions:** Track 56×32pt, Thumb 24×24pt with 4pt offset from edges.
+
+**Animation:** Thumb translates via spring (bounciness: 4); track color transitions via opacity timing (150ms).
 
 **Example:**
 ```tsx
@@ -413,16 +501,16 @@ const [accepted, setAccepted] = useState(false)
 ### Toggle
 
 **Import:** `import { Toggle } from '@retray-dev/ui-kit'`
-**When to use:** Toggleable button (e.g., bold/italic in a toolbar). Unlike Switch, it looks like a button.
+**When to use:** Toggleable button (e.g., bold/italic in a toolbar). Looks like a button, unlike `Switch`.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | pressed | `boolean` | `false` | — |
 | onPressedChange | `(pressed: boolean) => void` | — | — |
 | variant | `'default' \| 'outline'` | `'default'` | `outline` adds a border when unpressed |
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | — |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | sm=minH 40pt, md=minH 44pt, lg=minH 48pt |
 | label | `string` | — | Text label |
-| icon | `ReactNode` | — | Icon (can be combined with label) |
+| icon | `ReactNode` | — | Icon — can be combined with `label` |
 
 **Example:**
 ```tsx
@@ -437,10 +525,11 @@ const [accepted, setAccepted] = useState(false)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| options | `RadioOption[]` | required | Each option: `{ label, value, disabled? }` |
-| value | `string` | — | Selected value |
+| options | `RadioOption[]` | required | Each option: `{ label: string, value: string, disabled?: boolean }` |
+| value | `string` | — | Currently selected value |
 | onValueChange | `(value: string) => void` | — | — |
 | orientation | `'vertical' \| 'horizontal'` | `'vertical'` | — |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -464,13 +553,14 @@ const [accepted, setAccepted] = useState(false)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| options | `SelectOption[]` | required | Each option: `{ label, value, disabled? }` |
+| options | `SelectOption[]` | required | Each option: `{ label: string, value: string, disabled?: boolean }` |
 | value | `string` | — | Selected value |
 | onValueChange | `(value: string) => void` | — | — |
-| placeholder | `string` | `'Select an option'` | — |
+| placeholder | `string` | `'Select an option'` | Shown when no value is selected |
 | label | `string` | — | Label above the trigger |
-| error | `string` | — | Error text below |
+| error | `string` | — | Error text below the trigger |
 | disabled | `boolean` | — | — |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -495,10 +585,13 @@ const [accepted, setAccepted] = useState(false)
 | value | `number` | `0` | — |
 | minimumValue | `number` | `0` | — |
 | maximumValue | `number` | `1` | — |
-| step | `number` | `0` | `0` means continuous |
+| step | `number` | `0` | `0` means continuous (no snapping) |
 | onValueChange | `(value: number) => void` | — | Fires while dragging |
-| onSlidingComplete | `(value: number) => void` | — | Fires on release |
+| onSlidingComplete | `(value: number) => void` | — | Fires on finger release |
 | disabled | `boolean` | — | — |
+| style | `ViewStyle` | — | — |
+
+**Dimensions:** Container height=32pt, track height=6pt, thumb 28×28pt. Uses `PanResponder` internally.
 
 **Example:**
 ```tsx
@@ -507,8 +600,6 @@ const [accepted, setAccepted] = useState(false)
 
 ---
 
-
-
 ### Tabs
 
 **Import:** `import { Tabs, TabsContent } from '@retray-dev/ui-kit'`
@@ -516,18 +607,22 @@ const [accepted, setAccepted] = useState(false)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| tabs | `TabItem[]` | required | Each item: `{ label, value }` |
+| tabs | `TabItem[]` | required | Each item: `{ label: string, value: string }` |
 | value | `string` | — | Controlled active tab |
 | onValueChange | `(value: string) => void` | — | — |
 | children | `ReactNode` | — | `TabsContent` components |
+| style | `ViewStyle` | — | — |
 
 **`TabsContent` Props:**
 
 | Prop | Type | Notes |
 |------|------|-------|
-| value | `string` | Must match a tab value |
-| activeValue | `string` | Pass the current active tab value |
+| value | `string` | Must match a tab value in `tabs` |
+| activeValue | `string` | Pass the current active tab — content is hidden when not active |
 | children | `ReactNode` | — |
+| style | `ViewStyle` | — |
+
+**Animation:** An absolutely-positioned pill slides and resizes via spring (speed: 20, bounciness: 0) to track the active tab.
 
 **Example:**
 ```tsx
@@ -556,9 +651,12 @@ const [tab, setTab] = useState('profile')
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| items | `AccordionItem[]` | required | Each: `{ value, trigger: string, content: ReactNode }` |
-| type | `'single' \| 'multiple'` | `'single'` | `single`: only one open at a time. `multiple`: many can be open |
-| defaultValue | `string \| string[]` | — | Initially open item(s) |
+| items | `AccordionItem[]` | required | Each: `{ value: string, trigger: string, content: ReactNode }` |
+| type | `'single' \| 'multiple'` | `'single'` | `single`: only one open at a time. `multiple`: any number can be open |
+| defaultValue | `string \| string[]` | — | Initially open item(s). Use `string[]` with `type='multiple'` |
+| style | `ViewStyle` | — | — |
+
+**Animation:** Height and chevron rotation are animated on the UI thread via `react-native-reanimated` (`withTiming`, `useSharedValue`). `Easing.out(Easing.ease)` for expand, `Easing.in(Easing.ease)` for collapse (220ms, 60 fps).
 
 **Example:**
 ```tsx
@@ -573,38 +671,38 @@ const [tab, setTab] = useState('profile')
 
 ---
 
-
-
 ### Sheet
 
 **Import:** `import { Sheet, BottomSheetModalProvider } from '@retray-dev/ui-kit'`
 **When to use:** Bottom sheet with physics-based gestures, rubber-band overscroll, and snap points. Powered by `@gorhom/bottom-sheet`.
 
-**Setup:** Wrap your app root with `BottomSheetModalProvider` (alongside `ThemeProvider`):
+**Required setup** — add to your app root (see Setup section above):
 ```tsx
-import { ThemeProvider, BottomSheetModalProvider } from '@retray-dev/ui-kit'
+import { GestureHandlerRootView } from 'react-native-gesture-handler'
+import { BottomSheetModalProvider } from '@retray-dev/ui-kit'
 
-<ThemeProvider>
+<GestureHandlerRootView style={{ flex: 1 }}>
   <BottomSheetModalProvider>
     {/* rest of app */}
   </BottomSheetModalProvider>
-</ThemeProvider>
+</GestureHandlerRootView>
 ```
 
 **Peer dependencies** (install in your app):
 ```bash
-pnpm add @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler
+pnpm add @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets
 ```
-Add `react-native-reanimated/plugin` to your `babel.config.js` plugins.
+Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to your `babel.config.js` plugins.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| open | `boolean` | required | — |
+| open | `boolean` | required | `true` presents the sheet, `false` dismisses it |
 | onClose | `() => void` | required | Called on swipe-dismiss or backdrop press |
 | snapPoints | `(string \| number)[]` | `['50%']` | Snap positions, e.g. `['40%', '80%']` |
 | title | `string` | — | — |
 | description | `string` | — | — |
 | children | `ReactNode` | — | — |
+| style | `ViewStyle` | — | Applied to the inner content container |
 
 **Example:**
 ```tsx
@@ -615,14 +713,14 @@ Add `react-native-reanimated/plugin` to your `babel.config.js` plugins.
 
 ---
 
-
-
 ### Toast / useToast
 
 **Import:** `import { ToastProvider, useToast } from '@retray-dev/ui-kit'`
 **When to use:** Ephemeral feedback messages (save success, network error, copy confirmation).
 
-**Setup:** `ToastProvider` must be in the app root (see Setup section above).
+**Required setup** — `ToastProvider` must wrap your app inside `SafeAreaProvider` (see Setup section above).
+
+**Peer dependency:** `react-native-safe-area-context` — required for `useSafeAreaInsets` inside `ToastProvider`.
 
 ```tsx
 import { useToast } from '@retray-dev/ui-kit'
@@ -651,4 +749,11 @@ function MyComponent() {
 | variant | `'default' \| 'destructive' \| 'success'` | `'default'` | `default`: dark background. `destructive`: red. `success`: green |
 | duration | `number` (ms) | `3000` | Auto-dismiss after this delay |
 
-**Notes:** Max 3 toasts shown simultaneously. Toasts appear at the top of the screen. `dismiss(id)` dismisses programmatically (the `id` is returned by `toast()`... track it if needed).
+**`dismiss(id)`:** Dismiss a toast programmatically. The `id` is returned by the `toast()` call — store it if you need programmatic dismissal.
+
+**Notes:**
+- Max 3 toasts shown simultaneously (oldest is removed when a 4th arrives)
+- Toasts appear at the top of the screen, below the status bar (dynamic safe area inset)
+- Entrance: `withTiming(120ms, Easing.out(Easing.exp))` slide-down + opacity fade — fast, sharp feel
+- Exit: `withTiming(200ms)` slide-up + opacity fade
+- Swipe left or right to dismiss early (threshold: 80px or 800 pt/s velocity)

package/README.md

@@ -1,8 +1,8 @@
-# @retray-dev/ui-kit
+# 📦 @retray-dev/ui-kit
 
 A personal React Native / Expo UI component library with a built-in design system, dark mode support, haptic feedback, and smooth animations.
 
-- 23 components across 5 categories
+- 24 components across 5 categories
 - Light/dark theme with 18 color tokens and full customization
 - Apple HIG–compliant touch targets and haptic feedback
 - Animated interactions: spring press, sliding tabs, accordion easing, animated progress
@@ -55,9 +55,7 @@ export default function App() {
       <GestureHandlerRootView style={{ flex: 1 }}>
         <ThemeProvider colorScheme="system">
           <BottomSheetModalProvider>
-            <ToastProvider>
-              {/* your app */}
-            </ToastProvider>
+            <ToastProvider>{/* your app */}</ToastProvider>
           </BottomSheetModalProvider>
         </ThemeProvider>
       </GestureHandlerRootView>
@@ -66,13 +64,13 @@ export default function App() {
 }
 ```
 
-| Provider | Required by |
-|----------|-------------|
-| `SafeAreaProvider` | `ToastProvider` (uses `useSafeAreaInsets`) |
-| `GestureHandlerRootView` | `Sheet` (uses `@gorhom/bottom-sheet`) |
-| `ThemeProvider` | All components |
-| `BottomSheetModalProvider` | `Sheet` |
-| `ToastProvider` | `useToast` hook |
+| Provider                   | Required by                                |
+| -------------------------- | ------------------------------------------ |
+| `SafeAreaProvider`         | `ToastProvider` (uses `useSafeAreaInsets`) |
+| `GestureHandlerRootView`   | `Sheet` (uses `@gorhom/bottom-sheet`)      |
+| `ThemeProvider`            | All components                             |
+| `BottomSheetModalProvider` | `Sheet`                                    |
+| `ToastProvider`            | `useToast` hook                            |
 
 ## Theme
 
@@ -99,14 +97,14 @@ const { colors, colorScheme } = useTheme()
 
 ## Components
 
-| Category | Components |
-|----------|------------|
-| Display | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress` |
-| Surfaces | `Card`, `Alert`, `EmptyState` |
-| Form | `Button`, `Input`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
-| Composition | `Tabs`, `Accordion` |
-| Overlays | `Sheet` |
-| Feedback | `Toast` / `ToastProvider` / `useToast` |
+| Category    | Components                                                                                      |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`                       |
+| Surfaces    | `Card`, `Alert`, `EmptyState`                                                                   |
+| Form        | `Button`, `Input`, `CurrencyInput`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
+| Composition | `Tabs`, `Accordion`                                                                             |
+| Overlays    | `Sheet`                                                                                         |
+| Feedback    | `Toast` / `ToastProvider` / `useToast`                                                          |
 
 ### Quick examples
 
@@ -143,6 +141,7 @@ Full props reference and more examples are available in [COMPONENTS.md](./COMPON
 
 ```markdown
 ## UI Components
+
 @./node_modules/@retray-dev/ui-kit/COMPONENTS.md
 ```