@thewhileloop/whileui 1.2.3 → 2.0.0

package/README.md

@@ -6,6 +6,11 @@ Beautiful, accessible, themeable components built with [Uniwind](https://uniwind
 
 **Requirements:** React 19+, React Native 0.81+, Expo 52+ (if using Expo). Supports React Native Web.
 
+WhileUI has one renderer: React Native. iOS, Android and React Native Web are all
+production targets — iOS and Android set the interaction baseline. See
+[ROADMAP.md](./ROADMAP.md) for the product boundary and extraction rules, and
+[PLAN.md](./PLAN.md) for the supported stack and production contracts.
+
 ## Installation
 
 ```bash
@@ -101,15 +106,15 @@ module.exports = withUniwindConfig({
 
 ```tsx
 import './global.css';
-import { PortalHost } from '@thewhileloop/whileui';
+import { MotionProvider, PortalHost } from '@thewhileloop/whileui';
 import { Button, ButtonText } from '@thewhileloop/whileui';
 
 export default function App() {
   return (
-    <>
+    <MotionProvider>
       {/* Your app content */}
       <PortalHost />
-    </>
+    </MotionProvider>
   );
 }
 ```
@@ -209,6 +214,8 @@ function MyScreen() {
 - **Layout:** `Stack` (vertical), `Row` (horizontal) — both support `gap`, `align`, `justify`
 - **Auth callbacks:** Auth templates use objects: `onSubmit({ email, password })`, `onSubmit({ firstName, lastName, email, password })`, etc. Copy templates from `apps/showcase/templates/auth/`.
 - **PortalHost:** Add `<PortalHost />` at app root for Select, Popover, Tooltip, HoverCard.
+- **Motion:** Wrap the root in `<MotionProvider>`; use `useMotionPolicy()` for semantic
+  durations, the responsive spring, and reduced-motion behavior.
 - **Uniwind:** `withUniwindConfig` must wrap metro config. `global.css` at app root, imported in `App.tsx`.
 - **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/templates/` (auth, profile); flow patterns in README "Flow Patterns" section.
 
@@ -223,7 +230,12 @@ function MyScreen() {
 | **Pressable** | Themed pressable wrapper         |
 | **Stack**     | Vertical flex layout with gap    |
 | **Row**       | Horizontal flex layout with gap  |
-| **Box**       | Flexible container with variants |
+
+### Root Providers
+
+| Provider           | Notes                                                                    |
+| ------------------ | ------------------------------------------------------------------------ |
+| **MotionProvider** | System reduced motion, explicit preview modes, and deterministic testing |
 
 ### Form Controls
 
@@ -267,6 +279,7 @@ function MyScreen() {
 | **Tabs**        | TabsList, TabsTrigger, TabsContent       |
 | **Accordion**   | AccordionItem, AccordionTrigger, Content |
 | **Collapsible** | CollapsibleTrigger, CollapsibleContent   |
+| **Container**   | Centred content column with a max width  |
 
 ### Overlays & Menus
 
@@ -305,37 +318,37 @@ Copy from `apps/showcase/templates/auth/`:
 
 ### Navigation
 
-| Block                 | Description                                       |
-| --------------------- | ------------------------------------------------- |
-| **AppShell**          | Layout shell with header/footer/bottomNav slots   |
-| **NavigationSidebar** | Sidebar nav with grouped sections and footer slot |
-| **Header**            | Top app bar with back/actions                     |
-| **BottomNav**         | Tab-style bottom navigation bar                   |
-| **FloatingBottomNav** | Elevated bottom nav with safe area support        |
-| **TabBar**            | Top tab bar with indicator                        |
-| **DrawerMenu**        | Drawer with sections and items                    |
+| Block                 | Description                                     |
+| --------------------- | ----------------------------------------------- |
+| **AppShell**          | Layout shell with header/footer/bottomNav slots |
+| **Header**            | Top app bar with back/actions                   |
+| **BottomNav**         | Tab-style bottom navigation bar                 |
+| **FloatingBottomNav** | Elevated bottom nav with safe area support      |
+| **TabBar**            | Top tab bar with indicator                      |
+| **DrawerMenu**        | Drawer with sections and items                  |
 
 ### Layout
 
-| Block                       | Description                                                             |
-| --------------------------- | ----------------------------------------------------------------------- |
-| **ActionBar**               | Sticky bottom action row with safe-area padding                         |
-| **ConfirmActionSheet**      | Reusable destructive confirmation sheet                                 |
-| **Sheet**                   | Bottom sheet modal with header/content/footer slots                     |
-| **FormModalScreen**         | Modal scaffold for forms with loading states                            |
-| **ContentSkeleton**         | Page/content placeholder with variants (list, card, generic)            |
-| **PageSkeleton**            | Variant-based page layouts (dashboard, list, settings, card, generic)   |
-| **ScreenSkeleton**          | Header slot/placeholder + PageSkeleton content in one block             |
-| **ErrorBoundary**           | React ErrorBoundary that renders ErrorState by default                  |
-| **EmptyState**              | Empty content placeholder                                               |
-| **ErrorState**              | Error display with retry                                                |
-| **LoadingScreen**           | Full-screen loading indicator                                           |
-| **PullToRefreshScrollView** | Themed ScrollView with RefreshControl (useThemeTokens for colors)       |
-| **SmartInput**              | Keyboard-aware compose input: left/center/right slots, bar/card variant |
-| **OnboardingScreen**        | Onboarding flow screen                                                  |
-| **SplashScreen**            | Branded splash (fade/scale/slide variants)                              |
-| **MinimalSplash**           | Minimal monochrome splash                                               |
-| **BrandedSplash**           | Splash with brand imagery                                               |
+| Block                       | Description                                                           |
+| --------------------------- | --------------------------------------------------------------------- |
+| **ActionBar**               | Sticky bottom action row with safe-area padding                       |
+| **ConfirmActionSheet**      | Reusable destructive confirmation sheet                               |
+| **Sheet**                   | Bottom sheet modal with header/content/footer slots                   |
+| **FormModalScreen**         | Modal scaffold for forms with loading states                          |
+| **ContentSkeleton**         | Page/content placeholder with variants (list, card, generic)          |
+| **PageSkeleton**            | Variant-based page layouts (dashboard, list, settings, card, generic) |
+| **ScreenSkeleton**          | Header slot/placeholder + PageSkeleton content in one block           |
+| **ErrorBoundary**           | React ErrorBoundary that renders ErrorState by default                |
+| **EmptyState**              | Empty content placeholder                                             |
+| **ErrorState**              | Error display with retry                                              |
+| **LoadingScreen**           | Full-screen loading indicator                                         |
+| **PullToRefreshScrollView** | Themed ScrollView with RefreshControl (useThemeTokens for colors)     |
+| **KeyboardAwareScreen**     | One screen-level keyboard policy for bottom-docked controls           |
+| **DockedInput**             | Safe-area-aware bottom dock that reports its complete height          |
+| **SmartInput**              | Compose input with slots, variants, and optional rotating examples    |
+| **SplashScreen**            | Branded splash (fade/scale/slide variants)                            |
+| **MinimalSplash**           | Minimal monochrome splash                                             |
+| **BrandedSplash**           | Splash with brand imagery                                             |
 
 ### Chat
 
@@ -362,7 +375,6 @@ Copy from `apps/showcase/templates/profile/`:
 | -------------------- | ----------------------------------- |
 | **ListItem**         | Title/subtitle row                  |
 | **NotificationItem** | Notification row with metadata      |
-| **SwipeableItem**    | Swipe actions list item             |
 | **TimelineFeed**     | Vertical feed with connecting lines |
 
 ### Commerce
@@ -393,12 +405,19 @@ Copy from `apps/showcase/templates/profile/`:
 | **DatePickerInline**     | Inline calendar for forms or dashboards           |
 | **DateRangePickerModal** | Range selection modal with period marking         |
 
-## Layout Primitives (Stack, Row, Box)
+**Tokens without a renderer.** `@thewhileloop/whileui/tokens` exports the theme
+and visual contracts, the presets, and `deriveThemeColors(base, scheme)` — give it
+the 25 base colours an app defines and it returns all 52, using the same ratios
+as the default presets. Safe in a build script (no React, RN or Uniwind
+imports); `useThemeColors()` uses it too, so a missing `--color-primary-soft`
+derives from the app's own primary instead of falling back to the default palette.
+
+## Layout Primitives (Stack, Row)
 
 Use `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.
 
 ```tsx
-import { Stack, Row, Box } from '@thewhileloop/whileui';
+import { Stack, Row } from '@thewhileloop/whileui';
 
 <Stack gap="lg">
   <Text>Title</Text>
@@ -419,7 +438,32 @@ import { Stack, Row, Box } from '@thewhileloop/whileui';
 | align   | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`           | Cross-axis alignment     |
 | justify | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | Main-axis alignment      |
 
-`Box` provides optional padding and margin variants for consistent spacing.
+### 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 | Notes                       |
+| ----------- | -------------------------------------- | ------- | --------------------------- |
+| `size`      | `sm` \| `md` \| `lg` \| `xl` \| `full` | `md`    | `sm` forms, `lg` dashboards |
+| `fill`      | `boolean`                              | `false` | `flex-1`, for a screen root |
+| `className` | `string`                               | —       | Merged after the variant    |
+
+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" />
+```
 
 ## Full-Screen Composition
 
@@ -548,7 +592,7 @@ The WhileUI token contract is strict for cross-app reuse. Define these in **ever
 - Required core tokens: `background`, `foreground`, `card`, `card-foreground`, `popover`, `popover-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `muted`, `muted-foreground`, `accent`, `accent-foreground`, `destructive`, `destructive-foreground`, `border`, `input`, `ring`
 - Optional status tokens: `success`, `success-foreground`, `warning`, `warning-foreground`, `info`, `info-foreground`
 - Optional effect tokens: `overlay`, `overlay-strong`, `surface-elevated`, `surface-border`, `surface-highlight`, `surface-translucent`, `surface-translucent-border`, `state-hover`, `state-pressed`, `state-disabled`
-- Optional interaction/motion tokens: `--ui-press-opacity`, `--ui-press-opacity-strong`, `--ui-disabled-opacity`, `--ui-disabled-opacity-soft`, `--ui-disabled-opacity-subtle`, `--ui-inactive-opacity`, `--ui-motion-fast`, `--ui-motion-normal`, `--ui-motion-slow`, `--ui-drawer-open-duration`, `--ui-drawer-close-duration`, `--ui-blur-intensity-subtle`, `--ui-blur-intensity-medium`, `--ui-blur-intensity-strong`, `--ui-blur-saturation-pct`, `--ui-frosted-highlight-height`, `--ui-frosted-backdrop-blur-intensity`, `--ui-frosted-backdrop-blur-scale`, `--ui-frosted-android-experimental-blur`, `--ui-drawer-frosted-inset`, `--ui-drawer-frosted-radius`, `--ui-drawer-content-top-padding`
+- Optional interaction/motion tokens: `--ui-press-opacity`, `--ui-press-opacity-strong`, `--ui-disabled-opacity`, `--ui-disabled-opacity-soft`, `--ui-disabled-opacity-subtle`, `--ui-inactive-opacity`, `--ui-motion-fast`, `--ui-motion-normal`, `--ui-motion-slow`, `--ui-motion-spring-damping`, `--ui-motion-spring-stiffness`, `--ui-motion-spring-mass`, `--ui-drawer-open-duration`, `--ui-drawer-close-duration`, `--ui-blur-intensity-subtle`, `--ui-blur-intensity-medium`, `--ui-blur-intensity-strong`, `--ui-blur-saturation-pct`, `--ui-frosted-highlight-height`, `--ui-frosted-backdrop-blur-intensity`, `--ui-frosted-backdrop-blur-scale`, `--ui-frosted-android-tint-alpha-scale`, `--ui-frosted-android-experimental-blur`, `--ui-drawer-frosted-inset`, `--ui-drawer-frosted-radius`, `--ui-drawer-content-top-padding`
 - Optional scale tokens: spacing (`--spacing`, `--spacing-*`), typography (`--text-*`, `--leading-*`, `--tracking-*`), radius (`--radius-*`), elevation (`--shadow-*`)
 
 Minimal contract example:
@@ -608,6 +652,8 @@ Some apps want a frosted or translucent look for floating panels (modals, sheets
 
 **Optional:** Add `expo-blur` and register its `BlurView` once at app startup for full frosted blur. For tint-only (no blur), translucent surface tokens are sufficient.
 
+**Android note:** frosted panels usually need denser tint than iOS/web. WhileUI now scales frosted tint alpha on Android with `--ui-frosted-android-tint-alpha-scale` (default `1.18`). Set it to `1` to match other platforms exactly, or raise it if your Android surfaces still feel washed out.
+
 ```tsx
 import { BlurView } from 'expo-blur';
 import { registerFrostedBlurView } from '@thewhileloop/whileui';
@@ -635,6 +681,7 @@ Additional frosted tuning tokens:
 - `--ui-frosted-highlight-height` (top highlight strip height in px, set `0` to disable hard top sheen)
 - `--ui-frosted-backdrop-blur-intensity` (default backdrop blur amount)
 - `--ui-frosted-backdrop-blur-scale` (ratio used when component blur is overridden)
+- `--ui-frosted-android-tint-alpha-scale` (Android-only alpha multiplier applied to frosted tint and backdrop layers)
 - `--ui-frosted-android-experimental-blur` (`1` enables `expo-blur` Android experimental path)
 - `--ui-drawer-frosted-inset` (floating inset for frosted drawer shells)
 - `--ui-drawer-frosted-radius` (drawer corner radius in px)
@@ -678,6 +725,9 @@ WhileUI components also read optional `--ui-*` tokens for deeper control of pres
   --ui-motion-fast: 160;
   --ui-motion-normal: 220;
   --ui-motion-slow: 300;
+  --ui-motion-spring-damping: 20;
+  --ui-motion-spring-stiffness: 260;
+  --ui-motion-spring-mass: 0.8;
   --ui-drawer-open-duration: 300;
   --ui-drawer-close-duration: 220;
   --ui-blur-intensity-subtle: 18;
@@ -687,6 +737,7 @@ WhileUI components also read optional `--ui-*` tokens for deeper control of pres
   --ui-frosted-highlight-height: 0;
   --ui-frosted-backdrop-blur-intensity: 14;
   --ui-frosted-backdrop-blur-scale: 0.55;
+  --ui-frosted-android-tint-alpha-scale: 1.22;
   --ui-frosted-android-experimental-blur: 1;
   --ui-drawer-frosted-inset: 0;
   --ui-drawer-frosted-radius: 28;
@@ -700,6 +751,23 @@ For custom components, use:
 import { useInteractionTokens, withInteractivePressableStyle } from '@thewhileloop/whileui';
 ```
 
+Wrap the application in `MotionProvider` to coordinate system reduced motion, explicit
+preview overrides, and deterministic animation-free tests. The provider is optional:
+without it `useMotionPolicy` returns the token defaults with Reanimated following the
+system setting, and `--ui-motion-*` overrides are not read. `reduced` preserves
+non-spatial feedback while asking Reanimated to skip motion; `disabled` also resolves
+semantic durations to zero.
+
+```tsx
+import { MotionProvider, useMotionPolicy } from '@thewhileloop/whileui';
+
+<MotionProvider mode="system">{/* application */}</MotionProvider>;
+
+const motion = useMotionPolicy();
+motion.durations.normal;
+motion.springs.responsive;
+```
+
 Optional RN fallback tokens (hex/rgb/hsl/named):
 
 ```css
@@ -798,6 +866,33 @@ const adapter: ThemeBridgeAdapter = {
 const { mode, resolvedTheme, setMode, cycleMode } = useThemeBridge({ adapter });
 ```
 
+## Focus rings
+
+Every interactive component draws a themed focus ring on web. It uses `:focus-visible`,
+so it appears for keyboard users and not after a mouse click, and it is driven by the
+`--color-ring` token — restyle it with your theme, not with component overrides.
+
+Use the same treatment on your own controls:
+
+```tsx
+import { focusRing, focusRingInset, cn } from '@thewhileloop/whileui';
+
+<Pressable className={cn('rounded-full px-4 py-2', focusRing)} onPress={onPress}>
+  <Text>Custom control</Text>
+</Pressable>;
+```
+
+| Export           | Use for                                                                         |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `focusRing`      | Standalone controls — buttons, inputs, cards, nav items                         |
+| `focusRingInset` | Controls flush inside a track, where an offset ring would clip (segments, tabs) |
+
+**Do not use a bare `outline-none`.** It removes the browser's indicator and leaves
+keyboard users with nothing, which fails WCAG 2.4.7. `focusRing` removes the default and
+supplies a themed replacement in the same class. The one exemption is a visually hidden
+input, where a visible proxy shows the focus instead — `OTPInput` does this with its
+blinking cursor.
+
 ## Tech Stack
 
 - **Styling**: [Uniwind](https://uniwind.dev) (free tier) + Tailwind CSS v4
@@ -808,28 +903,57 @@ const { mode, resolvedTheme, setMode, cycleMode } = useThemeBridge({ adapter });
 
 # API Reference
 
+## 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                                |
+| ---------------- | ------------------------------------------- | ----------- | ------------------------------------------ |
+| feedback         | `'none' \| 'default' \| 'strong'`           | `'none'`    | Semantic pressed opacity                   |
+| disabledFeedback | `'none' \| 'default' \| 'soft' \| 'subtle'` | `'default'` | Semantic unavailable opacity               |
+| loading          | `boolean`                                   | `false`     | Expose busy/disabled state and block input |
+| className        | `string`                                    | —           | Additional Tailwind classes                |
+
 ## Button
 
 ```tsx
 import { Button, ButtonText, ButtonIcon } from '@thewhileloop/whileui';
 
-<Button variant="default" size="default" disabled={false} onPress={() => {}}>
+<Button variant="default" size="default" disabled={false} loading={false} onPress={() => {}}>
   <ButtonIcon>
     <Icon />
   </ButtonIcon>
   <ButtonText>Click me</ButtonText>
-  <ButtonIcon position="right">
+  {/* Placement is child order — a trailing ButtonIcon renders after the label. */}
+  <ButtonIcon>
     <Icon />
   </ButtonIcon>
 </Button>;
 ```
 
-| Prop      | Type                                                                          | Default     | Description                 |
-| --------- | ----------------------------------------------------------------------------- | ----------- | --------------------------- |
-| variant   | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Button style variant        |
-| size      | `'default' \| 'sm' \| 'lg' \| 'icon'`                                         | `'default'` | Button size                 |
-| disabled  | `boolean`                                                                     | `false`     | Disable the button          |
-| className | `string`                                                                      | —           | Additional Tailwind classes |
+| Prop      | Type                                                                          | Default     | Description                                        |
+| --------- | ----------------------------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| variant   | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Button style variant                               |
+| size      | `'default' \| 'sm' \| 'lg' \| 'icon'`                                         | `'default'` | Button size                                        |
+| disabled  | `boolean`                                                                     | `false`     | Disable the button                                 |
+| loading   | `boolean`                                                                     | `false`     | Show a spinner, expose busy state, and block input |
+| className | `string`                                                                      | —           | Additional Tailwind classes                        |
 
 ## Input
 
@@ -1138,12 +1262,12 @@ import {
 
 `AlertDialogContent` supports the same frosted props as `DialogContent`.
 
-| Prop          | Type                     | Default   | Description                                                                                                                                                                                                                                                                                                                                                                 |
-| ------------- | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| presentation  | `'modal' \| 'native' \| 'overlay'`    | `'modal'` | **`modal`** — themed card in an RN `Modal` (iOS `overFullScreen`). **`native`** — `Alert.alert` on iOS/Android (system UI); use when a second `Modal` won’t stack; ignored on web. **`overlay`** — same themed card as `modal`, but absolutely positioned **inside the parent view** (no second `Modal`). Nest `<AlertDialog>` under your fullscreen sheet’s root so the confirm matches app styling. **Web:** `'native'` is ignored; `overlay` behaves like `modal`. |
-| frosted       | `boolean`                | `false`   | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                     |
-| blurIntensity | `number`                 | —         | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                     |
-| blurTintToken | `'surfaceElevated' \| …` | —         | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                     |
+| Prop          | Type                               | Default   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------- | ---------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| presentation  | `'modal' \| 'native' \| 'overlay'` | `'modal'` | **`modal`** — themed card in an RN `Modal` (iOS `overFullScreen`). **`native`** — `Alert.alert` on iOS/Android (system UI); use when a second `Modal` won’t stack; ignored on web. **`overlay`** — same themed card as `modal`, but absolutely positioned **inside the parent view** (no second `Modal`). Nest `<AlertDialog>` under your fullscreen sheet’s root so the confirm matches app styling. **Web:** `'native'` is ignored; `overlay` behaves like `modal`. |
+| frosted       | `boolean`                          | `false`   | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| blurIntensity | `number`                           | —         | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| blurTintToken | `'surfaceElevated' \| …`           | —         | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ### React Native: stacked modals
 
@@ -1384,6 +1508,40 @@ import {
 
 ## 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).
 
 ---
@@ -1494,9 +1652,24 @@ import { ActionBar, Button, ButtonText } from '@thewhileloop/whileui';
 </ActionBar>;
 ```
 
+## 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>;
+```
+
 ## SmartInput
 
-Keyboard-aware compose input. `variant`: "bar" (sticky bottom) or "card" (floating). Slots: `leftSlot`, `centerSlot` (intent selector), `rightSlot`. `submitBehavior`: "newline" (default) or "submit"/"blurAndSubmit". Forwards ref to `TextInput`.
+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';
@@ -1504,7 +1677,7 @@ import { SmartInput, Button, ButtonText } from '@thewhileloop/whileui';
 <SmartInput
   value={message}
   onChangeText={setMessage}
-  placeholder="Type a message..."
+  placeholderExamples={['Log breakfast', 'Add a 30 minute walk', 'Set weight to 72 kg']}
   leftSlot={
     <Button variant="ghost" size="icon">
       <Icon name="add" />
@@ -1677,27 +1850,12 @@ import {
 | blurIntensity | `number`                                                           | medium preset          |
 | blurTintToken | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'surfaceTranslucent'` |
 
-## NavigationSidebar
-
-```tsx
-import { NavigationSidebar } from '@thewhileloop/whileui';
-
-<NavigationSidebar
-  sections={[
-    {
-      title: 'Workspace',
-      items: [
-        { key: 'overview', label: 'Overview', icon: <Icon /> },
-        { key: 'billing', label: 'Billing', icon: <Icon />, badge: 2 },
-      ],
-    },
-  ]}
-  activeKey="overview"
-  onSelect={(key) => {}}
-  header={<Text>Acme Inc.</Text>}
-  footer={<Text className="text-xs text-muted-foreground">v1.0.0</Text>}
-/>;
-```
+`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`.
 
 ## Header
 
@@ -1825,11 +1983,17 @@ import { PullToRefreshScrollView } from '@thewhileloop/whileui';
 </PullToRefreshScrollView>;
 ```
 
-| Prop         | Type         | Description                                |
-| ------------ | ------------ | ------------------------------------------ |
-| refreshing   | `boolean`    | Whether refresh is in progress             |
-| onRefresh    | `() => void` | Called when user pulls to refresh          |
-| refreshColor | `string`     | Optional hex override; defaults to primary |
+| Prop         | Type                          | Description                                                                                                     |
+| ------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| refreshing   | `boolean`                     | Whether refresh is in progress                                                                                  |
+| onRefresh    | `() => void \| Promise<void>` | Called when user pulls to refresh. Not awaited — drive the spinner with `refreshing`, and catch your own errors |
+| refreshColor | `string`                      | Optional hex override; defaults to primary                                                                      |
+
+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.
 
 ## EmptyState
 
@@ -2064,13 +2228,12 @@ Tracked work items for future releases.
 
 - [x] ProductCard, ListItem, NotificationItem, MetricCard, SubscriptionCard, PricingCard
 - [x] AppShell, Chat, FormModalScreen, CheckoutSummary (already had `loading`)
-- [ ] Add `loading` to remaining blocks: Header, BottomNav, DrawerMenu, TimelineFeed, SwipeableItem
+- [ ] Add `loading` to remaining blocks: Header, BottomNav, DrawerMenu, TimelineFeed
 
 ### Documentation Gaps
 
-- [ ] Add `## API` sections for: Textarea, Toggle, ToggleGroup, Label, Separator, Skeleton, AspectRatio, Collapsible, Text, View, Pressable
-- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, OnboardingScreen, ListItem, NotificationItem, MetricCard, SmartImage, TimelineFeed
-- [ ] Build `apps/site/` (docs website) with `registry.ts`, `demos.tsx`, `block-demos.tsx`, `props-data.ts`
+- [ ] Add `## API` sections for: Textarea, Toggle, ToggleGroup, Label, Separator, Skeleton, AspectRatio, Collapsible, Text, View
+- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, ListItem, NotificationItem, MetricCard, SmartImage, TimelineFeed
 
 ### Infrastructure
 

package/dist/blocks/chat/chat.d.ts

@@ -43,7 +43,6 @@ export interface ChatProps {
 export declare function ChatMessageBubble({ message, contentClassName, }: {
     message: ChatMessage;
     contentClassName?: string;
-}): import("react/jsx-runtime").JSX.Element;
-export declare function ChatSuggestions({ suggestions, onSelect, className }: ChatSuggestionsProps): import("react/jsx-runtime").JSX.Element;
-export declare function Chat({ messages, value, onChangeText, onSend, placeholder, suggestions, onSuggestionPress, leftSlot, rightSlot, loading, header, emptyTitle, emptyDescription, exampleMessage, renderMessage, loadingIndicator, inputSafeArea, keyboardVerticalOffset, className, messagesClassName, }: ChatProps): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=chat.d.ts.map
+}): React.JSX.Element;
+export declare function ChatSuggestions({ suggestions, onSelect, className }: ChatSuggestionsProps): React.JSX.Element;
+export declare function Chat({ messages, value, onChangeText, onSend, placeholder, suggestions, onSuggestionPress, leftSlot, rightSlot, loading, header, emptyTitle, emptyDescription, exampleMessage, renderMessage, loadingIndicator, inputSafeArea, keyboardVerticalOffset, className, messagesClassName, }: ChatProps): React.JSX.Element;

package/dist/blocks/chat/chat.js

@@ -6,15 +6,15 @@ import { SmartInput } from '../layout/smart-input';
 import { cn } from '../../lib/cn';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
+import { typographyStyle } from '../../lib/recipes';
 import { tv } from '../../lib/tv';
-// ─── ChatMessage Variants ────────────────────────────────────
-const contentSizeClasses = {
-    sm: 'text-sm',
-    default: 'text-base',
-    lg: 'text-lg',
+const CONTENT_SIZE_ROLE = {
+    sm: 'label',
+    default: 'body',
+    lg: 'emphasis',
 };
 const chatMessageBubbleVariants = tv({
-    base: 'rounded-2xl px-4 py-3',
+    base: '',
     variants: {
         role: {
             user: 'self-end bg-primary',
@@ -24,25 +24,35 @@ const chatMessageBubbleVariants = tv({
     },
     defaultVariants: { role: 'assistant' },
 });
-// ─── ChatMessage ─────────────────────────────────────────────
 export function ChatMessageBubble({ message, contentClassName, }) {
     const role = message.role === 'system' ? 'system' : message.role;
     const isUser = message.role === 'user';
-    const sizeClass = contentSizeClasses[message.contentSize ?? 'default'];
+    const contentRole = CONTENT_SIZE_ROLE[message.contentSize ?? 'default'];
     const visual = useVisualTokens();
     const { width: screenWidth } = useWindowDimensions();
     const ratio = role === 'system' ? visual.chatSystemBubbleMaxWidthRatio : visual.chatBubbleMaxWidthRatio;
     const maxWidth = screenWidth * ratio;
-    return (_jsxs(View, { accessible: true, accessibilityRole: "none", accessibilityLabel: isUser ? 'Your message' : message.role === 'system' ? 'System message' : 'Assistant message', className: chatMessageBubbleVariants({ role }), style: { maxWidth }, children: [_jsx(Text, { className: cn('leading-relaxed', sizeClass, isUser ? 'text-primary-foreground' : 'text-foreground', contentClassName), children: message.content }), message.secondary && (_jsx(Text, { className: cn('mt-1 text-xs', isUser ? 'text-primary-foreground-muted' : 'text-muted-foreground'), children: message.secondary }))] }));
+    return (_jsxs(View, { accessible: true, accessibilityRole: "none", accessibilityLabel: isUser ? 'Your message' : message.role === 'system' ? 'System message' : 'Assistant message', className: chatMessageBubbleVariants({ role }), style: {
+            maxWidth,
+            borderRadius: visual.radiusLg,
+            paddingHorizontal: visual.controlPaddingXDefault,
+            paddingVertical: visual.controlPaddingYDefault,
+        }, children: [_jsx(Text, { className: cn('leading-relaxed', isUser ? 'text-primary-foreground' : 'text-foreground', contentClassName), style: typographyStyle(visual, contentRole), children: message.content }), message.secondary && (_jsx(Text, { className: cn('mt-1', isUser ? 'text-primary-foreground-muted' : 'text-muted-foreground'), style: typographyStyle(visual, 'caption'), children: message.secondary }))] }));
 }
-// ─── ChatSuggestions ──────────────────────────────────────────
 export function ChatSuggestions({ suggestions, onSelect, className }) {
-    return (_jsx(View, { className: cn('flex-row flex-wrap justify-center gap-2 px-4 py-6', className), children: suggestions.map((text, i) => (_jsx(Pressable, { onPress: () => onSelect(text), accessibilityRole: "button", accessibilityLabel: `Suggestion: ${text}`, className: "rounded-full border border-border bg-muted px-4 py-2 active:bg-muted", children: _jsx(Text, { className: "text-sm text-foreground", children: text }) }, `${text}-${i}`))) }));
+    const visual = useVisualTokens();
+    return (_jsx(View, { className: cn('flex-row flex-wrap justify-center gap-2 px-4 py-6', className), children: suggestions.map((text) => (_jsx(Pressable, { onPress: () => onSelect(text), accessibilityRole: "button", accessibilityLabel: `Suggestion: ${text}`, className: "rounded-full border-border bg-muted active:bg-muted", style: {
+                borderWidth: visual.borderWidthHairline,
+                paddingHorizontal: visual.controlPaddingXDefault,
+                paddingVertical: visual.controlPaddingYSm,
+            }, children: _jsx(Text, { className: "text-foreground", style: typographyStyle(visual, 'label'), children: text }) }, text))) }));
 }
 const EMPTY_SUGGESTIONS = [];
-// ─── Chat ────────────────────────────────────────────────────
 export function Chat({ messages, value, onChangeText, onSend, placeholder = 'Message...', suggestions = EMPTY_SUGGESTIONS, onSuggestionPress, leftSlot, rightSlot, loading = false, header, emptyTitle, emptyDescription, exampleMessage, renderMessage, loadingIndicator, inputSafeArea = true, keyboardVerticalOffset = 0, className, messagesClassName, }) {
     const scrollRef = useRef(null);
+    const visual = useVisualTokens();
+    const emptyTitleTypography = typographyStyle(visual, 'emphasis');
+    const emptyDescriptionTypography = typographyStyle(visual, 'label');
     const isEmpty = messages.length === 0;
     const showSuggestions = isEmpty && suggestions.length > 0;
     useEffect(() => {
@@ -55,14 +65,16 @@ export function Chat({ messages, value, onChangeText, onSend, placeholder = 'Mes
                     flexGrow: 1,
                     paddingBottom: 8,
                     justifyContent: showSuggestions ? 'center' : 'flex-end',
-                }, keyboardShouldPersistTaps: "handled", children: showSuggestions ? (_jsxs(View, { className: "flex-1 justify-center", children: [exampleMessage && (_jsx(View, { className: "mb-6 px-4", children: renderMessage ? (renderMessage(exampleMessage)) : (_jsx(ChatMessageBubble, { message: exampleMessage })) })), emptyTitle && (_jsx(Text, { className: "mb-1 text-center text-lg font-medium text-foreground", children: emptyTitle })), emptyDescription && (_jsx(Text, { className: "mb-4 text-center text-sm text-muted-foreground", children: emptyDescription })), _jsx(ChatSuggestions, { suggestions: suggestions, onSelect: onSuggestionPress ?? (() => { }) })] })) : (_jsxs(View, { className: "gap-3 px-4 pt-4", children: [messages.map((msg) => renderMessage ? (_jsx(React.Fragment, { children: renderMessage(msg) }, msg.id)) : (_jsx(ChatMessageBubble, { message: msg }, msg.id))), loading && loadingIndicator && _jsx(View, { className: "px-4", children: loadingIndicator })] })) }), _jsx(SmartInput, { value: value, onChangeText: onChangeText, placeholder: placeholder, leftSlot: leftSlot, rightSlot: defaultRightSlot, editable: !loading, safeArea: inputSafeArea })] }));
+                }, keyboardShouldPersistTaps: "handled", children: showSuggestions ? (_jsxs(View, { className: "flex-1 justify-center", children: [exampleMessage && (_jsx(View, { className: "mb-6 px-4", children: renderMessage ? (renderMessage(exampleMessage)) : (_jsx(ChatMessageBubble, { message: exampleMessage })) })), emptyTitle && (_jsx(Text, { className: "mb-1 text-center font-medium text-foreground", style: emptyTitleTypography, children: emptyTitle })), emptyDescription && (_jsx(Text, { className: "mb-4 text-center text-muted-foreground", style: emptyDescriptionTypography, children: emptyDescription })), _jsx(ChatSuggestions, { suggestions: suggestions, onSelect: onSuggestionPress ?? (() => { }) })] })) : (_jsxs(View, { className: "gap-3 px-4 pt-4", children: [messages.map((msg) => renderMessage ? (_jsx(React.Fragment, { children: renderMessage(msg) }, msg.id)) : (_jsx(ChatMessageBubble, { message: msg }, msg.id))), loading && loadingIndicator && _jsx(View, { className: "px-4", children: loadingIndicator })] })) }), _jsx(SmartInput, { value: value, onChangeText: onChangeText, placeholder: placeholder, leftSlot: leftSlot, rightSlot: defaultRightSlot, editable: !loading, safeArea: inputSafeArea })] }));
 }
