@retray-dev/ui-kit 2.6.0 → 2.8.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v2.6.0)
+# @retray-dev/ui-kit — Component Reference (v2.8.0)
 
 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:
 
@@ -105,6 +105,99 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 
 ---
 
+## Design Tokens
+
+Static structural constants exported from the package root — no context or provider needed. Use these instead of hardcoding values.
+
+```ts
+import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS } from '@retray-dev/ui-kit'
+```
+
+### SPACING
+
+8pt-grid spacing scale.
+
+| Key | Value |
+|-----|-------|
+| `xs` | 4 |
+| `sm` | 8 |
+| `md` | 12 |
+| `lg` | 16 |
+| `xl` | 24 |
+| `2xl` | 32 |
+| `3xl` | 48 |
+
+**Types:** `Spacing`, `SpacingKey`
+
+```tsx
+<View style={{ gap: SPACING.md, padding: SPACING.lg }} />
+```
+
+### ICON_SIZES
+
+Semantic icon size scale aligned to HIG roles.
+
+| Key | Value |
+|-----|-------|
+| `sm` | 14 |
+| `md` | 18 |
+| `lg` | 22 |
+| `xl` | 28 |
+| `2xl` | 32 |
+
+**Types:** `IconSize`, `IconSizeKey`
+
+```tsx
+<Icon name="home" size={ICON_SIZES.md} color={colors.foreground} />
+```
+
+### RADIUS
+
+Border radius scale used throughout the library.
+
+| Key | Value | Used in |
+|-----|-------|---------|
+| `sm` | 4 | — |
+| `md` | 8 | Inputs, Buttons, Checkboxes, Toggles, Tabs |
+| `lg` | 12 | Cards, AlertBanner, Toast, EmptyState, Select list |
+| `xl` | 16 | Sheet top corners |
+| `full` | 9999 | Pills, circular elements |
+
+**Types:** `Radius`, `RadiusKey`
+
+```tsx
+<View style={{ borderRadius: RADIUS.lg }} />
+```
+
+### SHADOWS
+
+Cross-platform shadow presets (RN `shadow*` properties + `elevation`).
+
+| Key | Height | Opacity | Radius | Elevation |
+|-----|--------|---------|--------|-----------|
+| `sm` | 1 | 0.08 | 4 | 2 |
+| `md` | 3 | 0.12 | 8 | 5 |
+| `lg` | 6 | 0.20 | 16 | 10 |
+| `xl` | 12 | 0.28 | 24 | 18 |
+
+```tsx
+<View style={[styles.card, SHADOWS.md]} />
+```
+
+### BREAKPOINTS
+
+Layout breakpoints.
+
+| Key | Value |
+|-----|-------|
+| `wide` | 700 |
+
+```tsx
+const isWide = width >= BREAKPOINTS.wide
+```
+
+---
+
 ## Components
 
 ---
@@ -178,6 +271,36 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 
 ---
 
+### IconButton
+
+**Import:** `import { IconButton } from '@retray-dev/ui-kit'`
+**When to use:** Compact icon-only pressable action — toolbars, FABs, inline icon actions. Use `Button` when a label is needed.
+**Extends:** `TouchableOpacityProps` — all RN TouchableOpacity props pass through.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| iconName | `string` | — | Icon name from `@expo/vector-icons` (e.g. `"plus"`, `"x"`, `"home"`). Takes precedence over `icon` |
+| icon | `React.ReactNode` | — | Custom icon node — used when `iconName` is not provided |
+| iconColor | `string` | — | Override icon color. Defaults to variant foreground color |
+| variant | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive'` | `'primary'` | Visual style — same tokens as `Button` |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | sm=40pt / md=44pt / lg=52pt (all ≥44pt on md/lg per HIG) |
+| loading | `boolean` | `false` | Replaces icon with a spinner and forces disabled state |
+| disabled | `boolean` | — | Reduces opacity to 0.5 |
+
+**Variants:** Same color logic as `Button` — `primary`, `secondary`, `outline`, `ghost`, `destructive`.
+
+**Animations:** Scale springs to 0.95 on `onPressIn`, back to 1.0 on `onPressOut`. `impactAsync(Light)` haptic on press.
+
+**Example:**
+```tsx
+<IconButton iconName="plus" onPress={handleAdd} />
+<IconButton iconName="x" variant="ghost" size="sm" onPress={handleClose} />
+<IconButton iconName="trash-2" variant="destructive" onPress={handleDelete} />
+<IconButton iconName="check" variant="outline" size="lg" loading={saving} />
+```
+
+---
+
 ### Input
 
 **Import:** `import { Input } from '@retray-dev/ui-kit'`
@@ -1214,6 +1337,7 @@ Each component that accepts icon slots now has a corresponding `iconName` prop.
 | Component | Prop(s) | Slot | Default size | Default color |
 |---|---|---|---|---|
 | `Button` | `iconName`, `iconColor` | Left or right of label | sm=16 / md=18 / lg=20 | Variant label color |
