@retray-dev/ui-kit 0.1.0 → 1.5.0

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.

package/README.md

@@ -0,0 +1,150 @@
+# 📦 @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.
+
+- 23 components across 5 categories
+- Light/dark theme with 18 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`
+
+## Components
+
+| Category    | Components                                                                                      |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`                       |
+| Surfaces    | `Card`, `Alert`, `EmptyState`                                                                   |
+| Form        | `Button`, `Input`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
+| Composition | `Tabs`, `Accordion`                                                                             |
+| Overlays    | `Sheet`                                                                                         |
+| Feedback    | `Toast` / `ToastProvider` / `useToast`                                                          |
+
+### 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

package/dist/index.d.mts

@@ -1,16 +1,81 @@
 import React from 'react';
-import { TouchableOpacityProps, TextProps as TextProps$1, TextInputProps } from 'react-native';
+import { TouchableOpacityProps, TextProps as TextProps$1, TextInputProps, ViewStyle, TextStyle, ActivityIndicatorProps } from 'react-native';
+export { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
+
+type ThemeColors = {
+    background: string;
+    foreground: string;
+    card: string;
+    cardForeground: string;
+    primary: string;
+    primaryForeground: string;
+    secondary: string;
+    secondaryForeground: string;
+    muted: string;
+    mutedForeground: string;
+    accent: string;
+    accentForeground: string;
+    destructive: string;
+    destructiveForeground: string;
+    border: string;
+    input: string;
+    ring: string;
+    success: string;
+    successForeground: string;
+};
+type Theme = {
+    light?: Partial<ThemeColors>;
+    dark?: Partial<ThemeColors>;
+};
+type ColorScheme = 'light' | 'dark' | 'system';
+type ThemeContextValue = {
+    colors: ThemeColors;
+    colorScheme: 'light' | 'dark';
+};
+
+interface ThemeProviderProps {
+    children: React.ReactNode;
+    /**
+     * Override individual color tokens per scheme. Only provide the tokens you want
+     * to change — the rest fall back to the defaults.
+     * @example
+     * { light: { primary: '#6366f1', primaryForeground: '#fff' },
+     *   dark:  { primary: '#818cf8', primaryForeground: '#fff' } }
+     */
+    theme?: Theme;
+    /**
+     * - `'system'` (default): auto-detects device setting and updates when it changes.
+     * - `'light'` / `'dark'`: forces a specific scheme regardless of device setting.
+     */
+    colorScheme?: ColorScheme;
+}
+declare function ThemeProvider({ children, theme, colorScheme }: ThemeProviderProps): React.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+
+declare const defaultLight: ThemeColors;
+declare const defaultDark: ThemeColors;
 
 type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost';
 type ButtonSize = 'sm' | 'md' | 'lg';
 interface ButtonProps extends TouchableOpacityProps {
     label: string;
+    /**
+     * - `primary`: filled with `primary` token — main CTA
+     * - `secondary`: filled with `secondary` token — less prominent
+     * - `outline`: transparent with border — alternative actions
+     * - `ghost`: fully transparent — in-context or low-emphasis actions
+     */
     variant?: ButtonVariant;
     size?: ButtonSize;
+    /** Replaces the label with a spinner and forces `disabled`. */
     loading?: boolean;
     fullWidth?: boolean;
+    /** Icon rendered alongside the label. */
+    icon?: React.ReactNode;
+    /** Side the icon appears on. Defaults to `'left'`. */
+    iconPosition?: 'left' | 'right';
 }
-declare function Button({ label, variant, size, loading, fullWidth, disabled, style, ...props }: ButtonProps): React.JSX.Element;
+declare function Button({ label, variant, size, loading, fullWidth, icon, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'body' | 'caption' | 'label';
 interface TextProps extends TextProps$1 {
@@ -21,9 +86,285 @@ declare function Text({ variant, color, style, children, ...props }: TextProps):
 
 interface InputProps extends TextInputProps {
     label?: string;
+    /** Red helper text below the input; also changes border to `destructive` color. Takes priority over `hint`. */
+    error?: string;
+    /** Helper text shown below the input when there is no error. */
+    hint?: string;
+    /** Style for the outer container `View`. Use `style` (from `TextInputProps`) to style the `TextInput` itself. */
+    containerStyle?: ViewStyle;
+}
+declare function Input({ label, error, hint, containerStyle, style, onFocus, onBlur, ...props }: InputProps): React.JSX.Element;
+
+type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
+interface BadgeProps {
+    label: string;
+    variant?: BadgeVariant;
+    style?: ViewStyle;
+}
+declare function Badge({ label, variant, style }: BadgeProps): React.JSX.Element;
+
+interface CardProps {
+    children: React.ReactNode;
+    style?: ViewStyle;
+}
+interface CardHeaderProps {
+    children: React.ReactNode;
+    style?: ViewStyle;
+}
+interface CardTitleProps {
+    children: React.ReactNode;
+    style?: TextStyle;
+}
+interface CardDescriptionProps {
+    children: React.ReactNode;
+    style?: TextStyle;
+}
+interface CardContentProps {
+    children: React.ReactNode;
+    style?: ViewStyle;
+}
+interface CardFooterProps {
+    children: React.ReactNode;
+    style?: ViewStyle;
+}
+declare function Card({ children, style }: CardProps): React.JSX.Element;
+declare function CardHeader({ children, style }: CardHeaderProps): React.JSX.Element;
+declare function CardTitle({ children, style }: CardTitleProps): React.JSX.Element;
+declare function CardDescription({ children, style }: CardDescriptionProps): React.JSX.Element;
+declare function CardContent({ children, style }: CardContentProps): React.JSX.Element;
+declare function CardFooter({ children, style }: CardFooterProps): React.JSX.Element;
+
+interface SeparatorProps {
+    orientation?: 'horizontal' | 'vertical';
+    style?: ViewStyle;
+}
+declare function Separator({ orientation, style }: SeparatorProps): React.JSX.Element;
+
+type SpinnerSize = 'sm' | 'md' | 'lg';
+interface SpinnerProps extends Omit<ActivityIndicatorProps, 'size'> {
+    size?: SpinnerSize;
+    color?: string;
+}
+declare function Spinner({ size, color, ...props }: SpinnerProps): React.JSX.Element;
+
+interface SkeletonProps {
+    width?: number | string;
+    height?: number;
+    borderRadius?: number;
+    style?: ViewStyle;
+}
+declare function Skeleton({ width, height, borderRadius, style }: SkeletonProps): React.JSX.Element;
+
+type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
+interface AvatarProps {
+    /** Remote image URI. Falls back to `fallback` initials on error or when omitted. */
+    src?: string;
+    /** Up to 2 characters shown when the image is unavailable. Auto-uppercased. Defaults to `'?'`. */
+    fallback?: string;
+    size?: AvatarSize;
+    style?: ViewStyle;
+}
+declare function Avatar({ src, fallback, size, style }: AvatarProps): React.JSX.Element;
+
+type AlertVariant = 'default' | 'destructive';
+interface AlertProps {
+    title?: string;
+    description?: string;
+    variant?: AlertVariant;
+    icon?: React.ReactNode;
+    style?: ViewStyle;
+}
+declare function Alert({ title, description, variant, icon, style }: AlertProps): React.JSX.Element;
+
+interface ProgressProps {
+    /** Current progress value. Clamped to `[0, max]`. Defaults to `0`. */
+    value?: number;
+    /** Maximum value. Defaults to `100`. */
+    max?: number;
+    style?: ViewStyle;
+}
+declare function Progress({ value, max, style }: ProgressProps): React.JSX.Element;
+
+interface EmptyStateProps {
+    icon?: React.ReactNode;
+    title: string;
+    description?: string;
+    action?: React.ReactNode;
+    style?: ViewStyle;
+}
+declare function EmptyState({ icon, title, description, action, style }: EmptyStateProps): React.JSX.Element;
+
+interface TextareaProps extends TextInputProps {
+    label?: string;
+    /** Red helper text below the textarea; also changes border to `destructive` color. Takes priority over `hint`. */
     error?: string;
+    /** Helper text shown below the textarea when there is no error. */
     hint?: string;
+    /** Number of visible text rows. Defaults to `4`. Controls `numberOfLines` and `minHeight`. */
+    rows?: number;
+    /** Style for the outer container `View`. Use `style` (from `TextInputProps`) to style the `TextInput` itself. */
+    containerStyle?: ViewStyle;
+}
+declare function Textarea({ label, error, hint, rows, containerStyle, style, onFocus, onBlur, ...props }: TextareaProps): React.JSX.Element;
+
+interface CheckboxProps {
+    checked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    label?: string;
+    disabled?: boolean;
+    style?: ViewStyle;
+}
+declare function Checkbox({ checked, onCheckedChange, label, disabled, style, }: CheckboxProps): React.JSX.Element;
+
+interface SwitchProps {
+    checked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    style?: ViewStyle;
+}
+declare function Switch({ checked, onCheckedChange, disabled, style }: SwitchProps): React.JSX.Element;
+
+type ToggleVariant = 'default' | 'outline';
+type ToggleSize = 'sm' | 'md' | 'lg';
+interface ToggleProps extends TouchableOpacityProps {
+    pressed?: boolean;
+    onPressedChange?: (pressed: boolean) => void;
+    variant?: ToggleVariant;
+    size?: ToggleSize;
+    label?: string;
+    icon?: React.ReactNode;
+}
+declare function Toggle({ pressed, onPressedChange, variant, size, label, icon, disabled, style, ...props }: ToggleProps): React.JSX.Element;
+
+interface RadioOption {
+    label: string;
+    value: string;
+    disabled?: boolean;
+}
+interface RadioGroupProps {
+    options: RadioOption[];
+    value?: string;
+    onValueChange?: (value: string) => void;
+    orientation?: 'vertical' | 'horizontal';
+    style?: ViewStyle;
+}
+declare function RadioGroup({ options, value, onValueChange, orientation, style, }: RadioGroupProps): React.JSX.Element;
+
+interface TabItem {
+    label: string;
+    value: string;
+}
+interface TabsProps {
+    tabs: TabItem[];
+    /**
+     * Controlled active tab value. When omitted the component manages state internally
+     * (uncontrolled), defaulting to the first tab.
+     */
+    value?: string;
+    onValueChange?: (value: string) => void;
+    children?: React.ReactNode;
+    style?: ViewStyle;
+}
+interface TabsContentProps {
+    value: string;
+    activeValue: string;
+    children: React.ReactNode;
+    style?: ViewStyle;
+}
+declare function Tabs({ tabs, value, onValueChange, children, style }: TabsProps): React.JSX.Element;
+declare function TabsContent({ value, activeValue, children, style }: TabsContentProps): React.JSX.Element | null;
+
+interface AccordionItem {
+    value: string;
+    trigger: string;
+    content: React.ReactNode;
+}
+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;
+
+interface SliderProps {
+    /** Current value. Controlled when provided; falls back to internal state otherwise. */
+    value?: number;
+    minimumValue?: number;
+    maximumValue?: number;
+    /** Snap interval. `0` (default) means continuous (no snapping). */
+    step?: number;
+    /** Called on every move while dragging. */
+    onValueChange?: (value: number) => void;
+    /** Called once when the user releases the thumb. */
+    onSlidingComplete?: (value: number) => void;
+    disabled?: boolean;
+    style?: ViewStyle;
+}
+declare function Slider({ value, minimumValue, maximumValue, step, onValueChange, onSlidingComplete, disabled, style, }: SliderProps): React.JSX.Element;
+
+interface SheetProps {
+    open: boolean;
+    onClose: () => void;
+    title?: string;
+    description?: string;
+    children?: React.ReactNode;
+    /**
+     * Heights the sheet can snap to. Accepts percentage strings (`'50%'`) or
+     * absolute point values (`300`). Defaults to `['50%']`.
+     */
+    snapPoints?: (string | number)[];
+    /** Style for the inner `BottomSheetView` content container. */
+    style?: ViewStyle;
+}
+declare function Sheet({ open, onClose, title, description, children, snapPoints, style, }: SheetProps): React.JSX.Element;
+
+interface SelectOption {
+    label: string;
+    value: string;
+    disabled?: boolean;
+}
+interface SelectProps {
+    options: SelectOption[];
+    value?: string;
+    onValueChange?: (value: string) => void;
+    /** Text shown when no option is selected. Defaults to `'Select an option'`. */
+    placeholder?: string;
+    label?: string;
+    /** Red helper text; also changes trigger border to `destructive` color. */
+    error?: string;
+    disabled?: boolean;
+    style?: ViewStyle;
+}
+declare function Select({ options, value, onValueChange, placeholder, label, error, disabled, style, }: SelectProps): React.JSX.Element;
+
+type ToastVariant = 'default' | 'destructive' | 'success';
+interface ToastItem {
+    id: string;
+    title?: string;
+    description?: string;
+    variant?: ToastVariant;
+    /** Auto-dismiss delay in milliseconds. Defaults to `3000`. */
+    duration?: number;
+}
+interface ToastContextValue {
+    toast: (item: Omit<ToastItem, 'id'>) => void;
+    dismiss: (id: string) => void;
+}
+declare function useToast(): ToastContextValue;
+/**
+ * Must wrap the app root alongside ThemeProvider.
+ * Renders toasts in an absolute overlay at the top of the screen.
+ * Use `useToast()` anywhere inside to trigger toasts.
+ */
+interface ToastProviderProps {
+    children: React.ReactNode;
 }
-declare function Input({ label, error, hint, style, onFocus, onBlur, ...props }: InputProps): React.JSX.Element;
+declare function ToastProvider({ children }: ToastProviderProps): React.JSX.Element;
 
-export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, Input, type InputProps, Text, type TextProps, type TextVariant };
+export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, type AlertVariant, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, Checkbox, type CheckboxProps, type ColorScheme, EmptyState, type EmptyStateProps, Input, type InputProps, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, type TabItem, Tabs, TabsContent, type TabsContentProps, type TabsProps, Text, type TextProps, type TextVariant, Textarea, type TextareaProps, type Theme, type ThemeColors, ThemeProvider, type ThemeProviderProps, type ToastItem, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, defaultDark, defaultLight, useTheme, useToast };