@retray-dev/ui-kit 9.1.0 → 9.2.0

package/COMPONENTS.md

@@ -1,10 +1,12 @@
-# @retray-dev/ui-kit — Component Reference (v9.1.0)
+# @retray-dev/ui-kit — Component Reference (v9.2.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:
+This file is the AI reference for this package. Add all three lines below to your project's `CLAUDE.md` to give Claude full context — components, setup guide, and usage examples:
 
 ```markdown
 ## UI Components
 @./node_modules/@retray-dev/ui-kit/COMPONENTS.md
+@./node_modules/@retray-dev/ui-kit/CONSUMER.md
+@./node_modules/@retray-dev/ui-kit/EXAMPLES.md
 ```
 
 ---
@@ -67,7 +69,7 @@ export default function App() {
 Install all required peers (Expo projects: swap `pnpm add` for `npx expo install` to get SDK-pinned versions):
 
 ```bash
-pnpm add expo-font expo-haptics expo-linear-gradient react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons react-native-size-matters react-native-svg react-native-screens sonner-native pressto
+pnpm add expo-font expo-haptics expo-linear-gradient react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons react-native-size-matters react-native-svg react-native-screens sonner-native pressto react-native-ease
 ```
 
 Then add the Worklets Babel plugin to `babel.config.js` (required by `@gorhom/bottom-sheet` and the pressable animations):
@@ -96,6 +98,7 @@ module.exports = function (api) {
 | `@react-native-community/slider` | **Required** | `Slider` | |
 | `@expo/vector-icons` | **Required** | Icons everywhere | |
 | `react-native-size-matters` | **Required** | Responsive scaling | |
+| `react-native-ease` | **Required** | `Checkbox`, `Chip`, `CategoryStrip`, `Switch`, `RadioGroup`, `Toggle` | Declarative `EaseView` animation layer. Static import in source — omitting it crashes the module load. `pnpm add react-native-ease` |
 | `react-native-pulsar` | **Optional** | Rich haptics on dev builds | Loaded via dynamic `import()` + try/catch; falls back to `expo-haptics`. Skip in Expo Go. `pnpm add react-native-pulsar` |
 | `@shopify/react-native-skia` + `expo-sensors` | **Optional** | Deep-import `HolographicCard` only | `pnpm add @shopify/react-native-skia expo-sensors` |
 
@@ -896,6 +899,7 @@ import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 | type | `'text' \| 'password'` | `'text'` | Password shows eye/eye-off toggle button in suffix slot |
 | containerStyle | `ViewStyle` | — | Outer container View style |
 | inputWrapperStyle | `ViewStyle` | — | The bordered wrapper around the input row |
+| sheetMode | `boolean` | `false` | Use inside a Sheet — swaps `TextInput` for `BottomSheetTextInput` to fix keyboard handling |
 | style | `TextStyle` | — | TextInput element style |
 
 **Dimensions:** 56px height (14px vertical padding), 8px border radius.
@@ -1010,6 +1014,7 @@ import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 | placeholder | `string` | `'$0'` | Defaults to `prefix + '0'` |
 | editable | `boolean` | — | Pass `false` to disable |
 | containerStyle | `ViewStyle` | — | Outer container style |
+| sheetMode | `boolean` | `false` | Use inside a Sheet — forwards `sheetMode` to underlying `Input` |
 
 **Formatting behavior:** Strips all non-digit characters from input, then re-applies thousands separator every 3 digits from the right, then prepends `prefix`. Decimal point input is not supported — this is for whole-number monetary amounts.
 
@@ -1675,6 +1680,7 @@ const renderItem = useCallback(({ item }) => (
 | icon | `ReactNode` | — | Override default icon with custom ReactNode |
 | iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon`, but still falls back to variant default when neither is set |
 | iconColor | `string` | — | Override icon color. Defaults to variant title color |
+| onDismiss | `() => void` | — | When provided, shows an × button on the right. Call to hide the banner from state. |
 | style | `ViewStyle` | — | — |
 
 **Variants:**
@@ -2579,6 +2585,7 @@ dismiss(id)
 | confirmLabel | `string` | `'Confirm'` | Confirm button text |
 | cancelLabel | `string` | `'Cancel'` | Cancel button text |
 | confirmVariant | `'primary' \| 'destructive'` | `'primary'` | Use `'destructive'` for delete/remove actions |
+| loading | `boolean` | `false` | Show spinner in confirm button and disable it (for async `onConfirm`) |
 | onConfirm | `() => void` | required | Called when confirm is tapped |
 | onCancel | `() => void` | required | Called when cancel is tapped or backdrop pressed |
 
@@ -2654,6 +2661,7 @@ dismiss(id)
 | style | `ViewStyle` | — | Outer container style |
 | titleStyle | `TextStyle` | — | Override title text style |
 | subtitleStyle | `TextStyle` | — | Override subtitle text style |
+| subtitleNumberOfLines | `number` | `2` | Max lines for subtitle before truncation |
 | captionStyle | `TextStyle` | — | Override caption text style |
 | icon | `ReactNode` | — | **Deprecated** — use `leftRender` |
 | trailing | `string \| ReactNode` | — | **Deprecated** — use `rightRender` |
@@ -3738,6 +3746,159 @@ import { HolographicCard, FOIL_PRESETS } from '@retray-dev/ui-kit/HolographicCar
 
 ---
 
+### SheetSelect
+
+**Import:** `import { SheetSelect } from '@retray-dev/ui-kit'`
+
+**When to use:** Selecting one or multiple options from a list *inside a Sheet or BottomSheet*. Replaces `Select` (which uses `@react-native-picker/picker` — broken inside BottomSheet) with a chip-based UI that works correctly in any surface.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| options | `SheetSelectOption[]` | required | `{ label, value, iconName?, disabled? }` |
+| value | `string \| number \| (string \| number)[]` | — | Controlled selected value(s) |
+| onValueChange | `(value) => void` | — | Called with new value on selection |
+| multiSelect | `boolean` | `false` | Allow multiple simultaneous selections |
+| label | `string` | — | Label above the chips |
+| error | `string` | — | Error text below |
+| wrap | `boolean` | `false` | Wrap chips to multiple rows. Default: single horizontal scroll |
+| style | `ViewStyle` | — | — |
+| accessibilityLabel | `string` | — | — |
+
+**Examples:**
+```tsx
+// Single-select category picker (inside Sheet)
+<SheetSelect
+  label="Category"
+  options={[
+    { label: 'Food', value: 'food', iconName: 'coffee' },
+    { label: 'Transport', value: 'transport', iconName: 'truck' },
+    { label: 'Entertainment', value: 'entertainment' },
+  ]}
+  value={category}
+  onValueChange={(v) => setCategory(v as string)}
+/>
+
+// Multi-select roles (wrap layout)
+<SheetSelect
+  label="Roles"
+  options={roles.map((r) => ({ label: r.name, value: r.id }))}
+  value={selectedRoles}
+  onValueChange={(v) => setSelectedRoles(v as string[])}
+  multiSelect
+  wrap
+/>
+```
+
+---
+
+### ImageUpload
+
+**Import:** `import { ImageUpload } from '@retray-dev/ui-kit'`
+
+**When to use:** Image selection from the device library — product photos, profile avatars, tenant logos. Shows a dashed placeholder when empty, the selected image when filled, and a loading overlay while uploading.
+
+**Requires:** `expo-image-picker` installed in the consuming app (`pnpm add expo-image-picker`). It is an optional peer dep — consumers who don't use `ImageUpload` never pull it.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `string \| null` | — | Current image URI. `null`/`undefined` shows placeholder |
+| onChange | `(uri: string \| null) => void` | — | Called with selected URI after picker completes |
+| loading | `boolean` | `false` | Show spinner overlay (e.g. while uploading to server) |
+| placeholder | `string` | `'Tap to add image'` | Text shown when no image selected |
+| width | `number` | — | Width of the upload area. Defaults to full width |
+| height | `number` | `200` | Height of the upload area |
+| borderRadius | `number` | `RADIUS.lg` | — |
+| resizeMode | `'cover' \| 'contain' \| 'stretch'` | `'cover'` | Image resize mode |
+| disabled | `boolean` | `false` | Prevents pressing |
+| style | `ViewStyle` | — | — |
+| accessibilityLabel | `string` | — | — |
+
+**Examples:**
+```tsx
+const [imageUri, setImageUri] = useState<string | null>(null)
+const [uploading, setUploading] = useState(false)
+
+const handleChange = async (uri: string | null) => {
+  if (!uri) return
+  setImageUri(uri)
+  setUploading(true)
+  await uploadToServer(uri)
+  setUploading(false)
+}
+
+<ImageUpload
+  value={imageUri}
+  onChange={handleChange}
+  loading={uploading}
+  placeholder="Tap to add product image"
+  height={200}
+/>
+
+// Avatar upload (square)
+<ImageUpload
+  value={avatarUri}
+  onChange={setAvatarUri}
+  width={100}
+  height={100}
+  borderRadius={50}
+/>
+```
+
+---
+
+### useConfirmDialog
+
+**Import:** `import { useConfirmDialog } from '@retray-dev/ui-kit'`
+
+**When to use:** Manage `ConfirmDialog` state without boilerplate. Replaces the `[target, setTarget]` + `visible` + `loading` state pattern that each screen would otherwise duplicate.
+
+```ts
+function useConfirmDialog<T>(options: UseConfirmDialogOptions): UseConfirmDialogResult<T>
+
+interface UseConfirmDialogOptions {
+  onConfirm: () => void | Promise<void>
+  onCancel?: () => void
+}
+```
+
+**Returns:**
+
+| Field | Type | Notes |
+|-------|------|-------|
+| visible | `boolean` | Pass to `ConfirmDialog.visible` |
+| target | `T \| null` | The value passed to `open()` — e.g. the item being deleted |
+| loading | `boolean` | Pass to `ConfirmDialog.loading` |
+| open | `(target?: T) => void` | Call to show the dialog |
+| dialogProps | `object` | Spread directly onto `<ConfirmDialog>` (contains `visible`, `loading`, `onConfirm`, `onCancel`) |
+
+**Example:**
+```tsx
+const { open, target, dialogProps } = useConfirmDialog<Product>({
+  onConfirm: async () => {
+    await deleteProduct(target!.id)
+    toast.success('Product deleted')
+  },
+})
+
+// Somewhere in your list:
+<ListItem
+  title={product.name}
+  rightIcon="trash-2"
+  onPress={() => open(product)}
+/>
+
+// Once in your screen's JSX:
+<ConfirmDialog
+  title={`Delete "${target?.name}"?`}
+  description="This action cannot be undone."
+  confirmLabel="Delete"
+  confirmVariant="destructive"
+  {...dialogProps}
+/>
+```
+
+---
+
 ## Icon System
 
 The library ships a built-in icon resolver — pass any icon name string to components without manual imports.
@@ -3939,4 +4100,4 @@ Each example includes:
 - Common patterns (spacing, colors, navigation, toast feedback)
 - StyleSheet definitions
 
-**For human developers:** Examples are also live in the `example/` app. Clone the repo, run `pnpm install && pnpm build`, then `cd example && pnpm start` to see them in action. Access via "🖥 App Screen Compositions" accordion.
+**For human developers:** Examples are also live in the `example/` app. Clone the repo, run `pnpm install && pnpm build`, then `cd example && pnpm start` to see them in action.

package/CONSUMER.md

@@ -0,0 +1,247 @@
+# @retray-dev/ui-kit — Consumer Setup Guide (v9.2.0)
+
+> **For AI assistants (Claude Code):** Add all three lines below to your project's `CLAUDE.md` so Claude has full context about this UI kit:
+> ```markdown
+> ## UI Components
+> @./node_modules/@retray-dev/ui-kit/COMPONENTS.md
+> @./node_modules/@retray-dev/ui-kit/CONSUMER.md
+> @./node_modules/@retray-dev/ui-kit/EXAMPLES.md
+> ```
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum | Notes |
+|---|---|---|
+| Node | 18.18 | |
+| Expo SDK | 54 | SDK 53 not supported |
+| React Native | 0.79 | Tested up to 0.81.5 |
+| React | 19 | |
+| Expo Go | NOT supported | Missing native TurboModules for Sheet, ConfirmDialog, haptics |
+| Dev build | Required | Use `npx expo run:ios` / `npx expo run:android` or EAS Build |
+
+---
+
+## Install: Required Peer Dependencies
+
+**All of these are required.** Missing any one will crash the app at load time.
+
+```bash
+npx expo install \
+  expo-haptics \
+  expo-linear-gradient \
+  expo-font \
+  react-native-reanimated \
+  react-native-gesture-handler \
+  react-native-worklets \
+  react-native-safe-area-context \
+  react-native-screens \
+  react-native-svg \
+  @gorhom/bottom-sheet \
+  @react-native-picker/picker \
+  @react-native-community/slider \
+  @expo/vector-icons \
+  react-native-size-matters \
+  sonner-native \
+  react-native-ease \
+  pressto
+```
+
+> `react-native-ease` and `pressto` are hard required. Omitting either crashes every component at module load — you will see a blank screen with no error message on screen.
+
+---
+
+## Install: Optional Peer Dependencies
+
+```bash
+npx expo install expo-image-picker   # Required only for ImageUpload component
+npx expo install react-native-pulsar # Richer haptic feedback (graceful fallback to expo-haptics when absent)
+
+# HolographicCard only — deep-import, NOT in main barrel:
+npx expo install @shopify/react-native-skia expo-sensors
+```
+
+---
+
+## Bundler Configuration
+
+### `babel.config.js` — CRITICAL
+
+```js
+module.exports = function (api) {
+  api.cache(true)
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['react-native-worklets/plugin'], // ← NOT 'react-native-reanimated/plugin'
+  }
+}
+```
+
+> Using `react-native-reanimated/plugin` instead of `react-native-worklets/plugin` is the **#1 cause of broken animations and missing input borders**. The worklets plugin covers both.
+
+After changing `babel.config.js` always clear cache:
+```bash
+npx expo start --clear
+```
+
+### `metro.config.js` — Monorepo / Workspace only
+
+If your app lives inside a monorepo (pnpm/yarn workspaces), you must prevent duplicate React/React Native instances:
+
+```js
+const { getDefaultConfig } = require('expo/metro-config')
+const path = require('path')
+
+const projectRoot = __dirname
+const workspaceRoot = path.resolve(projectRoot, '../..') // adjust to your repo root
+
+const config = getDefaultConfig(projectRoot)
+
+config.watchFolders = [workspaceRoot]
+config.resolver.nodeModulesPaths = [
+  path.resolve(projectRoot, 'node_modules'),
+  path.resolve(workspaceRoot, 'node_modules'),
+]
+config.resolver.extraNodeModules = {
+  react: path.resolve(projectRoot, 'node_modules/react'),
+  'react-native': path.resolve(projectRoot, 'node_modules/react-native'),
+}
+
+module.exports = config
+```
+
+---
+
+## Provider Setup
+
+### Recommended — `RetrayProvider` (one wrapper, correct order)
+
+```tsx
+import { useFonts } from 'expo-font'
+import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+import { RetrayProvider } from '@retray-dev/ui-kit'
+
+export default function App() {
+  const [fontsLoaded] = useFonts(SohneFonts)
+  if (!fontsLoaded) return null
+  return (
+    <RetrayProvider colorScheme="system">
+      {/* your app */}
+    </RetrayProvider>
+  )
+}
+```
+
+### Manual — only if custom provider tree required
+
+```tsx
+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 App() {
+  return (
+    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+      <GestureHandlerRootView style={{ flex: 1 }}>
+        <ThemeProvider>
+          <BottomSheetModalProvider>
+            <ToastProvider>
+              {/* your app */}
+            </ToastProvider>
+          </BottomSheetModalProvider>
+        </ThemeProvider>
+      </GestureHandlerRootView>
+    </SafeAreaProvider>
+  )
+}
+```
+
+Provider order is strict: `SafeAreaProvider` outermost, `GestureHandlerRootView` second.
+
+---
+
+## Version Compatibility Table
+
+| Package | Min | Max tested | Notes |
+|---|---|---|---|
+| Expo SDK | 54 | 54 | SDK 53 not supported |
+| React Native | 0.79 | 0.81.5 | |
+| react-native-reanimated | 4.0.0 | 4.1.1 | **v3 NOT supported** — animations will not work |
+| react-native-worklets | 0.5.1 | 0.5.1 | Exact version — other 0.5.x may crash |
+| @gorhom/bottom-sheet | 5.2.0 | 5.2.8 | <5.2.0 crashes with Reanimated v4 |
+| sonner-native | 0.22.0 | 0.23.1 | <0.22.0 has incompatible toast API |
+| react-native-ease | 0.7.0 | 0.7.2 | **Required** — not optional |
+| pressto | 0.6.0 | 0.6.1 | **Required** — not optional |
+| expo-haptics | 15.0.0 | 15.0.8 | |
+| expo-linear-gradient | 15.0.0 | 15.0.8 | |
+| expo-font | 14.0.0 | 14.0.11 | |
+
+---
+
+## Troubleshooting
+
+### 1. Blank screen / "Cannot find module 'react-native-ease'" or `'pressto'`
+
+These are required peers — not optional. The barrel import crashes at module load, rendering nothing.
+
+**Fix:**
+```bash
+npx expo install react-native-ease pressto
+npx expo run:ios   # or run:android — full native rebuild required
+```
+
+### 2. Input has no visible border / all animations are frozen
+
+Wrong or missing Babel plugin. Reanimated worklets never initialize.
+
+**Fix:**
+1. Open `babel.config.js` — confirm it has `plugins: ['react-native-worklets/plugin']`
+2. If it has `react-native-reanimated/plugin` instead, replace it with `react-native-worklets/plugin`
+3. Clear cache and restart:
+   ```bash
+   npx expo start --clear
+   ```
+4. If in monorepo: verify `metro.config.js` `extraNodeModules` points `react-native` to a single copy (duplicate instances break Reanimated context)
+
+### 3. "useWorkletCallback is not a function" crash on Sheet or ConfirmDialog
+
+`@gorhom/bottom-sheet` version older than 5.2.0 installed.
+
+**Fix:**
+```bash
+npx expo install @gorhom/bottom-sheet@5.2.8
+npx expo run:ios   # or run:android
+```
+
+---
+
+## HolographicCard (Optional Deep Import)
+
+`HolographicCard` depends on `@shopify/react-native-skia` and `expo-sensors` which are heavy optional peers. It is **not included in the main barrel** to avoid pulling Skia for consumers who don't need it.
+
+```tsx
+// Deep import — do NOT import from '@retray-dev/ui-kit'
+import { HolographicCard } from '@retray-dev/ui-kit/HolographicCard'
+```
+
+Install before using:
+```bash
+npx expo install @shopify/react-native-skia expo-sensors
+```
+
+---
+
+## Fonts
+
+All components use the **Sohne** font family. Load fonts before rendering any component:
+
+```tsx
+import { useFonts } from 'expo-font'
+import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+const [fontsLoaded] = useFonts(SohneFonts)
+if (!fontsLoaded) return null
+```
+
+See `FONTS.md` for the full font inventory and weight reference.