@retray-dev/ui-kit 1.0.0 → 1.5.0

package/COMPONENTS.md

@@ -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 |
@@ -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 |
@@ -91,12 +106,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,16 +142,18 @@ 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 |
 
 **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} />
@@ -151,13 +168,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
@@ -171,15 +190,15 @@ All 18 tokens are available via `useTheme().colors`.
 ### 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 +216,7 @@ All 18 tokens are available via `useTheme().colors`.
 |------|------|---------|-------|
 | label | `string` | required | — |
 | variant | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | — |
+| style | `ViewStyle` | — | — |
 
 **Example:**
 ```tsx
@@ -216,8 +236,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 +255,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 +273,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 +292,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 +318,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 +353,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 +391,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 +416,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 +429,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 +452,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 +476,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 +504,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 +536,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 +551,6 @@ const [accepted, setAccepted] = useState(false)
 
 ---
 
-
-
 ### Tabs
 
 **Import:** `import { Tabs, TabsContent } from '@retray-dev/ui-kit'`
@@ -516,18 +558,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 +602,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 +622,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 +664,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 +700,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,4 +1,4 @@
-# @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.
 
@@ -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`, `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
 ```
 

package/dist/index.d.mts

@@ -20,6 +20,8 @@ type ThemeColors = {
     border: string;
     input: string;
     ring: string;
+    success: string;
+    successForeground: string;
 };
 type Theme = {
     light?: Partial<ThemeColors>;
@@ -68,8 +70,12 @@ interface ButtonProps extends TouchableOpacityProps {
     /** Replaces the label with a spinner and forces `disabled`. */
     loading?: boolean;
     fullWidth?: boolean;
+    /** Icon rendered alongside the label. */
+    icon?: React.ReactNode;
+    /** Side the icon appears on. Defaults to `'left'`. */
+    iconPosition?: 'left' | 'right';
 }
-declare function Button({ label, variant, size, loading, fullWidth, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
+declare function Button({ label, variant, size, loading, fullWidth, icon, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'body' | 'caption' | 'label';
 interface TextProps extends TextProps$1 {
@@ -80,10 +86,14 @@ declare function Text({ variant, color, style, children, ...props }: TextProps):
 
 interface InputProps extends TextInputProps {
     label?: string;
+    /** Red helper text below the input; also changes border to `destructive` color. Takes priority over `hint`. */
     error?: string;
+    /** Helper text shown below the input when there is no error. */
     hint?: string;
+    /** Style for the outer container `View`. Use `style` (from `TextInputProps`) to style the `TextInput` itself. */
+    containerStyle?: ViewStyle;
 }
-declare function Input({ label, error, hint, style, onFocus, onBlur, ...props }: InputProps): React.JSX.Element;
+declare function Input({ label, error, hint, containerStyle, style, onFocus, onBlur, ...props }: InputProps): React.JSX.Element;
 
 type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
 interface BadgeProps {
@@ -147,7 +157,9 @@ declare function Skeleton({ width, height, borderRadius, style }: SkeletonProps)
 
 type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
 interface AvatarProps {
+    /** Remote image URI. Falls back to `fallback` initials on error or when omitted. */
     src?: string;
+    /** Up to 2 characters shown when the image is unavailable. Auto-uppercased. Defaults to `'?'`. */
     fallback?: string;
     size?: AvatarSize;
     style?: ViewStyle;
@@ -165,7 +177,9 @@ interface AlertProps {
 declare function Alert({ title, description, variant, icon, style }: AlertProps): React.JSX.Element;
 
 interface ProgressProps {
+    /** Current progress value. Clamped to `[0, max]`. Defaults to `0`. */
     value?: number;
+    /** Maximum value. Defaults to `100`. */
     max?: number;
     style?: ViewStyle;
 }
@@ -182,11 +196,16 @@ declare function EmptyState({ icon, title, description, action, style }: EmptySt
 
 interface TextareaProps extends TextInputProps {
     label?: string;
+    /** Red helper text below the textarea; also changes border to `destructive` color. Takes priority over `hint`. */
     error?: string;
+    /** Helper text shown below the textarea when there is no error. */
     hint?: string;
+    /** Number of visible text rows. Defaults to `4`. Controls `numberOfLines` and `minHeight`. */
     rows?: number;
+    /** Style for the outer container `View`. Use `style` (from `TextInputProps`) to style the `TextInput` itself. */
+    containerStyle?: ViewStyle;
 }
-declare function Textarea({ label, error, hint, rows, style, onFocus, onBlur, ...props }: TextareaProps): React.JSX.Element;
+declare function Textarea({ label, error, hint, rows, containerStyle, style, onFocus, onBlur, ...props }: TextareaProps): React.JSX.Element;
 
 interface CheckboxProps {
     checked?: boolean;
@@ -195,7 +214,7 @@ interface CheckboxProps {
     disabled?: boolean;
     style?: ViewStyle;
 }
-declare function Checkbox({ checked, onCheckedChange, label, disabled, style }: CheckboxProps): React.JSX.Element;
+declare function Checkbox({ checked, onCheckedChange, label, disabled, style, }: CheckboxProps): React.JSX.Element;
 
 interface SwitchProps {
     checked?: boolean;
@@ -237,6 +256,10 @@ interface TabItem {
 }
 interface TabsProps {
     tabs: TabItem[];
+    /**
+     * Controlled active tab value. When omitted the component manages state internally
+     * (uncontrolled), defaulting to the first tab.
+     */
     value?: string;
     onValueChange?: (value: string) => void;
     children?: React.ReactNode;
@@ -270,11 +293,15 @@ interface AccordionProps {
 declare function Accordion({ items, type, defaultValue, style }: AccordionProps): React.JSX.Element;
 
 interface SliderProps {
+    /** Current value. Controlled when provided; falls back to internal state otherwise. */
     value?: number;
     minimumValue?: number;
     maximumValue?: number;
+    /** Snap interval. `0` (default) means continuous (no snapping). */
     step?: number;
+    /** Called on every move while dragging. */
     onValueChange?: (value: number) => void;
+    /** Called once when the user releases the thumb. */
     onSlidingComplete?: (value: number) => void;
     disabled?: boolean;
     style?: ViewStyle;
@@ -287,7 +314,12 @@ interface SheetProps {
     title?: string;
     description?: string;
     children?: React.ReactNode;
+    /**
+     * Heights the sheet can snap to. Accepts percentage strings (`'50%'`) or
+     * absolute point values (`300`). Defaults to `['50%']`.
+     */
     snapPoints?: (string | number)[];
+    /** Style for the inner `BottomSheetView` content container. */
     style?: ViewStyle;
 }
 declare function Sheet({ open, onClose, title, description, children, snapPoints, style, }: SheetProps): React.JSX.Element;
@@ -301,8 +333,10 @@ interface SelectProps {
     options: SelectOption[];
     value?: string;
     onValueChange?: (value: string) => void;
+    /** Text shown when no option is selected. Defaults to `'Select an option'`. */
     placeholder?: string;
     label?: string;
+    /** Red helper text; also changes trigger border to `destructive` color. */
     error?: string;
     disabled?: boolean;
     style?: ViewStyle;
@@ -315,6 +349,7 @@ interface ToastItem {
     title?: string;
     description?: string;
     variant?: ToastVariant;
+    /** Auto-dismiss delay in milliseconds. Defaults to `3000`. */
     duration?: number;
 }
 interface ToastContextValue {