+| `IconButton` | `iconName`, `iconColor` | Center (icon-only) | sm=18 / md=20 / lg=24 | Variant foreground color |
 | `Input` | `prefixIcon`, `prefixIconColor` | Before input text | 20 | `mutedForeground` |
 | `Input` | `suffixIcon`, `suffixIconColor` | After input text | 20 | `mutedForeground` |
 | `ListItem` | `leftIcon`, `leftIconColor` | Left 44×44 slot | 24 | `foreground` |

package/README.md

@@ -2,7 +2,7 @@
 
 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
+- 33 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
@@ -95,13 +95,31 @@ 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`
 
+## Design Tokens
+
+Static structural constants — no provider required:
+
+```ts
+import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS } from '@retray-dev/ui-kit'
+
+<View style={{ gap: SPACING.md, padding: SPACING.lg, borderRadius: RADIUS.lg, ...SHADOWS.sm }} />
+```
+
+| Token | Keys |
+|-------|------|
+| `SPACING` | `xs` (4), `sm` (8), `md` (12), `lg` (16), `xl` (24), `2xl` (32), `3xl` (48) |
+| `ICON_SIZES` | `sm` (14), `md` (18), `lg` (22), `xl` (28), `2xl` (32) |
+| `RADIUS` | `sm` (4), `md` (8), `lg` (12), `xl` (16), `full` (9999) |
+| `SHADOWS` | `sm`, `md`, `lg`, `xl` — cross-platform shadow presets |
+| `BREAKPOINTS` | `wide` (700) |
+
 ## Components
 
 | Category    | Components                                                                                      |
 | ----------- | ----------------------------------------------------------------------------------------------- |
 | Display     | `Text`, `Badge`, `Avatar`, `Separator`, `Spinner`, `Skeleton`, `Progress`, `CurrencyDisplay`   |
 | Surfaces    | `Card`, `AlertBanner`, `EmptyState`                                                             |
-| Form        | `Button`, `Input`, `CurrencyInput`, `CurrencyInputLarge`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
+| Form        | `Button`, `IconButton`, `Input`, `CurrencyInput`, `CurrencyInputLarge`, `Textarea`, `Checkbox`, `Switch`, `Toggle`, `RadioGroup`, `Select`, `Slider` |
 | Composition | `Tabs`, `Accordion`                                                                             |
 | Overlays    | `Sheet`, `ConfirmDialog`                                                                        |
 | Feedback    | `Toast` / `ToastProvider` / `useToast`                                                          |

package/dist/index.d.mts

@@ -88,6 +88,25 @@ interface ButtonProps extends TouchableOpacityProps {
 }
 declare function Button({ label, variant, size, loading, fullWidth, icon, iconName, iconColor, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
+type IconButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive';
+type IconButtonSize = 'sm' | 'md' | 'lg';
+interface IconButtonProps extends TouchableOpacityProps {
+    /**
+     * Icon name from `@expo/vector-icons` (e.g. `"home"`, `"star"`, `"plus"`).
+     * See https://icons.expo.fyi. Takes precedence over `icon` when both supplied.
+     */
+    iconName?: string;
+    /** ReactNode icon — used when `iconName` is not provided. */
+    icon?: React.ReactNode;
+    /** Override the resolved icon color. Defaults to the foreground color for the active variant. */
+    iconColor?: string;
+    variant?: IconButtonVariant;
+    size?: IconButtonSize;
+    /** Replaces icon with a spinner and forces `disabled`. */
+    loading?: boolean;
+}
+declare function IconButton({ iconName, icon, iconColor, variant, size, loading, disabled, style, onPress, ...props }: IconButtonProps): React.JSX.Element;
+
 type TextVariant = 'h1' | 'h2' | 'h3' | 'body' | 'caption' | 'label';
 interface TextProps extends TextProps$1 {
     variant?: TextVariant;
@@ -615,4 +634,79 @@ interface IconProps {
 declare function Icon({ name, size, color, family }: IconProps): React.ReactElement | null;
 declare function renderIcon(name: string, size: number, color: string): React.ReactElement | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, 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, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, Icon, type IconFamily, type IconProps, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, 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, renderIcon, useTheme, useToast };
+declare const SPACING: {
+    readonly xs: 4;
+    readonly sm: 8;
+    readonly md: 12;
+    readonly lg: 16;
+    readonly xl: 24;
+    readonly '2xl': 32;
+    readonly '3xl': 48;
+};
+declare const ICON_SIZES: {
+    readonly sm: 14;
+    readonly md: 18;
+    readonly lg: 22;
+    readonly xl: 28;
+    readonly '2xl': 32;
+};
+declare const RADIUS: {
+    readonly sm: 4;
+    readonly md: 8;
+    readonly lg: 12;
+    readonly xl: 16;
+    readonly full: 9999;
+};
+declare const SHADOWS: {
+    readonly sm: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 1;
+        };
+        readonly shadowOpacity: 0.08;
+        readonly shadowRadius: 4;
+        readonly elevation: 2;
+    };
+    readonly md: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 3;
+        };
+        readonly shadowOpacity: 0.12;
+        readonly shadowRadius: 8;
+        readonly elevation: 5;
+    };
+    readonly lg: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 6;
+        };
+        readonly shadowOpacity: 0.2;
+        readonly shadowRadius: 16;
+        readonly elevation: 10;
+    };
+    readonly xl: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 12;
+        };
+        readonly shadowOpacity: 0.28;
+        readonly shadowRadius: 24;
+        readonly elevation: 18;
+    };
+};
+declare const BREAKPOINTS: {
+    readonly wide: 700;
+};
+type Spacing = typeof SPACING;
+type SpacingKey = keyof Spacing;
+type IconSize = typeof ICON_SIZES;
+type IconSizeKey = keyof IconSize;
+type Radius = typeof RADIUS;
+type RadiusKey = keyof Radius;
+
+export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, BREAKPOINTS, 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, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, ICON_SIZES, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconFamily, type IconProps, type IconSize, type IconSizeKey, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Progress, type ProgressProps, RADIUS, RadioGroup, type RadioGroupProps, type RadioOption, type Radius, type RadiusKey, SHADOWS, SPACING, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, type Spacing, type SpacingKey, 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, renderIcon, useTheme, useToast };

package/dist/index.d.ts

@@ -88,6 +88,25 @@ interface ButtonProps extends TouchableOpacityProps {
 }
 declare function Button({ label, variant, size, loading, fullWidth, icon, iconName, iconColor, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
+type IconButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive';
+type IconButtonSize = 'sm' | 'md' | 'lg';
+interface IconButtonProps extends TouchableOpacityProps {
+    /**
+     * Icon name from `@expo/vector-icons` (e.g. `"home"`, `"star"`, `"plus"`).
+     * See https://icons.expo.fyi. Takes precedence over `icon` when both supplied.
+     */
+    iconName?: string;
+    /** ReactNode icon — used when `iconName` is not provided. */
+    icon?: React.ReactNode;
+    /** Override the resolved icon color. Defaults to the foreground color for the active variant. */
+    iconColor?: string;
+    variant?: IconButtonVariant;
+    size?: IconButtonSize;
+    /** Replaces icon with a spinner and forces `disabled`. */
+    loading?: boolean;
+}
+declare function IconButton({ iconName, icon, iconColor, variant, size, loading, disabled, style, onPress, ...props }: IconButtonProps): React.JSX.Element;
+
 type TextVariant = 'h1' | 'h2' | 'h3' | 'body' | 'caption' | 'label';
 interface TextProps extends TextProps$1 {
     variant?: TextVariant;
@@ -615,4 +634,79 @@ interface IconProps {
 declare function Icon({ name, size, color, family }: IconProps): React.ReactElement | null;
 declare function renderIcon(name: string, size: number, color: string): React.ReactElement | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, 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, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, Icon, type IconFamily, type IconProps, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, 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, renderIcon, useTheme, useToast };
+declare const SPACING: {
+    readonly xs: 4;
+    readonly sm: 8;
+    readonly md: 12;
+    readonly lg: 16;
+    readonly xl: 24;
+    readonly '2xl': 32;
+    readonly '3xl': 48;
+};
+declare const ICON_SIZES: {
+    readonly sm: 14;
+    readonly md: 18;
+    readonly lg: 22;
+    readonly xl: 28;
+    readonly '2xl': 32;
+};
+declare const RADIUS: {
+    readonly sm: 4;
+    readonly md: 8;
+    readonly lg: 12;
+    readonly xl: 16;
+    readonly full: 9999;
+};
+declare const SHADOWS: {
+    readonly sm: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 1;
+        };
+        readonly shadowOpacity: 0.08;
+        readonly shadowRadius: 4;
+        readonly elevation: 2;
+    };
+    readonly md: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 3;
+        };
+        readonly shadowOpacity: 0.12;
+        readonly shadowRadius: 8;
+        readonly elevation: 5;
+    };
+    readonly lg: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 6;
+        };
+        readonly shadowOpacity: 0.2;
+        readonly shadowRadius: 16;
+        readonly elevation: 10;
+    };
+    readonly xl: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 12;
+        };
+        readonly shadowOpacity: 0.28;
+        readonly shadowRadius: 24;
+        readonly elevation: 18;
+    };
+};
+declare const BREAKPOINTS: {
+    readonly wide: 700;
+};
+type Spacing = typeof SPACING;
+type SpacingKey = keyof Spacing;
+type IconSize = typeof ICON_SIZES;
+type IconSizeKey = keyof IconSize;
+type Radius = typeof RADIUS;
+type RadiusKey = keyof Radius;
+
+export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, BREAKPOINTS, 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, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, ICON_SIZES, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconFamily, type IconProps, type IconSize, type IconSizeKey, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Progress, type ProgressProps, RADIUS, RadioGroup, type RadioGroupProps, type RadioOption, type Radius, type RadiusKey, SHADOWS, SPACING, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, type Spacing, type SpacingKey, 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, renderIcon, useTheme, useToast };