@praxiis/ui 0.0.1 → 0.0.3

package/src/README.md

@@ -0,0 +1,688 @@
+# Design System
+
+A complete, production-ready design system for React Native (Expo). Built on top of [Shopify Restyle](https://github.com/Shopify/restyle) with full TypeScript support, light/dark theming, i18n, and a comprehensive component library.
+
+---
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Theming](#theming)
+   - [Built-in Presets](#built-in-presets)
+   - [Customizing with buildPair](#customizing-with-buildpair)
+   - [Single-mode Override](#single-mode-override)
+   - [Building from Scratch](#building-from-scratch)
+3. [Components](#components)
+   - [Layout](#layout)
+   - [Typography](#typography)
+   - [Actions](#actions)
+   - [Content](#content)
+   - [Inputs](#inputs)
+   - [Feedback](#feedback)
+   - [Overlays](#overlays)
+   - [Composite Components](#composite-components)
+4. [i18n / Labels](#i18n--labels)
+5. [Tokens](#tokens)
+6. [Hooks](#hooks)
+7. [Utilities](#utilities)
+8. [TypeScript Reference](#typescript-reference)
+
+---
+
+## Quick Start
+
+Wrap your app with `DesignSystemProvider`. All components automatically pick up the active theme and color scheme.
+
+```tsx
+import { DesignSystemProvider } from "@design-system";
+
+export default function App() {
+  return (
+    <DesignSystemProvider>
+      <YourApp />
+    </DesignSystemProvider>
+  );
+}
+```
+
+### With language
+
+```tsx
+<DesignSystemProvider language="es">
+  <YourApp />
+</DesignSystemProvider>
+```
+
+### With a custom theme
+
+```tsx
+import { DesignSystemProvider, buildPair } from "@design-system";
+import { myTheme } from "./theme";
+
+<DesignSystemProvider
+  lightTheme={myTheme.light}
+  darkTheme={myTheme.dark}
+>
+  <YourApp />
+</DesignSystemProvider>
+```
+
+---
+
+## Theming
+
+The design system ships with default light and dark themes. You can keep them, extend them with a few color overrides, or replace them entirely.
+
+All theme building utilities are exported from `@design-system`.
+
+---
+
+### Built-in Presets
+
+Six ready-to-use theme pairs, all with light + dark modes:
+
+```tsx
+import { DesignSystemProvider, restylePresetThemes } from "@design-system";
+
+// Available: horizon | sage | sunset | ocean | lavender | rose
+const { light, dark } = restylePresetThemes.ocean;
+
+<DesignSystemProvider lightTheme={light} darkTheme={dark}>
+  <YourApp />
+</DesignSystemProvider>
+```
+
+---
+
+### Customizing with `buildPair`
+
+**The recommended path.** Supply accent color overrides for light and dark modes. Everything else (backgrounds, surfaces, typography colors, feedback colors) is inherited from the defaults.
+
+```tsx
+import {
+  buildPair,
+  DesignSystemProvider,
+  type DeepPartial,
+  type RestyleThemePair,
+  type ThemeColors,
+} from "@design-system";
+
+const myTheme: RestyleThemePair = buildPair(
+  // light mode overrides
+  {
+    accent: {
+      primary: "#1877F2",
+      primaryHover: "#166FE5",
+      primaryPressed: "#0E5FC2",
+      secondary: "#42A5F5",
+      secondaryHover: "#1877F2",
+      secondaryPressed: "#166FE5",
+    },
+    text: { link: "#1877F2" },
+    border: { focus: "#1877F2" },
+  } satisfies DeepPartial<ThemeColors>,
+  // dark mode overrides
+  {
+    accent: {
+      primary: "#2D88FF",
+      primaryHover: "#5BA3FF",
+      primaryPressed: "#1877F2",
+      secondary: "#1877F2",
+      secondaryHover: "#2D88FF",
+      secondaryPressed: "#166FE5",
+    },
+    text: { link: "#2D88FF" },
+    border: { focus: "#2D88FF" },
+  } satisfies DeepPartial<ThemeColors>,
+);
+```
+
+#### What you can override
+
+`buildPair` accepts `DeepPartial<ThemeColors>` — override any subset:
+
+```
+ThemeColors
+├── background    { primary, secondary, tertiary, inverse }
+├── surface       { primary, secondary, elevated, overlay }
+├── text          { primary, secondary, tertiary, disabled, inverse, link }
+├── border        { default, subtle, strong, focus }
+├── accent        { primary, primaryHover, primaryPressed,
+│                   secondary, secondaryHover, secondaryPressed }
+├── interactive   { default, hover, pressed, disabled }
+├── feedback      { success, successLight, successDark,
+│                   warning, warningLight, warningDark,
+│                   error, errorLight, errorDark,
+│                   info, infoLight, infoDark }
+└── special       { skeleton, divider, scrim }
+```
+
+---
+
+### Single-mode Override
+
+Use `buildRestyleThemeFromThemeColors` when you want full control over a single mode, merging overrides into your chosen base palette:
+
+```tsx
+import {
+  buildRestyleThemeFromThemeColors,
+  lightSemanticColors,
+  darkSemanticColors,
+} from "@design-system";
+
+const customLight = buildRestyleThemeFromThemeColors(lightSemanticColors, {
+  accent: { primary: "#E8836B", /* ... */ },
+  background: { primary: "#FFF9F5" },
+});
+
+const customDark = buildRestyleThemeFromThemeColors(darkSemanticColors, {
+  accent: { primary: "#FF9B85", /* ... */ },
+});
+```
+
+---
+
+### Building from Scratch
+
+Use `buildRestyleTheme` when you want to define **every color yourself** with nothing inherited from defaults. Pass a complete `SemanticColorsInput` object.
+
+```tsx
+import {
+  buildRestyleTheme,
+  lightSemanticColors,
+  type SemanticColorsInput,
+} from "@design-system";
+
+const myLight = buildRestyleTheme({
+  ...lightSemanticColors, // spread defaults, then override whole groups
+  background: {
+    primary: "#0D1117",
+    secondary: "#161B22",
+    tertiary: "#21262D",
+    inverse: "#F0F6FF",
+  },
+  accent: {
+    primary: "#58A6FF",
+    primaryHover: "#79BEFF",
+    primaryPressed: "#388BFD",
+    secondary: "#1F6FEB",
+    secondaryHover: "#388BFD",
+    secondaryPressed: "#0D4EA6",
+  },
+} satisfies SemanticColorsInput);
+```
+
+---
+
+## Components
+
+All components import from `@design-system`.
+
+---
+
+### Layout
+
+`Box` is the core layout primitive — a `View` with all Restyle spacing, color, and layout props.
+
+```tsx
+import { Box, AnimatedBox, ScrollView, FlatList, Pressable, Divider } from "@design-system";
+
+<Box
+  flex={1}
+  backgroundColor="backgroundPrimary"
+  padding="lg"
+  borderRadius="md"
+  flexDirection="row"
+  alignItems="center"
+  gap="sm"
+>
+  {children}
+</Box>
+
+<Divider orientation="horizontal" color="borderSubtle" />
+```
+
+**Spacing tokens:** `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl` · `4xl`
+
+**Border radius tokens:** `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `full`
+
+**Common color tokens:** `backgroundPrimary` · `backgroundSecondary` · `surfacePrimary` · `surfaceElevated` · `textPrimary` · `textSecondary` · `accentPrimary` · `borderSubtle`
+
+---
+
+### Typography
+
+```tsx
+import { Text } from "@design-system";
+
+<Text variant="headingLarge" color="textPrimary">Hello</Text>
+<Text variant="bodyMedium" color="textSecondary">Subtitle</Text>
+<Text variant="labelSmall" color="accentPrimary">BADGE</Text>
+```
+
+**Available variants:**
+
+| Scale | Variants |
+|---|---|
+| Display | `displayLarge` · `displayMedium` · `displaySmall` |
+| Heading | `headingLarge` · `headingMedium` · `headingSmall` |
+| Body | `bodyLarge` · `bodyMedium` · `bodySmall` |
+| Label | `labelLarge` · `labelMedium` · `labelSmall` |
+| Misc | `caption` · `captionSmall` · `overline` · `code` |
+
+---
+
+### Actions
+
+```tsx
+import { Button, IconButton } from "@design-system";
+
+<Button title="Save" onPress={handleSave} />
+<Button title="Delete" variant="destructive" size="sm" />
+<Button title="Loading" isLoading />
+<Button title="Ghost" variant="ghost" />
+
+<IconButton name="close" onPress={handleClose} accessibilityLabel="Close" />
+<IconButton name="settings" size="lg" color="textSecondary" />
+```
+
+**Button variants:** `primary` · `secondary` · `ghost` · `destructive`
+**Button sizes:** `sm` · `md` · `lg`
+
+---
+
+### Content
+
+```tsx
+import { Icon, Card, Avatar, Badge, Chip, getInitials } from "@design-system";
+
+// Icon — Material Icons
+<Icon name="home" size="lg" color="accentPrimary" />
+<Icon name="check" accessibilityLabel="Confirmed" />
+
+// Card
+<Card variant="elevated" padding="lg">
+  <Text variant="bodyMedium">Card content</Text>
+</Card>
+
+// Avatar
+<Avatar initials={getInitials("María García")} size="lg" />
+<Avatar imageUri="https://..." size="md" status="online" />
+
+// Badge
+<Badge label={42} variant="filled" color="error" />
+<Badge label="NEW" variant="outline" />
+
+// Chip
+<Chip label="React Native" variant="filled" onPress={handlePress} />
+```
+
+**Icon sizes:** `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl`
+
+---
+
+### Inputs
+
+```tsx
+import {
+  TextInput,
+  Checkbox,
+  RadioButton,
+  Switch,
+  SegmentedControl,
+  SelectSheet,
+} from "@design-system";
+
+<TextInput
+  label="Email"
+  placeholder="you@example.com"
+  value={email}
+  onChangeText={setEmail}
+  keyboardType="email-address"
+  leftIcon="mail"
+/>
+
+<Checkbox label="Accept terms" checked={accepted} onChange={setAccepted} />
+
+<RadioButton
+  label="Option A"
+  selected={selected === "a"}
+  onSelect={() => setSelected("a")}
+/>
+
+<Switch label="Notifications" value={enabled} onValueChange={setEnabled} />
+
+<SegmentedControl
+  options={[
+    { label: "Day", value: "day" },
+    { label: "Week", value: "week" },
+    { label: "Month", value: "month" },
+  ]}
+  selectedValue={period}
+  onChange={setPeriod}
+/>
+
+<SelectSheet
+  label="Country"
+  options={countries}
+  value={country}
+  onChange={setCountry}
+  placeholder="Select a country"
+/>
+```
+
+---
+
+### Feedback
+
+```tsx
+import { Spinner, ProgressBar, Skeleton, ToastProvider, useToast } from "@design-system";
+
+<Spinner size="md" color="accentPrimary" />
+
+<ProgressBar progress={0.65} variant="determinate" />
+
+<Skeleton width={200} height={16} borderRadius="sm" />
+<Skeleton variant="circle" size="lg" />
+
+// Wrap your app (or screen) with ToastProvider
+<ToastProvider position="bottom">
+  <YourScreen />
+</ToastProvider>
+
+// Trigger toasts from any child
+function MyComponent() {
+  const toast = useToast();
+  return (
+    <Button
+      title="Show toast"
+      onPress={() => toast.show({ message: "Saved!", variant: "success" })}
+    />
+  );
+}
+```
+
+---
+
+### Overlays
+
+```tsx
+import { Modal } from "@design-system";
+
+<Modal
+  visible={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Confirm Delete"
+>
+  <Text variant="bodyMedium">Are you sure?</Text>
+  <Button title="Delete" variant="destructive" onPress={handleDelete} />
+</Modal>
+```
+
+---
+
+### Composite Components
+
+```tsx
+import { Header, EmptyState, CalendarStrip, ScheduleItem } from "@design-system";
+
+// Header — back button only shows when onBackPress is provided
+<Header
+  title="Profile"
+  accessibilityLabel="Profile screen"
+  onBackPress={goBack}           // omit on root screens
+  right={<IconButton name="edit" />}
+/>
+
+// EmptyState — types: "empty" | "error" | "offline" | "search"
+<EmptyState
+  type="empty"
+  title="No results"
+  description="Try adjusting your search."
+  actionLabel="Clear filters"
+  onAction={clearFilters}
+/>
+
+// CalendarStrip
+<CalendarStrip selectedDate={date} onDateSelect={setDate} />
+
+// ScheduleItem
+<ScheduleItem
+  data={{
+    title: "Morning run",
+    startTime: "07:00",
+    endTime: "08:00",
+    category: "fitness",
+  }}
+  onPress={handlePress}
+/>
+```
+
+---
+
+## i18n / Labels
+
+Built-in English and Spanish label sets. Components use these internally for loading messages, error text, and accessibility strings.
+
+### Switch language
+
+```tsx
+<DesignSystemProvider language="es">
+  <YourApp />
+</DesignSystemProvider>
+```
+
+### Override specific labels
+
+```tsx
+<DesignSystemProvider
+  language="es"
+  overrides={{
+    designSystem: {
+      button: { loadingLabel: "Guardando..." },
+    },
+  }}
+>
+  <YourApp />
+</DesignSystemProvider>
+```
+
+### Read labels in a component
+
+```tsx
+import { useDesignSystem } from "@design-system";
+
+const { labels } = useDesignSystem();
+// labels.designSystem.button.loadingLabel
+```
+
+### Inspect the full label structure
+
+```tsx
+import { en } from "@design-system";
+console.log(en); // full label tree — useful as a reference when extending
+```
+
+---
+
+## Tokens
+
+All design tokens are exported for use in `StyleSheet.create` or any non-Restyle context.
+
+```tsx
+import {
+  spacing,
+  radii,
+  fontFamily,
+  fontSize,
+  fontWeight,
+  lineHeight,
+  duration,
+  easing,
+  iconSize,
+  lightSemanticColors,
+} from "@design-system";
+
+const styles = StyleSheet.create({
+  container: {
+    padding: spacing.lg,
+    borderRadius: radii.md,
+  },
+  label: {
+    fontFamily: fontFamily.primary,
+    fontSize: fontSize.md,
+    fontWeight: fontWeight.semibold,
+    lineHeight: lineHeight.md,
+  },
+});
+```
+
+| Scale | Keys |
+|---|---|
+| Spacing | `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl` · `4xl` |
+| Radii | `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `full` |
+| Font size | `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl` · `4xl` |
+| Duration (ms) | `instant` · `fast` · `normal` · `slow` · `slower` |
+| Icon size (px) | `xs=12` · `sm=16` · `md=20` · `lg=24` · `xl=32` · `2xl=40` · `3xl=48` |
+
+---
+
+## Hooks
+
+### `useRestyleTheme`
+
+Access raw theme tokens for dynamic styles.
+
+```tsx
+import { useRestyleTheme } from "@design-system";
+
+const { colors, spacing } = useRestyleTheme();
+// colors.accentPrimary, spacing.md, etc.
+```
+
+### `useDesignSystem`
+
+Access active i18n labels.
+
+```tsx
+import { useDesignSystem } from "@design-system";
+
+const { labels } = useDesignSystem();
+```
+
+### `useToast`
+
+Trigger toasts imperatively from anywhere inside `ToastProvider`.
+
+```tsx
+import { useToast } from "@design-system";
+
+const toast = useToast();
+toast.show({ message: "Saved!", variant: "success" });
+toast.show({ message: "Error", variant: "error", duration: 4000 });
+```
+
+### `useReducedMotion`
+
+```tsx
+import { useReducedMotion } from "@design-system";
+
+const reducedMotion = useReducedMotion(); // boolean
+```
+
+### `useMotionSafeDuration`
+
+Returns `0` when reduced motion is on, the given duration otherwise.
+
+```tsx
+import { useMotionSafeDuration, duration } from "@design-system";
+
+const animDuration = useMotionSafeDuration(duration.normal); // 0 or 300
+```
+
+---
+
+## Utilities
+
+### Platform
+
+```tsx
+import { isIOS, isAndroid, platformSelect, getStatusBarHeight, MIN_TOUCH_TARGET } from "@design-system";
+
+const shadow = platformSelect({
+  ios: { shadowColor: "#000", shadowOpacity: 0.1, shadowRadius: 4 },
+  android: { elevation: 4 },
+});
+```
+
+### Accessibility
+
+```tsx
+import {
+  buttonA11yProps,
+  checkboxA11yProps,
+  imageA11yProps,
+  getContrastRatio,
+  meetsContrastAA,
+} from "@design-system";
+
+<TouchableOpacity {...buttonA11yProps("Save changes")} />
+
+const ratio = getContrastRatio("#1877F2", "#FFFFFF"); // → 4.56
+const passes = meetsContrastAA(ratio);                // → true
+```
+
+### Helpers
+
+```tsx
+import { getInitials, formatBadgeLabel } from "@design-system";
+
+getInitials("María García"); // → "MG"
+formatBadgeLabel(100);       // → "99+"
+```
+
+---
+
+## TypeScript Reference
+
+### Theme utilities
+
+| Export | Description |
+|---|---|
+| `buildPair(light, dark)` | Build a `RestyleThemePair` from partial color overrides — recommended |
+| `buildRestyleThemeFromThemeColors(base, overrides)` | Build one mode by merging overrides into a base palette |
+| `buildRestyleTheme(colors)` | Build one mode from a complete `SemanticColorsInput` — from scratch |
+| `restylePresetThemes` | Map of 6 built-in `RestyleThemePair` objects |
+| `lightSemanticColors` | Default light palette — use as base for `buildRestyleThemeFromThemeColors` |
+| `darkSemanticColors` | Default dark palette |
+
+### Key types
+
+| Type | Description |
+|---|---|
+| `ThemeColors` | Full color map shape |
+| `DeepPartial<ThemeColors>` | Partial overrides for `buildPair` |
+| `SemanticColorsInput` | Complete color map with `string` values for `buildRestyleTheme` |
+| `RestyleTheme` | Compiled Restyle theme object |
+| `RestyleThemePair` | `{ light: RestyleTheme, dark: RestyleTheme }` |
+| `DesignSystemLanguage` | `"en" \| "es"` |
+| `DesignSystemLabels` | Complete label tree |
+| `DesignSystemLabelsOverride` | `DeepPartial<DesignSystemLabels>` |
+| `DesignSystemProviderProps` | All props for `DesignSystemProvider` |
+| `IconName` | Union of all valid Material Icon names |
+| `RestyleColor` | Union of all valid theme color token names |
+
+### Component prop types
+
+Every component exports its props type as `ComponentNameProps`:
+
+```tsx
+import type {
+  ButtonProps, IconButtonProps,
+  TextInputProps, CheckboxProps, RadioButtonProps,
+  SwitchProps, SegmentedControlProps, SelectSheetProps,
+  AvatarProps, BadgeProps, ChipProps, CardProps, IconProps,
+  SpinnerProps, ProgressBarProps, SkeletonProps, ToastProps, ModalProps,
+  HeaderProps, EmptyStateProps, CalendarStripProps, ScheduleItemProps,
+} from "@design-system";
+```