@retray-dev/ui-kit 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# @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,75 @@
 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;
+};
+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;
 }
-declare function Button({ label, variant, size, loading, fullWidth, disabled, style, ...props }: ButtonProps): React.JSX.Element;
+declare function Button({ label, variant, size, loading, fullWidth, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'body' | 'caption' | 'label';
 interface TextProps extends TextProps$1 {
@@ -26,4 +85,251 @@ interface InputProps extends TextInputProps {
 }
 declare function Input({ label, error, hint, style, onFocus, onBlur, ...props }: InputProps): React.JSX.Element;
 
-export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, Input, type InputProps, Text, type TextProps, type TextVariant };
+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 {
+    src?: string;
+    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 {
+    value?: number;
+    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;
+    error?: string;
+    hint?: string;
+    rows?: number;
+}
+declare function Textarea({ label, error, hint, rows, 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[];
+    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 {
+    value?: number;
+    minimumValue?: number;
+    maximumValue?: number;
+    step?: number;
+    onValueChange?: (value: number) => void;
+    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;
+    snapPoints?: (string | number)[];
+    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;
+    placeholder?: string;
+    label?: string;
+    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;
+    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 ToastProvider({ children }: ToastProviderProps): React.JSX.Element;
+
+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 };