npm package: @retray-dev/ui-kit
Description: Personal UI Kit for React Native / Expo
Latest version: 2.3.0

# 📦 @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.

- 32 components across 6 categories
- Light/dark theme with 20 color tokens 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

## Installation

```bash
# npm
npm install @retray-dev/ui-kit

# pnpm
pnpm add @retray-dev/ui-kit
```

### Peer dependencies

Install these in your app if not already present:

```bash
pnpm add expo-haptics react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets
```

For Expo projects, run `npx expo install` instead to get SDK-compatible versions.

Add the Worklets Babel plugin to `babel.config.js` (required by `@gorhom/bottom-sheet`):

```js
module.exports = function (api) {
  api.cache(true)
  return {
    presets: ['babel-preset-expo'],
    plugins: ['react-native-worklets/plugin'],
  }
}
```

## Setup

Wrap your app root with all required providers. Order matters.

```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 colorScheme="system">
          <BottomSheetModalProvider>
            <ToastProvider>{/* your app */}</ToastProvider>
          </BottomSheetModalProvider>
        </ThemeProvider>
      </GestureHandlerRootView>
    </SafeAreaProvider>
  )
}
```

| Provider                   | Required by                                |
| -------------------------- | ------------------------------------------ |
| `SafeAreaProvider`         | `ToastProvider` (uses `useSafeAreaInsets`) |
| `GestureHandlerRootView`   | `Sheet` (uses `@gorhom/bottom-sheet`)      |
| `ThemeProvider`            | All components                             |
| `BottomSheetModalProvider` | `Sheet`                                    |
| `ToastProvider`            | `useToast` hook                            |

## Theme

Customize any color token per scheme:

```tsx
const myTheme = {
  light: { primary: '#6366f1', primaryForeground: '#ffffff' },
  dark:  { primary: '#818cf8', primaryForeground: '#ffffff' },
}

<ThemeProvider theme={myTheme} colorScheme="system">
```

Access theme colors anywhere inside the tree:

```tsx
import { useTheme } from '@retray-dev/ui-kit'

const { colors, colorScheme } = useTheme()
```

**Available tokens:** `background`, `foreground`, `card`, `cardForeground`, `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `muted`, `mutedForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, `border`, `input`, `ring`, `success`, `successForeground`

## Components

| Category    | Components                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`   |
| Surfaces    | `Card`, `Alert`, `EmptyState`                                                                   |
| Form        | `Button`, `Input`, `CurrencyInput`, `CurrencyInputLarge`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
| Composition | `Tabs`, `Accordion`                                                                             |
| Overlays    | `Sheet`, `ConfirmDialog`                                                                        |
| Feedback    | `Toast` / `ToastProvider` / `useToast`                                                          |
| Data        | `ListItem`, `Chip` / `ChipGroup`, `LabelValue`, `MonthPicker`                                  |

### Quick examples

```tsx
import {
  Button, Input, Badge, Card, CardHeader, CardTitle, CardContent,
  Toast, useToast, Sheet, Select, Tabs, TabsContent,
} from '@retray-dev/ui-kit'

// Button
<Button variant="default" size="md" onPress={() => {}}>
  Save
</Button>

// Toast
const { toast } = useToast()
toast({ title: 'Saved', variant: 'success' })

// Sheet (bottom sheet)
<Sheet open={open} onClose={() => setOpen(false)} title="Options" snapPoints={['40%']}>
  <Text>Sheet content</Text>
</Sheet>

// Select
<Select
  value={value}
  onValueChange={setValue}
  options={[{ label: 'Option A', value: 'a' }, { label: 'Option B', value: 'b' }]}
  placeholder="Pick one"
/>
```

Full props reference and more examples are available in [COMPONENTS.md](./COMPONENTS.md), which is also shipped inside the npm package for use with AI tools:

```markdown
## UI Components

@./node_modules/@retray-dev/ui-kit/COMPONENTS.md
```

## License

MIT © Julian Camilo Cruz Sanchez