@thewhileloop/whileui 4.1.0 → 4.1.2

package/README.md

@@ -11,6 +11,18 @@ 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.
 
+## See it in action
+
+One React Native component contract across native and web, with semantic typography,
+token-driven light and dark themes, accessible controls, and application-owned chat
+composition. The same component tree can feel airy and atmospheric or compact and
+editorial by changing tokens alone.
+
+<p align="center">
+  <img src="./docs/assets/whileui-showcase.gif" width="300" alt="WhileUI Cosmic Aura mobile theme demonstrating light and dark modes, controls, Select, and composable chat" />
+  <img src="./docs/assets/whileui-showcase-atelier.gif" width="300" alt="WhileUI Atelier mobile theme demonstrating compact controls, authentication forms, Select, and composable chat" />
+</p>
+
 ## Installation
 
 ```bash
@@ -26,23 +38,26 @@ Use `npm install` instead of `bun add` if you prefer npm.
 
 ### Setup Uniwind (required)
 
-1. **metro.config.js** (wrap with withUniwindConfig):
+1. **metro.config.js** (wrap with `withWhileUIMetro`):
 
 ```js
 const { getDefaultConfig } = require('expo/metro-config');
-const { withUniwindConfig } = require('uniwind/metro');
+const { withWhileUIMetro } = require('@thewhileloop/whileui/metro');
 
 /** @type {import('expo/metro-config').MetroConfig} */
 const config = getDefaultConfig(__dirname);
 