-// ─── ChatSendButton ───────────────────────────────────────────
 function ChatSendButton({ onPress, disabled }) {
     const interaction = useInteractionTokens();
-    return (_jsx(Pressable, { onPress: onPress, disabled: disabled, accessibilityRole: "button", accessibilityLabel: disabled ? 'Send (disabled)' : 'Send message', style: withInteractivePressableStyle(undefined, interaction, {
+    const visual = useVisualTokens();
+    return (_jsx(Pressable, { onPress: onPress, disabled: disabled, accessibilityRole: "button", accessibilityLabel: disabled ? 'Send (disabled)' : 'Send message', style: withInteractivePressableStyle({
+            height: visual.controlHeightDefault,
+            width: visual.controlHeightDefault,
+        }, interaction, {
             disabled: Boolean(disabled),
             pressedVariant: 'strong',
-        }), className: cn('h-11 w-11 items-center justify-center rounded-full', disabled ? 'bg-muted' : 'bg-primary'), children: _jsx(Text, { className: "text-lg text-primary-foreground", children: "\u2191" }) }));
+        }), className: cn('items-center justify-center rounded-full', disabled ? 'bg-muted' : 'bg-primary'), children: _jsx(Text, { className: "text-primary-foreground", style: typographyStyle(visual, 'emphasis'), children: "\u2191" }) }));
 }
-//# sourceMappingURL=chat.js.map