@retray-dev/ui-kit 0.1.0 → 1.0.0

package/COMPONENTS.md

@@ -0,0 +1,654 @@
+# @retray-dev/ui-kit — Component Reference
+
+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:
+
+```markdown
+## UI Components
+@./node_modules/@retray-dev/ui-kit/COMPONENTS.md
+```
+
+---
+
+## Setup (Required)
+
+Wrap your app root with both providers. `ThemeProvider` enables theming; `ToastProvider` enables the toast notification system.
+
+```tsx
+import { ThemeProvider, ToastProvider } from '@retray-dev/ui-kit'
+
+export default function RootLayout({ children }) {
+  return (
+    <ThemeProvider colorScheme="system">
+      <ToastProvider>
+        {children}
+      </ToastProvider>
+    </ThemeProvider>
+  )
+}
+```
+
+### ThemeProvider Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| colorScheme | `'light' \| 'dark' \| 'system'` | `'system'` | `'system'` auto-detects the device setting and updates when it changes |
+| theme | `{ light?: Partial<ThemeColors>, dark?: Partial<ThemeColors> }` | — | Override any subset of color tokens per scheme |
+
+**Custom theme example:**
+```tsx
+const myTheme = {
+  light: { primary: '#6366f1', primaryForeground: '#ffffff' },
+  dark:  { primary: '#818cf8', primaryForeground: '#ffffff' },
+}
+<ThemeProvider theme={myTheme} colorScheme="system">
+```
+
+### useTheme Hook
+
+Access the active color tokens and scheme inside any component:
+```tsx
+import { useTheme } from '@retray-dev/ui-kit'
+
+function MyComponent() {
+  const { colors, colorScheme } = useTheme()
+  return <View style={{ backgroundColor: colors.background }} />
+}
+```
+
+---
+
+## Theme Tokens
+
+All 18 tokens are available via `useTheme().colors`.
+
+| Token | Light | Dark | Semantic Role |
+|-------|-------|------|---------------|
+| `background` | `#ffffff` | `#171717` | Screen / page background |
+| `foreground` | `#171717` | `#fafafa` | Primary text color |
+| `card` | `#ffffff` | `#1f1f1f` | Card / surface background |
+| `cardForeground` | `#171717` | `#fafafa` | Text on cards |
+| `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states) |
+| `primaryForeground` | `#fafafa` | `#1a1a1a` | Text/icon on primary background |
+| `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 |
+| `accent` | `#f5f5f5` | `#2a2a2a` | Hover / pressed state fills |
+| `accentForeground` | `#1a1a1a` | `#fafafa` | Text on accent |
+| `destructive` | `#ef4444` | `#dc2626` | Error / danger / delete actions |
+| `destructiveForeground` | `#fafafa` | `#fafafa` | Text on destructive |
+| `border` | `#e5e5e5` | `#2a2a2a` | Borders and dividers |
+| `input` | `#e5e5e5` | `#2a2a2a` | Input field border color |
+| `ring` | `#a3a3a3` | `#d4d4d4` | Focus ring color |
+
+---
+
+## Components
+
+---
+
+### Text
+
+**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.
+
+| 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` |
+
+**Sizes:**
+- `h1`: 32px / 700 weight
+- `h2`: 24px / 700 weight
+- `h3`: 20px / 600 weight
+- `body`: 16px / 400 weight
+- `label`: 14px / 500 weight
+- `caption`: 12px / 400 weight / `mutedForeground` color by default
+
+**Example:**
+```tsx
+<Text variant="h2">Welcome back</Text>
+<Text variant="body">Your account is ready.</Text>
+<Text variant="caption">Last updated 2 hours ago</Text>
+<Text variant="label" color="#6366f1">Pro plan</Text>
+```
+
+---
+
+### Button
+
+**Import:** `import { Button } from '@retray-dev/ui-kit'`
+**When to use:** Any interactive action. Use `variant` to communicate intent.
+**Extends:** `TouchableOpacityProps` — all RN TouchableOpacity props pass through.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| 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 |
+| 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
+- `ghost`: fully transparent — in-context or low-emphasis actions
+
+**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 />
+```
+
+---
+
+### Input
+
+**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.
+
+| 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) |
+
+**Example:**
+```tsx
+<Input label="Email" placeholder="you@example.com" keyboardType="email-address" />
+<Input label="Password" secureTextEntry error="Incorrect password" />
+<Input label="Username" hint="Must be at least 4 characters" />
+```
+
+---
+
+### 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.
+
+| 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) |
+
+**Example:**
+```tsx
+<Textarea label="Bio" placeholder="Tell us about yourself" rows={5} />
+```
+
+---
+
+### Badge
+
+**Import:** `import { Badge } from '@retray-dev/ui-kit'`
+**When to use:** Status labels, tags, counts.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string` | required | — |
+| variant | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | — |
+
+**Example:**
+```tsx
+<Badge label="New" />
+<Badge label="Error" variant="destructive" />
+<Badge label="Draft" variant="secondary" />
+<Badge label="Beta" variant="outline" />
+```
+
+---
+
+### Avatar
+
+**Import:** `import { Avatar } from '@retray-dev/ui-kit'`
+**When to use:** User profile pictures with automatic fallback to initials.
+
+| 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 |
+
+**Example:**
+```tsx
+<Avatar src="https://..." fallback="JC" size="lg" />
+<Avatar fallback="AN" size="md" />
+```
+
+---
+
+### Separator
+
+**Import:** `import { Separator } from '@retray-dev/ui-kit'`
+**When to use:** Visual dividers between sections.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical requires a parent with defined height |
+
+**Example:**
+```tsx
+<Separator />
+<View style={{ flexDirection: 'row', height: 40 }}>
+  <Text>Left</Text>
+  <Separator orientation="vertical" style={{ marginHorizontal: 12 }} />
+  <Text>Right</Text>
+</View>
+```
+
+---
+
+### Spinner
+
+**Import:** `import { Spinner } from '@retray-dev/ui-kit'`
+**When to use:** Loading state indicator.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | sm/md map to RN `'small'`, lg maps to `'large'` |
+| color | `string` | `primary` token | Override spinner color |
+
+**Example:**
+```tsx
+<Spinner />
+<Spinner size="lg" color="#6366f1" />
+```
+
+---
+
+### Skeleton
+
+**Import:** `import { Skeleton } from '@retray-dev/ui-kit'`
+**When to use:** Placeholder while content is loading. Pulses with animation.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| width | `number \| string` | `'100%'` | — |
+| height | `number` | `16` | — |
+| borderRadius | `number` | `6` | — |
+
+**Example:**
+```tsx
+<Skeleton height={20} width="60%" />
+<Skeleton height={80} borderRadius={10} />
+```
+
+---
+
+### Progress
+
+**Import:** `import { Progress } from '@retray-dev/ui-kit'`
+**When to use:** Show completion percentage for a task or upload.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `number` | `0` | Current value |
+| max | `number` | `100` | Maximum value |
+
+**Example:**
+```tsx
+<Progress value={60} />
+<Progress value={3} max={10} />
+```
+
+---
+
+### Card
+
+**Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@retray-dev/ui-kit'`
+**When to use:** Grouped content with a surface background, border, and shadow.
+
+All sub-components accept a `style` prop for overrides.
+
+**Example:**
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Account</CardTitle>
+    <CardDescription>Manage your profile settings</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <Input label="Name" />
+  </CardContent>
+  <CardFooter>
+    <Button label="Save" fullWidth />
+  </CardFooter>
+</Card>
+```
+
+**Notes:** `CardHeader` and `CardContent` have `padding: 24`. `CardFooter` has `paddingTop: 0` so it connects naturally to `CardContent`.
+
+---
+
+### Alert
+
+**Import:** `import { Alert } from '@retray-dev/ui-kit'`
+**When to use:** Inline feedback messages (info, success, warning, error). Not for 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 |
+
+**Example:**
+```tsx
+<Alert title="Success" description="Your profile has been updated." />
+<Alert variant="destructive" title="Error" description="Failed to save. Try again." />
+```
+
+---
+
+### EmptyState
+
+**Import:** `import { EmptyState } from '@retray-dev/ui-kit'`
+**When to use:** When a list or section has no content yet.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| title | `string` | required | — |
+| description | `string` | — | — |
+| icon | `ReactNode` | — | Shown in a muted square above the text |
+| action | `ReactNode` | — | Usually a `Button`, placed below the text |
+
+**Example:**
+```tsx
+<EmptyState
+  title="No notifications"
+  description="You're all caught up!"
+  action={<Button label="Refresh" variant="outline" size="sm" />}
+/>
+```
+
+---
+
+### Checkbox
+
+**Import:** `import { Checkbox } from '@retray-dev/ui-kit'`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| checked | `boolean` | `false` | — |
+| onCheckedChange | `(checked: boolean) => void` | — | — |
+| label | `string` | — | Text to the right of the box |
+| disabled | `boolean` | — | — |
+
+**Example:**
+```tsx
+const [accepted, setAccepted] = useState(false)
+<Checkbox checked={accepted} onCheckedChange={setAccepted} label="I agree to the terms" />
+```
+
+---
+
+### Switch
+
+**Import:** `import { Switch } from '@retray-dev/ui-kit'`
+**When to use:** Binary on/off settings. Animated thumb.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| checked | `boolean` | `false` | — |
+| onCheckedChange | `(checked: boolean) => void` | — | — |
+| disabled | `boolean` | — | — |
+
+**Example:**
+```tsx
+<Switch checked={notifications} onCheckedChange={setNotifications} />
+```
+
+---
+
+### 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.
+
+| 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'` | — |
+| label | `string` | — | Text label |
+| icon | `ReactNode` | — | Icon (can be combined with label) |
+
+**Example:**
+```tsx
+<Toggle pressed={bold} onPressedChange={setBold} label="Bold" variant="outline" />
+```
+
+---
+
+### RadioGroup
+
+**Import:** `import { RadioGroup } from '@retray-dev/ui-kit'`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| options | `RadioOption[]` | required | Each option: `{ label, value, disabled? }` |
+| value | `string` | — | Selected value |
+| onValueChange | `(value: string) => void` | — | — |
+| orientation | `'vertical' \| 'horizontal'` | `'vertical'` | — |
+
+**Example:**
+```tsx
+<RadioGroup
+  options={[
+    { label: 'Free', value: 'free' },
+    { label: 'Pro', value: 'pro' },
+    { label: 'Enterprise', value: 'enterprise', disabled: true },
+  ]}
+  value={plan}
+  onValueChange={setPlan}
+/>
+```
+
+---
+
+### Select
+
+**Import:** `import { Select } from '@retray-dev/ui-kit'`
+**When to use:** Dropdown picker. Tapping the trigger opens a modal with a scrollable list.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| options | `SelectOption[]` | required | Each option: `{ label, value, disabled? }` |
+| value | `string` | — | Selected value |
+| onValueChange | `(value: string) => void` | — | — |
+| placeholder | `string` | `'Select an option'` | — |
+| label | `string` | — | Label above the trigger |
+| error | `string` | — | Error text below |
+| disabled | `boolean` | — | — |
+
+**Example:**
+```tsx
+<Select
+  label="Country"
+  options={[{ label: 'Argentina', value: 'AR' }, { label: 'Spain', value: 'ES' }]}
+  value={country}
+  onValueChange={setCountry}
+  placeholder="Pick a country"
+/>
+```
+
+---
+
+### Slider
+
+**Import:** `import { Slider } from '@retray-dev/ui-kit'`
+**When to use:** Select a numeric value within a range by dragging.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `number` | `0` | — |
+| minimumValue | `number` | `0` | — |
+| maximumValue | `number` | `1` | — |
+| step | `number` | `0` | `0` means continuous |
+| onValueChange | `(value: number) => void` | — | Fires while dragging |
+| onSlidingComplete | `(value: number) => void` | — | Fires on release |
+| disabled | `boolean` | — | — |
+
+**Example:**
+```tsx
+<Slider value={volume} minimumValue={0} maximumValue={100} step={1} onValueChange={setVolume} />
+```
+
+---
+
+
+
+### Tabs
+
+**Import:** `import { Tabs, TabsContent } from '@retray-dev/ui-kit'`
+**When to use:** Switching between categorized sections on the same screen.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| tabs | `TabItem[]` | required | Each item: `{ label, value }` |
+| value | `string` | — | Controlled active tab |
+| onValueChange | `(value: string) => void` | — | — |
+| children | `ReactNode` | — | `TabsContent` components |
+
+**`TabsContent` Props:**
+
+| Prop | Type | Notes |
+|------|------|-------|
+| value | `string` | Must match a tab value |
+| activeValue | `string` | Pass the current active tab value |
+| children | `ReactNode` | — |
+
+**Example:**
+```tsx
+const [tab, setTab] = useState('profile')
+
+<Tabs
+  tabs={[{ label: 'Profile', value: 'profile' }, { label: 'Security', value: 'security' }]}
+  value={tab}
+  onValueChange={setTab}
+>
+  <TabsContent value="profile" activeValue={tab}>
+    <Text>Profile content</Text>
+  </TabsContent>
+  <TabsContent value="security" activeValue={tab}>
+    <Text>Security content</Text>
+  </TabsContent>
+</Tabs>
+```
+
+---
+
+### Accordion
+
+**Import:** `import { Accordion } from '@retray-dev/ui-kit'`
+**When to use:** FAQs, collapsible sections. Animated expand/collapse.
+
+| 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) |
+
+**Example:**
+```tsx
+<Accordion
+  type="single"
+  items={[
+    { value: 'q1', trigger: 'What is this?', content: <Text>It's a UI kit.</Text> },
+    { value: 'q2', trigger: 'Is it free?', content: <Text>Yes.</Text> },
+  ]}
+/>
+```
+
+---
+
+
+
+### 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`):
+```tsx
+import { ThemeProvider, BottomSheetModalProvider } from '@retray-dev/ui-kit'
+
+<ThemeProvider>
+  <BottomSheetModalProvider>
+    {/* rest of app */}
+  </BottomSheetModalProvider>
+</ThemeProvider>
+```
+
+**Peer dependencies** (install in your app):
+```bash
+pnpm add @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler
+```
+Add `react-native-reanimated/plugin` to your `babel.config.js` plugins.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| open | `boolean` | required | — |
+| 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` | — | — |
+
+**Example:**
+```tsx
+<Sheet open={open} onClose={() => setOpen(false)} title="Filters" snapPoints={['50%']}>
+  <RadioGroup options={sortOptions} value={sort} onValueChange={setSort} />
+</Sheet>
+```
+
+---
+
+
+
+### 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).
+
+```tsx
+import { useToast } from '@retray-dev/ui-kit'
+
+function MyComponent() {
+  const { toast, dismiss } = useToast()
+
+  return (
+    <Button
+      label="Save"
+      onPress={async () => {
+        await save()
+        toast({ title: 'Saved', description: 'Your changes were saved.', variant: 'success' })
+      }}
+    />
+  )
+}
+```
+
+**`toast()` options:**
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| title | `string` | — | Bold heading |
+| description | `string` | — | Detail text |
+| 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).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julian Camilo Cruz Sanchez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.