@retray-dev/ui-kit 6.2.0 → 9.0.0

package/EXAMPLES.md

@@ -541,6 +541,254 @@ const styles = StyleSheet.create({
 
 ---
 
+## Example 4: Settings Screen with Compound Components
+
+**Use case:** App settings screen demonstrating MenuGroup, ListGroup, and Form compound components for standardized layouts.
+
+**Components used:** MenuGroup, ListGroup, Form, MenuItem, ListItem, Input, Textarea, Select, Switch, Avatar, Badge, Button
+
+**Features:**
+- MenuGroup with auto-separators for settings navigation
+- ListGroup for account info display
+- Form with sections for structured input
+- Compound component headers and footers
+- Mixed card and plain variants
+
+### State Setup
+
+```tsx
+const [name, setName] = useState('Julian Cruz')
+const [email, setEmail] = useState('julian@email.com')
+const [bio, setBio] = useState('')
+const [notifications, setNotifications] = useState(true)
+const [darkMode, setDarkMode] = useState(false)
+const [language, setLanguage] = useState('es')
+```
+
+### Implementation
+
+```tsx
+import { View, ScrollView, StyleSheet } from 'react-native'
+import {
+  MenuGroup,
+  MenuItem,
+  ListGroup,
+  ListItem,
+  Form,
+  Input,
+  Textarea,
+  Select,
+  Switch,
+  Avatar,
+  Badge,
+  Button,
+  Card,
+  Text,
+  useTheme,
+  useToast,
+} from '@retray-dev/ui-kit'
+
+function SettingsScreen() {
+  const { colors } = useTheme()
+  const { toast } = useToast()
+
+  return (
+    <ScrollView contentContainerStyle={styles.content}>
+      {/* Profile Section with ListGroup */}
+      <Text variant="caption" style={{ marginBottom: 8, paddingHorizontal: 4 }}>
+        Profile
+      </Text>
+      <ListGroup variant="card">
+        <ListGroup.Header>Account Overview</ListGroup.Header>
+        <ListItem
+          leftRender={<Avatar fallbackText={name} size={40} status="online" />}
+          title={name}
+          subtitle={email}
+          rightRender={<Badge label="Pro" variant="success" size="sm" />}
+          onPress={() => toast.success('Profile tapped')}
+        />
+        <ListItem
+          leftIcon="calendar"
+          title="Member since"
+          subtitle="Jan 2022"
+          rightRender="2 years"
+        />
+        <ListItem
+          leftIcon="star"
+          title="Reviews"
+          subtitle="Total written"
+          rightRender="24"
+        />
+        <ListGroup.Footer>Last updated today</ListGroup.Footer>
+      </ListGroup>
+
+      <View style={{ height: 24 }} />
+
+      {/* Settings Menu with MenuGroup */}
+      <Text variant="caption" style={{ marginBottom: 8, paddingHorizontal: 4 }}>
+        Account Settings
+      </Text>
+      <MenuGroup variant="card">
+        <MenuGroup.Header>Personal</MenuGroup.Header>
+        <MenuItem
+          label="Personal Information"
+          subtitle="Name, email, phone"
+          iconName="user"
+          onPress={() => toast('Personal Info')}
+        />
+        <MenuItem
+          label="Security & Privacy"
+          iconName="shield"
+          onPress={() => toast('Security')}
+        />
+        <MenuItem
+          label="Payments & Payouts"
+          iconName="credit-card"
+          rightRender={<Badge label="2" variant="warning" size="sm" />}
+          onPress={() => toast('Payments')}
+        />
+      </MenuGroup>
+
+      <View style={{ height: 16 }} />
+
+      {/* Preferences with switches */}
+      <MenuGroup variant="card">
+        <MenuGroup.Header>Preferences</MenuGroup.Header>
+        <MenuItem
+          label="Notifications"
+          subtitle="Push, email, and SMS"
+          iconName="bell"
+          rightRender={
+            <Switch checked={notifications} onCheckedChange={setNotifications} />
+          }
+          onPress={() => {}}
+        />
+        <MenuItem
+          label="Dark Mode"
+          iconName="moon"
+          rightRender={<Switch checked={darkMode} onCheckedChange={setDarkMode} />}
+          onPress={() => {}}
+        />
+        <MenuItem
+          label="Language"
+          iconName="globe"
+          rightRender={<Text color={colors.foregroundMuted}>English</Text>}
+          onPress={() => toast('Language')}
+        />
+      </MenuGroup>
+
+      <View style={{ height: 24 }} />
+
+      {/* Edit Profile Form */}
+      <Card>
+        <Form>
+          <Form.Section
+            title="Edit Profile"
+            description="Update your personal information"
+          >
+            <Form.Field label="Full Name" required>
+              <Input
+                value={name}
+                onChangeText={setName}
+                placeholder="Your name"
+                prefixIcon="user"
+              />
+            </Form.Field>
+
+            <Form.Field label="Email" required>
+              <Input
+                value={email}
+                onChangeText={setEmail}
+                placeholder="you@example.com"
+                keyboardType="email-address"
+                prefixIcon="mail"
+              />
+            </Form.Field>
+
+            <Form.Field label="Bio">
+              <Textarea
+                value={bio}
+                onChangeText={setBio}
+                placeholder="Tell us about yourself"
+                rows={3}
+              />
+            </Form.Field>
+
+            <Form.Field label="Language">
+              <Select
+                value={language}
+                onValueChange={setLanguage}
+                options={[
+                  { label: 'English', value: 'en' },
+                  { label: 'Español', value: 'es' },
+                  { label: 'Français', value: 'fr' },
+                ]}
+              />
+            </Form.Field>
+          </Form.Section>
+
+          <Form.Footer>
+            <Button
+              label="Cancel"
+              variant="secondary"
+              onPress={() => toast('Cancelled')}
+            />
+            <Button
+              label="Save Changes"
+              onPress={() => toast.success('Profile updated')}
+            />
+          </Form.Footer>
+        </Form>
+      </Card>
+
+      <View style={{ height: 24 }} />
+
+      {/* Support MenuGroup */}
+      <Text variant="caption" style={{ marginBottom: 8, paddingHorizontal: 4 }}>
+        Support
+      </Text>
+      <MenuGroup variant="card">
+        <MenuItem
+          label="Help Center"
+          iconName="help-circle"
+          onPress={() => toast('Help')}
+        />
+        <MenuItem
+          label="Report an Issue"
+          iconName="alert-triangle"
+          onPress={() => toast('Report')}
+        />
+        <MenuItem
+          label="Terms of Service"
+          iconName="file-text"
+          onPress={() => toast('Terms')}
+        />
+      </MenuGroup>
+
+      <View style={{ height: 32 }} />
+    </ScrollView>
+  )
+}
+
+const styles = StyleSheet.create({
+  content: {
+    padding: 16,
+    paddingBottom: 48,
+  },
+})
+```
+
+**Key patterns demonstrated:**
+
+1. **MenuGroup auto-separators** — No need to add `showSeparator` to each MenuItem
+2. **ListGroup with header/footer** — Compound components for structured lists
+3. **Form.Section** — Grouped fields with title and description
+4. **Form.Footer** — Button row with automatic spacing
+5. **Mixed variants** — `variant="card"` for standalone groups, `variant="plain"` inside Card
+6. **rightRender flexibility** — Switch, Badge, Text, or custom content
+
+---
+
 ## Common Patterns
 
 ### Full-Screen Overlay Pattern
@@ -644,7 +892,7 @@ These examples are live in the `example/` app included with the source. To run t
 
 ```bash
 # Clone the repo
-git clone https://github.com/YOUR_USERNAME/retray-ui-kit
+git clone https://github.com/retray-dev/retray-ui-kit
 cd retray-ui-kit
 
 # Install dependencies
@@ -659,7 +907,7 @@ pnpm start
 # Or: pnpm ios / pnpm android
 ```
 
-Inside the example app, navigate to the "🖥 App Screen Compositions" accordion to access all three screens.
+Inside the example app, open the **Compose** tab in the bottom tab bar to browse the composed screen patterns alongside the per-category component showcases (Display, Form, Surfaces, Data, Demos, Theme).
 
 ---
 

package/README.md

@@ -2,8 +2,8 @@
 
 A personal React Native / Expo UI component library with a built-in design system, dark mode support, haptic feedback, and smooth animations.
 
-- 37 components across 7 categories
-- Light/dark theme with 12 public tokens (24 resolved) and full customization
+- 49 components across 9 categories (plus the deep-import `HolographicCard`)
+- Light/dark theme with 12 public tokens (25 resolved) and full customization
 - Apple HIG–compliant touch targets and haptic feedback
 - Animated interactions: spring press, sliding tabs, accordion easing, animated progress
 - Built with TypeScript — full type declarations included
@@ -23,11 +23,15 @@ pnpm add @retray-dev/ui-kit
 Install these in your app if not already present:
 
 ```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
+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
 ```
 
 For Expo projects, run `npx expo install` instead to get SDK-compatible versions.
 
+`pressto` is **required** — it powers the press animations on every interactive component. Omitting it crashes the import. `sonner-native` is **required** for `Toast`.
+
+**Optional:** for richer haptics in a custom dev build (not Expo Go), also `pnpm add react-native-pulsar`. The kit falls back to `expo-haptics` automatically when it is absent. For the deep-import `HolographicCard`, add `@shopify/react-native-skia expo-sensors`.
+
 Add the Worklets Babel plugin to `babel.config.js` (required by `@gorhom/bottom-sheet`):
 
 ```js
@@ -42,14 +46,14 @@ module.exports = function (api) {
 
 ## Typography
 
-All components use **Poppins** font family. You must load the fonts at app root before rendering any component:
+All components use **Sohne** font family. You must load the fonts at app root before rendering any 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 (
@@ -58,7 +62,7 @@ export default function App() {
 }
 ```
 
-The library ships 13 font files (9 regular weights + 4 italic variants) as raw `.ttf` files. Metro resolves them at bundle time.
+The library ships 28 font files (14 Sohne base + 14 SohneMono, each with 7 weights + italic variants) as raw `.otf` files. Metro resolves them at bundle time.
 
 ## Setup
 
@@ -113,9 +117,9 @@ import { useTheme } from '@retray-dev/ui-kit'
 const { colors, colorScheme } = useTheme()
 ```
 
-**Public tokens (12 — override these):** `background`, `foreground`, `card`, `primary`, `primaryForeground`, `border`, `destructive`, `destructiveForeground`, `success`, `successForeground`, `warning`, `warningForeground`
+**Public tokens (12 — override these):** `background`, `foreground`, `card`, `primary`, `primaryForeground`, `border`, `destructive`, `destructiveForeground`, `success`, `successForeground`, `warning`, `warningForeground`. Optional: `overlay`, `accent`, `accentForeground`.
 
-**Derived tokens (read-only via `useTheme()`):** `foregroundSubtle`, `foregroundMuted`, `surface`, `surfaceStrong`, `destructiveTint`, `destructiveBorder`, `successTint`, `successBorder`, `warningTint`, `warningBorder`, `ring`, `input`
+**Derived tokens (read-only via `useTheme()`):** `foregroundSubtle`, `foregroundMuted`, `surface`, `surfaceStrong`, `destructiveTint`, `destructiveBorder`, `successTint`, `successBorder`, `warningTint`, `warningBorder`, `ring`, `input`, `separator`, `overlay`, `accentResolved`, `accentForegroundResolved`
 
 ## Design Tokens
 
@@ -141,13 +145,16 @@ import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@
 | Category    | Components                                                                                      |
 | ----------- | ----------------------------------------------------------------------------------------------- |
 | Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`   |
-| Surfaces    | `Card`, `AlertBanner`, `EmptyState`, `MediaCard`                                                |
-| Form        | `Button`, `ButtonGroup`, `IconButton`, `Input`, `CurrencyInput`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
+| Surfaces    | `Card`, `AlertBanner`, `EmptyState`, `MediaCard`, `PricingCard`                                 |
+| Form        | `Form` (+ `Form.Field` / `Form.Section` / `Form.Footer`), `Button`, `ButtonGroup`, `IconButton`, `Input`, `CurrencyInput`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider`, `SelectableGrid` |
 | Composition | `Tabs`, `Accordion`                                                                             |
-| Overlays    | `Sheet`, `ConfirmDialog`                                                                        |
+| Navigation  | `AppHeader`, `TabBar`, `PagerDots`                                                              |
+| Overlays    | `Sheet`, `ConfirmDialog`, `ImageViewer`                                                         |
 | Feedback    | `Toast` / `ToastProvider` / `useToast`                                                          |
-| Data        | `ListItem`, `Chip` / `ChipGroup`, `LabelValue`, `MonthPicker`, `CategoryStrip`, `DetailRow`    |
-| Utilities   | `Pressable`                                                                                     |
+| Data        | `ListItem`, `ListGroup` (+ `.Header` / `.Footer`), `MenuItem`, `MenuGroup` (+ `.Header` / `.Footer`), `VirtualList`, `Chip` / `ChipGroup`, `LabelValue`, `MonthPicker`, `CategoryStrip`, `DetailRow` |
+| Utilities   | `Pressable`, `Icon`, `RetrayProvider`, `ErrorBoundary`                                          |
+
+Deep-import only: `HolographicCard` — `import { HolographicCard } from '@retray-dev/ui-kit/HolographicCard'`.
 
 ### Quick examples
 

package/dist/Accordion.d.mts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { ViewStyle } from 'react-native';
+
+interface AccordionItem {
+    value: string;
+    trigger: string;
+    content: React.ReactNode;
+    /** Icon name from @expo/vector-icons rendered left of trigger. */
+    iconName?: string;
+    /** Custom icon node rendered left of trigger. */
+    icon?: React.ReactNode;
+    /** Override icon color. Defaults to foregroundMuted. */
+    iconColor?: string;
+}
+interface AccordionProps {
+    items: AccordionItem[];
+    /**
+     * - `'single'` (default): only one item can be open at a time. Opening another closes the current one.
+     * - `'multiple'`: any number of items can be open simultaneously.
+     */
+    type?: 'single' | 'multiple';
+    /** Item value(s) that should be open on first render. */
+    defaultValue?: string | string[];
+    style?: ViewStyle;
+}
+declare function Accordion({ items, type, defaultValue, style }: AccordionProps): React.JSX.Element;
+
+export { Accordion, type AccordionItem, type AccordionProps };

package/dist/Accordion.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { ViewStyle } from 'react-native';
+
+interface AccordionItem {
+    value: string;
+    trigger: string;
+    content: React.ReactNode;
+    /** Icon name from @expo/vector-icons rendered left of trigger. */
+    iconName?: string;
+    /** Custom icon node rendered left of trigger. */
+    icon?: React.ReactNode;
+    /** Override icon color. Defaults to foregroundMuted. */
+    iconColor?: string;
+}
+interface AccordionProps {
+    items: AccordionItem[];
+    /**
+     * - `'single'` (default): only one item can be open at a time. Opening another closes the current one.
+     * - `'multiple'`: any number of items can be open simultaneously.
+     */
+    type?: 'single' | 'multiple';
+    /** Item value(s) that should be open on first render. */
+    defaultValue?: string | string[];
+    style?: ViewStyle;
+}
+declare function Accordion({ items, type, defaultValue, style }: AccordionProps): React.JSX.Element;
+
+export { Accordion, type AccordionItem, type AccordionProps };