@thewhileloop/whileui 4.1.1 → 4.2.0

package/README.md

@@ -38,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:
 
@@ -144,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.
@@ -237,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
@@ -384,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           |
@@ -1046,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
 
@@ -1394,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
 
@@ -1472,6 +1489,11 @@ itself to the collision-available viewport, and wraps long option labels inside
 | 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
@@ -2086,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
 
@@ -2097,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' },
+  ]}
 />;
 ```
 
@@ -2239,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:
@@ -2438,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.

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/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;

package/dist/blocks/navigation/header.js

@@ -14,7 +14,7 @@ export function Header({ title, subtitle, leftAction, rightActions, centerConten
                 paddingVertical: visual.controlPaddingYDefault,
             },
             style,
-        ], ...props, children: [_jsx(View, { className: "min-w-12", children: leftAction }), _jsx(View, { className: "flex-1 items-center", children: centerContent || (_jsxs(View, { className: "items-center", children: [title && (_jsx(Text, { className: "font-semibold text-foreground", style: typographyStyle(visual, 'body'), numberOfLines: 1, children: title })), subtitle && (_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'caption'), numberOfLines: 1, children: subtitle }))] })) }), _jsx(View, { className: "min-w-12 flex-row items-center justify-end gap-2", children: rightActions?.map((action) => (_jsx(Pressable, { accessibilityRole: "button", onPress: action.onPress, className: "rounded-full p-2 active:bg-accent", style: withInteractivePressableStyle(undefined, interaction, {
+        ], ...props, children: [_jsx(View, { className: "min-w-12", children: leftAction }), _jsx(View, { className: "flex-1 items-center", children: centerContent || (_jsxs(View, { className: "items-center", children: [title && (_jsx(Text, { className: "font-semibold text-foreground", style: typographyStyle(visual, 'body'), numberOfLines: 1, children: title })), subtitle && (_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'caption'), numberOfLines: 1, children: subtitle }))] })) }), _jsx(View, { className: "min-w-12 flex-row items-center justify-end gap-2", children: rightActions?.map((action) => (_jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: action.accessibilityLabel, onPress: action.onPress, className: "rounded-full p-2 active:bg-state-pressed", style: withInteractivePressableStyle(undefined, interaction, {
                         pressedVariant: 'default',
                     }), children: action.icon }, action.key))) })] }));
 }

package/dist/components/alert/alert.js

@@ -22,7 +22,10 @@ const alertVariants = tv({
 });
 const Alert = React.forwardRef(({ className, variant, style, ...props }, ref) => {
     const visual = useVisualTokens();
-    return (_jsx(View, { ref: ref, className: cn(alertVariants({ variant }), className), style: [
+    return (_jsx(View, { ref: ref, 
+        // A status message that appears is announced without focus moving to it. Set
+        // before the spread so a decorative note can opt out.
+        accessibilityRole: "alert", accessibilityLiveRegion: "polite", className: cn(alertVariants({ variant }), className), style: [
             {
                 borderRadius: surfaceRadius(visual, 'lg'),
                 borderWidth: visual.borderWidthHairline,

package/dist/components/alert-dialog/alert-dialog.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { View, Modal, Pressable, Text, Alert, Platform, StyleSheet, } from 'react-native';
+import { View, Pressable, Text, Alert, Platform, StyleSheet, } from 'react-native';
 import { cn } from '../../lib/cn';
 import { composeEventHandlers } from '../../lib/compose-event-handlers';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useFrostedSurface } from '../../lib/frosted-surface';
+import { OverlayHost } from '../../lib/overlay-host';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { shadowStyle, typographyStyle } from '../../lib/recipes';
 function emptyNativeCopy() {
@@ -231,7 +232,7 @@ function AlertDialogContent({ className, children, presentation = 'modal', frost
         }
         return (_jsx(View, { pointerEvents: "box-none", style: [StyleSheet.absoluteFill, { zIndex: 100 }], children: themedBody }));
     }
-    return (_jsx(Modal, { visible: open, transparent: true, animationType: "fade", presentationStyle: Platform.OS === 'ios' ? 'overFullScreen' : undefined, statusBarTranslucent: Platform.OS === 'android', navigationBarTranslucent: Platform.OS === 'android', onRequestClose: () => setOpen(false), children: themedBody }));
+    return (_jsx(OverlayHost, { open: open, animationType: "fade", onRequestClose: () => setOpen(false), children: themedBody }));
 }
 function useAlertDialogNativeCopy() {
     return useContext(AlertDialogContext).nativeCopyRef;

package/dist/components/context-menu/context-menu.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { createContext, useContext, useMemo, useState } from 'react';
-import { View, Modal, Pressable, Text } from 'react-native';
+import { View, Pressable, Text } from 'react-native';
+import { OverlayHost } from '../../lib/overlay-host';
 import { cn } from '../../lib/cn';
 import { useFrostedSurface } from '../../lib/frosted-surface';
 import { useVisualTokens } from '../../lib/visual-tokens';
@@ -53,7 +54,7 @@ function ContextMenuContent({ className, children, frosted = false, blurIntensit
         frostedSurface.surfaceStyle,
         style,
     ];
-    return (_jsx(Modal, { visible: open, transparent: true, animationType: "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: () => setOpen(false), children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", onPress: () => setOpen(false), children: _jsxs(Pressable, { accessible: false, accessibilityRole: "menu", className: cn('w-full border-border p-2 pb-8 relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', className), style: contentStyle, onPress: (e) => e.stopPropagation(), ...props, children: [frostedSurface.overlay, children] }) }) }));
+    return (_jsx(OverlayHost, { open: open, animationType: "slide", onRequestClose: () => setOpen(false), children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", onPress: () => setOpen(false), children: _jsxs(Pressable, { accessible: false, accessibilityRole: "menu", className: cn('w-full border-border p-2 pb-8 relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', className), style: contentStyle, onPress: (e) => e.stopPropagation(), ...props, children: [frostedSurface.overlay, children] }) }) }));
 }
 function ContextMenuItem({ className, style, ...props }) {
     const { setOpen } = useContext(ContextMenuContext);
@@ -64,7 +65,7 @@ function ContextMenuItem({ className, style, ...props }) {
         paddingHorizontal: visual.controlPaddingXSm,
         paddingVertical: visual.controlPaddingYSm,
     };
-    return (_jsx(Pressable, { accessibilityRole: "menuitem", className: cn('flex flex-row items-center active:bg-accent', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: (e) => {
+    return (_jsx(Pressable, { accessibilityRole: "menuitem", className: cn('flex flex-row items-center active:bg-state-pressed', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: (e) => {
             props.onPress?.(e);
             setOpen(false);
         }, ...props }));

package/dist/components/dialog/dialog.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
-import { View, Modal, Pressable, Text, } from 'react-native';
+import { View, Pressable, Text, } from 'react-native';
 import { cn } from '../../lib/cn';
 import { composeEventHandlers } from '../../lib/compose-event-handlers';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useFrostedSurface } from '../../lib/frosted-surface';
+import { OverlayHost } from '../../lib/overlay-host';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { shadowStyle, typographyStyle } from '../../lib/recipes';
 const DialogContext = createContext({
@@ -47,7 +48,7 @@ function DialogContent({ className, children, frosted = false, blurIntensity, bl
         defaultBlurPreset: 'medium',
     });
     const contentStyle = [frostedSurface.surfaceStyle, style];
-    return (_jsx(Modal, { visible: open, transparent: true, animationType: "fade", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: () => setOpen(false), children: _jsx(Pressable
+    return (_jsx(OverlayHost, { open: open, animationType: "fade", onRequestClose: () => setOpen(false), children: _jsx(Pressable
         // Tap-to-dismiss is a pointer affordance. Left accessible it would swallow the
         // whole panel into one element; screen reader users close from inside.
         , { 
@@ -78,7 +79,7 @@ function DialogFooter({ className, ...props }) {
 }
 function DialogTitle({ className, style, ...props }) {
     const visual = useVisualTokens();
-    return (_jsx(Text, { className: cn('font-semibold text-foreground', className), style: [typographyStyle(visual, 'title'), style], ...props }));
+    return (_jsx(Text, { accessibilityRole: "header", className: cn('font-semibold text-foreground', className), style: [typographyStyle(visual, 'title'), style], ...props }));
 }
 function DialogDescription({ className, style, ...props }) {
     const visual = useVisualTokens();

package/dist/components/dropdown-menu/dropdown-menu.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { createContext, useContext, useMemo, useState } from 'react';
-import { View, Modal, Pressable, Text } from 'react-native';
+import { View, Pressable, Text } from 'react-native';
+import { OverlayHost } from '../../lib/overlay-host';
 import { cn } from '../../lib/cn';
 import { useFrostedSurface } from '../../lib/frosted-surface';
 import { useVisualTokens } from '../../lib/visual-tokens';
@@ -52,7 +53,7 @@ function DropdownMenuContent({ className, children, frosted = false, blurIntensi
         frostedSurface.surfaceStyle,
         style,
     ];
-    return (_jsx(Modal, { visible: open, transparent: true, animationType: "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: () => setOpen(false), children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", onPress: () => setOpen(false), children: _jsxs(Pressable, { accessible: false, 
+    return (_jsx(OverlayHost, { open: open, animationType: "slide", onRequestClose: () => setOpen(false), children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", onPress: () => setOpen(false), children: _jsxs(Pressable, { accessible: false, 
                 // Names the container for the `menuitem` children below; without a `menu`
                 // ancestor the role is invalid ARIA and assistive tech ignores it.
                 accessibilityRole: "menu", className: cn('w-full border-border p-2 pb-8 relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', className), style: contentStyle, onPress: (e) => e.stopPropagation(), ...props, children: [frostedSurface.overlay, children] }) }) }));
@@ -66,7 +67,7 @@ function DropdownMenuItem({ className, style, ...props }) {
         paddingHorizontal: visual.controlPaddingXSm,
         paddingVertical: visual.controlPaddingYSm,
     };
-    return (_jsx(Pressable, { accessibilityRole: "menuitem", className: cn('flex flex-row items-center active:bg-accent', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: (e) => {
+    return (_jsx(Pressable, { accessibilityRole: "menuitem", className: cn('flex flex-row items-center active:bg-state-pressed', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: (e) => {
             props.onPress?.(e);
             setOpen(false);
         }, ...props }));

package/dist/components/hover-card/hover-card.js

@@ -4,6 +4,7 @@ import { Platform, StyleSheet } from 'react-native';
 import * as HoverCardPrimitive from '@rn-primitives/hover-card';
 import { cn } from '../../lib/cn';
 import { useFrostedSurface } from '../../lib/frosted-surface';
+import { useNestedOverlay, useOverlayPortalTarget } from '../../lib/overlay-host';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { useThemeColors } from '../../lib/theme-colors';
 import { shadowStyle, surfacePadding, surfaceRadius } from '../../lib/recipes';
@@ -22,6 +23,9 @@ const HoverCardContent = React.forwardRef(({ className, align = 'center', sideOf
     });
     const visual = useVisualTokens();
     const colors = useThemeColors();
+    const { open, onOpenChange } = HoverCardPrimitive.useRootContext();
+    const portalTarget = useOverlayPortalTarget(portalHost);
+    useNestedOverlay(open, () => onOpenChange(false));
     const resolvedStyle = StyleSheet.flatten([
         Platform.OS === 'web' ? undefined : contentStyles,
         {
@@ -33,7 +37,7 @@ const HoverCardContent = React.forwardRef(({ className, align = 'center', sideOf
         frostedSurface.surfaceStyle,
         style,
     ]);
-    return (_jsx(HoverCardPrimitive.Portal, { hostName: portalHost, children: _jsx(HoverCardPrimitive.Overlay, { style: Platform.OS !== 'web' ? StyleSheet.absoluteFill : undefined, children: _jsxs(HoverCardPrimitive.Content, { ref: ref, align: align, sideOffset: sideOffset, className: cn('z-50 w-64 border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', 'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1', className), style: resolvedStyle, ...props, children: [frostedSurface.overlay, children] }) }) }));
+    return (_jsx(HoverCardPrimitive.Portal, { ...portalTarget, children: _jsx(HoverCardPrimitive.Overlay, { style: Platform.OS !== 'web' ? StyleSheet.absoluteFill : undefined, children: _jsxs(HoverCardPrimitive.Content, { ref: ref, align: align, sideOffset: sideOffset, className: cn('z-50 w-64 border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', 'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1', className), style: resolvedStyle, ...props, children: [frostedSurface.overlay, children] }) }) }));
 });
 HoverCardContent.displayName = 'HoverCardContent';
 const contentStyles = {

package/dist/components/menubar/menubar.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useContext, useMemo, useState } from 'react';
-import { View, Modal, Pressable, Text } from 'react-native';
+import { View, Pressable, Text } from 'react-native';
+import { OverlayHost } from '../../lib/overlay-host';
 import { cn } from '../../lib/cn';
 import { useFrostedSurface } from '../../lib/frosted-surface';
 import { useVisualTokens } from '../../lib/visual-tokens';
@@ -23,7 +24,7 @@ function MenubarTrigger({ className, style, ...props }) {
     const { setOpen } = useContext(MenubarMenuContext);
     const visual = useVisualTokens();
     const tokenStyle = controlRecipe(visual, 'sm');
-    return (_jsx(Pressable, { accessibilityRole: "button", className: cn('active:bg-accent', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: () => setOpen(true), ...props }));
+    return (_jsx(Pressable, { accessibilityRole: "button", className: cn('active:bg-state-pressed', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: () => setOpen(true), ...props }));
 }
 function MenubarContent({ className, children, frosted = false, blurIntensity, blurTintToken, style, ...props }) {
     const { open, setOpen } = useContext(MenubarMenuContext);
@@ -48,7 +49,7 @@ function MenubarContent({ className, children, frosted = false, blurIntensity, b
         frostedSurface.surfaceStyle,
         style,
     ];
-    return (_jsx(Modal, { visible: open, transparent: true, animationType: "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: () => setOpen(false), children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", onPress: () => setOpen(false), children: _jsxs(Pressable, { accessible: false, accessibilityRole: "menu", className: cn('w-full border-border p-2 pb-8 relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', className), style: contentStyle, onPress: (e) => e.stopPropagation(), ...props, children: [frostedSurface.overlay, children] }) }) }));
+    return (_jsx(OverlayHost, { open: open, animationType: "slide", onRequestClose: () => setOpen(false), children: _jsx(Pressable, { accessible: false, importantForAccessibility: "no", className: "flex-1 justify-end", onPress: () => setOpen(false), children: _jsxs(Pressable, { accessible: false, accessibilityRole: "menu", className: cn('w-full border-border p-2 pb-8 relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', className), style: contentStyle, onPress: (e) => e.stopPropagation(), ...props, children: [frostedSurface.overlay, children] }) }) }));
 }
 function MenubarItem({ className, style, ...props }) {
     const { setOpen } = useContext(MenubarMenuContext);
@@ -59,7 +60,7 @@ function MenubarItem({ className, style, ...props }) {
         paddingHorizontal: visual.controlPaddingXSm,
         paddingVertical: visual.controlPaddingYSm,
     };
-    return (_jsx(Pressable, { accessibilityRole: "menuitem", className: cn('flex flex-row items-center active:bg-accent', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: (e) => {
+    return (_jsx(Pressable, { accessibilityRole: "menuitem", className: cn('flex flex-row items-center active:bg-state-pressed', className), style: (state) => [tokenStyle, typeof style === 'function' ? style(state) : style], onPress: (e) => {
             props.onPress?.(e);
             setOpen(false);
         }, ...props }));

package/dist/components/popover/popover.js

@@ -4,6 +4,7 @@ import { Platform, StyleSheet } from 'react-native';
 import * as PopoverPrimitive from '@rn-primitives/popover';
 import { cn } from '../../lib/cn';
 import { useFrostedSurface } from '../../lib/frosted-surface';
+import { useNestedOverlay, useOverlayPortalTarget } from '../../lib/overlay-host';
 import { useOverlayInsets } from '../../lib/overlay-insets';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { useThemeColors } from '../../lib/theme-colors';
@@ -23,6 +24,9 @@ const PopoverContent = React.forwardRef(({ className, align = 'center', sideOffs
     });
     const visual = useVisualTokens();
     const colors = useThemeColors();
+    const { open, onOpenChange } = PopoverPrimitive.useRootContext();
+    const portalTarget = useOverlayPortalTarget(portalHost);
+    useNestedOverlay(open, () => onOpenChange(false));
     // Keeps the panel off the screen edge and out from under the notch.
     const defaultInsets = useOverlayInsets();
     const resolvedInsets = { ...defaultInsets, ...insets };
@@ -41,7 +45,7 @@ const PopoverContent = React.forwardRef(({ className, align = 'center', sideOffs
         frostedSurface.surfaceStyle,
         style,
     ]);
-    return (_jsx(PopoverPrimitive.Portal, { hostName: portalHost, children: _jsx(PopoverPrimitive.Overlay, { style: Platform.OS !== 'web' ? StyleSheet.absoluteFill : undefined, children: _jsxs(PopoverPrimitive.Content, { ref: ref, align: align, sideOffset: sideOffset, insets: resolvedInsets, className: cn('z-50 w-72 border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', 'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1', className), style: resolvedStyle, ...props, children: [frostedSurface.overlay, children] }) }) }));
+    return (_jsx(PopoverPrimitive.Portal, { ...portalTarget, children: _jsx(PopoverPrimitive.Overlay, { style: Platform.OS !== 'web' ? StyleSheet.absoluteFill : undefined, children: _jsxs(PopoverPrimitive.Content, { ref: ref, align: align, sideOffset: sideOffset, insets: resolvedInsets, className: cn('z-50 w-72 border-border relative overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', 'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1', className), style: resolvedStyle, ...props, children: [frostedSurface.overlay, children] }) }) }));
 });
 PopoverContent.displayName = 'PopoverContent';
 const PopoverClose = React.forwardRef(({ className, ...props }, ref) => (_jsx(PopoverPrimitive.Close, { ref: ref, className: cn(className), ...props })));

package/dist/components/select/select.js

@@ -8,6 +8,8 @@ import { cn } from '../../lib/cn';
 import { focusRing } from '../../lib/focus-ring';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
 import { useFrostedSurface } from '../../lib/frosted-surface';
+import { useNestedOverlay, useOverlayPortalTarget } from '../../lib/overlay-host';
+import { useOverlayInsets } from '../../lib/overlay-insets';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { useThemeColors } from '../../lib/theme-colors';
 import { fieldRecipe, shadowStyle, surfaceRadius, typographyStyle } from '../../lib/recipes';
@@ -59,6 +61,13 @@ const SelectContent = React.forwardRef(({ className, children, portalHost, posit
     });
     const visual = useVisualTokens();
     const colors = useThemeColors();
+    const { open, onOpenChange } = SelectPrimitive.useRootContext();
+    const portalTarget = useOverlayPortalTarget(portalHost);
+    useNestedOverlay(open, () => onOpenChange(false));
+    // Keeps the listbox off the screen edge and clear of the notch and home indicator
+    // without every caller reading the safe area itself.
+    const defaultInsets = useOverlayInsets();
+    const resolvedInsets = { ...defaultInsets, ...insets };
     // Radix applies its collision variables to the listbox wrapper, while
     // @rn-primitives renders our visual surface one level inside it. Keep the sizing
     // on that surface as inline web CSS: the Viewport's own `width: 100%` otherwise
@@ -71,7 +80,7 @@ const SelectContent = React.forwardRef(({ className, children, portalHost, posit
             maxHeight: 'var(--radix-select-content-available-height)',
         }
         : undefined;
-    return (_jsx(SelectPrimitive.Portal, { hostName: portalHost, children: _jsx(FullWindowOverlay, { children: _jsx(SelectPrimitive.Overlay, { style: Platform.select({ native: StyleSheet.absoluteFill }), children: _jsxs(SelectPrimitive.Content, { ref: ref, position: position, insets: insets, style: {
+    return (_jsx(SelectPrimitive.Portal, { ...portalTarget, children: _jsx(FullWindowOverlay, { children: _jsx(SelectPrimitive.Overlay, { style: Platform.select({ native: StyleSheet.absoluteFill }), children: _jsxs(SelectPrimitive.Content, { ref: ref, position: position, insets: resolvedInsets, style: {
                         ...webSizingStyle,
                         ...StyleSheet.flatten([
                             {

package/dist/components/text/text.d.ts

@@ -10,6 +10,7 @@ declare const textVariants: import("tailwind-variants").TVReturnType<{
         body: "font-normal";
         caption: "text-muted-foreground font-normal";
         label: "font-medium leading-tight";
+        eyebrow: "text-muted-foreground font-medium";
         code: "font-mono bg-muted rounded px-1 py-0.5";
     };
     size: {
@@ -30,6 +31,7 @@ declare const textVariants: import("tailwind-variants").TVReturnType<{
         body: "font-normal";
         caption: "text-muted-foreground font-normal";
         label: "font-medium leading-tight";
+        eyebrow: "text-muted-foreground font-medium";
         code: "font-mono bg-muted rounded px-1 py-0.5";
     };
     size: {
@@ -50,6 +52,7 @@ declare const textVariants: import("tailwind-variants").TVReturnType<{
         body: "font-normal";
         caption: "text-muted-foreground font-normal";
         label: "font-medium leading-tight";
+        eyebrow: "text-muted-foreground font-medium";
         code: "font-mono bg-muted rounded px-1 py-0.5";
     };
     size: {

package/dist/components/text/text.js

@@ -16,6 +16,7 @@ const textVariants = tv({
             body: 'font-normal',
             caption: 'text-muted-foreground font-normal',
             label: 'font-medium leading-tight',
+            eyebrow: 'text-muted-foreground font-medium',
             code: 'font-mono bg-muted rounded px-1 py-0.5',
         },
         size: {
@@ -40,6 +41,7 @@ const VARIANT_ROLES = {
     body: 'body',
     caption: 'caption',
     label: 'label',
+    eyebrow: 'label',
     code: 'label',
 };
 const SIZE_ROLES = {

package/dist/components/toggle/toggle.d.ts

@@ -15,7 +15,7 @@ declare const toggleVariants: import("tailwind-variants").TVReturnType<{
         true: "bg-accent";
         false: "";
     };
-}, undefined, "inline-flex items-center justify-center active:bg-accent", {
+}, undefined, "inline-flex items-center justify-center active:bg-state-pressed", {
     variant: {
         default: "bg-transparent";
         outline: "border border-input bg-transparent";

package/dist/components/toggle/toggle.js

@@ -12,7 +12,7 @@ const ToggleContext = createContext({
     size: 'default',
 });
 const toggleVariants = tv({
-    base: 'inline-flex items-center justify-center active:bg-accent',
+    base: 'inline-flex items-center justify-center active:bg-state-pressed',
     variants: {
         variant: {
             default: 'bg-transparent',

package/dist/components/tooltip/tooltip.js

@@ -3,6 +3,7 @@ import * as React from 'react';
 import { Platform, StyleSheet, Text } from 'react-native';
 import * as TooltipPrimitive from '@rn-primitives/tooltip';
 import { cn } from '../../lib/cn';
+import { useOverlayPortalTarget } from '../../lib/overlay-host';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { useThemeColors } from '../../lib/theme-colors';
 import { shadowStyle, surfaceRadius, typographyStyle } from '../../lib/recipes';
@@ -14,6 +15,7 @@ TooltipTrigger.displayName = 'TooltipTrigger';
 const TooltipContent = React.forwardRef(({ className, sideOffset = 4, portalHost, children, style, ...props }, ref) => {
     const visual = useVisualTokens();
     const colors = useThemeColors();
+    const portalTarget = useOverlayPortalTarget(portalHost);
     const resolvedStyle = StyleSheet.flatten([
         Platform.OS === 'web' ? undefined : contentStyles,
         {
@@ -26,7 +28,7 @@ const TooltipContent = React.forwardRef(({ className, sideOffset = 4, portalHost
         shadowStyle(visual, colors, 'md'),
         style,
     ]);
-    return (_jsx(TooltipPrimitive.Portal, { hostName: portalHost, children: _jsx(TooltipPrimitive.Overlay, { style: Platform.OS !== 'web' ? StyleSheet.absoluteFill : undefined, children: _jsx(TooltipPrimitive.Content, { ref: ref, sideOffset: sideOffset, className: cn('z-50 overflow-hidden bg-primary', 'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1', className), style: resolvedStyle, ...props, children: typeof children === 'string' ? (_jsx(Text, { className: "text-primary-foreground", style: typographyStyle(visual, 'caption'), children: children })) : (children) }) }) }));
+    return (_jsx(TooltipPrimitive.Portal, { ...portalTarget, children: _jsx(TooltipPrimitive.Overlay, { style: Platform.OS !== 'web' ? StyleSheet.absoluteFill : undefined, children: _jsx(TooltipPrimitive.Content, { ref: ref, sideOffset: sideOffset, className: cn('z-50 overflow-hidden bg-primary', 'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1', className), style: resolvedStyle, ...props, children: typeof children === 'string' ? (_jsx(Text, { className: "text-primary-foreground", style: typographyStyle(visual, 'caption'), children: children })) : (children) }) }) }));
 });
 TooltipContent.displayName = 'TooltipContent';
 const contentStyles = {

package/dist/lib/overlay-host.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import { type ModalProps } from 'react-native';
+import type * as PopoverPrimitive from '@rn-primitives/popover';
+type PortalContainer = React.ComponentProps<typeof PopoverPrimitive.Portal>['container'];
+export interface OverlayHostProps extends Pick<ModalProps, 'animationType' | 'onShow' | 'onDismiss'> {
+    open: boolean;
+    /** Android back and web Escape. Omit for a host that only closes from inside. */
+    onRequestClose?: () => void;
+    children: React.ReactNode;
+}
+/**
+ * The platform `Modal` every WhileUI overlay is hosted in. Each Modal is its own window,
+ * so the platform already routes Android back and web Escape to the topmost one and, on
+ * web, traps and restores focus. The host adds what a root-level portal cannot reach:
+ * nested Select, Popover, Tooltip and HoverCard content renders inside this window, and a
+ * dismiss request closes the topmost nested overlay before the host itself.
+ */
+export declare function OverlayHost({ open, onRequestClose, children, animationType, onShow, onDismiss, }: OverlayHostProps): React.JSX.Element;
+/** Portal props for content rendered inside the nearest host. An explicit `portalHost` wins. */
+export declare function useOverlayPortalTarget(portalHost?: string): {
+    hostName?: string;
+    container?: PortalContainer;
+};
+/** Lets the nearest host close this overlay before itself while `open` is true. */
+export declare function useNestedOverlay(open: boolean, close: () => void): void;
+export {};

package/dist/lib/overlay-host.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { Modal, Platform, View } from 'react-native';
+import { PortalHost } from '@rn-primitives/portal';
+const OverlayHostContext = createContext(null);
+// Radix closes a nested overlay on the Escape keydown; React Native Web closes the Modal
+// on the keyup of the same press. Seeing the keydown first lets the host drop that keyup.
+const escapeKeyTarget = Platform.OS === 'web' ? globalThis.document : undefined;
+/**
+ * The platform `Modal` every WhileUI overlay is hosted in. Each Modal is its own window,
+ * so the platform already routes Android back and web Escape to the topmost one and, on
+ * web, traps and restores focus. The host adds what a root-level portal cannot reach:
+ * nested Select, Popover, Tooltip and HoverCard content renders inside this window, and a
+ * dismiss request closes the topmost nested overlay before the host itself.
+ */
+export function OverlayHost({ open, onRequestClose, children, animationType, onShow, onDismiss, }) {
+    const hostName = useId();
+    const nested = useRef([]);
+    const consumedByNested = useRef(false);
+    const [container, setContainer] = useState(undefined);
+    const register = useCallback((overlay) => {
+        nested.current = [...nested.current, overlay];
+        return () => {
+            nested.current = nested.current.filter((entry) => entry !== overlay);
+        };
+    }, []);
+    const requestClose = useCallback(() => {
+        if (consumedByNested.current) {
+            consumedByNested.current = false;
+            return;
+        }
+        const topmost = nested.current.at(-1);
+        if (topmost) {
+            topmost.close();
+            return;
+        }
+        onRequestClose?.();
+    }, [onRequestClose]);
+    useEffect(() => {
+        if (!escapeKeyTarget || !open)
+            return;
+        const markConsumed = (event) => {
+            if (event.key === 'Escape' && nested.current.length > 0)
+                consumedByNested.current = true;
+        };
+        escapeKeyTarget.addEventListener('keydown', markConsumed, true);
+        return () => {
+            escapeKeyTarget.removeEventListener('keydown', markConsumed, true);
+            consumedByNested.current = false;
+        };
+    }, [open]);
+    const attachContainer = useCallback((node) => {
+        setContainer(node);
+    }, []);
+    const value = useMemo(() => ({ hostName, container, register }), [hostName, container, register]);
+    return (_jsx(Modal, { visible: open, transparent: true, animationType: animationType, presentationStyle: "overFullScreen", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: requestClose, onShow: onShow, onDismiss: onDismiss, children: _jsxs(OverlayHostContext.Provider, { value: value, children: [children, Platform.OS === 'web' ? _jsx(View, { ref: attachContainer }) : _jsx(PortalHost, { name: hostName })] }) }));
+}
+/** Portal props for content rendered inside the nearest host. An explicit `portalHost` wins. */
+export function useOverlayPortalTarget(portalHost) {
+    const host = useContext(OverlayHostContext);
+    if (portalHost !== undefined)
+        return { hostName: portalHost };
+    return { hostName: host?.hostName, container: host?.container };
+}
+/** Lets the nearest host close this overlay before itself while `open` is true. */
+export function useNestedOverlay(open, close) {
+    const host = useContext(OverlayHostContext);
+    const closeRef = useRef(close);
+    useEffect(() => {
+        closeRef.current = close;
+    });
+    useEffect(() => {
+        if (!host || !open)
+            return;
+        return host.register({ close: () => closeRef.current() });
+    }, [host, open]);
+}

package/dist/lib/overlay-presence.d.ts

@@ -0,0 +1,15 @@
+interface OverlayPresenceOptions {
+    visible: boolean;
+    openDuration: number;
+    closeDuration: number;
+}
+/**
+ * Keeps an overlay mounted through its exit animation. `progress` runs 0 → 1 on open and
+ * back to 0 on close; `mounted` drops once the exit finishes. Reduced motion and the
+ * disabled test policy collapse both durations to zero.
+ */
+export declare function useOverlayPresence({ visible, openDuration, closeDuration, }: OverlayPresenceOptions): {
+    mounted: boolean;
+    progress: import("react-native-reanimated").SharedValue<number>;
+};
+export {};

package/dist/lib/overlay-presence.js

@@ -0,0 +1,55 @@
+import { useEffect, useRef, useState } from 'react';
+import { Easing, useSharedValue, withTiming } from 'react-native-reanimated';
+import { useMotionPolicy } from './motion-policy';
+/**
+ * Keeps an overlay mounted through its exit animation. `progress` runs 0 → 1 on open and
+ * back to 0 on close; `mounted` drops once the exit finishes. Reduced motion and the
+ * disabled test policy collapse both durations to zero.
+ */
+export function useOverlayPresence({ visible, openDuration, closeDuration, }) {
+    const motion = useMotionPolicy();
+    const progress = useSharedValue(0);
+    const [mounted, setMounted] = useState(visible);
+    const closeTimerRef = useRef(null);
+    const [prevVisible, setPrevVisible] = 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);
+    }
+    useEffect(() => {
+        if (!mounted)
+            return;
+        if (closeTimerRef.current) {
+            clearTimeout(closeTimerRef.current);
+            closeTimerRef.current = null;
+        }
+        const duration = motion.reduceMotion || !motion.animationsEnabled ? 0 : visible ? openDuration : closeDuration;
+        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,
+        visible,
+        progress,
+        openDuration,
+        closeDuration,
+        motion.animationsEnabled,
+        motion.reduceMotion,
+        motion.reanimatedReduceMotion,
+    ]);
+    return { mounted, progress };
+}

package/dist/lib/recipes.d.ts

@@ -1,4 +1,4 @@
-import type { TextStyle, ViewStyle } from 'react-native';
+import { type TextStyle, type ViewStyle } from 'react-native';
 import { type ThemeColors } from './theme-colors';
 import { type VisualTokens } from './visual-tokens';
 /**

package/dist/lib/recipes.js

@@ -1,3 +1,5 @@
+import { Platform } from 'react-native';
+import { formatRgb, parse } from 'culori';
 import { useThemeColors } from './theme-colors';
 import { useVisualTokens } from './visual-tokens';
 export function controlRecipe(visual, size = 'default') {
@@ -92,14 +94,31 @@ export function shadowStyle(visual, colors, tier) {
             : visual.shadowElevationLg;
     if (opacity <= 0)
         return {};
+    // Android below 9 cannot draw an outset box shadow and keeps the elevation fallback.
+    if (Platform.OS === 'android' && typeof Platform.Version === 'number' && Platform.Version < 28) {
+        return { elevation };
+    }
+    // A box shadow is clipped outside the border box, so it never shows through a
+    // translucent surface. Elevation and the legacy `shadow*` props draw under the whole
+    // view, which greyed every translucent card on Android. CSS blur is twice the
+    // Core Animation radius the tokens were tuned for.
     return {
-        shadowColor: colors.shadow,
-        shadowOpacity: opacity,
-        shadowRadius: radius,
-        shadowOffset: { width: 0, height: offsetY },
-        elevation,
+        boxShadow: [
+            {
+                offsetX: 0,
+                offsetY,
+                blurRadius: radius * 2,
+                color: shadowColorWithOpacity(colors.shadow, opacity),
+            },
+        ],
     };
 }
+function shadowColorWithOpacity(color, opacity) {
+    const parsed = parse(color);
+    if (!parsed)
+        return color;
+    return formatRgb({ ...parsed, alpha: opacity });
+}
 // Component-owned text sizes. Font family/weight stays on className
 // (font-medium etc.) so app font mappings keep working.
 export function typographyStyle(visual, role) {

package/dist/metro.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+const { withUniwindConfig } = require('uniwind/metro');
+
+/**
+ * Packages that must resolve the real `react-native`. Uniwind's native resolver
+ * rewrites every `from 'react-native'` to its component wrapper, which re-exports
+ * components and nothing else, so a package importing a non-component export gets
+ * `undefined` with no build error. `expo-asset` imports `AssetRegistry` that way, and
+ * without it every `@expo/vector-icons` glyph is silently absent on iOS and Android.
+ */
+const NEEDS_REAL_REACT_NATIVE = ['expo-asset', 'expo-font', '@expo/vector-icons'];
+
+function withWhileUIMetro(config, options) {
+  const { exemptFromUniwindRewrite = [], ...uniwindOptions } = options;
+  const wrapped = withUniwindConfig(config, uniwindOptions);
+  const exempt = [...NEEDS_REAL_REACT_NATIVE, ...exemptFromUniwindRewrite];
+  const uniwindResolveRequest = wrapped.resolver.resolveRequest;
+
+  wrapped.resolver.resolveRequest = (context, moduleName, platform) => {
+    if (moduleName === 'react-native') {
+      const origin = context.originModulePath ?? '';
+      if (exempt.some((pkg) => origin.includes(`node_modules/${pkg}/`))) {
+        return context.resolveRequest(context, moduleName, platform);
+      }
+    }
+    return uniwindResolveRequest(context, moduleName, platform);
+  };
+
+  return wrapped;
+}
+
+module.exports = { withWhileUIMetro, NEEDS_REAL_REACT_NATIVE };

package/dist/metro.d.cts

@@ -0,0 +1,21 @@
+import type { withUniwindConfig } from 'uniwind/metro';
+
+type UniwindMetroOptions = Parameters<typeof withUniwindConfig>[1];
+
+export interface WithWhileUIMetroOptions extends UniwindMetroOptions {
+  /** Extra packages that must import the real `react-native` instead of Uniwind's wrapper. */
+  exemptFromUniwindRewrite?: string[];
+}
+
+/** Packages exempted from Uniwind's `react-native` rewrite by default. */
+export const NEEDS_REAL_REACT_NATIVE: readonly string[];
+
+/**
+ * Wraps an Expo Metro config with Uniwind and keeps `expo-asset`, `expo-font` and
+ * `@expo/vector-icons` on the real `react-native`, so icon fonts load on device.
+ * Use this in `metro.config.js` instead of calling `withUniwindConfig` yourself.
+ */
+export function withWhileUIMetro<T extends Parameters<typeof withUniwindConfig>[0]>(
+  config: T,
+  options: WithWhileUIMetroOptions
+): ReturnType<typeof withUniwindConfig>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thewhileloop/whileui",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "WhileUI Native — Copy-paste components for React Native. You own the code.",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,10 @@
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
     },
+    "./metro": {
+      "types": "./dist/metro.d.cts",
+      "default": "./dist/metro.cjs"
+    },
     "./tokens": {
       "types": "./dist/tokens.d.ts",
       "import": "./dist/tokens.js"
@@ -59,7 +63,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && cp src/metro.cjs src/metro.d.cts dist/",
     "prepack": "cp ../../README.md README.md",
     "postpack": "rm -f README.md",
     "prepare": "bun run build",