@thewhileloop/whileui 4.2.3 → 4.4.0

package/dist/agent/llms-components.txt

@@ -0,0 +1,2808 @@
+# WhileUI 4.4.0
+
+> React Native components and blocks for iOS, Android and web, styled with Uniwind and
+> themed through a typed token contract. Package: `@thewhileloop/whileui`.
+
+- **Text** (Primitives) — Themed text with variant support
+
+## Text
+
+`Text` maps semantic roles to the active visual typography tokens; custom font-size
+classes are unnecessary for normal hierarchy. `heading` also sets
+`accessibilityRole="header"` unless the caller supplies another role.
+
+
+| Prop      | Type                                                                                                       | Default     | Description |
+| --------- | ---------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
+| className | `string`                                                                                                   | —           |             |
+| size      | `'base' \| 'xs' \| 'sm' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`                                                 | —           |             |
+| variant   | `'default' \| 'heading' \| 'title' \| 'subtitle' \| 'body' \| 'caption' \| 'label' \| 'eyebrow' \| 'code'` | `'default'` |             |
+
+Also accepts the props of React Native's `TextProps`.
+
+---
+
+- **Surface** (Primitives) — Token-backed base, raised, and overlay container
+
+## Surface
+
+```tsx
+import { Surface } from '@thewhileloop/whileui';
+
+<Surface level="raised" padding="default">
+  {/* grouped content */}
+</Surface>;
+```
+
+
+| Prop          | Type                           | Default             | Description                          |
+| ------------- | ------------------------------ | ------------------- | ------------------------------------ |
+| level         | `SurfaceLevel`                 | `'base'`            | Semantic background and depth tier.  |
+| padding       | `SurfacePaddingSize`           | `'default'`         | Token-backed interior spacing.       |
+| radius        | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'xl'`              | Token-backed corner radius.          |
+| bordered      | `boolean`                      | `true`              | Draw the theme hairline border.      |
+| shadow        | `ShadowTier`                   | —                   | Override the level's depth.          |
+| className     | `string`                       | —                   |                                      |
+| frosted       | `boolean`                      | `false`             | Enable the optional frosted overlay. |
+| blurIntensity | `number`                       | subtle preset       | Override blur amount directly.       |
+| blurTintToken | `FrostedTintToken`             | `LEVEL_TINT[level]` | Tint token used for frosted mode.    |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **View** (Primitives) — Themed view wrapper
+
+### View
+
+Themed view wrapper
+
+```tsx
+import { View } from '@thewhileloop/whileui';
+```
+
+
+| Prop      | Type     | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| className | `string` | —       |             |
+
+Also accepts the props of React Native's `ViewProps`.
+
+---
+
+- **Pressable** (Primitives) — Themed pressable wrapper
+
+## Pressable
+
+```tsx
+import { Pressable, Text } from '@thewhileloop/whileui';
+
+<Pressable
+  accessibilityRole="button"
+  feedback="strong"
+  disabledFeedback="default"
+  loading={false}
+  onPress={() => {}}
+>
+  <Text>Open</Text>
+</Pressable>;
+```
+
+`Pressable` preserves React Native's event, ref, accessibility, and function-style
+`style` contracts. Feedback changes opacity without changing layout. Native press state
+comes directly from React Native; web adds a motion-policy-aware opacity transition.
+
+
+| Prop             | Type              | Default     | Description                                                                 |
+| ---------------- | ----------------- | ----------- | --------------------------------------------------------------------------- |
+| className        | `string`          | —           | Additional Tailwind classes.                                                |
+| feedback         | `PressedVariant`  | `'none'`    | Semantic press feedback. `none` preserves a plain React Native Pressable.   |
+| disabledFeedback | `DisabledVariant` | `'default'` | Opacity used while the control is unavailable.                              |
+| loading          | `boolean`         | `false`     | Loading controls are busy and non-interactive, just like disabled controls. |
+
+Also accepts the props of React Native's `PressableProps`.
+
+---
+
+- **Stack** (Primitives) — Vertical flex layout with gap
+
+### Stack
+
+Vertical flex layout with gap
+
+```tsx
+import { Stack } from '@thewhileloop/whileui';
+```
+
+
+| Prop      | Type                                                                | Default     | Description |
+| --------- | ------------------------------------------------------------------- | ----------- | ----------- |
+| className | `string`                                                            | —           |             |
+| gap       | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`           | `'md'`      |             |
+| align     | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`           | `'stretch'` |             |
+| justify   | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | `'start'`   |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Row** (Primitives) — Horizontal flex layout with gap
+
+## Layout Primitives (Stack, Row)
+
+Use `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.
+
+```tsx
+import { Stack, Row } from '@thewhileloop/whileui';
+
+<Stack gap="lg">
+  <Text>Title</Text>
+  <Row gap="md" justify="between">
+    <Button>
+      <ButtonText>Cancel</ButtonText>
+    </Button>
+    <Button>
+      <ButtonText>Save</ButtonText>
+    </Button>
+  </Row>
+</Stack>;
+```
+
+
+| Prop      | Type                                                                | Default    | Description |
+| --------- | ------------------------------------------------------------------- | ---------- | ----------- |
+| className | `string`                                                            | —          |             |
+| gap       | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`           | `'md'`     |             |
+| align     | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`           | `'center'` |             |
+| justify   | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | `'start'`  |             |
+
+Also accepts the props of `ViewProps`.
+
+### Container
+
+Caps content width and centres it. Phone-first layouts stretch to the viewport, which
+is right at 390px and wrong at 1600px — line lengths become unreadable and related
+controls drift apart.
+
+```tsx
+<Container size="lg">{children}</Container>
+```
+
+
+| Prop      | Type                                     | Default | Description |
+| --------- | ---------------------------------------- | ------- | ----------- |
+| className | `string`                                 | —       |             |
+| size      | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`  |             |
+| fill      | `boolean`                                | `false` |             |
+
+Also accepts the props of `ViewProps`.
+
+No platform branch, and none is needed: every size is wider than any phone, so on iOS
+and Android the cap never engages and it renders as a plain full-width `View`. The same
+component is a no-op on native and the whole fix on desktop.
+
+For a scroll view, put the column on the content container so the scrollbar stays at
+the window edge:
+
+```tsx
+<ScrollView contentContainerClassName="w-full max-w-5xl self-center" />
+```
+
+---
+
+- **MotionProvider** (Root Providers) — System reduced motion, explicit preview modes, and deterministic testing
+
+### MotionProvider
+
+System reduced motion, explicit preview modes, and deterministic testing
+
+```tsx
+import { MotionProvider } from '@thewhileloop/whileui';
+```
+
+
+| Prop                | Type              | Default    | Description |
+| ------------------- | ----------------- | ---------- | ----------- |
+| children (required) | `React.ReactNode` | —          |             |
+| mode                | `MotionMode`      | `'system'` |             |
+
+---
+
+- **Button** (Form Controls) — 4 sizes, ButtonText & ButtonIcon sub-components
+
+## Button
+
+```tsx
+import { Button, ButtonText, ButtonIcon } from '@thewhileloop/whileui';
+
+<Button variant="default" size="default" disabled={false} loading={false} onPress={() => {}}>
+  <ButtonIcon>
+    <Icon />
+  </ButtonIcon>
+  <ButtonText>Click me</ButtonText>
+  {/* Placement is child order — a trailing ButtonIcon renders after the label. */}
+  <ButtonIcon>
+    <Icon />
+  </ButtonIcon>
+</Button>;
+```
+
+
+| Prop             | Type                                                                          | Default     | Description                                                             |
+| ---------------- | ----------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
+| children         | `React.ReactNode`                                                             | —           |                                                                         |
+| className        | `string`                                                                      | —           | Additional Tailwind classes.                                            |
+| disabled         | `boolean`                                                                     | `false`     | Disable the button.                                                     |
+| loading          | `boolean`                                                                     | `false`     | Shows a centered spinner, exposes busy state, and prevents interaction. |
+| disabledFeedback | `DisabledVariant`                                                             | —           | Opacity used while the control is unavailable.                          |
+| size             | `'sm' \| 'lg' \| 'default' \| 'icon'`                                         | `'default'` |                                                                         |
+| variant          | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` |                                                                         |
+
+Also accepts the props of `PressableProps`.
+
+---
+
+- **Input** (Form Controls) — TextInput wrapper with themed styling
+
+## Input
+
+```tsx
+import { Input, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
+
+<Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
+
+<Input
+  placeholder="Search"
+  prefix={<Feather name="search" size={16} color={icons.muted} aria-hidden />}
+/>;
+```
+
+On iOS and Android, Input, Textarea, NumericInput and SmartInput draw the caret and
+selection in the theme's primary colour; pass `selectionColor` (and `cursorColor` on
+Android) to override it. On web, filled surfaces keep their themed background,
+foreground and caret when the browser autofills them.
+
+
+| Prop           | Type                              | Default     | Description                                                                                                                                          |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| aria-invalid   | `boolean`                         | —           |                                                                                                                                                      |
+| className      | `string`                          | —           |                                                                                                                                                      |
+| prefix         | `React.ReactNode`                 | —           | Shown before the text. A decorative icon here needs `aria-hidden`; screen readers otherwise stop on it as a separate element and read out its glyph. |
+| suffix         | `React.ReactNode`                 | —           | Shown after the text: a unit, or a control such as a clear button.                                                                                   |
+| inputClassName | `string`                          | —           |                                                                                                                                                      |
+| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |                                                                                                                                                      |
+
+Also accepts the props of `TextInputProps`.
+
+---
+
+- **NumericInput** (Form Controls) — Numeric input with prefix/suffix slots, optional steppers, and compact size
+
+## NumericInput
+
+```tsx
+import { NumericInput } from '@thewhileloop/whileui';
+
+<NumericInput
+  value={amount}
+  onValueChange={setAmount}
+  prefix={<Text className="text-muted-foreground">$</Text>}
+  suffix={<Text className="text-muted-foreground">USD</Text>}
+  min={0}
+  step={0.5}
+  showSteppers
+  size="compact"
+/>;
+```
+
+
+| Prop           | Type                              | Default     | Description                                                                                                            |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| aria-invalid   | `boolean`                         | —           |                                                                                                                        |
+| className      | `string`                          | —           |                                                                                                                        |
+| inputClassName | `string`                          | —           |                                                                                                                        |
+| prefix         | `React.ReactNode`                 | —           |                                                                                                                        |
+| suffix         | `React.ReactNode`                 | —           |                                                                                                                        |
+| value          | `number \| null`                  | —           | Controlled numeric value.                                                                                              |
+| defaultValue   | `number`                          | —           |                                                                                                                        |
+| onValueChange  | `(value: number \| null) => void` | —           | Numeric value change callback.                                                                                         |
+| min            | `number`                          | —           |                                                                                                                        |
+| max            | `number`                          | —           |                                                                                                                        |
+| step           | `number`                          | `1`         |                                                                                                                        |
+| showSteppers   | `boolean`                         | `false`     | Show decrement/increment controls.                                                                                     |
+| unstyled       | `boolean`                         | `false`     | Drop the field shell (border, background, radius, padding) for embedding inside another field shell like LabeledField. |
+| size           | `'default' \| 'compact'`          | `'default'` |                                                                                                                        |
+| variant        | `'default' \| 'error'`            | `'default'` |                                                                                                                        |
+
+Also accepts the props of `TextInputProps`.
+
+---
+
+- **OTPInput** (Form Controls) — Verification code input with auto-focus, paste, secure mask, loading skeleton, error shake
+
+## OTPInput
+
+```tsx
+import { OTPInput } from '@thewhileloop/whileui';
+
+<OTPInput
+  value={otp}
+  onValueChange={setOtp}
+  onComplete={(code) => verify(code)}
+  length={6}
+  variant="default"
+/>;
+```
+
+
+| Prop          | Type                      | Default     | Description                        |
+| ------------- | ------------------------- | ----------- | ---------------------------------- |
+| length        | `number`                  | `6`         | Number of digit cells.             |
+| value         | `string`                  | —           | Controlled value.                  |
+| onValueChange | `(value: string) => void` | —           | Called on each digit change.       |
+| onComplete    | `(code: string) => void`  | —           | Called when all digits are filled. |
+| variant       | `'default' \| 'error'`    | `'default'` | Error variant triggers shake.      |
+| size          | `'default' \| 'compact'`  | `'default'` | Cell size.                         |
+| secure        | `boolean`                 | `false`     | Mask digits with dots.             |
+| disabled      | `boolean`                 | `false`     |                                    |
+| autoFocus     | `boolean`                 | `false`     | Focus first cell on mount.         |
+| className     | `string`                  | —           |                                    |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **FormField** (Form Controls) — Compound API: FormField, FormLabel, FormControl, FormHint, FormMessage
+
+## FormField
+
+```tsx
+import {
+  FormField,
+  FormLabel,
+  FormControl,
+  FormHint,
+  FormMessage,
+  Input,
+} from '@thewhileloop/whileui';
+
+<FormField required invalid={Boolean(error)}>
+  <FormLabel>Email</FormLabel>
+  <FormControl>
+    <Input placeholder="you@example.com" />
+  </FormControl>
+  {error ? <FormMessage>{error}</FormMessage> : <FormHint>We'll never share your email.</FormHint>}
+</FormField>;
+```
+
+`invalid` and `disabled` are inherited by `Input`, `Textarea`, `NumericInput`, and
+`Select`. An explicit control prop wins. `useFormFieldState()` exposes the same state for
+custom controls; labels, hints, messages, density, and required indicators remain part
+of the compound field rather than each input.
+
+`FormLabel` names the `Input`, `Textarea` or `NumericInput` beside it for assistive
+technology (`aria-labelledby` on web and Android; `useFormFieldState().labelId` gives a
+custom control the same id). A label passed to the control itself wins.
+
+---
+
+- **LabeledField** (Form Controls) — Field wrapper with label/helper/error plus left/right slots
+
+## LabeledField
+
+```tsx
+import { LabeledField, LabeledFieldControl, Input } from '@thewhileloop/whileui';
+
+<LabeledField
+  label="Username"
+  hint="3-20 characters"
+  leftSlot={<Icon />}
+  rightSlot={
+    <Button size="sm">
+      <ButtonText>Check</ButtonText>
+    </Button>
+  }
+>
+  <LabeledFieldControl>
+    <Input className="border-0 bg-transparent px-0" />
+  </LabeledFieldControl>
+</LabeledField>;
+```
+
+---
+
+- **Textarea** (Form Controls) — Multi-line text input
+
+### Textarea
+
+Multi-line text input
+
+```tsx
+import { Textarea } from '@thewhileloop/whileui';
+```
+
+
+| Prop         | Type                        | Default     | Description |
+| ------------ | --------------------------- | ----------- | ----------- |
+| aria-invalid | `boolean`                   | —           |             |
+| className    | `string`                    | —           |             |
+| size         | `'sm' \| 'lg' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `TextInputProps`.
+
+---
+
+- **Checkbox** (Form Controls) — Controlled/uncontrolled, accessibility roles
+
+## Checkbox
+
+```tsx
+import { Checkbox } from '@thewhileloop/whileui';
+
+<Checkbox checked={checked} onCheckedChange={setChecked} />;
+```
+
+
+| Prop            | Type                         | Default | Description |
+| --------------- | ---------------------------- | ------- | ----------- |
+| checked         | `boolean`                    | —       |             |
+| defaultChecked  | `boolean`                    | `false` |             |
+| onCheckedChange | `(checked: boolean) => void` | —       |             |
+| disabled        | `boolean`                    | `false` |             |
+| className       | `string`                     | —       |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Switch** (Form Controls) — Controlled/uncontrolled, accessibility roles
+
+## Switch
+
+```tsx
+import { Switch } from '@thewhileloop/whileui';
+
+<Switch checked={checked} onCheckedChange={setChecked} />;
+```
+
+
+| Prop            | Type                         | Default | Description |
+| --------------- | ---------------------------- | ------- | ----------- |
+| checked         | `boolean`                    | —       |             |
+| defaultChecked  | `boolean`                    | `false` |             |
+| onCheckedChange | `(checked: boolean) => void` | —       |             |
+| disabled        | `boolean`                    | `false` |             |
+| className       | `string`                     | —       |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **RadioGroup** (Form Controls) — RadioGroup + RadioGroupItem
+
+## RadioGroup
+
+```tsx
+import { RadioGroup, RadioGroupItem } from '@thewhileloop/whileui';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroupItem value="option1" />
+  <RadioGroupItem value="option2" />
+</RadioGroup>;
+```
+
+---
+
+- **Select** (Form Controls) — Uses `SelectOption` type `{value, label}`. Includes SelectGroup, SelectLabel, SelectSeparator
+
+## Select
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+} from '@thewhileloop/whileui';
+
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger>
+    <SelectValue placeholder="Select..." />
+  </SelectTrigger>
+  <SelectContent frosted blurIntensity={24} blurTintToken="surfaceTranslucent">
+    <SelectItem label="Option 1" value="1" />
+    <SelectItem label="Option 2" value="2" />
+  </SelectContent>
+</Select>;
+```
+
+Focused and pressed options use the subtle interaction-state tokens; the primary token
+marks the selected indicator without replacing the option's foreground colour. Long
+selected values stay on one line and truncate without displacing the trigger chevron.
+For popover presentation on web, the options panel matches the trigger width, caps
+itself to the collision-available viewport, and wraps long option labels inside it.
+
+Opening a Select, or a Popover, closes the on-screen keyboard first, so options opened
+from a form are never hidden behind it. Both draw in a portal, where the platform would
+otherwise leave the keyboard up; the Modal-hosted overlays close it on their own.
+
+`SelectContent` supports optional frosted props:
+
+
+| Prop          | Type                                                               | Default       | Description                          |
+| ------------- | ------------------------------------------------------------------ | ------------- | ------------------------------------ |
+| className     | `string`                                                           | —             |                                      |
+| portalHost    | `string`                                                           | —             |                                      |
+| insets        | `{ top?: number; bottom?: number; left?: number; right?: number }` | —             |                                      |
+| frosted       | `boolean`                                                          | `false`       | Enable the optional frosted overlay. |
+| blurIntensity | `number`                                                           | subtle preset | Override blur amount directly.       |
+| blurTintToken | `FrostedTintToken`                                                 | `'popover'`   | Tint token used for frosted mode.    |
+
+Also accepts the props of the underlying primitive.
+
+`SelectContent` keeps its listbox inside the safe area by default; pass `insets` only to
+change that margin. A list taller than the screen scrolls inside the listbox on every
+platform. Inside a Dialog, Sheet or other WhileUI overlay it renders in that
+overlay's layer automatically. Option values must be non-empty strings: the web
+primitive rejects `""`, so model "none" as an explicit value such as `'none'`.
+
+---
+
+- **Label** (Form Controls) — Form field label
+
+### Label
+
+Form field label
+
+```tsx
+import { Label } from '@thewhileloop/whileui';
+```
+
+
+| Prop      | Type     | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| className | `string` | —       |             |
+
+Also accepts the props of `TextProps`.
+
+---
+
+- **SegmentedControl** (Form Controls) — SegmentedControl, SegmentedControlItem, SegmentedControlItemText with wrapping layout support
+
+## SegmentedControl
+
+```tsx
+import {
+  SegmentedControl,
+  SegmentedControlItem,
+  SegmentedControlItemText,
+} from '@thewhileloop/whileui';
+
+<SegmentedControl value={unit} onValueChange={setUnit} variant="pill" wrap>
+  <SegmentedControlItem value="metric">
+    <SegmentedControlItemText>Metric</SegmentedControlItemText>
+  </SegmentedControlItem>
+  <SegmentedControlItem value="imperial">
+    <SegmentedControlItemText>Imperial</SegmentedControlItemText>
+  </SegmentedControlItem>
+</SegmentedControl>;
+```
+
+When the labels do not fit a phone, `wrap="scroll"` keeps them on one row at full width
+and scrolls sideways, instead of wrapping or truncating them.
+
+
+| Prop          | Type                            | Default     | Description                                                                                                                                                                                                                                                                |
+| ------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value         | `string`                        | —           |                                                                                                                                                                                                                                                                            |
+| defaultValue  | `string`                        | `''`        |                                                                                                                                                                                                                                                                            |
+| onValueChange | `(value: string) => void`       | —           |                                                                                                                                                                                                                                                                            |
+| variant       | `'default' \| 'pill'`           | `'default'` | Pill = rounded-full items.                                                                                                                                                                                                                                                 |
+| wrap          | `boolean \| 'auto' \| 'scroll'` | `'auto'`    | `true` wraps segments onto more rows; `false` keeps one row and shares its width. `'scroll'` keeps one row with each segment as wide as its label and scrolls sideways when they do not fit — for labels a phone cannot show in full. `'auto'` wraps above three segments. |
+| size          | `'default' \| 'compact'`        | `'default'` |                                                                                                                                                                                                                                                                            |
+| disabled      | `boolean`                       | `false`     |                                                                                                                                                                                                                                                                            |
+| className     | `string`                        | —           |                                                                                                                                                                                                                                                                            |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Toggle** (Form Controls) — ToggleText sub-component
+
+### Toggle
+
+ToggleText sub-component
+
+```tsx
+import { Toggle } from '@thewhileloop/whileui';
+```
+
+
+| Prop            | Type                                             | Default     | Description |
+| --------------- | ------------------------------------------------ | ----------- | ----------- |
+| pressed         | `boolean`                                        | `false`     |             |
+| defaultPressed  | `boolean`                                        | `false`     |             |
+| onPressedChange | `(pressed: boolean) => void`                     | —           |             |
+| variant         | `VariantProps<typeof toggleVariants>['variant']` | `'default'` |             |
+| size            | `VariantProps<typeof toggleVariants>['size']`    | `'default'` |             |
+| className       | `string`                                         | —           |             |
+| children        | `React.ReactNode`                                | —           |             |
+
+Also accepts the props of `PressableProps`.
+
+---
+
+- **ToggleGroup** (Form Controls) — Group of toggle items
+
+### ToggleGroup
+
+Group of toggle items
+
+```tsx
+import { ToggleGroup } from '@thewhileloop/whileui';
+```
+
+
+| Prop          | Type                                  | Default     | Description |
+| ------------- | ------------------------------------- | ----------- | ----------- |
+| type          | `ToggleGroupType`                     | `'single'`  |             |
+| defaultValue  | `string \| string[]`                  | —           |             |
+| value         | `string \| string[]`                  | —           |             |
+| onValueChange | `(value: string \| string[]) => void` | —           |             |
+| variant       | `'default' \| 'outline'`              | `'default'` |             |
+| size          | `'default' \| 'sm' \| 'lg'`           | `'default'` |             |
+| className     | `string`                              | —           |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Card** (Display) — Compound: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
+
+## Card
+
+```tsx
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+} from '@thewhileloop/whileui';
+
+<Card padding="default">
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>{/* Content */}</CardContent>
+  <CardFooter>{/* Footer */}</CardFooter>
+</Card>;
+
+<Card unstyled padding="none" className="rounded-xl border border-border bg-card">
+  {/* advanced custom layouts */}
+</Card>;
+```
+
+
+| Prop          | Type                                  | Default     | Description                                             |
+| ------------- | ------------------------------------- | ----------- | ------------------------------------------------------- |
+| shadow        | `ShadowTier`                          | `'sm'`      | Elevation tier; 'sm' by default, 'none' for flat cards. |
+| className     | `string`                              | —           |                                                         |
+| padding       | `'none' \| 'sm' \| 'lg' \| 'default'` | `'default'` |                                                         |
+| unstyled      | `boolean`                             | `false`     |                                                         |
+| frosted       | `boolean`                             | `false`     | Enable the optional frosted overlay.                    |
+| blurIntensity | `number`                              | —           | Override blur amount directly.                          |
+| blurTintToken | `FrostedTintToken`                    | —           | Tint token used for frosted mode.                       |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Surface** (Display) — Shared radius, padding, border, shadow, and optional frosted treatment
+
+Documented under Surface.
+
+---
+
+- **Badge** (Display) — BadgeText sub-component
+
+## Badge
+
+```tsx
+import { Badge, BadgeText } from '@thewhileloop/whileui';
+
+<Badge variant="default">
+  <BadgeText>New</BadgeText>
+</Badge>;
+```
+
+
+| Prop      | Type                                                                                                                                                                                                | Default     | Description |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
+| className | `string`                                                                                                                                                                                            | —           |             |
+| variant   | `'default' \| 'soft' \| 'destructive' \| 'outline' \| 'secondary' \| 'success' \| 'warning' \| 'info' \| 'soft-secondary' \| 'soft-destructive' \| 'soft-success' \| 'soft-warning' \| 'soft-info'` | `'default'` |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **FAB** (Display) — Floating action button. `label` required; pass your own icon as children
+
+### FAB
+
+One primary action, raised above the content. It owns no icon dependency — pass the
+glyph as children and colour it from `useIconColors()`, because icon libraries need a
+concrete colour rather than a class.
+
+```tsx
+import { FAB, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
+
+<FAB label="New group" onPress={create}>
+  <Feather name="plus" size={24} color={icons.primaryForeground} />
+</FAB>;
+```
+
+| Prop        | Type                                             | Default    | Notes                                   |
+| ----------- | ------------------------------------------------ | ---------- | --------------------------------------- |
+| `label`     | `string`                                         | —          | Required. The accessible name           |
+| `variant`   | `default \| secondary \| destructive \| surface` | `default`  |                                         |
+| `size`      | `sm \| default \| lg`                            | `default`  | 48 / 56 / 64 — all clear touch minimums |
+| `placement` | `floating \| floating-left \| inline`            | `floating` | `inline` lets the caller position it    |
+
+`FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never
+needs `hitSlop`.
+
+A floating FAB covers whatever scrolls under it, so a list behind one ends with room for
+it: `contentContainerStyle={{ paddingBottom: fabClearance() }}`, passing the FAB's `size`
+when it is not the default.
+
+---
+
+- **Alert** (Display) — AlertTitle & AlertDescription
+
+## Alert
+
+```tsx
+import { Alert, AlertTitle, AlertDescription } from '@thewhileloop/whileui';
+
+<Alert variant="default">
+  <AlertTitle>Heads up!</AlertTitle>
+  <AlertDescription>Something happened.</AlertDescription>
+</Alert>;
+
+// Shown after a failed submit: also spoken on iOS when it appears.
+<Alert variant="destructive" announce>
+  <AlertTitle>Could not save</AlertTitle>
+  <AlertDescription>Check your connection and try again.</AlertDescription>
+</Alert>;
+```
+
+
+| Prop      | Type                                                             | Default     | Description                                                                                                                                                                                                                                                                                                        |
+| --------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| announce  | `boolean`                                                        | `false`     | Speak the alert when it appears, for alerts shown in response to an action such as a failed submit. Android and the web already read it through the live region; iOS has none, so this announces its text once. Leave it off for alerts that are part of a screen's content, or every visit would read them aloud. |
+| className | `string`                                                         | —           |                                                                                                                                                                                                                                                                                                                    |
+| variant   | `'default' \| 'destructive' \| 'success' \| 'warning' \| 'info'` | `'default'` |                                                                                                                                                                                                                                                                                                                    |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Avatar** (Display) — AvatarImage + AvatarFallback
+
+## Avatar
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
+
+<Avatar size="default">
+  <AvatarImage source={{ uri: 'https://...' }} />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>;
+```
+
+
+| Prop      | Type                                | Default     | Description |
+| --------- | ----------------------------------- | ----------- | ----------- |
+| className | `string`                            | —           |             |
+| size      | `'sm' \| 'lg' \| 'xl' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `ViewProps`.
+
+`AvatarImage` keeps `AvatarFallback` visible while loading or after an error. Its
+`onLoadingStatusChange` callback reports `'loading'`, `'loaded'`, and `'error'`, including
+when a changed source begins loading, while the standard image event callbacks still run.
+
+---
+
+- **DataRow** (Display) — DataRow, DataRowLeft/Center/Right, DataRowLabel/Description/Value
+
+## DataRow
+
+```tsx
+import {
+  DataRow,
+  DataRowLeft,
+  DataRowCenter,
+  DataRowRight,
+  DataRowLabel,
+  DataRowDescription,
+  DataRowValue,
+  Avatar,
+  AvatarFallback,
+} from '@thewhileloop/whileui';
+
+<DataRow>
+  <DataRowLeft>
+    <Avatar size="sm">
+      <AvatarFallback>JD</AvatarFallback>
+    </Avatar>
+  </DataRowLeft>
+  <DataRowCenter>
+    <DataRowLabel>Jane Doe</DataRowLabel>
+    <DataRowDescription>Product Designer</DataRowDescription>
+  </DataRowCenter>
+  <DataRowRight>
+    <DataRowValue>Owner</DataRowValue>
+  </DataRowRight>
+</DataRow>;
+```
+
+---
+
+- **Separator** (Display) — Themed divider
+
+### Separator
+
+Themed divider
+
+```tsx
+import { Separator } from '@thewhileloop/whileui';
+```
+
+
+| Prop        | Type                         | Default        | Description |
+| ----------- | ---------------------------- | -------------- | ----------- |
+| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` |             |
+| className   | `string`                     | —              |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Progress** (Display) — Value-based progress bar with accessibility
+
+## Progress
+
+```tsx
+import { Progress } from '@thewhileloop/whileui';
+
+<Progress value={50} size="default" />;
+```
+
+
+| Prop               | Type                        | Default     | Description |
+| ------------------ | --------------------------- | ----------- | ----------- |
+| value              | `number`                    | `0`         |             |
+| indicatorClassName | `string`                    | —           |             |
+| className          | `string`                    | —           |             |
+| size               | `'sm' \| 'lg' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Spinner** (Display) — ActivityIndicator wrapper
+
+### Spinner
+
+ActivityIndicator wrapper
+
+```tsx
+import { Spinner } from '@thewhileloop/whileui';
+```
+
+
+| Prop      | Type                        | Default     | Description |
+| --------- | --------------------------- | ----------- | ----------- |
+| className | `string`                    | —           |             |
+| size      | `'sm' \| 'lg' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `ActivityIndicatorProps`.
+
+---
+
+- **Skeleton** (Display) — Loading placeholder (pulse = opacity fade, shimmer = sweep)
+
+### Skeleton
+
+Loading placeholder (pulse = opacity fade, shimmer = sweep)
+
+```tsx
+import { Skeleton } from '@thewhileloop/whileui';
+```
+
+
+| Prop      | Type                   | Default   | Description |
+| --------- | ---------------------- | --------- | ----------- |
+| className | `string`               | —         |             |
+| variant   | `'pulse' \| 'shimmer'` | `'pulse'` |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **AspectRatio** (Display) — Maintain aspect ratio container
+
+### AspectRatio
+
+Maintain aspect ratio container
+
+```tsx
+import { AspectRatio } from '@thewhileloop/whileui';
+```
+
+
+| Prop      | Type     | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| ratio     | `number` | `1`     |             |
+| className | `string` | —       |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Tabs** (Layout) — TabsList, TabsTrigger, TabsContent
+
+## Tabs
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@thewhileloop/whileui';
+
+<Tabs defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">
+      <Text>Tab 1</Text>
+    </TabsTrigger>
+    <TabsTrigger value="tab2">
+      <Text>Tab 2</Text>
+    </TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">{/* Content 1 */}</TabsContent>
+  <TabsContent value="tab2">{/* Content 2 */}</TabsContent>
+</Tabs>;
+```
+
+---
+
+- **Accordion** (Layout) — AccordionItem, AccordionTrigger, Content
+
+## Accordion
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from '@thewhileloop/whileui';
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="item1">
+    <AccordionTrigger>
+      <Text>Section 1</Text>
+    </AccordionTrigger>
+    <AccordionContent>
+      <Text>Content 1</Text>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>;
+```
+
+
+| Prop         | Type                 | Default    | Description |
+| ------------ | -------------------- | ---------- | ----------- |
+| type         | `AccordionType`      | `'single'` |             |
+| defaultValue | `string \| string[]` | —          |             |
+| collapsible  | `boolean`            | `true`     |             |
+| className    | `string`             | —          |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Collapsible** (Layout) — CollapsibleTrigger, CollapsibleContent
+
+### Collapsible
+
+CollapsibleTrigger, CollapsibleContent
+
+```tsx
+import { Collapsible } from '@thewhileloop/whileui';
+```
+
+
+| Prop         | Type                      | Default | Description |
+| ------------ | ------------------------- | ------- | ----------- |
+| defaultOpen  | `boolean`                 | `false` |             |
+| open         | `boolean`                 | —       |             |
+| onOpenChange | `(open: boolean) => void` | —       |             |
+| disabled     | `boolean`                 | `false` |             |
+| className    | `string`                  | —       |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Container** (Layout) — Centred content column with a max width
+
+### Container
+
+Caps content width and centres it. Phone-first layouts stretch to the viewport, which
+is right at 390px and wrong at 1600px — line lengths become unreadable and related
+controls drift apart.
+
+```tsx
+<Container size="lg">{children}</Container>
+```
+
+
+| Prop      | Type                                     | Default | Description |
+| --------- | ---------------------------------------- | ------- | ----------- |
+| className | `string`                                 | —       |             |
+| size      | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`  |             |
+| fill      | `boolean`                                | `false` |             |
+
+Also accepts the props of `ViewProps`.
+
+No platform branch, and none is needed: every size is wider than any phone, so on iOS
+and Android the cap never engages and it renders as a plain full-width `View`. The same
+component is a no-op on native and the whole fix on desktop.
+
+For a scroll view, put the column on the content container so the scrollbar stays at
+the window edge:
+
+```tsx
+<ScrollView contentContainerClassName="w-full max-w-5xl self-center" />
+```
+
+---
+
+- **Dialog** (Overlays & Menus) — Modal dialog with Header, Footer, Title, Description
+
+## Dialog
+
+```tsx
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  DialogClose,
+} from '@thewhileloop/whileui';
+
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>
+      <ButtonText>Open</ButtonText>
+    </Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    {/* Content */}
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button>
+          <ButtonText>Close</ButtonText>
+        </Button>
+      </DialogClose>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>;
+```
+
+`DialogContent` supports frosted props:
+
+
+| Prop          | Type               | Default                | Description                          |
+| ------------- | ------------------ | ---------------------- | ------------------------------------ |
+| className     | `string`           | —                      |                                      |
+| frosted       | `boolean`          | `false`                | Enable the optional frosted overlay. |
+| blurIntensity | `number`           | medium preset          | Override blur amount directly.       |
+| blurTintToken | `FrostedTintToken` | `'surfaceTranslucent'` | Tint token used for frosted mode.    |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **AlertDialog** (Overlays & Menus) — Confirmation dialog with Action/Cancel buttons
+
+## AlertDialog
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogTrigger,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from '@thewhileloop/whileui';
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">
+      <ButtonText>Delete</ButtonText>
+    </Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>;
+```
+
+`AlertDialogContent` supports the same frosted props as `DialogContent`.
+
+
+| Prop          | Type                      | Default                | Description                                                                                                                                                                                                                          |
+| ------------- | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| className     | `string`                  | —                      |                                                                                                                                                                                                                                      |
+| presentation  | `AlertDialogPresentation` | `'modal'`              | `modal` — RN `Modal` + themed card (default). `native` — `Alert.alert` on iOS/Android (system chrome); ignored on web. `overlay` — same themed card as `modal`, but absolute fill inside the parent view (nest inside your `Modal`). |
+| frosted       | `boolean`                 | `false`                | Enable the optional frosted overlay.                                                                                                                                                                                                 |
+| blurIntensity | `number`                  | medium preset          | Override blur amount directly.                                                                                                                                                                                                       |
+| blurTintToken | `FrostedTintToken`        | `'surfaceTranslucent'` | Tint token used for frosted mode.                                                                                                                                                                                                    |
+
+Also accepts the props of `ViewProps`.
+
+### React Native: stacked modals
+
+Render a confirmation **inside** the overlay it belongs to. An `AlertDialog` or `Dialog`
+nested in a `Sheet` opens above it, and Android back or Escape closes the confirmation
+before the sheet. If `AlertDialog` must be a **sibling** of another fullscreen `Modal`, iOS
+often fails to show a second `Modal` on top; use **`presentation="overlay"`** inside that
+`Modal`, or **`presentation="native"`** for a system `Alert.alert` when themed UI is not
+required.
+
+---
+
+- **Popover** (Overlays & Menus) — Position-aware popover (requires PortalHost)
+
+## Popover
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent } from '@thewhileloop/whileui';
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>
+      <ButtonText>Open</ButtonText>
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <Text>Popover content</Text>
+  </PopoverContent>
+</Popover>;
+```
+
+`PopoverContent` supports frosted props:
+
+
+| Prop          | Type                     | Default       | Description                                                                                           |
+| ------------- | ------------------------ | ------------- | ----------------------------------------------------------------------------------------------------- |
+| className     | `string`                 | —             |                                                                                                       |
+| portalHost    | `string`                 | —             |                                                                                                       |
+| insets        | `Partial<OverlayInsets>` | —             | Collision padding. Defaults to safe area plus a margin so the panel never sits flush against an edge. |
+| frosted       | `boolean`                | `false`       | Enable the optional frosted overlay.                                                                  |
+| blurIntensity | `number`                 | subtle preset | Override blur amount directly.                                                                        |
+| blurTintToken | `FrostedTintToken`       | `'popover'`   | Tint token used for frosted mode.                                                                     |
+
+Also accepts the props of the underlying primitive.
+
+---
+
+- **Tooltip** (Overlays & Menus) — Position-aware tooltip (requires PortalHost)
+
+### Tooltip
+
+Position-aware tooltip (requires PortalHost)
+
+```tsx
+import { Tooltip } from '@thewhileloop/whileui';
+```
+
+
+| Prop                    | Type                      | Default | Description |
+| ----------------------- | ------------------------- | ------- | ----------- |
+| onOpenChange            | `(open: boolean) => void` | —       |             |
+| delayDuration           | `number`                  | —       |             |
+| skipDelayDuration       | `number`                  | —       |             |
+| disableHoverableContent | `boolean`                 | —       |             |
+| children (required)     | `React.ReactNode`         | —       |             |
+
+---
+
+- **DropdownMenu** (Overlays & Menus) — DropdownMenuTrigger, Content, Item, Label, Separator
+
+## DropdownMenu
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+} from '@thewhileloop/whileui';
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button>
+      <ButtonText>Menu</ButtonText>
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuLabel>Actions</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>
+      <Text>Edit</Text>
+    </DropdownMenuItem>
+    <DropdownMenuItem>
+      <Text>Delete</Text>
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>;
+```
+
+`DropdownMenuContent`, `ContextMenuContent`, and `MenubarContent` support the same frosted props as `PopoverContent` (default blur preset: medium).
+
+---
+
+- **ContextMenu** (Overlays & Menus) — Long-press context menu
+
+## ContextMenu
+
+`ContextMenuContent` supports the same frosted props as `PopoverContent` (default blur preset: medium).
+
+---
+
+- **HoverCard** (Overlays & Menus) — Position-aware hover card (requires PortalHost)
+
+## HoverCard
+
+`HoverCardContent` supports the same frosted props as `PopoverContent` (default blur preset: subtle).
+
+---
+
+- **Menubar** (Overlays & Menus) — Horizontal menu bar
+
+## Menubar
+
+```tsx
+import {
+  Menubar,
+  MenubarMenu,
+  MenubarTrigger,
+  MenubarContent,
+  MenubarLabel,
+  MenubarItem,
+  MenubarSeparator,
+} from '@thewhileloop/whileui';
+
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>
+      <Text className="text-foreground text-sm">File</Text>
+    </MenubarTrigger>
+    <MenubarContent>
+      <MenubarLabel>Project</MenubarLabel>
+      <MenubarItem>
+        <Text className="text-foreground">New Project</Text>
+      </MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem>
+        <Text className="text-foreground">Export</Text>
+      </MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>;
+```
+
+`MenubarLabel` is a non-interactive section heading. It takes a string or elements, and
+announces as a heading to assistive technology — as do `DropdownMenuLabel` and
+`ContextMenuLabel`.
+
+`MenubarContent` supports the same frosted props as `PopoverContent` (default blur preset: medium).
+
+---
+
+# Blocks API
+
+---
+
+- **Toast** (Feedback) — ToastProvider, ToastContainer, useToast() hook
+
+## Toast
+
+```tsx
+import { ToastProvider, ToastContainer, useToast } from '@thewhileloop/whileui';
+
+// Wrap app
+<ToastProvider>
+  <App />
+  <ToastContainer position="top" />
+</ToastProvider>;
+
+// Use in component
+const { toast } = useToast();
+toast({ title: 'Success', description: 'Saved!', variant: 'success' });
+```
+
+| Toast Options | Type                                      |
+| ------------- | ----------------------------------------- |
+| title         | `string`                                  |
+| description   | `string`                                  |
+| variant       | `'default' \| 'success' \| 'destructive'` |
+| duration      | `number` (ms)                             |
+
+Each toast owns its duration from the moment it appears; adding or dismissing another
+toast does not restart timers already in progress.
+
+Every variant sits on the theme's `popover` surface; `success` and `destructive` mark the
+toast with a status dot and tinted border rather than a solid fill. The stack is capped
+at `max-w-md` and centred, which never engages on a phone. A toast is announced politely
+to screen readers without taking focus, and its slide-in follows the motion policy.
+
+---
+
+- **SignInForm** (Auth, copy-paste template) — Email/password sign in with callbacks
+
+## SignInForm
+
+Copy `sign-in-form.tsx` and its sibling `auth-form-footer.tsx` from
+`apps/showcase/catalog/templates/auth/`, then:
+
+```tsx
+import { SignInForm } from './templates/auth'; // or your path
+
+<SignInForm
+  onSubmit={({ email, password }) => signIn(email, password)}
+  onForgotPassword={() => navigate('ForgotPassword')}
+  onSignUp={() => navigate('SignUp')}
+  onGooglePress={() => signInWithGoogle()}
+  onApplePress={() => signInWithApple()}
+/>;
+```
+
+| Prop             | Type                                  | Description                  |
+| ---------------- | ------------------------------------- | ---------------------------- |
+| onSubmit         | `(data: { email, password }) => void` | Called on sign-in submit     |
+| onForgotPassword | `() => void`                          | Called when "Forgot?" tapped |
+| onSignUp         | `() => void`                          | Called when "Sign Up" tapped |
+| onGooglePress    | `() => void`                          | Called when Google tapped    |
+| onApplePress     | `() => void`                          | Called when Apple tapped     |
+
+---
+
+- **SignUpForm** (Auth, copy-paste template) — Registration form with callbacks
+
+## SignUpForm
+
+Copy `sign-up-form.tsx` and its sibling `auth-form-footer.tsx` from
+`apps/showcase/catalog/templates/auth/`, then:
+
+```tsx
+import { SignUpForm } from './templates/auth'; // or your path
+
+<SignUpForm
+  onSubmit={({ firstName, lastName, email, password }) =>
+    signUp(firstName, lastName, email, password)
+  }
+  onSignIn={() => navigate('SignIn')}
+  onGooglePress={() => signInWithGoogle()}
+  onApplePress={() => signInWithApple()}
+/>;
+```
+
+| Prop          | Type                                                       | Description                  |
+| ------------- | ---------------------------------------------------------- | ---------------------------- |
+| onSubmit      | `(data: { firstName, lastName, email, password }) => void` | Called on registration       |
+| onSignIn      | `() => void`                                               | Called when "Sign In" tapped |
+| onGooglePress | `() => void`                                               | Called when Google tapped    |
+| onApplePress  | `() => void`                                               | Called when Apple tapped     |
+
+---
+
+- **ForgotPasswordForm** (Auth, copy-paste template) — Password reset request
+
+No API section yet; the summary above is the full description.
+
+---
+
+- **ResetPasswordForm** (Auth, copy-paste template) — Set new password
+
+No API section yet; the summary above is the full description.
+
+---
+
+- **VerifyEmailForm** (Auth, copy-paste template) — Email verification code input
+
+No API section yet; the summary above is the full description.
+
+---
+
+- **SocialConnections** (Auth, copy-paste template) — OAuth provider buttons
+
+No API section yet; the summary above is the full description.
+
+---
+
+- **UserMenu** (Auth, copy-paste template) — Profile dropdown for auth flows
+
+No API section yet; the summary above is the full description.
+
+---
+
+- **AppShell** (Navigation) — Layout shell with header/footer/bottomNav slots
+
+## AppShell
+
+Layout shell for full-screen pages. Keep shell chrome mounted and swap only content via `loading` + `skeleton`.
+
+```tsx
+import { AppShell, PageSkeleton } from '@thewhileloop/whileui';
+
+<AppShell
+  header={<Header title="Settings" />}
+  bottomNav={<BottomNav items={[...]} activeKey="settings" onSelect={setTab} />}
+  loading={loading}
+  skeleton={<PageSkeleton variant="settings" headerPlaceholder />}
+>
+  <ScrollView className="flex-1 p-4">{/* Content */}</ScrollView>
+</AppShell>;
+```
+
+
+| Prop      | Type              | Default | Description                                               |
+| --------- | ----------------- | ------- | --------------------------------------------------------- |
+| header    | `React.ReactNode` | —       | Header slot.                                              |
+| footer    | `React.ReactNode` | —       | Footer slot.                                              |
+| bottomNav | `React.ReactNode` | —       | Bottom navigation slot.                                   |
+| safeArea  | `boolean`         | `true`  | Wrap in SafeAreaView.                                     |
+| loading   | `boolean`         | `false` | Keep shell mounted while swapping content with skeleton.  |
+| skeleton  | `React.ReactNode` | —       | Optional custom loading placeholder for the content area. |
+| className | `string`          | —       |                                                           |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Header** (Navigation) — Top app bar with back/actions
+
+## Header
+
+```tsx
+import { Header, HeaderBackButton } from '@thewhileloop/whileui';
+
+<Header
+  title="Settings"
+  subtitle="Manage preferences"
+  leftAction={<HeaderBackButton onPress={() => {}} />}
+  rightActions={[
+    { key: 'search', icon: <Icon />, onPress: () => {}, accessibilityLabel: 'Search' },
+  ]}
+/>;
+```
+
+---
+
+- **BottomNav** (Navigation) — Tab-style bottom navigation bar
+
+## BottomNav
+
+```tsx
+import { BottomNav } from '@thewhileloop/whileui';
+
+<BottomNav
+  items={[
+    { key: 'home', label: 'Home', icon: <Icon /> },
+    { key: 'profile', label: 'Profile', icon: <Icon />, badge: 3 },
+  ]}
+  activeKey="home"
+  onSelect={(key) => {}}
+/>;
+```
+
+---
+
+- **FloatingBottomNav** (Navigation) — Elevated bottom nav with safe area support
+
+### FloatingBottomNav
+
+Elevated bottom nav with safe area support
+
+```tsx
+import { FloatingBottomNav } from '@thewhileloop/whileui';
+```
+
+
+| Prop                 | Type                      | Default | Description |
+| -------------------- | ------------------------- | ------- | ----------- |
+| items (required)     | `FloatingBottomNavItem[]` | —       |             |
+| activeKey (required) | `string`                  | —       |             |
+| onSelect (required)  | `(key: string) => void`   | —       |             |
+| className            | `string`                  | —       |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **TabBar** (Navigation) — Top tab bar with indicator
+
+### TabBar
+
+Top tab bar with indicator
+
+```tsx
+import { TabBar } from '@thewhileloop/whileui';
+```
+
+
+| Prop                 | Type                                  | Default     | Description |
+| -------------------- | ------------------------------------- | ----------- | ----------- |
+| items (required)     | `TabBarItem[]`                        | —           |             |
+| activeKey (required) | `string`                              | —           |             |
+| onSelect (required)  | `(key: string) => void`               | —           |             |
+| variant              | `'default' \| 'pills' \| 'underline'` | `'default'` |             |
+| scrollable           | `boolean`                             | `false`     |             |
+| className            | `string`                              | —           |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **DrawerMenu** (Navigation) — Drawer with sections and items
+
+## DrawerMenu
+
+```tsx
+import { DrawerMenu } from '@thewhileloop/whileui';
+
+<DrawerMenu
+  visible={open}
+  onClose={() => setOpen(false)}
+  sections={[
+    {
+      title: 'Menu',
+      items: [
+        { key: 'home', label: 'Home', icon: <Icon /> },
+        { key: 'settings', label: 'Settings', icon: <Icon /> },
+      ],
+    },
+  ]}
+  activeKey="home"
+  onSelect={(key) => {}}
+  header={<View>...</View>}
+  footer={<Text>v1.0</Text>}
+/>;
+```
+
+
+| Prop                | Type                    | Default                | Description                                                 |
+| ------------------- | ----------------------- | ---------------------- | ----------------------------------------------------------- |
+| visible (required)  | `boolean`               | —                      |                                                             |
+| onClose (required)  | `() => void`            | —                      |                                                             |
+| sections (required) | `DrawerMenuSection[]`   | —                      |                                                             |
+| activeKey           | `string`                | —                      |                                                             |
+| onSelect            | `(key: string) => void` | —                      |                                                             |
+| header              | `React.ReactNode`       | —                      |                                                             |
+| footer              | `React.ReactNode`       | —                      |                                                             |
+| maxWidth            | `number`                | —                      | Max width in px. On web, defaults to 360 when not provided. |
+| className           | `string`                | —                      |                                                             |
+| style               | `StyleProp<ViewStyle>`  | —                      |                                                             |
+| frosted             | `boolean`               | `false`                | Enable the optional frosted overlay.                        |
+| blurIntensity       | `number`                | medium preset          | Override blur amount directly.                              |
+| blurTintToken       | `FrostedTintToken`      | `'surfaceTranslucent'` | Tint token used for frosted mode.                           |
+
+
+Closes from the backdrop, an item, Android back or Escape on web. It is hosted in a modal
+on every platform, so keyboard focus stays inside it while it is open.
+
+---
+
+- **ActionBar** (Layout) — Sticky bottom action row with safe-area padding
+
+## ActionBar
+
+```tsx
+import { ActionBar, Button, ButtonText } from '@thewhileloop/whileui';
+
+<ActionBar>
+  <Button variant="outline" className="flex-1">
+    <ButtonText>Cancel</ButtonText>
+  </Button>
+  <Button className="flex-1">
+    <ButtonText>Save</ButtonText>
+  </Button>
+</ActionBar>;
+```
+
+---
+
+- **ConfirmActionSheet** (Layout) — Reusable destructive confirmation sheet
+
+## ConfirmActionSheet
+
+```tsx
+import { ConfirmActionSheet } from '@thewhileloop/whileui';
+
+<ConfirmActionSheet
+  open={open}
+  onOpenChange={setOpen}
+  title="Delete project?"
+  description="This action cannot be undone."
+  confirmLabel="Delete"
+  destructive
+  onConfirm={() => deleteProject()}
+/>;
+```
+
+
+| Prop                    | Type                         | Default                | Description                          |
+| ----------------------- | ---------------------------- | ---------------------- | ------------------------------------ |
+| open (required)         | `boolean`                    | —                      |                                      |
+| onOpenChange (required) | `(open: boolean) => void`    | —                      |                                      |
+| title (required)        | `string`                     | —                      |                                      |
+| description             | `string`                     | —                      |                                      |
+| actions                 | `ConfirmActionSheetAction[]` | —                      |                                      |
+| confirmLabel            | `string`                     | `'Confirm'`            |                                      |
+| cancelLabel             | `string`                     | `'Cancel'`             |                                      |
+| onConfirm               | `() => void`                 | —                      |                                      |
+| onCancel                | `() => void`                 | —                      |                                      |
+| destructive             | `boolean`                    | `true`                 |                                      |
+| className               | `string`                     | —                      |                                      |
+| frosted                 | `boolean`                    | `false`                | Enable the optional frosted overlay. |
+| blurIntensity           | `number`                     | medium preset          | Override blur amount directly.       |
+| blurTintToken           | `FrostedTintToken`           | `'surfaceTranslucent'` | Tint token used for frosted mode.    |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **Sheet** (Layout) — Bottom sheet modal with header/content/footer slots
+
+## Sheet
+
+Bottom sheet modal with slide animation. Slots: `SheetHeader`, `SheetContent`, `SheetFooter`, `SheetClose`.
+
+```tsx
+import {
+  Sheet,
+  SheetHeader,
+  SheetContent,
+  SheetFooter,
+  SheetClose,
+  Button,
+  ButtonText,
+} from '@thewhileloop/whileui';
+
+<Sheet open={open} onOpenChange={setOpen} maxHeight="half">
+  <SheetHeader title="Settings" description="Adjust preferences" />
+  <SheetContent>{/* Scrollable body */}</SheetContent>
+  <SheetFooter>
+    <SheetClose asChild>
+      <Button>
+        <ButtonText>Save</ButtonText>
+      </Button>
+    </SheetClose>
+  </SheetFooter>
+</Sheet>;
+```
+
+
+| Prop                    | Type                         | Default                | Description                                                 |
+| ----------------------- | ---------------------------- | ---------------------- | ----------------------------------------------------------- |
+| open (required)         | `boolean`                    | —                      |                                                             |
+| onOpenChange (required) | `(open: boolean) => void`    | —                      |                                                             |
+| children (required)     | `React.ReactNode`            | —                      |                                                             |
+| maxHeight               | `'half' \| 'full' \| number` | `'full'`               | Max height: 'half' \| 'full' \| number (px). Default 'full' |
+| maxWidth                | `number`                     | —                      | Web: max width. Default ~360 for mobile-first.              |
+| frosted                 | `boolean`                    | `false`                | Enable the optional frosted overlay.                        |
+| blurIntensity           | `number`                     | medium preset          | Override blur amount directly.                              |
+| blurTintToken           | `FrostedTintToken`           | `'surfaceTranslucent'` | Tint token used for frosted mode.                           |
+
+
+`SheetContent` is a `ScrollView` and accepts its props. It enables nested scrolling and
+keeps taps on inputs while the keyboard is open (`keyboardShouldPersistTaps="handled"`).
+Your `contentContainerStyle` is merged after the default padding. Tapping the backdrop
+closes the sheet; a drag across the backdrop does not, so a missed scroll never dismisses
+it. There is no drag-to-dismiss: close with the backdrop, Android back, Escape on web or
+`SheetClose`. A Select, Popover or confirmation Dialog placed inside the sheet opens above
+it, and back or Escape closes that inner layer before the sheet.
+
+---
+
+- **FormModalScreen** (Layout) — Modal scaffold for forms with loading states
+
+### FormModalScreen
+
+Modal scaffold for forms with loading states
+
+```tsx
+import { FormModalScreen } from '@thewhileloop/whileui';
+```
+
+
+| Prop                | Type              | Default       | Description                                                                               |
+| ------------------- | ----------------- | ------------- | ----------------------------------------------------------------------------------------- |
+| className           | `string`          | —             |                                                                                           |
+| title (required)    | `string`          | —             |                                                                                           |
+| subtitle            | `string`          | —             |                                                                                           |
+| leftSlot            | `React.ReactNode` | —             |                                                                                           |
+| rightSlot           | `React.ReactNode` | —             |                                                                                           |
+| onClose             | `() => void`      | —             |                                                                                           |
+| loading             | `boolean`         | `false`       |                                                                                           |
+| saving              | `boolean`         | `false`       |                                                                                           |
+| savingText          | `string`          | `'Saving...'` |                                                                                           |
+| loadingSpinnerColor | `string`          | —             | Hex color for spinner in loading state. ActivityIndicator requires hex.                   |
+| savingSpinnerColor  | `string`          | —             | Hex color for spinner in saving banner. Defaults to platform (Android blue) when not set. |
+| scrollEnabled       | `boolean`         | `true`        |                                                                                           |
+| children (required) | `React.ReactNode` | —             |                                                                                           |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **ContentSkeleton** (Layout) — Page/content placeholder with variants (list, card, generic)
+
+## ContentSkeleton
+
+Page/content placeholder with layout presets. Use while loading data instead of a spinner when you want to preview the layout.
+
+```tsx
+import { ContentSkeleton } from '@thewhileloop/whileui';
+
+<ContentSkeleton variant="list" rows={4} />
+<ContentSkeleton variant="card" />
+<ContentSkeleton variant="generic" />
+```
+
+
+| Prop      | Type                            | Default  | Description                                                                                                |
+| --------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| variant   | `'list' \| 'card' \| 'generic'` | `'list'` | Layout preset. `list` = avatar + lines rows, `card` = card with image/body, `generic` = simple page lines. |
+| rows      | `number`                        | `4`      | Number of list rows (list variant only). Default 4.                                                        |
+| className | `string`                        | —        |                                                                                                            |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **PageSkeleton** (Layout) — Variant-based page layouts (dashboard, list, settings, card, generic)
+
+## PageSkeleton
+
+Variant-based page layouts for loading states. Replaces app-specific skeletons with presets for dashboard, list, settings, card, and generic pages.
+
+```tsx
+import { PageSkeleton } from '@thewhileloop/whileui';
+
+<PageSkeleton variant="dashboard" />
+<PageSkeleton variant="list" count={5} />
+<PageSkeleton variant="settings" count={6} />
+<PageSkeleton variant="card" />
+<PageSkeleton variant="generic" />
+<PageSkeleton variant="dashboard" headerPlaceholder />
+<PageSkeleton variant="list" header={<Header title="Loading..." />} />
+<PageSkeleton variant="list" padding="none" className="flex-1" />
+```
+
+
+| Prop               | Type                                       | Default     | Description                                                         |
+| ------------------ | ------------------------------------------ | ----------- | ------------------------------------------------------------------- |
+| variant (required) | `PageSkeletonVariant`                      | —           | Layout preset.                                                      |
+| count              | `number`                                   | `3`         | Rows/items for list (default 3) or settings (default 4) variant.    |
+| padding            | `PageSkeletonPadding`                      | `'default'` | Container padding.                                                  |
+| header             | `ReactNode`                                | —           | Optional header slot rendered above skeleton content.               |
+| headerPlaceholder  | `boolean \| PageSkeletonHeaderPlaceholder` | `false`     | Optional placeholder header (when no real header is available yet). |
+| className          | `string`                                   | —           |                                                                     |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **ScreenSkeleton** (Layout) — Header slot/placeholder + PageSkeleton content in one block
+
+## ScreenSkeleton
+
+Convenience block for loading screens that need both header and content continuity.
+
+```tsx
+import { ScreenSkeleton } from '@thewhileloop/whileui';
+
+<ScreenSkeleton variant="dashboard" headerPlaceholder />
+<ScreenSkeleton variant="list" count={5} header={<Header title="Projects" />} />
+```
+
+
+| Prop              | Type                                       | Default     | Description                            |
+| ----------------- | ------------------------------------------ | ----------- | -------------------------------------- |
+| variant           | `PageSkeletonVariant`                      | `'generic'` | Skeleton content preset.               |
+| count             | `number`                                   | —           | Rows/items for list/settings variants. |
+| padding           | `PageSkeletonPadding`                      | `'default'` | Inner content padding.                 |
+| header            | `ReactNode`                                | —           | Real header slot.                      |
+| headerPlaceholder | `boolean \| PageSkeletonHeaderPlaceholder` | `'default'` | Placeholder header.                    |
+| className         | `string`                                   | —           |                                        |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **ErrorBoundary** (Layout) — React ErrorBoundary that renders ErrorState by default
+
+## ErrorBoundary
+
+React ErrorBoundary that catches render errors and renders ErrorState by default.
+
+```tsx
+import { ErrorBoundary } from '@thewhileloop/whileui';
+
+<ErrorBoundary onError={(err) => console.error(err)}>
+  <App />
+</ErrorBoundary>;
+```
+
+
+| Prop                | Type                                                            | Default | Description                                        |
+| ------------------- | --------------------------------------------------------------- | ------- | -------------------------------------------------- |
+| children (required) | `ReactNode`                                                     | —       |                                                    |
+| fallback            | `ReactNode \| ((error: Error, reset: () => void) => ReactNode)` | —       | Custom fallback. If not provided, uses ErrorState. |
+| onError             | `(error: Error, errorInfo: ErrorInfo) => void`                  | —       | Called when error is caught.                       |
+
+---
+
+- **EmptyState** (Layout) — Empty content placeholder
+
+## EmptyState
+
+```tsx
+import { EmptyState } from '@thewhileloop/whileui';
+
+<EmptyState
+  icon={<Icon />}
+  title="No items"
+  description="Add your first item."
+  action={{ label: 'Add Item', onPress: () => {} }}
+/>;
+```
+
+---
+
+- **ErrorState** (Layout) — Error display with retry
+
+### ErrorState
+
+Error display with retry
+
+```tsx
+import { ErrorState } from '@thewhileloop/whileui';
+```
+
+
+| Prop        | Type              | Default                  | Description |
+| ----------- | ----------------- | ------------------------ | ----------- |
+| icon        | `React.ReactNode` | —                        |             |
+| title       | `string`          | `'Something went wrong'` |             |
+| description | `string`          | —                        |             |
+| error       | `Error \| string` | —                        |             |
+| onRetry     | `() => void`      | —                        |             |
+| retryLabel  | `string`          | `'Try again'`            |             |
+| className   | `string`          | —                        |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **LoadingState** (Layout) — In-flow loading placeholder for a section still fetching
+
+## LoadingState
+
+```tsx
+import { LoadingState } from '@thewhileloop/whileui';
+
+<LoadingState label="Loading activity" />;
+```
+
+The in-flow counterpart of `EmptyState` and `ErrorState` for a section that is still
+fetching. The spinner is named for assistive technology by `label` (default "Loading").
+
+
+| Prop      | Type                        | Default     | Description                                                                    |
+| --------- | --------------------------- | ----------- | ------------------------------------------------------------------------------ |
+| label     | `string`                    | —           | Read by assistive technology as the spinner's name; shown under it when given. |
+| size      | `'sm' \| 'default' \| 'lg'` | `'default'` |                                                                                |
+| className | `string`                    | —           |                                                                                |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **LoadingScreen** (Layout) — Full-screen loading indicator
+
+### LoadingScreen
+
+Full-screen loading indicator
+
+```tsx
+import { LoadingScreen } from '@thewhileloop/whileui';
+```
+
+
+| Prop         | Type                   | Default | Description                                            |
+| ------------ | ---------------------- | ------- | ------------------------------------------------------ |
+| message      | `string`               | —       |                                                        |
+| size         | `'sm' \| 'md' \| 'lg'` | `'md'`  |                                                        |
+| spinnerColor | `string`               | —       | Hex color for spinner. ActivityIndicator requires hex. |
+| className    | `string`               | —       |                                                        |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **PullToRefreshScrollView** (Layout) — Themed ScrollView with RefreshControl (useThemeTokens for colors)
+
+## PullToRefreshScrollView
+
+Themed ScrollView with RefreshControl. Uses `useThemeTokens` for spinner color.
+
+```tsx
+import { PullToRefreshScrollView } from '@thewhileloop/whileui';
+
+<PullToRefreshScrollView refreshing={refreshing} onRefresh={fetchData} refreshColor="#22c55e">
+  {content}
+</PullToRefreshScrollView>;
+```
+
+
+| Prop                  | Type                          | Default | Description                                                                                                                                                                                                     |
+| --------------------- | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| refreshing (required) | `boolean`                     | —       | Whether refresh is in progress.                                                                                                                                                                                 |
+| onRefresh (required)  | `() => void \| Promise<void>` | —       | Refreshing is almost always async, so the signature says so. Nothing here awaits it — the spinner is driven by `refreshing`, which the owner controls — so a handler that can reject must catch its own errors. |
+| refreshColor          | `string`                      | —       | Override tint/colors. Defaults to theme primary.                                                                                                                                                                |
+| className             | `string`                      | —       |                                                                                                                                                                                                                 |
+
+Also accepts the props of `ScrollViewProps`.
+
+The scroll view owns the refresh gesture; don't pass `refreshControl`. It bounces even
+when content is shorter than the screen, so a short list can still be pulled. Screen
+reader users get the same refresh as a **Refresh** accessibility action, since they
+cannot pull. It is ignored while `refreshing` is true, and any `accessibilityActions` you
+pass are kept.
+
+---
+
+- **KeyboardAwareScreen** (Layout) — One screen-level keyboard policy for bottom-docked controls
+
+## KeyboardAwareScreen and DockedInput
+
+Use one keyboard-aware root for the screen, then place the composer in a bottom dock. Feed the dock height into the scroll content inset so the last item remains visible.
+
+```tsx
+import { DockedInput, KeyboardAwareScreen, SmartInput } from '@thewhileloop/whileui';
+
+<KeyboardAwareScreen>
+  <ScrollView contentContainerStyle={{ paddingBottom: inputHeight }} />
+  <DockedInput onHeightChange={setInputHeight}>
+    <SmartInput variant="card" safeArea={false} />
+  </DockedInput>
+</KeyboardAwareScreen>;
+```
+
+---
+
+- **DockedInput** (Layout) — Safe-area-aware bottom dock that reports its complete height
+
+Documented under KeyboardAwareScreen.
+
+---
+
+- **SmartInput** (Layout) — Compose input with slots, variants, and optional rotating examples
+
+## SmartInput
+
+Compose input for use inline or inside `DockedInput`. `variant`: "bar" or "card". Slots: `leftSlot`, `centerSlot` (intent selector), `rightSlot`. `submitBehavior`: "newline" (default) or "submit"/"blurAndSubmit". `placeholderExamples` animates rotating prompts and respects the platform reduced-motion setting. Forwards ref to `TextInput`.
+
+```tsx
+import { SmartInput, Button, ButtonText } from '@thewhileloop/whileui';
+
+<SmartInput
+  value={message}
+  onChangeText={setMessage}
+  placeholderExamples={['Log breakfast', 'Add a 30 minute walk', 'Set weight to 72 kg']}
+  leftSlot={
+    <Button variant="ghost" size="icon" accessibilityLabel="Add">
+      <Icon name="add" />
+    </Button>
+  }
+  rightSlot={
+    <Button size="icon" onPress={handleSend}>
+      <ButtonText>Send</ButtonText>
+    </Button>
+  }
+/>;
+```
+
+---
+
+- **SplashScreen** (Layout) — Branded splash (fade/scale/slide variants)
+
+## SplashScreen
+
+```tsx
+import { SplashScreen } from '@thewhileloop/whileui';
+
+<SplashScreen
+  logo={<MyLogo />}
+  appName="MyApp"
+  tagline="Your tagline"
+  variant="scale"
+  duration={1500}
+  showLoading
+  onAnimationComplete={() => {}}
+/>;
+```
+
+
+| Prop                | Type                           | Default   | Description                                     |
+| ------------------- | ------------------------------ | --------- | ----------------------------------------------- |
+| appName             | `string`                       | —         | App name displayed below logo                   |
+| tagline             | `string`                       | —         | Tagline displayed below app name                |
+| logo                | `React.ReactNode`              | —         | Logo element (icon, image, or custom component) |
+| variant             | `'fade' \| 'scale' \| 'slide'` | `'scale'` | Animation variant                               |
+| duration            | `number`                       | `800`     | Animation duration in ms                        |
+| onAnimationComplete | `() => void`                   | —         | Callback when animation completes               |
+| showLoading         | `boolean`                      | `false`   | Whether to show loading indicator               |
+| loadingText         | `string`                       | —         | Loading text                                    |
+| className           | `string`                       | —         |                                                 |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **MinimalSplash** (Layout) — Minimal monochrome splash
+
+### MinimalSplash
+
+Minimal monochrome splash
+
+```tsx
+import { MinimalSplash } from '@thewhileloop/whileui';
+```
+
+
+| Prop                | Type              | Default | Description                                     |
+| ------------------- | ----------------- | ------- | ----------------------------------------------- |
+| className           | `string`          | —       |                                                 |
+| appName             | `string`          | —       | App name displayed below logo                   |
+| tagline             | `string`          | —       | Tagline displayed below app name                |
+| logo                | `React.ReactNode` | —       | Logo element (icon, image, or custom component) |
+| duration            | `number`          | `800`   | Animation duration in ms                        |
+| onAnimationComplete | `() => void`      | —       | Callback when animation completes               |
+| showLoading         | `boolean`         | `false` | Whether to show loading indicator               |
+| loadingText         | `string`          | —       | Loading text                                    |
+
+Also accepts the props of `SplashScreenProps`.
+
+---
+
+- **BrandedSplash** (Layout) — Splash with brand imagery
+
+### BrandedSplash
+
+Splash with brand imagery
+
+```tsx
+import { BrandedSplash } from '@thewhileloop/whileui';
+```
+
+
+| Prop                | Type              | Default | Description                                     |
+| ------------------- | ----------------- | ------- | ----------------------------------------------- |
+| className           | `string`          | —       |                                                 |
+| appName             | `string`          | —       | App name displayed below logo                   |
+| tagline             | `string`          | —       | Tagline displayed below app name                |
+| logo                | `React.ReactNode` | —       | Logo element (icon, image, or custom component) |
+| duration            | `number`          | `800`   | Animation duration in ms                        |
+| onAnimationComplete | `() => void`      | —       | Callback when animation completes               |
+| loadingText         | `string`          | —       | Loading text                                    |
+
+Also accepts the props of `SplashScreenProps`.
+
+---
+
+- **Chat** (Chat) — Opinionated messages, suggestions, and SmartInput composition
+
+### Chat
+
+| Block                 | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| **Chat**              | Opinionated messages, suggestions, and SmartInput composition   |
+| **ChatConversation**  | Constrained conversation viewport that follows streaming output |
+| **ChatMessageBubble** | Message bubble (user/assistant, big/small text)                 |
+| **ChatSuggestions**   | Suggestion chips when empty                                     |
+
+---
+
+- **ChatConversation** (Chat) — Constrained conversation viewport that follows streaming output
+
+## ChatConversation / Chat
+
+`ChatConversation` is the low-level viewport for custom conversation screens. Its content stays constrained on wide windows, follows new or streaming output while the reader is near the bottom, and stops following after the reader scrolls upward. Compose it with `SmartInput`; the application owns message data, streaming, tools, approvals, and sources.
+
+It is a `ScrollView` for a bounded active transcript. Paginate or window historical messages; use a virtualized list when the full history can grow without a bound.
+
+```tsx
+import { ChatConversation, SmartInput, View } from '@thewhileloop/whileui';
+
+<View className="flex-1">
+  <ChatConversation contentContainerClassName="gap-4 px-4 py-6">
+    {messages.map((message) => (
+      <ProductMessage key={message.id} message={message} />
+    ))}
+  </ChatConversation>
+  <SmartInput
+    value={value}
+    onChangeText={setValue}
+    onSubmitEditing={send}
+    submitBehavior="submit"
+    leftSlot={<AttachButton />}
+    centerSlot={<ModelSelect />}
+    rightSlot={<SendButton />}
+  />
+</View>;
+```
+
+`Chat` is the opinionated convenience composition: message bubbles, suggestion chips, and `SmartInput` with attach/send slots. It uses semantic tokens; theme via `global.css`. Use `renderMessage` for markdown, code, tool calls, reasoning, or sources, and `loadingIndicator` for streaming feedback.
+
+```tsx
+import { Chat, type ChatMessage } from '@thewhileloop/whileui';
+
+const [messages, setMessages] = useState<ChatMessage[]>([...]);
+const [value, setValue] = useState('');
+
+<Chat
+  messages={messages}
+  value={value}
+  onChangeText={setValue}
+  onSend={() => { /* append user msg, clear input */ }}
+  placeholder="Message..."
+  suggestions={['Summarize this', 'Explain simply', 'Translate']}
+  onSuggestionPress={(text) => setValue(text)}
+  emptyTitle="How can I help?"
+  emptyDescription="Ask anything."
+  leftSlot={<Button variant="ghost" size="icon" accessibilityLabel="Attach"><Icon name="paperclip" /></Button>}
+  rightSlot={<Button size="icon" accessibilityLabel="Send" onPress={handleSend}><Icon name="send" /></Button>}
+/>;
+```
+
+
+| Prop                    | Type                                        | Default             | Description                                                                              |
+| ----------------------- | ------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------- |
+| messages (required)     | `ChatMessage[]`                             | —                   | Messages to show, each `{ id, role, content, secondary?, contentSize? }`.                |
+| value (required)        | `string`                                    | —                   | Input value.                                                                             |
+| onChangeText (required) | `(text: string) => void`                    | —                   | Input change.                                                                            |
+| onSend (required)       | `() => void`                                | —                   | Send handler.                                                                            |
+| placeholder             | `string`                                    | `'Message...'`      |                                                                                          |
+| suggestions             | `string[]`                                  | `EMPTY_SUGGESTIONS` | Chips when empty.                                                                        |
+| onSuggestionPress       | `(text: string) => void`                    | —                   |                                                                                          |
+| leftSlot                | `React.ReactNode`                           | —                   |                                                                                          |
+| rightSlot               | `React.ReactNode`                           | —                   |                                                                                          |
+| loading                 | `boolean`                                   | `false`             |                                                                                          |
+| header                  | `React.ReactNode`                           | —                   |                                                                                          |
+| emptyTitle              | `string`                                    | —                   |                                                                                          |
+| emptyDescription        | `string`                                    | —                   |                                                                                          |
+| exampleMessage          | `ChatMessage`                               | —                   | Example message shown in empty state so users see the bubble UI.                         |
+| renderMessage           | `(message: ChatMessage) => React.ReactNode` | —                   | Custom message renderer (markdown, code, images). Falls back to ChatMessageBubble.       |
+| loadingIndicator        | `React.ReactNode`                           | —                   | Shown at bottom when loading (typing indicator).                                         |
+| inputSafeArea           | `boolean`                                   | `true`              | Passed to SmartInput. Use false when Chat is in a contained demo.                        |
+| keyboardVerticalOffset  | `number`                                    | `0`                 | Offset for KeyboardAvoidingView when Chat has a header (e.g. StatusBar + header height). |
+| className               | `string`                                    | —                   |                                                                                          |
+| messagesClassName       | `string`                                    | —                   |                                                                                          |
+
+
+`ChatConversation` extends React Native `ScrollViewProps`, forwards its ref, and adds `contentContainerClassName` to style the constrained inner column. Caller `onScroll` and `onContentSizeChange` callbacks are preserved.
+
+### Optional Markdown and code
+
+These are explicit subpaths so the root package remains independent of a Markdown
+parser. Install `markdown-it` only in applications that render Markdown.
+
+```tsx
+import { Markdown } from '@thewhileloop/whileui/markdown';
+import { CodeBlock } from '@thewhileloop/whileui/code';
+
+<Markdown onLinkPress={openLink}>{assistantText}</Markdown>
+<CodeBlock code={source} language="TypeScript" actions={<CopyButton />} />
+```
+
+`Markdown` supports headings, paragraphs, emphasis, links, lists, quotes, rules, inline
+code, and fenced code. It never opens links or writes to the clipboard itself:
+`onLinkPress` and `codeActions` keep those capabilities in the application. `CodeBlock`
+is dependency-free and accepts an application-owned `actions` slot.
+
+---
+
+- **ChatMessageBubble** (Chat) — Message bubble (user/assistant, big/small text)
+
+### ChatMessageBubble
+
+One message in a `Chat`, rendered on its own when a screen composes the conversation itself.
+
+```tsx
+import { ChatMessageBubble } from '@thewhileloop/whileui';
+```
+
+
+| Prop               | Type          | Default | Description                                                     |
+| ------------------ | ------------- | ------- | --------------------------------------------------------------- |
+| message (required) | `ChatMessage` | —       | The message to render; its `role` decides alignment and colour. |
+| contentClassName   | `string`      | —       | Classes for the bubble's content wrapper.                       |
+
+---
+
+- **ChatSuggestions** (Chat) — Suggestion chips when empty
+
+### ChatSuggestions
+
+Suggestion chips when empty
+
+```tsx
+import { ChatSuggestions } from '@thewhileloop/whileui';
+```
+
+
+| Prop                   | Type                     | Default             | Description |
+| ---------------------- | ------------------------ | ------------------- | ----------- |
+| suggestions (required) | `string[]`               | `EMPTY_SUGGESTIONS` |             |
+| onSelect (required)    | `(text: string) => void` | —                   |             |
+| className              | `string`                 | —                   |             |
+
+---
+
+- **ProfileHeader** (Profile & Settings, copy-paste template) — Profile header with stats
+
+## ProfileHeader
+
+Copy from `apps/showcase/catalog/templates/profile/profile-header.tsx`, then:
+
+```tsx
+import { ProfileHeader } from './templates/profile'; // or your path
+
+<ProfileHeader
+  name="John Doe"
+  username="johndoe"
+  bio="Designer & Developer"
+  avatarFallback="JD"
+  avatarUrl="https://..."
+  verified
+  stats={[
+    { label: 'Followers', value: '1.2K' },
+    { label: 'Following', value: 234 },
+  ]}
+  action={{ label: 'Edit Profile', onPress: () => {} }}
+/>;
+```
+
+---
+
+- **AccountCard** (Profile & Settings, copy-paste template) — Account summary card
+
+No API section yet; the summary above is the full description.
+
+---
+
+- **SettingsSection** (Profile & Settings, copy-paste template) — Section header with optional action
+
+## SettingsSection / SettingsItem
+
+Copy from `apps/showcase/catalog/templates/profile/`, then:
+
+```tsx
+import { SettingsSection, SettingsItem } from './templates/profile'; // or your path
+
+<SettingsSection title="Preferences">
+  <SettingsItem
+    icon={<Icon />}
+    label="Notifications"
+    type="toggle"
+    toggleValue={enabled}
+    onToggle={setEnabled}
+  />
+  <SettingsItem icon={<Icon />} label="Privacy" value="Public" onPress={() => {}} />
+  <SettingsItem icon={<Icon />} label="Sign Out" type="action" destructive />
+</SettingsSection>;
+```
+
+---
+
+- **SettingsItem** (Profile & Settings, copy-paste template) — Row for toggles/links/settings
+
+Documented under SettingsSection.
+
+---
+
+- **ListItem** (Lists) — Title/subtitle row
+
+### ListItem
+
+Title/subtitle row
+
+```tsx
+import { ListItem } from '@thewhileloop/whileui';
+```
+
+
+| Prop             | Type              | Default | Description                                     |
+| ---------------- | ----------------- | ------- | ----------------------------------------------- |
+| icon             | `React.ReactNode` | —       |                                                 |
+| title (required) | `string`          | —       |                                                 |
+| subtitle         | `string`          | —       |                                                 |
+| description      | `string`          | —       |                                                 |
+| rightIcon        | `React.ReactNode` | —       |                                                 |
+| rightText        | `string`          | —       |                                                 |
+| action           | `React.ReactNode` | —       |                                                 |
+| showBorder       | `boolean`         | `true`  |                                                 |
+| compact          | `boolean`         | `false` |                                                 |
+| loading          | `boolean`         | `false` | Show a skeleton placeholder instead of content. |
+| className        | `string`          | —       |                                                 |
+
+Also accepts the props of `PressableProps`.
+
+---
+
+- **NotificationItem** (Lists) — Notification row with metadata
+
+### NotificationItem
+
+Notification row with metadata
+
+```tsx
+import { NotificationItem } from '@thewhileloop/whileui';
+```
+
+
+| Prop               | Type              | Default | Description                                     |
+| ------------------ | ----------------- | ------- | ----------------------------------------------- |
+| icon               | `React.ReactNode` | —       |                                                 |
+| avatarUrl          | `string`          | —       |                                                 |
+| avatarFallback     | `string`          | —       |                                                 |
+| title (required)   | `string`          | —       |                                                 |
+| message (required) | `string`          | —       |                                                 |
+| time (required)    | `string`          | —       |                                                 |
+| read               | `boolean`         | `false` |                                                 |
+| showDot            | `boolean`         | `true`  |                                                 |
+| loading            | `boolean`         | `false` | Show a skeleton placeholder instead of content. |
+| className          | `string`          | —       |                                                 |
+
+Also accepts the props of `PressableProps`.
+
+---
+
+- **TimelineFeed** (Lists) — Vertical feed with connecting lines
+
+### TimelineFeed
+
+Vertical feed with connecting lines
+
+```tsx
+import { TimelineFeed } from '@thewhileloop/whileui';
+```
+
+
+| Prop             | Type             | Default | Description |
+| ---------------- | ---------------- | ------- | ----------- |
+| className        | `string`         | —       |             |
+| items (required) | `TimelineItem[]` | —       |             |
+| showConnector    | `boolean`        | `true`  |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **ProductCard** (Commerce) — Product card with badge/media
+
+## ProductCard
+
+```tsx
+import { ProductCard } from '@thewhileloop/whileui';
+
+<ProductCard
+  title="Product Name"
+  price="$99"
+  originalPrice="$129"
+  badge="-23%"
+  rating={4.5}
+  reviewCount={128}
+  variant="vertical"
+  onPress={() => {}}
+/>;
+```
+
+
+| Prop             | Type                         | Default      | Description                                     |
+| ---------------- | ---------------------------- | ------------ | ----------------------------------------------- |
+| imageUrl         | `string`                     | —            |                                                 |
+| title (required) | `string`                     | —            |                                                 |
+| description      | `string`                     | —            |                                                 |
+| price (required) | `string`                     | —            |                                                 |
+| originalPrice    | `string`                     | —            |                                                 |
+| badge            | `string`                     | —            |                                                 |
+| rating           | `number`                     | —            |                                                 |
+| reviewCount      | `number`                     | —            |                                                 |
+| inStock          | `boolean`                    | `true`       |                                                 |
+| variant          | `'vertical' \| 'horizontal'` | `'vertical'` |                                                 |
+| loading          | `boolean`                    | `false`      | Show a skeleton placeholder instead of content. |
+| className        | `string`                     | —            |                                                 |
+
+Also accepts the props of `PressableProps`.
+
+---
+
+- **PricingCard** (Commerce) — Pricing tiers with feature list
+
+## PricingCard
+
+```tsx
+import { PricingCard } from '@thewhileloop/whileui';
+
+<PricingCard
+  name="Pro"
+  description="For teams"
+  price="$29"
+  period="/month"
+  badge="Popular"
+  highlighted
+  features={[
+    { label: 'Unlimited users', included: true },
+    { label: 'Priority support', included: true },
+    { label: 'Custom domain', included: false },
+  ]}
+  onPress={() => {}}
+/>;
+```
+
+---
+
+- **CheckoutSummary** (Commerce) — Cart summary with line items
+
+### CheckoutSummary
+
+Cart summary with line items
+
+```tsx
+import { CheckoutSummary } from '@thewhileloop/whileui';
+```
+
+
+| Prop                | Type                 | Default      | Description |
+| ------------------- | -------------------- | ------------ | ----------- |
+| items (required)    | `CheckoutLineItem[]` | —            |             |
+| subtotal (required) | `string`             | —            |             |
+| shipping            | `string`             | —            |             |
+| tax                 | `string`             | —            |             |
+| discount            | `string`             | —            |             |
+| total (required)    | `string`             | —            |             |
+| buttonLabel         | `string`             | `'Checkout'` |             |
+| onCheckout          | `() => void`         | —            |             |
+| loading             | `boolean`            | `false`      |             |
+| className           | `string`             | —            |             |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **MetricCard** (Commerce) — Stats/progress card for dashboards
+
+### MetricCard
+
+Stats/progress card for dashboards
+
+```tsx
+import { MetricCard } from '@thewhileloop/whileui';
+```
+
+
+| Prop             | Type                                 | Default     | Description                                     |
+| ---------------- | ------------------------------------ | ----------- | ----------------------------------------------- |
+| className        | `string`                             | —           |                                                 |
+| label (required) | `string`                             | —           |                                                 |
+| value (required) | `string \| number`                   | —           |                                                 |
+| subtitle         | `string`                             | —           |                                                 |
+| progress         | `number`                             | —           |                                                 |
+| segments         | `{ value: number; color: string }[]` | —           |                                                 |
+| icon             | `React.ReactNode`                    | —           |                                                 |
+| loading          | `boolean`                            | `false`     | Show a skeleton placeholder instead of content. |
+| variant          | `'default' \| 'outlined'`            | `'default'` |                                                 |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **SubscriptionCard** (Commerce) — Current plan card with manage/upgrade actions
+
+## SubscriptionCard
+
+```tsx
+import { SubscriptionCard } from '@thewhileloop/whileui';
+
+<SubscriptionCard
+  planName="Pro"
+  price="$29"
+  period="/month"
+  expiresAt="April 18, 2026"
+  isActive
+  onManage={() => {}}
+  onUpgrade={() => {}}
+/>;
+```
+
+
+| Prop                | Type         | Default         | Description                                     |
+| ------------------- | ------------ | --------------- | ----------------------------------------------- |
+| planName (required) | `string`     | —               | Current plan label.                             |
+| price (required)    | `string`     | —               | Plan price.                                     |
+| period              | `string`     | `'/month'`      | Billing period label.                           |
+| expiresAt           | `string`     | —               | Renewal/expiry date text.                       |
+| isActive            | `boolean`    | `true`          | Active/inactive badge state.                    |
+| onManage            | `() => void` | —               | Manage action.                                  |
+| onUpgrade           | `() => void` | —               | Upgrade action.                                 |
+| manageLabel         | `string`     | `'Manage plan'` |                                                 |
+| upgradeLabel        | `string`     | `'Upgrade'`     |                                                 |
+| loading             | `boolean`    | `false`         | Show a skeleton placeholder instead of content. |
+| className           | `string`     | —               |                                                 |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **FeatureGate** (Commerce) — Locked feature state with upgrade CTA
+
+## FeatureGate
+
+```tsx
+import { FeatureGate } from '@thewhileloop/whileui';
+
+<FeatureGate
+  title="Advanced export is locked"
+  description="Upgrade to unlock 4K export."
+  buttonLabel="Upgrade"
+  onUpgrade={() => {}}
+/>;
+```
+
+Use `children` to show dimmed preview content with an overlay CTA.
+
+---
+
+- **UsageBar** (Commerce) — Quota meter with warning/exceeded states
+
+## UsageBar
+
+```tsx
+import { UsageBar } from '@thewhileloop/whileui';
+
+<UsageBar label="AI generations" used={8} limit={20} />;
+```
+
+
+| Prop             | Type              | Default | Description                     |
+| ---------------- | ----------------- | ------- | ------------------------------- |
+| label (required) | `string`          | —       | Usage label.                    |
+| used (required)  | `number`          | —       | Used amount.                    |
+| limit (required) | `number`          | —       | Quota limit.                    |
+| variant          | `UsageBarVariant` | —       | Optional explicit visual state. |
+| className        | `string`          | —       |                                 |
+
+Also accepts the props of `ViewProps`.
+
+---
+
+- **PlanToggle** (Commerce) — Monthly vs annual plan switcher
+
+## PlanToggle
+
+```tsx
+import { PlanToggle } from '@thewhileloop/whileui';
+
+<PlanToggle
+  selected="monthly"
+  monthlyLabel="Monthly"
+  annualLabel="Annual"
+  annualDiscount="Save 20%"
+  onChange={(next) => {}}
+/>;
+```
+
+---
+
+- **UpgradeBanner** (Commerce) — Inline upgrade banner with action/dismiss
+
+## UpgradeBanner
+
+```tsx
+import { UpgradeBanner } from '@thewhileloop/whileui';
+
+<UpgradeBanner
+  message="Unlock unlimited exports with Pro."
+  actionLabel="See plans"
+  onAction={() => {}}
+  onDismiss={() => {}}
+/>;
+```
+
+---
+
+- **SmartImage** (Media) — Image with explicit loading, loaded, fallback, and error lifecycle
+
+## SmartImage
+
+```tsx
+import { SmartImage } from '@thewhileloop/whileui';
+
+<SmartImage
+  source={{ uri: imageUrl }}
+  fallbackSource={{ uri: fallbackUrl }}
+  alt="Product preview"
+  className="h-48 w-full"
+/>;
+```
+
+
+| Prop              | Type                                               | Default   | Description |
+| ----------------- | -------------------------------------------------- | --------- | ----------- |
+| className         | `string`                                           | —         |             |
+| source (required) | `ImageProps['source']`                             | —         |             |
+| alt (required)    | `string`                                           | —         |             |
+| skeleton          | `boolean`                                          | `true`    |             |
+| skeletonClassName | `string`                                           | —         |             |
+| transition        | `number`                                           | `200`     |             |
+| onLoad            | `() => void`                                       | —         |             |
+| onError           | `() => void`                                       | —         |             |
+| fallbackSource    | `ImageProps['source']`                             | —         |             |
+| radius            | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`    |             |
+| objectFit         | `'fill' \| 'cover' \| 'contain' \| 'scale-down'`   | `'cover'` |             |
+
+Also accepts the props of `ViewProps`.
+
+The skeleton returns whenever the primary image starts loading again. A failed primary
+source switches to `fallbackSource` when supplied without re-entering a primary/fallback
+loop.
+
+---
+
+- **DatePickerModal** (Date Picker) — Bottom sheet modal with calendar, compact trigger
+
+## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal
+
+Date selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.
+
+**DatePickerModal** — Compact trigger opens bottom sheet with calendar. Use `DatePickerTrigger` as the trigger content.
+
+**DatePickerInline** — Calendar embedded inline for forms or dashboards.
+
+**DateRangePickerModal** — Range selection with period marking. Use `DateRangePickerTrigger` as the trigger content.
+
+**TimePickerModal** — Hour and minute wheels (plus AM/PM under a 12-hour `hourCycle`) in the same bottom sheet, so a form's date and time fields open the same way. `value` is always `HH:MM` in 24-hour form. Each wheel is one `adjustable` element for assistive tech and the keyboard. Use `TimePickerTrigger` as the trigger content.
+
+```tsx
+import {
+  DatePickerModal,
+  DatePickerTrigger,
+  DatePickerInline,
+  DateRangePickerModal,
+  DateRangePickerTrigger,
+  TimePickerModal,
+  TimePickerTrigger,
+  type DateRange,
+} from '@thewhileloop/whileui';
+
+// Single date (modal)
+const [date, setDate] = useState<string | null>(null);
+const [open, setOpen] = useState(false);
+
+<DatePickerModal
+  value={date}
+  onValueChange={setDate}
+  open={open}
+  onOpenChange={setOpen}
+  trigger={<DatePickerTrigger value={date} placeholder="Pick a date" />}
+  title="Select date"
+/>;
+
+// Inline calendar
+<DatePickerInline value={date} onValueChange={setDate} />;
+
+// Date range (modal)
+const [range, setRange] = useState<DateRange | null>(null);
+
+<DateRangePickerModal
+  value={range}
+  onValueChange={setRange}
+  open={rangeOpen}
+  onOpenChange={setRangeOpen}
+  trigger={<DateRangePickerTrigger value={range} placeholder="Pick range" />}
+/>;
+
+// Time (modal) — "HH:MM", 24-hour, whatever the wheels show
+const [time, setTime] = useState<string | null>(null);
+
+<TimePickerModal
+  value={time}
+  onValueChange={setTime}
+  open={timeOpen}
+  onOpenChange={setTimeOpen}
+  minuteStep={5}
+  trigger={<TimePickerTrigger value={time} placeholder="Pick a time" />}
+/>;
+```
+
+
+| Prop                    | Type                             | Default                | Description                                               |
+| ----------------------- | -------------------------------- | ---------------------- | --------------------------------------------------------- |
+| value                   | `string \| null`                 | —                      | Controlled: selected date in YYYY-MM-DD                   |
+| onValueChange           | `(date: string \| null) => void` | —                      | Controlled: change handler                                |
+| open (required)         | `boolean`                        | —                      | Modal open state                                          |
+| onOpenChange (required) | `(open: boolean) => void`        | —                      | Modal open change handler                                 |
+| minDate                 | `string`                         | —                      | Minimum selectable date YYYY-MM-DD                        |
+| maxDate                 | `string`                         | —                      | Maximum selectable date YYYY-MM-DD                        |
+| theme                   | `CalendarTheme`                  | —                      | Override calendar theme (RN color strings)                |
+| trigger                 | `React.ReactNode`                | —                      | Trigger element. If not provided, no trigger is rendered. |
+| title                   | `string`                         | `'Select date'`        | Title shown in modal header                               |
+| confirmLabel            | `string`                         | `'Done'`               | Button label for confirm                                  |
+| className               | `string`                         | —                      |                                                           |
+| frosted                 | `boolean`                        | `false`                | Enable the optional frosted overlay.                      |
+| blurIntensity           | `number`                         | medium preset          | Override blur amount directly.                            |
+| blurTintToken           | `FrostedTintToken`               | `'surfaceTranslucent'` | Tint token used for frosted mode.                         |
+
+---
+
+- **DatePickerInline** (Date Picker) — Inline calendar for forms or dashboards
+
+Documented under DatePickerModal.
+
+---
+
+- **DateRangePickerModal** (Date Picker) — Range selection modal with period marking
+
+Documented under DatePickerModal.
+
+---
+
+- **TimePickerModal** (Date Picker) — Hour and minute wheels in the same bottom sheet
+
+Documented under DatePickerModal.