@retray-dev/ui-kit 2.8.0 → 3.1.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v2.8.0)
+# @retray-dev/ui-kit — Component Reference (v3.1.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:
 
@@ -42,6 +42,54 @@ export default function App() {
 - `BottomSheetModalProvider` must be inside `GestureHandlerRootView`
 - `ToastProvider` must be inside `SafeAreaProvider`
 
+## Typography — Poppins (Required)
+
+All components use **Poppins** as the font family. You **must** load it before rendering any UI kit component, otherwise text will fall back to the system font.
+
+```tsx
+import { useFonts } from 'expo-font'
+import { PoppinsFonts } from '@retray-dev/ui-kit/fonts'
+
+export default function App() {
+  const [fontsLoaded] = useFonts(PoppinsFonts)
+  if (!fontsLoaded) return null   // or show a splash screen
+
+  return (
+    // ... your providers and app
+  )
+}
+```
+
+**How it works:**
+1. Import `PoppinsFonts` from `@retray-dev/ui-kit/fonts` (separate export path)
+2. Pass it to `expo-font`'s `useFonts()` hook at your app root
+3. Metro resolves font files from `node_modules/@retray-dev/ui-kit/src/assets/fonts/` at bundle time
+4. All library components reference fonts by family name (e.g., `fontFamily: 'Poppins-SemiBold'`)
+
+**Why this pattern:**
+- Fonts are NOT bundled into `dist/` — they ship as raw `.ttf` files inside `src/assets/fonts/`
+- Metro resolves `require()` calls to these files when it bundles your app
+- This prevents font corruption that can occur when `.ttf` files pass through bundlers like esbuild/tsup
+
+**Setup:**
+- Add `expo-font` to your app: `pnpm add expo-font`
+- The `if (!fontsLoaded) return null` guard prevents text from rendering before fonts are ready
+- Pair with `expo-splash-screen` in production to avoid a flash:
+  ```tsx
+  import * as SplashScreen from 'expo-splash-screen'
+  SplashScreen.preventAutoHideAsync()
+  
+  useEffect(() => {
+    if (fontsLoaded) SplashScreen.hideAsync()
+  }, [fontsLoaded])
+  ```
+
+**Included weights:**
+- Regular: `Poppins-Thin`, `Poppins-ExtraLight`, `Poppins-Light`, `Poppins-Regular`, `Poppins-Medium`, `Poppins-SemiBold`, `Poppins-Bold`, `Poppins-ExtraBold`, `Poppins-Black`
+- Italic: `Poppins-Italic`, `Poppins-MediumItalic`, `Poppins-SemiBoldItalic`, `Poppins-BoldItalic`
+
+**Total: 13 font files** exported from the package. Additional italic variants exist in `src/assets/fonts/` but are not exported — if you need them, open an issue.
+
 ### ThemeProvider Props
 
 | Prop | Type | Default | Notes |
@@ -74,7 +122,7 @@ function MyComponent() {
 
 ## Theme Tokens
 
-All 20 tokens are available via `useTheme().colors` and are applied exactly as provided — there is no automatic color derivation or forced contrast applied by the library. Consumers may pass partial overrides for `light` and/or `dark` and the values are used as-is.
+All 23 tokens are available via `useTheme().colors` and are applied exactly as provided — there is no automatic color derivation or forced contrast applied by the library. Consumers may pass partial overrides for `light` and/or `dark` and the values are used as-is.
 
 The `ThemeColors` type (and `Theme`, `ColorScheme`) are exported directly from the package:
 ```ts
@@ -83,25 +131,29 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 
 | Token | Light | Dark | Semantic Role |
 |-------|-------|------|---------------|
-| `background` | `#ffffff` | `#171717` | Screen / page background |
+| `background` | `#ffffff` | `#0f0f0f` | Screen / page background |
 | `foreground` | `#171717` | `#fafafa` | Primary text color |
-| `card` | `#ffffff` | `#222222` | Card / surface background |
+| `card` | `#ffffff` | `#1c1c1c` | Card / surface background |
 | `cardForeground` | `#171717` | `#fafafa` | Text on cards |
 | `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states) |
-| `primaryForeground` | `#ffffff` | `#1a1a1a` | Text/icon on primary background |
-| `secondary` | `#f1f1f1` | `#323232` | Secondary surfaces |
+| `primaryForeground` | `#ffffff` | `#0f0f0f` | Text/icon on primary background |
+| `secondary` | `#f1f1f1` | `#272727` | Secondary surfaces |
 | `secondaryForeground` | `#171717` | `#fafafa` | Text on secondary |
-| `muted` | `#f1f1f1` | `#323232` | Muted backgrounds, skeleton fills, track fills |
-| `mutedForeground` | `#a2a2a2` | `#888888` | Placeholder text, helper text, captions |
-| `accent` | `#e4e4e4` | `#323232` | Hover / pressed state fills |
+| `muted` | `#f1f1f1` | `#272727` | Muted backgrounds, skeleton fills, track fills |
+| `mutedForeground` | `#a2a2a2` | `#9a9a9a` | Placeholder text, helper text, captions |
+| `accent` | `#e4e4e4` | `#2e2e2e` | Hover / pressed state fills |
 | `accentForeground` | `#171717` | `#fafafa` | Text on accent |
-| `destructive` | `#ef4444` | `#dc2626` | Error / danger / delete actions |
-| `destructiveForeground` | `#1a1a1a` | `#1a1a1a` | Text on destructive |
-| `border` | `#e5e5e5` | `#2a2a2a` | Borders and dividers |
+| `destructive` | `#ef4444` | `#dc2626` | Error / danger / delete actions — base color |
+| `destructiveForeground` | `#ffffff` | `#ffffff` | Text on destructive |
+| `destructiveTint` | `#fff5f5` | `#3b0a0a` | Very light/dark background tint for destructive states |
+| `destructiveBorder` | `#fecaca` | `#7f1d1d` | Border color for destructive outlined elements |
+| `success` | `#1a7a45` | `#166534` | Success / confirmation / done actions — base color |
+| `successForeground` | `#ffffff` | `#ffffff` | Text on success |
+| `successTint` | `#f0fdf4` | `#052e16` | Very light/dark background tint for success states |
+| `successBorder` | `#bbf7d0` | `#166534` | Border color for success outlined elements |
+| `border` | `#e5e5e5` | `#303030` | Borders and dividers |
 | `input` | `#e5e5e5` | `#2a2a2a` | Input field border color |
 | `ring` | `#1a1a1a` | `#fafafa` | Optional focus ring token (components may use `primary` by default) |
-| `success` | `#16a34a` | `#22c55e` | Success state (Toast success variant) |
-| `successForeground` | `#1a1a1a` | `#1a1a1a` | Text on success background |
 
 ---
 
@@ -485,11 +537,13 @@ const [amount, setAmount] = useState(0)
 |------|------|---------|-------|
 | size | `'sm' \| 'md' \| 'lg'` | `'md'` | `sm`/`md` map to RN `'small'`, `lg` maps to `'large'` |
 | color | `string` | `primary` token | Override spinner color |
+| label | `string` | — | Text displayed below the spinner |
 
 **Example:**
 ```tsx
 <Spinner />
 <Spinner size="lg" color="#6366f1" />
+<Spinner size="lg" label="Loading..." />
 ```
 
 ---
@@ -659,8 +713,8 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| title | `string` | — | Bold heading |
-| description | `string` | — | Detail text |
+| title | `string` | required | Bold heading |
+| description | `string` | — | Optional detail text below the title |
 | variant | `'default' \| 'destructive' \| 'success'` | `'default'` | Controls border/text color |
 | icon | `ReactNode` | — | Icon placed to the left of the text content. Defaults to a variant-appropriate symbol (`ℹ`, `⚠`, `✓`) |
 | iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` (but still falls back to the variant default when neither is set) |
@@ -888,7 +942,7 @@ const [accepted, setAccepted] = useState(false)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| tabs | `TabItem[]` | required | Each item: `{ label: string, value: string }` |
+| tabs | `TabItem[]` | required | Each item: `{ label: string, value: string, icon?: ReactNode \| ((active: boolean) => ReactNode) }` |
 | value | `string` | — | Controlled active tab |
 | onValueChange | `(value: string) => void` | — | — |
 | children | `ReactNode` | — | `TabsContent` components |
@@ -1153,6 +1207,8 @@ function MyComponent() {
 | label | `string` | required | — |
 | selected | `boolean` | `false` | Controls fill color |
 | onPress | `() => void` | — | — |
+| icon | `ReactNode` | — | Custom icon rendered before the label |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
 | style | `ViewStyle` | — | — |
 
 **`ChipGroup` Props:**

package/README.md

@@ -3,7 +3,7 @@
 A personal React Native / Expo UI component library with a built-in design system, dark mode support, haptic feedback, and smooth animations.
 
 - 33 components across 6 categories
-- Light/dark theme with 20 color tokens and full customization
+- Light/dark theme with 23 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
@@ -23,7 +23,7 @@ pnpm add @retray-dev/ui-kit
 Install these in your app if not already present:
 
 ```bash
-pnpm add expo-haptics expo-linear-gradient react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons
+pnpm add expo-font expo-haptics expo-linear-gradient react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons
 ```
 
 For Expo projects, run `npx expo install` instead to get SDK-compatible versions.
@@ -40,6 +40,26 @@ module.exports = function (api) {
 }
 ```
 
+## Typography
+
+All components use **Poppins** font family. You must load the fonts at app root before rendering any component:
+
+```tsx
+import { useFonts } from 'expo-font'
+import { PoppinsFonts } from '@retray-dev/ui-kit/fonts'
+
+export default function App() {
+  const [fontsLoaded] = useFonts(PoppinsFonts)
+  if (!fontsLoaded) return null
+
+  return (
+    // ... providers and app
+  )
+}
+```
+
+The library ships 13 font files (9 regular weights + 4 italic variants) as raw `.ttf` files. Metro resolves them at bundle time.
+
 ## Setup
 
 Wrap your app root with all required providers. Order matters.
@@ -93,7 +113,7 @@ 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`
+**Available tokens:** `background`, `foreground`, `card`, `cardForeground`, `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `muted`, `mutedForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, `destructiveTint`, `destructiveBorder`, `border`, `input`, `ring`, `success`, `successForeground`, `successTint`, `successBorder`
 
 ## Design Tokens
 

package/dist/index.d.mts

@@ -22,6 +22,10 @@ type ThemeColors = {
     ring: string;
     success: string;
     successForeground: string;
+    destructiveTint: string;
+    destructiveBorder: string;
+    successTint: string;
+    successBorder: string;
 };
 type Theme = {
     light?: Partial<ThemeColors>;
@@ -146,10 +150,12 @@ interface InputProps extends TextInputProps {
     type?: 'text' | 'password';
     /** Style for the outer container \`View\`. Use \`style\` (from \`TextInputProps\`) to style the \`TextInput\` itself. */
     containerStyle?: ViewStyle;
+    /** Style for the inner border wrapper (overrides padding, etc). */
+    inputWrapperStyle?: ViewStyle;
 }
-declare function Input({ label, error, hint, prefix, suffix, prefixStyle, suffixStyle, prefixIcon, suffixIcon, prefixIconColor, suffixIconColor, type, containerStyle, style, onFocus, onBlur, secureTextEntry, ...props }: InputProps): React.JSX.Element;
+declare function Input({ label, error, hint, prefix, suffix, prefixStyle, suffixStyle, prefixIcon, suffixIcon, prefixIconColor, suffixIconColor, type, containerStyle, inputWrapperStyle, style, onFocus, onBlur, secureTextEntry, ...props }: InputProps): React.JSX.Element;
 
-type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
+type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline' | 'success' | 'warning' | 'successOutline' | 'destructiveOutline';
 type BadgeSize = 'sm' | 'md' | 'lg';
 interface BadgeProps {
     label?: string;
@@ -216,8 +222,9 @@ type SpinnerSize = 'sm' | 'md' | 'lg';
 interface SpinnerProps extends Omit<ActivityIndicatorProps, 'size'> {
     size?: SpinnerSize;
     color?: string;
+    label?: string;
 }
-declare function Spinner({ size, color, ...props }: SpinnerProps): React.JSX.Element;
+declare function Spinner({ size, color, label, ...props }: SpinnerProps): React.JSX.Element;
 
 interface SkeletonProps {
     width?: number | string;
@@ -240,7 +247,7 @@ declare function Avatar({ src, fallback, size, style }: AvatarProps): React.JSX.
 
 type AlertBannerVariant = 'default' | 'destructive' | 'success';
 interface AlertBannerProps {
-    title?: string;
+    title: string;
     description?: string;
     variant?: AlertBannerVariant;
     icon?: React.ReactNode;
@@ -358,7 +365,7 @@ declare function RadioGroup({ options, value, onValueChange, orientation, style,
 interface TabItem {
     label: string;
     value: string;
-    icon?: React.ReactNode;
+    icon?: React.ReactNode | ((active: boolean) => React.ReactNode);
 }
 interface TabsProps {
     tabs: TabItem[];
@@ -574,6 +581,10 @@ interface ChipProps {
     label: string;
     selected?: boolean;
     onPress?: () => void;
+    /** JSX icon rendered before the label. */
+    icon?: React.ReactNode;
+    /** Icon name from @expo/vector-icons resolved automatically. */
+    iconName?: string;
     style?: ViewStyle;
 }
 interface ChipOption {
@@ -588,7 +599,7 @@ interface ChipGroupProps {
     multiSelect?: boolean;
     style?: ViewStyle;
 }
-declare function Chip({ label, selected, onPress, style }: ChipProps): React.JSX.Element;
+declare function Chip({ label, selected, onPress, icon, iconName, style }: ChipProps): React.JSX.Element;
 declare function ChipGroup({ options, value, onValueChange, multiSelect, style }: ChipGroupProps): React.JSX.Element;
 
 interface ConfirmDialogProps {

package/dist/index.d.ts

@@ -22,6 +22,10 @@ type ThemeColors = {
     ring: string;
     success: string;
     successForeground: string;
+    destructiveTint: string;
+    destructiveBorder: string;
+    successTint: string;
+    successBorder: string;
 };
 type Theme = {
     light?: Partial<ThemeColors>;
@@ -146,10 +150,12 @@ interface InputProps extends TextInputProps {
     type?: 'text' | 'password';
     /** Style for the outer container \`View\`. Use \`style\` (from \`TextInputProps\`) to style the \`TextInput\` itself. */
     containerStyle?: ViewStyle;
+    /** Style for the inner border wrapper (overrides padding, etc). */
+    inputWrapperStyle?: ViewStyle;
 }
-declare function Input({ label, error, hint, prefix, suffix, prefixStyle, suffixStyle, prefixIcon, suffixIcon, prefixIconColor, suffixIconColor, type, containerStyle, style, onFocus, onBlur, secureTextEntry, ...props }: InputProps): React.JSX.Element;
+declare function Input({ label, error, hint, prefix, suffix, prefixStyle, suffixStyle, prefixIcon, suffixIcon, prefixIconColor, suffixIconColor, type, containerStyle, inputWrapperStyle, style, onFocus, onBlur, secureTextEntry, ...props }: InputProps): React.JSX.Element;
 
-type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
+type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline' | 'success' | 'warning' | 'successOutline' | 'destructiveOutline';
 type BadgeSize = 'sm' | 'md' | 'lg';
 interface BadgeProps {
     label?: string;
@@ -216,8 +222,9 @@ type SpinnerSize = 'sm' | 'md' | 'lg';
 interface SpinnerProps extends Omit<ActivityIndicatorProps, 'size'> {
     size?: SpinnerSize;
     color?: string;
+    label?: string;
 }
-declare function Spinner({ size, color, ...props }: SpinnerProps): React.JSX.Element;
+declare function Spinner({ size, color, label, ...props }: SpinnerProps): React.JSX.Element;
 
 interface SkeletonProps {
     width?: number | string;
@@ -240,7 +247,7 @@ declare function Avatar({ src, fallback, size, style }: AvatarProps): React.JSX.
 
 type AlertBannerVariant = 'default' | 'destructive' | 'success';
 interface AlertBannerProps {
-    title?: string;
+    title: string;
     description?: string;
     variant?: AlertBannerVariant;
     icon?: React.ReactNode;
@@ -358,7 +365,7 @@ declare function RadioGroup({ options, value, onValueChange, orientation, style,
 interface TabItem {
     label: string;
     value: string;
-    icon?: React.ReactNode;
+    icon?: React.ReactNode | ((active: boolean) => React.ReactNode);
 }
 interface TabsProps {
     tabs: TabItem[];
@@ -574,6 +581,10 @@ interface ChipProps {
     label: string;
     selected?: boolean;
     onPress?: () => void;
+    /** JSX icon rendered before the label. */
+    icon?: React.ReactNode;
+    /** Icon name from @expo/vector-icons resolved automatically. */
+    iconName?: string;
     style?: ViewStyle;
 }
 interface ChipOption {
@@ -588,7 +599,7 @@ interface ChipGroupProps {
     multiSelect?: boolean;
     style?: ViewStyle;
 }
-declare function Chip({ label, selected, onPress, style }: ChipProps): React.JSX.Element;
+declare function Chip({ label, selected, onPress, icon, iconName, style }: ChipProps): React.JSX.Element;
 declare function ChipGroup({ options, value, onValueChange, multiSelect, style }: ChipGroupProps): React.JSX.Element;
 
 interface ConfirmDialogProps {