-module.exports = withUniwindConfig(config, {
+module.exports = withWhileUIMetro(config, {
   cssEntryFile: './global.css',
 });
 ```
 
-> `withUniwindConfig(config, options)` takes the config first and returns the wrapped
-> config — it is not curried. It must wrap the outermost config object, and
-> `cssEntryFile` must be a relative path string.
+> `withWhileUIMetro` calls Uniwind's `withUniwindConfig(config, options)` for you — same
+> options, config first, `cssEntryFile` a relative path — and keeps `expo-asset`,
+> `expo-font` and `@expo/vector-icons` on the real `react-native`. Without that, Uniwind's
+> import rewrite leaves every icon glyph silently missing on iOS and Android while web
+> renders fine. Pass `exemptFromUniwindRewrite: ['pkg']` for any other package that
+> imports a non-component export from `react-native`. It must be the outermost wrapper.
 
 2. **global.css** at app root:
 
@@ -132,6 +147,12 @@ export default function App() {
 
 > **Note:** If you use Select, Popover, Tooltip, or HoverCard, add `<PortalHost />` at the root of your app (as the last child).
 
+Inside a Dialog, AlertDialog, Sheet, ConfirmActionSheet, DrawerMenu, menu or picker, those
+four render into that overlay's own layer automatically, so a Select in a sheet opens above
+the sheet. Android back and Escape on web close the innermost open layer first. Pass
+`portalHost` on their content only to target a `PortalHost` you placed yourself, such as
+inside a navigation-presented modal screen that WhileUI does not host.
+
 ### Vite + React Native Web + WhileUI setup
 
 Use the WhileUI Vite compatibility helper when your app includes portal-based primitives.
@@ -225,11 +246,15 @@ 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.
+  Inside any WhileUI overlay they render into that overlay's layer without configuration.
 - **Motion:** Wrap the root in `<MotionProvider>`; use `useMotionPolicy()` for semantic
   durations, the responsive spring, and reduced-motion behavior.
-- **Uniwind:** `withUniwindConfig(config, options)` wraps metro config — config first, not
-  curried. `global.css` at app root, imported in `App.tsx`. Installing from npm also needs
+- **Metro:** `withWhileUIMetro(config, { cssEntryFile: './global.css' })` from
+  `@thewhileloop/whileui/metro` — wraps Uniwind and keeps icon fonts loading on device.
+  `global.css` at app root, imported in `App.tsx`. Installing from npm also needs
   `@source './node_modules/@thewhileloop/whileui/dist';` or every component renders unstyled.
+- **States:** `LoadingState`, `EmptyState` and `ErrorState` share one shape; `ErrorState`
+  takes `onRetry`. `Text variant="eyebrow"` is the muted section label above a title.
 - **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/templates/` (auth, profile); flow patterns in README "Flow Patterns" section.
 
 ### Composition grammar
@@ -372,6 +397,7 @@ Copy from `apps/showcase/templates/auth/`:
 | **ErrorBoundary**           | React ErrorBoundary that renders ErrorState by default                |
 | **EmptyState**              | Empty content placeholder                                             |
 | **ErrorState**              | Error display with retry                                              |
+| **LoadingState**            | In-flow loading placeholder for a section still fetching              |
 | **LoadingScreen**           | Full-screen loading indicator                                         |
 | **PullToRefreshScrollView** | Themed ScrollView with RefreshControl (useThemeTokens for colors)     |
 | **KeyboardAwareScreen**     | One screen-level keyboard policy for bottom-docked controls           |
@@ -425,9 +451,9 @@ Copy from `apps/showcase/templates/profile/`:
 
 ### Media
 
-| Block          | Description                         |
-| -------------- | ----------------------------------- |
-| **SmartImage** | Image with aspect ratio and loading |
+| Block          | Description                                                        |
+| -------------- | ------------------------------------------------------------------ |
+| **SmartImage** | Image with explicit loading, loaded, fallback, and error lifecycle |
 
 ### Date Picker
 
@@ -926,6 +952,9 @@ const adapter: ThemeBridgeAdapter = {
 const { mode, resolvedTheme, setMode, cycleMode } = useThemeBridge({ adapter });
 ```
 
+The bridge loads a new adapter before saving into it. If a user changes the mode while
+storage is still loading, that explicit choice wins over the late persisted value.
+
 When another store already owns the mode, mount the controlled bridge once near the
 application root. Change `mode` in the owning event handler; the bridge applies and
 persists it without mirroring state back through a callback effect.
@@ -1031,10 +1060,10 @@ import { Button, ButtonText, ButtonIcon } from '@thewhileloop/whileui';
 classes are unnecessary for normal hierarchy. `heading` also sets
 `accessibilityRole="header"` unless the caller supplies another role.
 
-| Prop    | Type                                                                                          | Default     |
-| ------- | --------------------------------------------------------------------------------------------- | ----------- |
-| variant | `'default' \| 'heading' \| 'title' \| 'subtitle' \| 'body' \| 'caption' \| 'label' \| 'code'` | `'default'` |
-| size    | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`                                    | by variant  |
+| Prop    | Type                                                                                                       | Default     |
+| ------- | ---------------------------------------------------------------------------------------------------------- | ----------- |
+| variant | `'default' \| 'heading' \| 'title' \| 'subtitle' \| 'body' \| 'caption' \| 'label' \| 'eyebrow' \| 'code'` | `'default'` |
+| size    | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`                                                 | by variant  |
 
 ## Input
 
@@ -1379,9 +1408,12 @@ import {
 
 ### React Native: stacked modals
 
-If `AlertDialog` is a **sibling** of another fullscreen `Modal`, iOS often fails to show a second `Modal` on top. Prefer **`presentation="overlay"`** and render `<AlertDialog>` **inside** that `Modal` (themed UI, one native modal host). Alternatively use **`presentation="native"`** for a system `Alert.alert` when themed UI is not required.
-
-**Manual QA (iOS + Android):** Fullscreen sheet + `presentation="overlay"` nested in the sheet: themed confirm appears, **Cancel** / **Delete** behave correctly. Optionally repeat with `presentation="native"` for system alert stacking.
+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.
 
 ## Checkbox
 
@@ -1446,6 +1478,8 @@ import {
 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.
 
 `SelectContent` supports optional frosted props:
 
@@ -1455,6 +1489,11 @@ selected values stay on one line and truncate without displacing the trigger che
 | blurIntensity | `number`                                                           | subtle preset |
 | blurTintToken | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'popover'`   |
 
+`SelectContent` keeps its listbox inside the safe area by default; pass `insets` only to
+change that margin. 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'`.
+
 ## Tabs
 
 ```tsx
@@ -1507,7 +1546,7 @@ import {
 import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
 
 <Avatar size="default">
-  <AvatarImage src="https://..." />
+  <AvatarImage source={{ uri: 'https://...' }} />
   <AvatarFallback>JD</AvatarFallback>
 </Avatar>;
 ```
@@ -1516,6 +1555,10 @@ import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
 | ---- | --------------------------- | ----------- |
 | size | `'sm' \| 'default' \| 'lg'` | `'default'` |
 
+`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.
+
 ## Progress
 
 ```tsx
@@ -1552,6 +1595,9 @@ toast({ title: 'Success', description: 'Saved!', variant: 'success' });
 | 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.
+
 ## Popover
 
 ```tsx
@@ -1889,6 +1935,36 @@ 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.
 
+## 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   |
+| ------------------- | -------------------------------------------------- | --------- |
+| `source`            | `ImageProps['source']`                             | required  |
+| `alt`               | `string`                                           | required  |
+| `fallbackSource`    | `ImageProps['source']`                             | —         |
+| `skeleton`          | `boolean`                                          | `true`    |
+| `skeletonClassName` | `string`                                           | —         |
+| `transition`        | `number`                                           | `200`     |
+| `radius`            | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`    |
+| `objectFit`         | `'cover' \| 'contain' \| 'fill' \| 'scale-down'`   | `'cover'` |
+| `onLoad`            | `() => void`                                       | —         |
+| `onError`           | `() => void`                                       | —         |
+
+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 / 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.
@@ -2032,7 +2108,8 @@ keeps taps on inputs while the keyboard is open (`keyboardShouldPersistTaps="han
 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`.
+`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.
 
 ## Header
 
@@ -2043,7 +2120,9 @@ import { Header, HeaderBackButton } from '@thewhileloop/whileui';
   title="Settings"
   subtitle="Manage preferences"
   leftAction={<HeaderBackButton onPress={() => {}} />}
-  rightActions={[{ key: 'search', icon: <Icon />, onPress: () => {} }]}
+  rightActions={[
+    { key: 'search', icon: <Icon />, onPress: () => {}, accessibilityLabel: 'Search' },
+  ]}
 />;
 ```
 
@@ -2185,6 +2264,22 @@ import { EmptyState } from '@thewhileloop/whileui';
 />;
 ```
 
+## 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     |
+| ----- | --------------------------- | ----------- |
+| label | `string`                    | `'Loading'` |
+| size  | `'sm' \| 'default' \| 'lg'` | `'default'` |
+
 ## ProfileHeader
 
 Copy from `apps/showcase/templates/profile/profile-header.tsx`, then:
@@ -2384,6 +2479,9 @@ import { DrawerMenu } from '@thewhileloop/whileui';
 | `blurIntensity` | `number`                                                           | medium preset          |
 | `blurTintToken` | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'surfaceTranslucent'` |
 
+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.
+
 ## Roadmap
 
 Tracked work items for future releases.
@@ -2410,7 +2508,7 @@ Tracked work items for future releases.
 ### Documentation Gaps
 
 - [ ] 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
+- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, ListItem, NotificationItem, MetricCard, TimelineFeed
 
 ### Infrastructure
 

package/dist/blocks/datepicker/date-range-picker-modal.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useMemo, useState } from 'react';
-import { Modal, Pressable, View } from 'react-native';
+import { Pressable, View } from 'react-native';
+import { OverlayHost } from '../../lib/overlay-host';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { useUniwind } from 'uniwind';
 import { Calendar } from 'react-native-calendars';
@@ -124,7 +125,7 @@ function DateRangePickerModalSession({ value, onValueChange, open, onOpenChange,
         setDraftStart(null);
         setDraftEnd(null);
     }, [onOpenChange]);
-    return (_jsxs(_Fragment, { children: [trigger ? (_jsx(Pressable, { accessibilityRole: "button", onPress: handleOpen, className: cn('w-full flex-row items-center border-border bg-muted', className), style: fieldRecipe(visual, 'default'), children: trigger })) : null, _jsx(Modal, { visible: open, transparent: true, animationType: "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: handleBackdropPress, children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, onPress: handleBackdropPress, children: _jsxs(Pressable, { accessible: false, className: cn('border border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background'), style: [
+    return (_jsxs(_Fragment, { children: [trigger ? (_jsx(Pressable, { accessibilityRole: "button", onPress: handleOpen, className: cn('w-full flex-row items-center border-border bg-muted', className), style: fieldRecipe(visual, 'default'), children: trigger })) : null, _jsx(OverlayHost, { open: open, animationType: "slide", onRequestClose: handleBackdropPress, children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, onPress: handleBackdropPress, children: _jsxs(Pressable, { accessible: false, className: cn('border border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background'), style: [
                             {
                                 borderTopLeftRadius: surfaceRadius(visual, 'xl'),
                                 borderTopRightRadius: surfaceRadius(visual, 'xl'),

package/dist/blocks/datepicker/datepicker-modal.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useMemo, useState } from 'react';
-import { Modal, Pressable, View } from 'react-native';
+import { Pressable, View } from 'react-native';
+import { OverlayHost } from '../../lib/overlay-host';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { useUniwind } from 'uniwind';
 import { Calendar } from 'react-native-calendars';
@@ -70,7 +71,7 @@ function DatePickerModalSession({ value, onValueChange, open, onOpenChange, minD
         setDraftDate(value ?? null);
         onOpenChange(true);
     }, [onOpenChange, value]);
-    return (_jsxs(_Fragment, { children: [trigger ? (_jsx(Pressable, { accessibilityRole: "button", onPress: handleOpen, className: cn('w-full flex-row items-center border-border bg-muted', className), style: fieldRecipe(visual, 'default'), children: trigger })) : null, _jsx(Modal, { visible: open, transparent: true, animationType: "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: handleDismiss, children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, onPress: handleDismiss, children: _jsxs(Pressable, { accessible: false, className: cn('border border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background'), style: [
+    return (_jsxs(_Fragment, { children: [trigger ? (_jsx(Pressable, { accessibilityRole: "button", onPress: handleOpen, className: cn('w-full flex-row items-center border-border bg-muted', className), style: fieldRecipe(visual, 'default'), children: trigger })) : null, _jsx(OverlayHost, { open: open, animationType: "slide", onRequestClose: handleDismiss, children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, onPress: handleDismiss, children: _jsxs(Pressable, { accessible: false, className: cn('border border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background'), style: [
                             {
                                 borderTopLeftRadius: surfaceRadius(visual, 'xl'),
                                 borderTopRightRadius: surfaceRadius(visual, 'xl'),

package/dist/blocks/datepicker/time-picker-modal.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { Modal, Platform, Pressable, ScrollView, View, } from 'react-native';
+import { Platform, Pressable, ScrollView, View, } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { Text } from '../../components/text';
 import { Button, ButtonText } from '../../components/button';
 import { cn } from '../../lib/cn';
 import { focusRingInset } from '../../lib/focus-ring';
+import { OverlayHost } from '../../lib/overlay-host';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { fieldRecipe, surfacePadding, surfaceRadius, typographyStyle } from '../../lib/recipes';
@@ -157,7 +158,7 @@ function TimePickerModalSession({ value, onValueChange, open, onOpenChange, minu
     }, [hour, minute, onOpenChange, onValueChange]);
     const handleDismiss = useCallback(() => onOpenChange(false), [onOpenChange]);
     const handleOpen = useCallback(() => onOpenChange(true), [onOpenChange]);
-    return (_jsxs(_Fragment, { children: [trigger ? (_jsx(Pressable, { accessibilityRole: "button", onPress: handleOpen, className: cn('w-full flex-row items-center border-border bg-muted', className), style: fieldRecipe(visual, 'default'), children: trigger })) : null, _jsx(Modal, { visible: open, transparent: true, animationType: "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: handleDismiss, children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, onPress: handleDismiss, children: _jsxs(Pressable, { accessible: false, className: cn('border border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background'), style: [
+    return (_jsxs(_Fragment, { children: [trigger ? (_jsx(Pressable, { accessibilityRole: "button", onPress: handleOpen, className: cn('w-full flex-row items-center border-border bg-muted', className), style: fieldRecipe(visual, 'default'), children: trigger })) : null, _jsx(OverlayHost, { open: open, animationType: "slide", onRequestClose: handleDismiss, children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, onPress: handleDismiss, children: _jsxs(Pressable, { accessible: false, className: cn('border border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background'), style: [
                             {
                                 borderTopLeftRadius: surfaceRadius(visual, 'xl'),
                                 borderTopRightRadius: surfaceRadius(visual, 'xl'),

package/dist/blocks/layout/confirm-action-sheet.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
-import { Modal, Pressable, View, } from 'react-native';
+import { Pressable, View } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { Text } from '../../components/text';
 import { cn } from '../../lib/cn';
+import { OverlayHost } from '../../lib/overlay-host';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
@@ -47,7 +48,7 @@ export function ConfirmActionSheet({ open, onOpenChange, title, description, act
             onOpenChange(false);
         }
     };
-    return (_jsx(Modal, { visible: open, transparent: true, animationType: "fade", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: handleClose, children: _jsxs(View, { className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, children: [_jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1", onPress: handleClose }), _jsxs(View, { className: cn('border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background', className), style: [
+    return (_jsx(OverlayHost, { open: open, animationType: "fade", onRequestClose: handleClose, children: _jsxs(View, { className: "flex-1 justify-end", style: { backgroundColor: colors.overlay }, children: [_jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1", onPress: handleClose }), _jsxs(View, { className: cn('border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-background', className), style: [
                         {
                             borderTopLeftRadius: surfaceRadius(visual, 'xl'),
                             borderTopRightRadius: surfaceRadius(visual, 'xl'),

package/dist/blocks/layout/index.d.ts

@@ -9,6 +9,7 @@ export { ScreenSkeleton, type ScreenSkeletonProps } from './screen-skeleton';
 export { ErrorBoundary, type ErrorBoundaryProps } from './error-boundary';
 export { EmptyState, type EmptyStateProps } from './empty-state';
 export { ErrorState, type ErrorStateProps } from './error-state';
+export { LoadingState, type LoadingStateProps } from './loading-state';
 export { FormModalScreen, type FormModalScreenProps } from './form-modal-screen';
 export { LoadingScreen, type LoadingScreenProps } from './loading-screen';
 export { PullToRefreshScrollView, type PullToRefreshScrollViewProps, } from './pull-to-refresh-scroll-view';

package/dist/blocks/layout/index.js

@@ -9,6 +9,7 @@ export { ScreenSkeleton } from './screen-skeleton';
 export { ErrorBoundary } from './error-boundary';
 export { EmptyState } from './empty-state';
 export { ErrorState } from './error-state';
+export { LoadingState } from './loading-state';
 export { FormModalScreen } from './form-modal-screen';
 export { LoadingScreen } from './loading-screen';
 export { PullToRefreshScrollView, } from './pull-to-refresh-scroll-view';

package/dist/blocks/layout/loading-state.d.ts

@@ -0,0 +1,8 @@
+import { type ViewProps } from 'react-native';
+export interface LoadingStateProps extends ViewProps {
+    /** Read by assistive technology as the spinner's name; shown under it when given. */
+    label?: string;
+    size?: 'sm' | 'default' | 'lg';
+}
+/** The in-flow sibling of `EmptyState` and `ErrorState`, for a section still fetching. */
+export declare function LoadingState({ label, size, className, style, ...props }: LoadingStateProps): import("react").JSX.Element;

package/dist/blocks/layout/loading-state.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { View } from 'react-native';
+import { Spinner } from '../../components/spinner';
+import { Text } from '../../components/text';
+import { cn } from '../../lib/cn';
+import { useVisualTokens } from '../../lib/visual-tokens';
+import { surfacePadding } from '../../lib/recipes';
+/** The in-flow sibling of `EmptyState` and `ErrorState`, for a section still fetching. */
+export function LoadingState({ label, size = 'default', className, style, ...props }) {
+    const visual = useVisualTokens();
+    return (_jsxs(View, { className: cn('items-center justify-center', className), style: [{ paddingVertical: surfacePadding(visual, 'lg') }, style], ...props, children: [_jsx(Spinner, { size: size, accessibilityLabel: label ?? 'Loading' }), label ? (_jsx(Text, { variant: "caption", className: "mt-3 text-center", children: label })) : null] }));
+}

package/dist/blocks/layout/sheet.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { createContext, useCallback, useContext, useMemo } from 'react';
-import { Modal, Platform, Pressable, ScrollView, useWindowDimensions, View, } from 'react-native';
+import { Pressable, ScrollView, StyleSheet, useWindowDimensions, View, } from 'react-native';
+import Animated, { interpolate, useAnimatedStyle } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { Text } from '../../components/text';
 import { cn } from '../../lib/cn';
 import { composeEventHandlers } from '../../lib/compose-event-handlers';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
+import { OverlayHost } from '../../lib/overlay-host';
+import { useOverlayPresence } from '../../lib/overlay-presence';
 import { useTapOnly } from '../../lib/tap-only';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { surfacePadding, surfaceRadius, typographyStyle } from '../../lib/recipes';
@@ -16,6 +19,7 @@ export function Sheet({ open, onOpenChange, children, maxHeight = 'full', maxWid
     const insets = useSafeAreaInsets();
     const colors = useThemeColors();
     const visual = useVisualTokens();
+    const interaction = useInteractionTokens();
     const onClose = useCallback(() => onOpenChange(false), [onOpenChange]);
     const backdropPress = useTapOnly(onClose);
     const contextValue = useMemo(() => ({ onClose }), [onClose]);
@@ -34,6 +38,17 @@ export function Sheet({ open, onOpenChange, children, maxHeight = 'full', maxWid
         tintColor: colors.overlay,
     });
     const { height: screenHeight, width: windowWidth } = useWindowDimensions();
+    // The host Modal does not animate: the backdrop fades in place while the panel slides,
+    // so the dim layer never rises with the sheet.
+    const { mounted, progress } = useOverlayPresence({
+        visible: open,
+        openDuration: interaction.motionSlow,
+        closeDuration: interaction.motionNormal,
+    });
+    const backdropStyle = useAnimatedStyle(() => ({ opacity: progress.value }));
+    const panelStyle = useAnimatedStyle(() => ({
+        transform: [{ translateY: interpolate(progress.value, [0, 1], [screenHeight, 0]) }],
+    }));
     const maxWidth = maxWidthProp ?? visual.sheetMaxWidth;
     const widthStyle = typeof maxWidth === 'number' && windowWidth >= visual.sheetTabletBreakpoint
         ? { maxWidth, alignSelf: 'center', width: maxWidth }
@@ -64,7 +79,11 @@ export function Sheet({ open, onOpenChange, children, maxHeight = 'full', maxWid
         widthStyle,
         frostedSurface.surfaceStyle,
     ];
-    return (_jsx(Modal, { visible: open, transparent: true, animationType: "slide", onRequestClose: onClose, statusBarTranslucent: Platform.OS === 'android', navigationBarTranslucent: Platform.OS === 'android', presentationStyle: "overFullScreen", children: _jsxs(View, { className: "flex-1 justify-end", style: { backgroundColor: frosted ? 'transparent' : colors.overlay }, children: [frostedBackdrop, _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1", ...backdropPress }), _jsxs(View, { className: cn('border-border overflow-hidden relative', frosted ? 'bg-transparent' : 'bg-background'), style: sheetStyle, children: [frostedSurface.overlay, _jsx(SheetContext.Provider, { value: contextValue, children: children })] })] }) }));
+    return (_jsx(OverlayHost, { open: mounted, animationType: "none", onRequestClose: onClose, children: _jsxs(View, { className: "flex-1 justify-end", children: [_jsx(Animated.View, { style: [
+                        StyleSheet.absoluteFill,
+                        { backgroundColor: frosted ? 'transparent' : colors.overlay },
+                        backdropStyle,
+                    ], children: frostedBackdrop }), _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1", ...backdropPress }), _jsxs(Animated.View, { className: cn('border-border overflow-hidden relative', frosted ? 'bg-transparent' : 'bg-background'), style: [sheetStyle, panelStyle], children: [frostedSurface.overlay, _jsx(SheetContext.Provider, { value: contextValue, children: children })] })] }) }));
 }
 export function SheetHeader({ title, description, className, children, style, ...props }) {
     const { onClose } = useContext(SheetContext);

package/dist/blocks/media/smart-image.js

@@ -44,21 +44,19 @@ function resolveRadius(visual, radius) {
     return visual.radiusMd;
 }
 const SmartImage = React.forwardRef(({ className, source, alt, skeleton = true, skeletonClassName, transition = 200, radius, objectFit, onLoad, onError, fallbackSource, style, ...props }, ref) => {
-    const [loading, setLoading] = useState(true);
-    const [error, setError] = useState(false);
+    const [phase, setPhase] = useState('loading');
     const visual = useVisualTokens();
     const borderRadius = resolveRadius(visual, radius ?? 'md');
     const handleLoad = () => {
-        setLoading(false);
+        setPhase((current) => (current === 'fallback' ? 'fallback' : 'loaded'));
         onLoad?.();
     };
     const handleError = () => {
-        setLoading(false);
-        setError(true);
+        setPhase((current) => current === 'fallback' ? 'fallback' : fallbackSource ? 'fallback' : 'error');
         onError?.();
     };
-    const imageSource = error && fallbackSource ? fallbackSource : source;
-    return (_jsxs(View, { ref: ref, className: cn(smartImageVariants({ radius, objectFit }), className), style: [{ borderRadius }, style], ...props, children: [skeleton && loading && (_jsx(Skeleton, { className: cn('absolute inset-0', skeletonClassName) })), _jsx(Image, { source: imageSource, alt: alt, transition: transition, onLoad: handleLoad, onError: handleError, className: cn('w-full h-full', objectFit === 'cover' && 'object-cover', objectFit === 'contain' && 'object-contain', objectFit === 'fill' && 'object-fill', objectFit === 'scale-down' && 'object-scale-down'), style: { opacity: loading && !error ? 0 : 1 } })] }));
+    const imageSource = phase === 'fallback' ? fallbackSource : source;
+    return (_jsxs(View, { ref: ref, className: cn(smartImageVariants({ radius, objectFit }), className), style: [{ borderRadius }, style], ...props, children: [skeleton && phase === 'loading' && (_jsx(Skeleton, { className: cn('absolute inset-0', skeletonClassName) })), _jsx(Image, { source: imageSource, alt: alt, transition: transition, onLoadStart: () => setPhase((current) => (current === 'fallback' ? current : 'loading')), onLoad: handleLoad, onError: handleError, className: cn('w-full h-full', objectFit === 'cover' && 'object-cover', objectFit === 'contain' && 'object-contain', objectFit === 'fill' && 'object-fill', objectFit === 'scale-down' && 'object-scale-down'), style: { opacity: phase === 'loading' ? 0 : 1 } })] }));
 });
 SmartImage.displayName = 'SmartImage';
 export { SmartImage, smartImageVariants };

package/dist/blocks/navigation/drawer-menu.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
-import { View, Pressable, Platform, Modal, I18nManager, SectionList, useWindowDimensions, StyleSheet, } from 'react-native';
-import Animated, { useSharedValue, useAnimatedStyle, withTiming, Easing, interpolate, } from 'react-native-reanimated';
+import { View, Pressable, Platform, I18nManager, SectionList, useWindowDimensions, StyleSheet, } from 'react-native';
+import Animated, { useAnimatedStyle, interpolate } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { Text } from '../../components/text';
 import { cn } from '../../lib/cn';
@@ -9,7 +9,8 @@ import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { shadowStyle, surfaceRadius } from '../../lib/recipes';
-import { useMotionPolicy } from '../../lib/motion-policy';
+import { OverlayHost } from '../../lib/overlay-host';
+import { useOverlayPresence } from '../../lib/overlay-presence';
 import { useTapOnly } from '../../lib/tap-only';
 import { useFrostedSurface, useFrostedBackdrop, } from '../../lib/frosted-surface';
 function DrawerItemRow({ item, active, onSelect, interaction, visual }) {
@@ -34,54 +35,12 @@ function DrawerSectionList({ sections, activeKey, onSelect, interaction, visual,
     const renderSectionHeader = React.useCallback(({ section }) => section.title ? (_jsx(Text, { accessibilityRole: "header", className: "font-medium text-muted-foreground uppercase tracking-wide px-3 mb-2", style: { fontSize: visual.navSectionTitleFontSize }, children: section.title })) : null, [visual.navSectionTitleFontSize]);
     return (_jsx(SectionList, { sections: data, keyExtractor: (item) => item.key, className: "flex-1 px-3", keyboardShouldPersistTaps: "handled", showsVerticalScrollIndicator: false, renderSectionHeader: renderSectionHeader, renderSectionFooter: DrawerSectionGap, ItemSeparatorComponent: DrawerItemGap, renderItem: renderItem }));
 }
-function useDrawerAnimation({ visible, drawerWidth, interaction, motion }) {
-    const progress = useSharedValue(0);
-    const [mounted, setMounted] = React.useState(visible);
-    const closeTimerRef = React.useRef(null);
-    const [prevVisible, setPrevVisible] = React.useState(visible);
-    // Open in the prop-change render so the first animation frame has a mounted panel;
-    // closing stays mounted on the timer until the exit animation finishes.
-    if (prevVisible !== visible) {
-        setPrevVisible(visible);
-        if (visible)
-            setMounted(true);
-    }
-    React.useEffect(() => {
-        if (!mounted)
-            return;
-        if (closeTimerRef.current) {
-            clearTimeout(closeTimerRef.current);
-            closeTimerRef.current = null;
-        }
-        const duration = motion.reduceMotion || !motion.animationsEnabled
-            ? 0
-            : visible
-                ? interaction.drawerOpenDuration
-                : interaction.drawerCloseDuration;
-        progress.value = withTiming(visible ? 1 : 0, {
-            duration,
-            reduceMotion: motion.reanimatedReduceMotion,
-            easing: visible ? Easing.bezier(0.2, 0.8, 0.2, 1) : Easing.bezier(0.4, 0, 1, 1),
-        });
-        if (!visible) {
-            closeTimerRef.current = setTimeout(() => setMounted(false), duration);
-        }
-        return () => {
-            if (closeTimerRef.current) {
-                clearTimeout(closeTimerRef.current);
-                closeTimerRef.current = null;
-            }
-        };
-    }, [
-        mounted,
+function useDrawerAnimation({ visible, drawerWidth, interaction }) {
+    const { mounted, progress } = useOverlayPresence({
         visible,
-        progress,
-        interaction.drawerOpenDuration,
-        interaction.drawerCloseDuration,
-        motion.animationsEnabled,
-        motion.reduceMotion,
-        motion.reanimatedReduceMotion,
-    ]);
+        openDuration: interaction.drawerOpenDuration,
+        closeDuration: interaction.drawerCloseDuration,
+    });
     const backdropStyle = useAnimatedStyle(() => ({
         opacity: progress.value,
         pointerEvents: progress.value > 0 ? 'auto' : 'none',
@@ -119,7 +78,6 @@ export function DrawerMenu({ visible, onClose, sections, activeKey, onSelect, he
     const colors = useThemeColors();
     const interaction = useInteractionTokens();
     const visual = useVisualTokens();
-    const motion = useMotionPolicy();
     const backdropPress = useTapOnly(onClose);
     const frostedSurface = useFrostedSurface({
         frosted,
@@ -140,7 +98,6 @@ export function DrawerMenu({ visible, onClose, sections, activeKey, onSelect, he
         visible,
         drawerWidth: layout.width,
         interaction,
-        motion,
     });
     const handleItemPress = React.useCallback((key) => {
         onSelect?.(key);
@@ -168,7 +125,5 @@ export function DrawerMenu({ visible, onClose, sections, activeKey, onSelect, he
                     frostedSurface.surfaceStyle,
                     style,
                 ], className: drawerPanelClassName(frosted, className), children: [frostedSurface.overlay, _jsxs(View, { className: "flex-1 pb-8", style: { paddingTop: contentTopPadding }, children: [header && _jsx(View, { className: "px-5 pb-4 mb-2 border-b border-border", children: header }), _jsx(DrawerSectionList, { sections: sections, activeKey: activeKey, onSelect: handleItemPress, interaction: interaction, visual: visual }), footer && _jsx(View, { className: "px-5 py-4 mt-auto border-t border-border", children: footer })] })] })] }));
-    if (Platform.OS !== 'android')
-        return drawerTree;
-    return (_jsx(Modal, { visible: mounted, transparent: true, animationType: "none", onRequestClose: onClose, statusBarTranslucent: true, navigationBarTranslucent: true, presentationStyle: "overFullScreen", children: drawerTree }));
+    return (_jsx(OverlayHost, { open: mounted, animationType: "none", onRequestClose: onClose, children: drawerTree }));
 }

package/dist/blocks/navigation/header.d.ts

@@ -4,6 +4,8 @@ export interface HeaderAction {
     key: string;
     icon: React.ReactNode;
     onPress: () => void;
+    /** Required in practice: an icon-only button has no other accessible name. */
+    accessibilityLabel?: string;
 }
 export interface HeaderProps extends ViewProps {
     title?: string;