@retray-dev/ui-kit 6.2.0 → 7.0.1

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v6.2.0)
+# @retray-dev/ui-kit — Component Reference (v7.0.1)
 
 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:
 
@@ -42,16 +42,16 @@ export default function App() {
 - `BottomSheetModalProvider` must be inside `GestureHandlerRootView`
 - `ToastProvider` wraps children and renders `Toaster` (from `sonner-native`) internally
 
-## Typography — Poppins (Required)
+## Typography — Sohne (Required)
 
-All components use **Poppins** as the font family. You **must** load it before rendering any UI kit component.
+All components use **Sohne** as the font family. You **must** load it before rendering any UI kit component.
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { PoppinsFonts } from '@retray-dev/ui-kit/fonts'
+import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 
 export default function App() {
-  const [fontsLoaded] = useFonts(PoppinsFonts)
+  const [fontsLoaded] = useFonts(SohneFonts)
   if (!fontsLoaded) return null
   return (
     // ... your providers and app
@@ -60,16 +60,16 @@ export default function App() {
 ```
 
 **How it works:**
-1. Import `PoppinsFonts` from `@retray-dev/ui-kit/fonts` (separate export path)
+1. Import `SohneFonts` from `@retray-dev/ui-kit/fonts` (separate export path)
 2. Pass it to `expo-font`'s `useFonts()` hook at your app root
 3. Metro resolves font files from `node_modules/@retray-dev/ui-kit/src/assets/fonts/` at bundle time
-4. All library components reference fonts by family name (e.g., `fontFamily: 'Poppins-SemiBold'`)
+4. All library components reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
 
 **Included weights:**
-- Regular: `Poppins-Thin`, `Poppins-ExtraLight`, `Poppins-Light`, `Poppins-Regular`, `Poppins-Medium`, `Poppins-SemiBold`, `Poppins-Bold`, `Poppins-ExtraBold`, `Poppins-Black`
-- Italic: `Poppins-Italic`, `Poppins-MediumItalic`, `Poppins-SemiBoldItalic`, `Poppins-BoldItalic`
+- Sohne: `Sohne-ExtraLight`, `Sohne-Light`, `Sohne-Regular`, `Sohne-Medium`, `Sohne-SemiBold`, `Sohne-Bold`, `Sohne-ExtraBold` + italic variants
+- SohneMono: `SohneMono-ExtraLight`, `SohneMono-Light`, `SohneMono-Regular`, `SohneMono-Medium`, `SohneMono-SemiBold`, `SohneMono-Bold`, `SohneMono-ExtraBold` + italic variants
 
-**Total: 13 font files** exported from the package. Font `.ttf` files ship as raw assets in `src/assets/fonts/` — NOT bundled into `dist/`. Metro resolves `require()` calls at build time.
+**Total: 28 font files** exported from the package. Font `.otf` files ship as raw assets in `src/assets/fonts/` — NOT bundled into `dist/`. Metro resolves `require()` calls at build time.
 
 Pair with `expo-splash-screen` in production:
 ```tsx
@@ -403,6 +403,57 @@ Access resolved values via `useTheme().colors.overlay`, `.accentResolved`, `.acc
 
 ---
 
+## Migration Guide: v6 → v7
+
+### Breaking Changes
+
+**No prop API changes** — all component imports and props are identical. This is a breaking version bump due to visual behavior changes that affect rendered output.
+
+**Typography scale corrected:**
+
+| Token | v6 | v7 | Reason |
+|-------|----|----|--------|
+| `display-lg` | 22px / 500 | 24px / 600 | Removed weight inversion vs display-md |
+| `display-md` | 21px / 700 | 20px / 600 | 4px gap preserved; weight normalised |
+| `title-md` | 16px / 600 | 17px / 600 | Now visibly distinct from title-sm |
+| `title-sm` | 16px / 500 | 15px / 500 | Was same px as title-md |
+| `uppercase-tag` | 10px / 0.8 letterSpacing | 11px / 0.6 | Below Apple HIG 11pt minimum |
+| `badge-text-md` | (missing) | 13px / 600 | New canonical token for Badge md |
+
+**Default color values changed (WCAG AA fixes):**
+
+| Token | v6 | v7 | WCAG impact |
+|-------|----|----|-------------|
+| `foregroundMuted` opacity | 0.38 (~#ababab) | 0.62 (~#767676) | 2.2:1 ❌ → 4.5:1 ✓ |
+| `foregroundSubtle` opacity | 0.55 (~#858585) | 0.70 (~#646464) | 3.5:1 ❌ → 5.9:1 ✓ |
+| `warning` (light) | `#e67e00` | `#9a5200` | 2.86:1 ❌ → 5.86:1 ✓ |
+| `warningForeground` (dark) | `#ffffff` | `#0f0f0f` | Dark text on amber, 8.6:1 ✓ |
+| `destructive` (light) | `#e53935` | `#c72828` | 4.22:1 ❌ → 5.59:1 ✓ |
+| `accent` (light) | `= primary` | `#d4561d` | Explicit brand accent |
+| `accent` (dark) | `= primary` | `#e87645` | Warm accent for dark surfaces |
+
+**Component visual behavior changes:**
+
+| Component | Change |
+|-----------|--------|
+| `AlertBanner` | Background now uses semantic tint per variant (was white card); 1px semantic border added |
+| `Button` (text variant) | Label color: `foreground` → `accentResolved` — clearer CTA signal |
+| `Card` (elevated variant) | `borderWidth: 0` — shadow is sole depth signal; border was redundant |
+| `Chip` | `paddingVertical` doubled to hit 44pt WCAG 2.5.5 tap target |
+| `Input` / `Textarea` | Border: 1px at rest → animates to 2px on focus (was always 2px) |
+| `Switch` | Off-state now shows animated 1.5px border (invisible on white surfaces before) |
+| `Tabs` | Labels always `Sohne-SemiBold`; active = color only — eliminates layout reflow on selection |
+| `Checkbox` / `RadioGroup` | Disabled `opacity: 0.45` now on full row (was box only) |
+| `Toast` | `richColors={true}` — semantic variants now visually distinct by color |
+
+**If you customised any of these values** via `ThemeProvider` overrides, your overrides continue to take precedence — default palette changes only affect apps using the out-of-the-box defaults.
+
+### New Compound Component Section
+
+The example app now has a dedicated **Compound Components** section showcasing `Card`, `ButtonGroup`, `Form`, `ListGroup`, and `MenuGroup` with all sub-components and variants.
+
+---
+
 ## Components
 
 ---
@@ -1247,6 +1298,74 @@ const [amount, setAmount] = useState(0)
 
 ---
 
+### VirtualList
+
+**Import:** `import { VirtualList } from '@retray-dev/ui-kit'`
+
+**When to use:** Large lists (100+ items) where you need efficient rendering. Thin wrapper over `FlatList` with sane defaults for stable keys and optional fixed-height fast path.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| data | `T[]` | — | Array of items to render |
+| renderItem | `ListRenderItem<T>` | — | Render function for each item |
+| itemHeight | `number` | — | Fixed row height in px. Enables `getItemLayout` for performance with large datasets |
+| keyExtractor | `(item: T, index: number) => string` | Auto | Defaults to `item.id` or index. Override for custom keys |
+| ...FlatListProps | — | — | All standard FlatList props pass through |
+
+**Performance optimization:** When `itemHeight` is provided, `VirtualList` enables `getItemLayout` so FlatList skips async measurement. For 10k+ rows, combine with `React.memo`-wrapped `renderItem` so only on-screen rows mount and re-render.
+
+**Default key extraction:** Uses `item.id` (converted to string) or falls back to index. Override with `keyExtractor` for custom logic.
+
+**Example — simple list:**
+```tsx
+<VirtualList
+  data={items}
+  renderItem={({ item }) => (
+    <ListItem
+      title={item.title}
+      subtitle={item.subtitle}
+      onPress={() => handlePress(item.id)}
+    />
+  )}
+  itemHeight={56}
+/>
+```
+
+**Example — large dataset with memoized render:**
+```tsx
+const renderItem = useCallback(({ item }) => (
+  <ListItem
+    title={item.title}
+    subtitle={item.subtitle}
+    leftIcon="circle"
+    showSeparator
+    onPress={() => navigate('detail', { id: item.id })}
+  />
+), [])
+
+<VirtualList
+  data={thousands}
+  renderItem={renderItem}
+  itemHeight={64}
+/>
+```
+
+**Example — variable height rows (omit itemHeight):**
+```tsx
+<VirtualList
+  data={posts}
+  renderItem={({ item }) => (
+    <Card style={{ margin: SPACING.sm }}>
+      <CardContent>
+        <Text>{item.content}</Text>
+      </CardContent>
+    </Card>
+  )}
+/>
+```
+
+---
+
 ### Separator
 
 **Import:** `import { Separator } from '@retray-dev/ui-kit'`
@@ -2058,6 +2177,195 @@ const [open, setOpen] = useState(false)
 - Default `android_keyboardInputMode="adjustPan"` fixes the transparent gap that occurs with `adjustResize` when keyboard dismisses
 - `enableBlurKeyboardOnGesture={true}` (default) dismisses keyboard when dragging sheet
 
+**Compound components:**
+
+Sheet also supports compound components for custom layouts: `Sheet.Header`, `Sheet.Content`, `Sheet.Footer`.
+
+**Sheet.Header Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Custom header content — replaces title/subtitle/showCloseButton |
+| style | `ViewStyle` | — |
+
+**Sheet.Content Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Body content with automatic gap spacing |
+| style | `ViewStyle` | — |
+
+**Sheet.Footer Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Footer content (e.g., action buttons) |
+| style | `ViewStyle` | — |
+
+**Compound component examples:**
+```tsx
+// Custom header with close button
+<Sheet open={open} onClose={() => setOpen(false)}>
+  <Sheet.Header>
+    <View style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' }}>
+      <Text variant="title-md">Custom Header</Text>
+      <IconButton iconName="x" onPress={() => setOpen(false)} />
+    </View>
+  </Sheet.Header>
+  <Sheet.Content>
+    <Text>Content with auto spacing</Text>
+    <Input placeholder="Name" />
+    <Input placeholder="Email" />
+  </Sheet.Content>
+  <Sheet.Footer>
+    <Button label="Cancel" variant="outline" onPress={() => setOpen(false)} />
+    <Button label="Save" onPress={handleSave} />
+  </Sheet.Footer>
+</Sheet>
+
+// Mix compound components with props
+<Sheet open={open} onClose={() => setOpen(false)} title="Edit Profile">
+  <Sheet.Content>
+    <Input label="Name" value={name} onChangeText={setName} />
+    <Input label="Email" value={email} onChangeText={setEmail} />
+  </Sheet.Content>
+  <Sheet.Footer>
+    <Button label="Save" fullWidth onPress={handleSave} />
+  </Sheet.Footer>
+</Sheet>
+```
+
+When using compound components:
+- `Sheet.Header` replaces `title`, `subtitle`, and `showCloseButton` props
+- `Sheet.Content` automatically applies `gap: vs(16)` between children
+- `Sheet.Footer` renders sticky footer with automatic border, padding, and horizontal button layout
+
+---
+
+### Form
+
+**Import:** `import { Form } from '@retray-dev/ui-kit'`
+
+**When to use:** Standardize form layouts with consistent spacing, labels, and validation errors. Compound component pattern for wrapping Input, Select, Textarea, etc.
+
+**Sub-components:**
+- `Form` — Root wrapper with consistent gap spacing between fields
+- `Form.Field` — Wraps a single input with optional label and error
+- `Form.Section` — Groups related fields with title and description
+- `Form.Footer` — Footer area for submit/cancel buttons
+
+**Form Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Form.Field, Form.Section, Form.Footer components |
+| style | `ViewStyle` | — |
+
+**Form.Field Props:**
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Input, Select, Textarea, etc. |
+| label | `string` | — | Label above input |
+| error | `string` | — | Error message below input |
+| required | `boolean` | `false` | Shows asterisk after label |
+| style | `ViewStyle` | — | — |
+| labelStyle | `TextStyle` | — | — |
+| errorStyle | `TextStyle` | — | — |
+
+**Form.Section Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Form.Field components |
+| title | `string` | Section heading |
+| description | `string` | Supporting text below title |
+| style | `ViewStyle` | — |
+
+**Form.Footer Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Button components |
+| style | `ViewStyle` | — |
+
+**Features:**
+- **Automatic spacing:** `gap: vs(16)` between Form.Field components
+- **Required indicator:** Red asterisk (*) when `required={true}`
+- **Error styling:** Error text in destructive color below input
+- **Label hierarchy:** Sohne-Medium 14px for labels, 12px for errors
+- **Footer layout:** Horizontal row with `gap: s(12)` for button grouping
+
+**Examples:**
+```tsx
+// Basic form
+<Form>
+  <Form.Field label="Full Name" required>
+    <Input value={name} onChangeText={setName} placeholder="John Doe" />
+  </Form.Field>
+  
+  <Form.Field label="Email" required error={emailError}>
+    <Input 
+      value={email} 
+      onChangeText={setEmail} 
+      placeholder="john@example.com"
+      keyboardType="email-address"
+    />
+  </Form.Field>
+  
+  <Form.Field label="Country">
+    <Select 
+      value={country} 
+      onValueChange={setCountry}
+      options={countries}
+    />
+  </Form.Field>
+  
+  <Form.Footer>
+    <Button label="Cancel" variant="outline" onPress={onCancel} />
+    <Button label="Submit" onPress={handleSubmit} />
+  </Form.Footer>
+</Form>
+
+// With sections
+<Form>
+  <Form.Section title="Personal Information" description="Your basic profile details">
+    <Form.Field label="Name" required>
+      <Input value={name} onChangeText={setName} />
+    </Form.Field>
+    <Form.Field label="Email" required error={emailError}>
+      <Input value={email} onChangeText={setEmail} />
+    </Form.Field>
+  </Form.Section>
+  
+  <Form.Section title="Preferences">
+    <Form.Field label="Language">
+      <Select value={lang} onValueChange={setLang} options={languages} />
+    </Form.Field>
+    <Form.Field label="Timezone">
+      <Select value={tz} onValueChange={setTz} options={timezones} />
+    </Form.Field>
+  </Form.Section>
+  
+  <Form.Footer>
+    <Button label="Save" fullWidth onPress={handleSave} />
+  </Form.Footer>
+</Form>
+
+// Inside Sheet
+<Sheet open={open} onClose={() => setOpen(false)} title="Edit Profile">
+  <Form>
+    <Form.Field label="Name" required>
+      <SheetTextInput value={name} onChangeText={setName} />
+    </Form.Field>
+    <Form.Field label="Bio">
+      <SheetTextInput 
+        value={bio} 
+        onChangeText={setBio} 
+        multiline 
+        style={{ minHeight: 80 }}
+      />
+    </Form.Field>
+  </Form>
+  <View style={{ marginTop: 16 }}>
+    <Button label="Save" fullWidth onPress={handleSave} />
+  </View>
+</Sheet>
+```
+
 ---
 
 ### Toast / useToast
@@ -2297,6 +2605,77 @@ dismiss(id)
 
 ---
 
+### ListGroup
+
+**Import:** `import { ListGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Wrap multiple `ListItem` components to standardize spacing, add automatic separators, and optionally apply a card surface. Identical pattern to `MenuGroup`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | ListItem components + ListGroup.Header + ListGroup.Footer |
+| variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background. `card`: card surface with border |
+| style | `ViewStyle` | — | — |
+
+**Sub-components:**
+- `ListGroup.Header` — Header text or custom content
+- `ListGroup.Footer` — Footer text or custom content
+
+**Features:**
+- **Auto-separators:** Automatically adds `showSeparator={true}` to all ListItem children except the last
+- **Individual override:** ListItem can override with `showSeparator={false}`
+- **Variant `card`:** Applies card surface (`RADIUS.md`, border, shadow)
+
+**Examples:**
+```tsx
+// Transaction list with auto separators
+<ListGroup variant="card">
+  <ListGroup.Header>Recent Transactions</ListGroup.Header>
+  <ListItem
+    leftIcon="coffee"
+    title="Rappi"
+    subtitle="Food · May 12"
+    rightRender={<Text color={colors.destructive}>−$45.000</Text>}
+    onPress={() => {}}
+  />
+  <ListItem
+    leftIcon="car"
+    title="Uber"
+    subtitle="Transport · May 11"
+    rightRender={<Text color={colors.destructive}>−$18.200</Text>}
+    onPress={() => {}}
+  />
+  <ListItem
+    leftIcon="briefcase"
+    title="Salary"
+    subtitle="Income · May 1"
+    rightRender={<Text color={colors.success}>+$3.500.000</Text>}
+    onPress={() => {}}
+  />
+  <ListGroup.Footer>Last 7 days</ListGroup.Footer>
+</ListGroup>
+
+// Plain variant (inside Card)
+<Card>
+  <CardContent>
+    <ListGroup variant="plain">
+      {users.map((user) => (
+        <ListItem
+          key={user.id}
+          leftRender={<Avatar src={user.avatar} fallback={user.name[0]} />}
+          title={user.name}
+          subtitle={user.role}
+          rightRender={<Badge label={user.status} variant="success" />}
+          onPress={() => navigate('user', { id: user.id })}
+        />
+      ))}
+    </ListGroup>
+  </CardContent>
+</Card>
+```
+
+---
+
 ### MenuItem
 
 **Import:** `import { MenuItem } from '@retray-dev/ui-kit'`
@@ -2376,6 +2755,61 @@ dismiss(id)
 
 ---
 
+### MenuGroup
+
+**Import:** `import { MenuGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Wrap multiple `MenuItem` components to standardize spacing, add automatic separators, and optionally apply a card surface. Compound component pattern like `Card`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | MenuItem components + MenuGroup.Header + MenuGroup.Footer |
+| variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background. `card`: card surface with border |
+| style | `ViewStyle` | — | — |
+
+**Sub-components:**
+- `MenuGroup.Header` — Header text or custom content
+- `MenuGroup.Footer` — Footer text or custom content
+
+**Features:**
+- **Auto-separators:** Automatically adds `showSeparator={true}` to all MenuItem children except the last
+- **Individual override:** MenuItem can override with `showSeparator={false}`
+- **Variant `card`:** Applies card surface (`RADIUS.md`, border, shadow) like standalone MenuItems with `variant="card"`
+
+**Examples:**
+```tsx
+// Basic group with auto separators
+<MenuGroup variant="card">
+  <MenuItem label="Personal Info" iconName="user" onPress={() => {}} />
+  <MenuItem label="Security" iconName="shield" onPress={() => {}} />
+  <MenuItem label="Privacy" iconName="lock" onPress={() => {}} />
+</MenuGroup>
+
+// With header and footer
+<MenuGroup variant="card">
+  <MenuGroup.Header>Account Settings</MenuGroup.Header>
+  <MenuItem label="Personal Info" subtitle="Name, email, phone" iconName="user" onPress={() => {}} />
+  <MenuItem label="Security" iconName="shield" onPress={() => {}} />
+  <MenuItem label="Privacy" iconName="lock" onPress={() => {}} />
+  <MenuGroup.Footer>Last updated today</MenuGroup.Footer>
+</MenuGroup>
+
+// Plain variant (inside another container)
+<Card>
+  <CardHeader>
+    <CardTitle>Settings</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <MenuGroup variant="plain">
+      <MenuItem label="Notifications" iconName="bell" rightRender={<Switch checked={notifs} onCheckedChange={setNotifs} />} />
+      <MenuItem label="Dark Mode" iconName="moon" rightRender={<Switch checked={dark} onCheckedChange={setDark} />} />
+    </MenuGroup>
+  </CardContent>
+</Card>
+```
+
+---
+
 ### Chip / ChipGroup
 
 **Import:** `import { Chip, ChipGroup } from '@retray-dev/ui-kit'`