@thewhileloop/whileui 4.2.1 → 4.3.0

package/dist/agent/llms.txt

@@ -0,0 +1,152 @@
+# WhileUI 4.3.0
+
+> React Native components and blocks for iOS, Android and web, styled with Uniwind and
+> themed through a typed token contract. Package: `@thewhileloop/whileui`.
+
+Files in this folder:
+- llms-components.txt — every component and block with its API section
+- llms-full.txt — the complete README, including setup and theming
+- catalog.json — the same data, structured (served by `@thewhileloop/whileui-mcp`)
+
+Components import from `@thewhileloop/whileui`. Copy-paste templates are not in the
+package; copy them from https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates.
+
+## Quick Reference (AI / Code Generation)
+
+- **Full-screen:** `AppShell` + `Header` in `header` + `BottomNav` in `bottomNav` + content in `children`
+- **No-jump loading:** keep `AppShell` mounted, set `loading` + `skeleton` (e.g., `PageSkeleton`/`ScreenSkeleton`)
+- **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/catalog/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.
+- **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/catalog/templates/` (auth, profile); flow patterns in README "Flow Patterns" section.
+
+### Composition grammar
+
+- Start with one page canvas and flat sections. Add a `Surface` only when grouping or
+  elevation communicates something; do not wrap every section in a card.
+- Use `level="base"` for grouped content, `raised` for selectable or floating regions,
+  and `overlay` for content above the page. Avoid nesting more than one surfaced level.
+- Express hierarchy through `Text` variants before custom font-size classes. Keep one
+  primary action per region and constrain long-form content with `Container`.
+- Forms use `FormField`; its disabled and invalid state flows into `Input`, `Textarea`,
+  `NumericInput`, and `Select`. Pass a control prop only to override that inherited state.
+- Chat mechanics belong to `ChatConversation` + `SmartInput`. Message payloads, tools,
+  reasoning, approvals, sources, and action rows are application-owned compositions.
+- Import Markdown and code rendering from their optional subpaths. Do not make the root
+  package pay for content rendering when the screen does not use it.
+
+## Components and blocks
+
+- **Text** (Primitives) — Themed text with variant support
+- **Surface** (Primitives) — Token-backed base, raised, and overlay container
+- **View** (Primitives) — Themed view wrapper
+- **Pressable** (Primitives) — Themed pressable wrapper
+- **Stack** (Primitives) — Vertical flex layout with gap
+- **Row** (Primitives) — Horizontal flex layout with gap
+- **MotionProvider** (Root Providers) — System reduced motion, explicit preview modes, and deterministic testing
+- **Button** (Form Controls) — 4 sizes, ButtonText & ButtonIcon sub-components
+- **Input** (Form Controls) — TextInput wrapper with themed styling
+- **NumericInput** (Form Controls) — Numeric input with prefix/suffix slots, optional steppers, and compact size
+- **OTPInput** (Form Controls) — Verification code input with auto-focus, paste, secure mask, loading skeleton, error shake
+- **FormField** (Form Controls) — Compound API: FormField, FormLabel, FormControl, FormHint, FormMessage
+- **LabeledField** (Form Controls) — Field wrapper with label/helper/error plus left/right slots
+- **Textarea** (Form Controls) — Multi-line text input
+- **Checkbox** (Form Controls) — Controlled/uncontrolled, accessibility roles
+- **Switch** (Form Controls) — Controlled/uncontrolled, accessibility roles
+- **RadioGroup** (Form Controls) — RadioGroup + RadioGroupItem
+- **Select** (Form Controls) — Uses `SelectOption` type `{value, label}`. Includes SelectGroup, SelectLabel, SelectSeparator
+- **Label** (Form Controls) — Form field label
+- **SegmentedControl** (Form Controls) — SegmentedControl, SegmentedControlItem, SegmentedControlItemText with wrapping layout support
+- **Toggle** (Form Controls) — ToggleText sub-component
+- **ToggleGroup** (Form Controls) — Group of toggle items
+- **Card** (Display) — Compound: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
+- **Surface** (Display) — Shared radius, padding, border, shadow, and optional frosted treatment
+- **Badge** (Display) — BadgeText sub-component
+- **FAB** (Display) — Floating action button. `label` required; pass your own icon as children
+- **Alert** (Display) — AlertTitle & AlertDescription
+- **Avatar** (Display) — AvatarImage + AvatarFallback
+- **DataRow** (Display) — DataRow, DataRowLeft/Center/Right, DataRowLabel/Description/Value
+- **Separator** (Display) — Themed divider
+- **Progress** (Display) — Value-based progress bar with accessibility
+- **Spinner** (Display) — ActivityIndicator wrapper
+- **Skeleton** (Display) — Loading placeholder (pulse = opacity fade, shimmer = sweep)
+- **AspectRatio** (Display) — Maintain aspect ratio container
+- **Tabs** (Layout) — TabsList, TabsTrigger, TabsContent
+- **Accordion** (Layout) — AccordionItem, AccordionTrigger, Content
+- **Collapsible** (Layout) — CollapsibleTrigger, CollapsibleContent
+- **Container** (Layout) — Centred content column with a max width
+- **Dialog** (Overlays & Menus) — Modal dialog with Header, Footer, Title, Description
+- **AlertDialog** (Overlays & Menus) — Confirmation dialog with Action/Cancel buttons
+- **Popover** (Overlays & Menus) — Position-aware popover (requires PortalHost)
+- **Tooltip** (Overlays & Menus) — Position-aware tooltip (requires PortalHost)
+- **DropdownMenu** (Overlays & Menus) — DropdownMenuTrigger, Content, Item, Label, Separator
+- **ContextMenu** (Overlays & Menus) — Long-press context menu
+- **HoverCard** (Overlays & Menus) — Position-aware hover card (requires PortalHost)
+- **Menubar** (Overlays & Menus) — Horizontal menu bar
+- **Toast** (Feedback) — ToastProvider, ToastContainer, useToast() hook
+- **SignInForm** (Auth, copy-paste template) — Email/password sign in with callbacks
+- **SignUpForm** (Auth, copy-paste template) — Registration form with callbacks
+- **ForgotPasswordForm** (Auth, copy-paste template) — Password reset request
+- **ResetPasswordForm** (Auth, copy-paste template) — Set new password
+- **VerifyEmailForm** (Auth, copy-paste template) — Email verification code input
+- **SocialConnections** (Auth, copy-paste template) — OAuth provider buttons
+- **UserMenu** (Auth, copy-paste template) — Profile dropdown for auth flows
+- **AppShell** (Navigation) — Layout shell with header/footer/bottomNav slots
+- **Header** (Navigation) — Top app bar with back/actions
+- **BottomNav** (Navigation) — Tab-style bottom navigation bar
+- **FloatingBottomNav** (Navigation) — Elevated bottom nav with safe area support
+- **TabBar** (Navigation) — Top tab bar with indicator
+- **DrawerMenu** (Navigation) — Drawer with sections and items
+- **ActionBar** (Layout) — Sticky bottom action row with safe-area padding
+- **ConfirmActionSheet** (Layout) — Reusable destructive confirmation sheet
+- **Sheet** (Layout) — Bottom sheet modal with header/content/footer slots
+- **FormModalScreen** (Layout) — Modal scaffold for forms with loading states
+- **ContentSkeleton** (Layout) — Page/content placeholder with variants (list, card, generic)
+- **PageSkeleton** (Layout) — Variant-based page layouts (dashboard, list, settings, card, generic)
+- **ScreenSkeleton** (Layout) — Header slot/placeholder + PageSkeleton content in one block
+- **ErrorBoundary** (Layout) — React ErrorBoundary that renders ErrorState by default
+- **EmptyState** (Layout) — Empty content placeholder
+- **ErrorState** (Layout) — Error display with retry
+- **LoadingState** (Layout) — In-flow loading placeholder for a section still fetching
+- **LoadingScreen** (Layout) — Full-screen loading indicator
+- **PullToRefreshScrollView** (Layout) — Themed ScrollView with RefreshControl (useThemeTokens for colors)
+- **KeyboardAwareScreen** (Layout) — One screen-level keyboard policy for bottom-docked controls
+- **DockedInput** (Layout) — Safe-area-aware bottom dock that reports its complete height
+- **SmartInput** (Layout) — Compose input with slots, variants, and optional rotating examples
+- **SplashScreen** (Layout) — Branded splash (fade/scale/slide variants)
+- **MinimalSplash** (Layout) — Minimal monochrome splash
+- **BrandedSplash** (Layout) — Splash with brand imagery
+- **Chat** (Chat) — Opinionated messages, suggestions, and SmartInput composition
+- **ChatConversation** (Chat) — Constrained conversation viewport that follows streaming output
+- **ChatMessageBubble** (Chat) — Message bubble (user/assistant, big/small text)
+- **ChatSuggestions** (Chat) — Suggestion chips when empty
+- **ProfileHeader** (Profile & Settings, copy-paste template) — Profile header with stats
+- **AccountCard** (Profile & Settings, copy-paste template) — Account summary card
+- **SettingsSection** (Profile & Settings, copy-paste template) — Section header with optional action
+- **SettingsItem** (Profile & Settings, copy-paste template) — Row for toggles/links/settings
+- **ListItem** (Lists) — Title/subtitle row
+- **NotificationItem** (Lists) — Notification row with metadata
+- **TimelineFeed** (Lists) — Vertical feed with connecting lines
+- **ProductCard** (Commerce) — Product card with badge/media
+- **PricingCard** (Commerce) — Pricing tiers with feature list
+- **CheckoutSummary** (Commerce) — Cart summary with line items
+- **MetricCard** (Commerce) — Stats/progress card for dashboards
+- **SubscriptionCard** (Commerce) — Current plan card with manage/upgrade actions
+- **FeatureGate** (Commerce) — Locked feature state with upgrade CTA
+- **UsageBar** (Commerce) — Quota meter with warning/exceeded states
+- **PlanToggle** (Commerce) — Monthly vs annual plan switcher
+- **UpgradeBanner** (Commerce) — Inline upgrade banner with action/dismiss
+- **SmartImage** (Media) — Image with explicit loading, loaded, fallback, and error lifecycle
+- **DatePickerModal** (Date Picker) — Bottom sheet modal with calendar, compact trigger
+- **DatePickerInline** (Date Picker) — Inline calendar for forms or dashboards
+- **DateRangePickerModal** (Date Picker) — Range selection modal with period marking
+- **TimePickerModal** (Date Picker) — Hour and minute wheels in the same bottom sheet

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

@@ -14,11 +14,16 @@ export interface ChatSuggestionsProps {
     className?: string;
 }
 export interface ChatProps {
+    /** Messages to show, each `{ id, role, content, secondary?, contentSize? }`. */
     messages: ChatMessage[];
+    /** Input value. */
     value: string;
+    /** Input change. */
     onChangeText: (text: string) => void;
+    /** Send handler. */
     onSend: () => void;
     placeholder?: string;
+    /** Chips when empty. */
     suggestions?: string[];
     onSuggestionPress?: (text: string) => void;
     leftSlot?: React.ReactNode;
@@ -40,9 +45,12 @@ export interface ChatProps {
     className?: string;
     messagesClassName?: string;
 }
-export declare function ChatMessageBubble({ message, contentClassName, }: {
+export interface ChatMessageBubbleProps {
+    /** The message to render; its `role` decides alignment and colour. */
     message: ChatMessage;
+    /** Classes for the bubble's content wrapper. */
     contentClassName?: string;
-}): React.JSX.Element;
+}
+export declare function ChatMessageBubble({ message, contentClassName }: ChatMessageBubbleProps): React.JSX.Element;
 export declare function ChatSuggestions({ suggestions, onSelect, className }: ChatSuggestionsProps): React.JSX.Element;
 export declare function Chat({ messages, value, onChangeText, onSend, placeholder, suggestions, onSuggestionPress, leftSlot, rightSlot, loading, header, emptyTitle, emptyDescription, exampleMessage, renderMessage, loadingIndicator, inputSafeArea, keyboardVerticalOffset, className, messagesClassName, }: ChatProps): React.JSX.Element;

package/dist/blocks/chat/chat.js

@@ -25,7 +25,7 @@ const chatMessageBubbleVariants = tv({
     },
     defaultVariants: { role: 'assistant' },
 });
-export function ChatMessageBubble({ message, contentClassName, }) {
+export function ChatMessageBubble({ message, contentClassName }) {
     const role = message.role === 'system' ? 'system' : message.role;
     const isUser = message.role === 'user';
     const contentRole = CONTENT_SIZE_ROLE[message.contentSize ?? 'default'];

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

@@ -1,2 +1,2 @@
-export { Chat, ChatMessageBubble, ChatSuggestions, type ChatMessage, type ChatProps, type ChatSuggestionsProps, } from './chat';
+export { Chat, ChatMessageBubble, ChatSuggestions, type ChatMessage, type ChatMessageBubbleProps, type ChatProps, type ChatSuggestionsProps, } from './chat';
 export { ChatConversation, type ChatConversationProps } from './chat-conversation';

package/dist/blocks/commerce/feature-gate.js

@@ -11,7 +11,7 @@ export function FeatureGate({ title, description, icon, buttonLabel = 'Upgrade',
     const body = typographyStyle(visual, 'body');
     const label = typographyStyle(visual, 'label');
     if (!children) {
-        return (_jsx(Card, { className: cn('border-dashed border-border', className), padding: "lg", style: style, ...props, children: _jsxs(View, { className: "items-start gap-3", children: [icon ? _jsx(View, { children: icon }) : null, _jsxs(View, { className: "gap-1", children: [_jsx(Text, { className: "font-semibold text-foreground", style: body, children: title }), _jsx(Text, { className: "text-muted-foreground", style: label, children: description })] }), _jsx(Button, { onPress: onUpgrade, disabled: !onUpgrade, children: _jsx(ButtonText, { children: buttonLabel }) })] }) }));
+        return (_jsx(Card, { className: cn('border-dashed border-border', className), padding: "lg", style: style, ...props, children: _jsxs(View, { className: "items-start gap-3", children: [icon ? _jsx(View, { "aria-hidden": true, children: icon }) : null, _jsxs(View, { className: "gap-1", children: [_jsx(Text, { className: "font-semibold text-foreground", style: body, children: title }), _jsx(Text, { className: "text-muted-foreground", style: label, children: description })] }), _jsx(Button, { onPress: onUpgrade, disabled: !onUpgrade, children: _jsx(ButtonText, { children: buttonLabel }) })] }) }));
     }
     return (_jsxs(View, { className: cn('overflow-hidden border border-border', className), style: [
             {
@@ -19,5 +19,5 @@ export function FeatureGate({ title, description, icon, buttonLabel = 'Upgrade',
                 borderWidth: visual.borderWidthHairline,
             },
             style,
-        ], ...props, children: [_jsx(View, { className: "absolute inset-0 justify-center opacity-45", children: children }), _jsxs(View, { className: "items-center justify-center bg-background/70 px-6", style: { paddingVertical: surfacePadding(visual, 'default') }, children: [icon ? _jsx(View, { className: "mb-3", children: icon }) : null, _jsx(Text, { className: "text-center font-semibold text-foreground", style: body, children: title }), _jsx(Text, { className: "mt-1 text-center text-muted-foreground", style: label, children: description }), _jsx(Button, { className: "mt-4", onPress: onUpgrade, disabled: !onUpgrade, children: _jsx(ButtonText, { children: buttonLabel }) })] })] }));
+        ], ...props, children: [_jsx(View, { className: "absolute inset-0 justify-center opacity-45", children: children }), _jsxs(View, { className: "items-center justify-center bg-background/70 px-6", style: { paddingVertical: surfacePadding(visual, 'default') }, children: [icon ? (_jsx(View, { "aria-hidden": true, className: "mb-3", children: icon })) : null, _jsx(Text, { className: "text-center font-semibold text-foreground", style: body, children: title }), _jsx(Text, { className: "mt-1 text-center text-muted-foreground", style: label, children: description }), _jsx(Button, { className: "mt-4", onPress: onUpgrade, disabled: !onUpgrade, children: _jsx(ButtonText, { children: buttonLabel }) })] })] }));
 }

package/dist/blocks/commerce/metric-card.js

@@ -26,7 +26,7 @@ function MetricCard({ className, label, value, subtitle, progress, segments, ico
     if (loading) {
         return _jsx(MetricCardSkeleton, { className: className, variant: variant ?? 'default' });
     }
-    return (_jsxs(Card, { className: cn(metricCardVariants({ variant }), className), ...props, children: [_jsxs(View, { className: "flex-row items-start justify-between mb-2", children: [_jsx(Text, { variant: "caption", className: "text-muted-foreground", children: label }), icon && _jsx(View, { children: icon })] }), _jsx(Text, { variant: "heading", className: "mb-1", children: value }), subtitle && (_jsx(Text, { variant: "caption", className: "text-muted-foreground", children: subtitle })), progress !== undefined && (_jsx(View, { className: "mt-3", children: _jsx(View, { className: "h-2 bg-muted overflow-hidden", style: { borderRadius: visual.radiusSm }, children: _jsx(View, { className: "h-full bg-primary", style: {
+    return (_jsxs(Card, { className: cn(metricCardVariants({ variant }), className), ...props, children: [_jsxs(View, { className: "flex-row items-start justify-between mb-2", children: [_jsx(Text, { variant: "caption", className: "text-muted-foreground", children: label }), icon && _jsx(View, { "aria-hidden": true, children: icon })] }), _jsx(Text, { variant: "heading", className: "mb-1", children: value }), subtitle && (_jsx(Text, { variant: "caption", className: "text-muted-foreground", children: subtitle })), progress !== undefined && (_jsx(View, { className: "mt-3", children: _jsx(View, { className: "h-2 bg-muted overflow-hidden", style: { borderRadius: visual.radiusSm }, children: _jsx(View, { className: "h-full bg-primary", style: {
                             borderRadius: visual.radiusSm,
                             width: `${Math.min(100, Math.max(0, progress))}%`,
                         } }) }) })), segments && segments.length > 0 && (_jsx(View, { className: "mt-3 flex-row h-3 overflow-hidden", style: { borderRadius: visual.radiusSm }, children: segments.map((seg) => (_jsx(View, { className: "h-full", style: { width: `${seg.value}%`, backgroundColor: seg.color } }, `${seg.color}:${seg.value}`))) }))] }));

package/dist/blocks/commerce/subscription-card.d.ts

@@ -1,11 +1,18 @@
 import { type ViewProps } from 'react-native';
 export interface SubscriptionCardProps extends ViewProps {
+    /** Current plan label. */
     planName: string;
+    /** Plan price. */
     price: string;
+    /** Billing period label. */
     period?: string;
+    /** Renewal/expiry date text. */
     expiresAt?: string;
+    /** Active/inactive badge state. */
     isActive?: boolean;
+    /** Manage action. */
     onManage?: () => void;
+    /** Upgrade action. */
     onUpgrade?: () => void;
     manageLabel?: string;
     upgradeLabel?: string;

package/dist/blocks/commerce/usage-bar.d.ts

@@ -1,9 +1,13 @@
 import { type ViewProps } from 'react-native';
 export type UsageBarVariant = 'default' | 'warning' | 'exceeded';
 export interface UsageBarProps extends ViewProps {
+    /** Usage label. */
     label: string;
+    /** Used amount. */
     used: number;
+    /** Quota limit. */
     limit: number;
+    /** Optional explicit visual state. */
     variant?: UsageBarVariant;
     className?: string;
 }

package/dist/blocks/layout/app-shell.d.ts

@@ -1,9 +1,13 @@
 import React from 'react';
 import { type ViewProps } from 'react-native';
 export interface AppShellProps extends ViewProps {
+    /** Header slot. */
     header?: React.ReactNode;
+    /** Footer slot. */
     footer?: React.ReactNode;
+    /** Bottom navigation slot. */
     bottomNav?: React.ReactNode;
+    /** Wrap in SafeAreaView. */
     safeArea?: boolean;
     /** Keep shell mounted while swapping content with skeleton. */
     loading?: boolean;

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

@@ -14,5 +14,5 @@ function DefaultEmptyIcon() {
 }
 export function EmptyState({ icon, title, description, action, secondaryAction, className, style, ...props }) {
     const visual = useVisualTokens();
-    return (_jsxs(View, { className: cn('flex-1 items-center justify-center', className), style: [{ padding: surfacePadding(visual, 'lg') }, style], ...props, children: [_jsx(View, { className: "mb-6", children: icon ? _jsx(View, { className: "text-muted-foreground", children: icon }) : _jsx(DefaultEmptyIcon, {}) }), _jsx(Text, { className: "mb-2 text-center font-semibold text-foreground", style: typographyStyle(visual, 'title'), children: title }), description && (_jsx(Text, { className: "mb-6 max-w-xs text-center text-muted-foreground", children: description })), action && (_jsx(Button, { onPress: action.onPress, className: "mb-3", children: _jsx(ButtonText, { children: action.label }) })), secondaryAction && (_jsx(Button, { variant: "ghost", onPress: secondaryAction.onPress, children: _jsx(ButtonText, { children: secondaryAction.label }) }))] }));
+    return (_jsxs(View, { className: cn('flex-1 items-center justify-center', className), style: [{ padding: surfacePadding(visual, 'lg') }, style], ...props, children: [_jsx(View, { className: "mb-6", children: icon ? (_jsx(View, { "aria-hidden": true, className: "text-muted-foreground", children: icon })) : (_jsx(DefaultEmptyIcon, {})) }), _jsx(Text, { className: "mb-2 text-center font-semibold text-foreground", style: typographyStyle(visual, 'title'), children: title }), description && (_jsx(Text, { className: "mb-6 max-w-xs text-center text-muted-foreground", children: description })), action && (_jsx(Button, { onPress: action.onPress, className: "mb-3", children: _jsx(ButtonText, { children: action.label }) })), secondaryAction && (_jsx(Button, { variant: "ghost", onPress: secondaryAction.onPress, children: _jsx(ButtonText, { children: secondaryAction.label }) }))] }));
 }

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

@@ -7,5 +7,5 @@ export function ErrorState({ icon, title = 'Something went wrong', description,
     const errorMessage = description ||
         (error instanceof Error ? error.message : error) ||
         'An unexpected error occurred';
-    return (_jsxs(View, { className: cn('flex-1 items-center justify-center p-8', className), ...props, children: [icon && _jsx(View, { className: "mb-6 text-destructive", children: icon }), _jsx(Text, { className: "mb-2 text-center text-xl font-semibold text-foreground", children: title }), _jsx(Text, { className: "mb-6 max-w-xs text-center text-muted-foreground", children: errorMessage }), onRetry && (_jsx(Button, { onPress: onRetry, children: _jsx(ButtonText, { children: retryLabel }) }))] }));
+    return (_jsxs(View, { className: cn('flex-1 items-center justify-center p-8', className), ...props, children: [icon && (_jsx(View, { "aria-hidden": true, className: "mb-6 text-destructive", children: icon })), _jsx(Text, { className: "mb-2 text-center text-xl font-semibold text-foreground", children: title }), _jsx(Text, { className: "mb-6 max-w-xs text-center text-muted-foreground", children: errorMessage }), onRetry && (_jsx(Button, { onPress: onRetry, children: _jsx(ButtonText, { children: retryLabel }) }))] }));
 }

package/dist/blocks/layout/page-skeleton.d.ts

@@ -4,6 +4,7 @@ export type PageSkeletonVariant = 'dashboard' | 'list' | 'settings' | 'card' | '
 export type PageSkeletonPadding = 'none' | 'sm' | 'default' | 'lg';
 export type PageSkeletonHeaderPlaceholder = 'compact' | 'default';
 export interface PageSkeletonProps extends ViewProps {
+    /** Layout preset. */
     variant: PageSkeletonVariant;
     /** Rows/items for list (default 3) or settings (default 4) variant. */
     count?: number;

package/dist/blocks/layout/pull-to-refresh-scroll-view.d.ts

@@ -1,5 +1,6 @@
 import { type ScrollViewProps } from 'react-native';
 export interface PullToRefreshScrollViewProps extends Omit<ScrollViewProps, 'refreshControl'> {
+    /** Whether refresh is in progress. */
     refreshing: boolean;
     /**
      * Refreshing is almost always async, so the signature says so. Nothing here awaits it —

package/dist/blocks/layout/screen-skeleton.d.ts

@@ -2,10 +2,15 @@ import { type ViewProps } from 'react-native';
 import { type ReactNode } from 'react';
 import { type PageSkeletonHeaderPlaceholder, type PageSkeletonPadding, type PageSkeletonVariant } from './page-skeleton';
 export interface ScreenSkeletonProps extends Omit<ViewProps, 'children'> {
+    /** Skeleton content preset. */
     variant?: PageSkeletonVariant;
+    /** Rows/items for list/settings variants. */
     count?: number;
+    /** Inner content padding. */
     padding?: PageSkeletonPadding;
+    /** Real header slot. */
     header?: ReactNode;
+    /** Placeholder header. */
     headerPlaceholder?: boolean | PageSkeletonHeaderPlaceholder;
     className?: string;
 }

package/dist/blocks/layout/sheet.js

@@ -79,7 +79,7 @@ export function Sheet({ open, onOpenChange, children, maxHeight = 'full', maxWid
         widthStyle,
         frostedSurface.surfaceStyle,
     ];
-    return (_jsx(OverlayHost, { open: mounted, animationType: "none", onRequestClose: onClose, children: _jsxs(View, { className: "flex-1 justify-end", children: [_jsx(Animated.View, { style: [
+    return (_jsx(OverlayHost, { open: mounted, animationType: "none", onRequestClose: open ? onClose : undefined, children: _jsxs(View, { className: "flex-1 justify-end", children: [_jsx(Animated.View, { style: [
                         StyleSheet.absoluteFill,
                         { backgroundColor: frosted ? 'transparent' : colors.overlay },
                         backdropStyle,

package/dist/blocks/lists/list-item.js

@@ -27,5 +27,5 @@ export function ListItem({ icon, title, subtitle, description, rightIcon, rightT
     return (_jsxs(Pressable, { accessibilityRole: props.onPress || props.onLongPress ? 'button' : undefined, className: cn('flex-row items-center bg-card', focusRing, showBorder && 'border-border', 'active:bg-muted', className), style: (state) => {
             const callerStyle = typeof styleProp === 'function' ? styleProp(state) : styleProp;
             return [rowStyle, callerStyle];
-        }, ...props, children: [icon && _jsx(View, { className: "mr-3 text-muted-foreground", children: icon }), _jsxs(View, { className: "flex-1", children: [_jsx(Text, { className: "text-foreground", style: typographyStyle(visual, 'body'), children: title }), subtitle && (_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'label'), children: subtitle })), description && (_jsx(Text, { className: "mt-1 text-muted-foreground", style: typographyStyle(visual, 'label'), numberOfLines: 2, children: description }))] }), rightText && (_jsx(Text, { className: "mr-2 text-muted-foreground", style: typographyStyle(visual, 'label'), children: rightText })), rightIcon && _jsx(View, { className: "text-muted-foreground", children: rightIcon }), action, !action && !rightIcon && (_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'emphasis'), children: "\u203A" }))] }));
+        }, ...props, children: [icon && (_jsx(View, { "aria-hidden": true, className: "mr-3 text-muted-foreground", children: icon })), _jsxs(View, { className: "flex-1", children: [_jsx(Text, { className: "text-foreground", style: typographyStyle(visual, 'body'), children: title }), subtitle && (_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'label'), children: subtitle })), description && (_jsx(Text, { className: "mt-1 text-muted-foreground", style: typographyStyle(visual, 'label'), numberOfLines: 2, children: description }))] }), rightText && (_jsx(Text, { className: "mr-2 text-muted-foreground", style: typographyStyle(visual, 'label'), children: rightText })), rightIcon && (_jsx(View, { "aria-hidden": true, className: "text-muted-foreground", children: rightIcon })), action, !action && !rightIcon && (_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'emphasis'), children: "\u203A" }))] }));
 }

package/dist/blocks/lists/notification-item.js

@@ -27,5 +27,5 @@ export function NotificationItem({ icon, avatarUrl, avatarFallback, title, messa
     return (_jsxs(Pressable, { accessibilityRole: props.onPress || props.onLongPress ? 'button' : undefined, className: cn('flex-row items-start active:bg-muted', focusRing, !read && 'bg-primary-soft-subtle', className), style: (state) => {
             const callerStyle = typeof styleProp === 'function' ? styleProp(state) : styleProp;
             return [rowStyle, callerStyle];
-        }, ...props, children: [avatarUrl || avatarFallback ? (_jsxs(Avatar, { className: "h-10 w-10", children: [avatarUrl && _jsx(AvatarImage, { src: avatarUrl }), _jsx(AvatarFallback, { children: avatarFallback })] })) : (icon && (_jsx(View, { className: "h-10 w-10 items-center justify-center rounded-full bg-muted", children: icon }))), _jsxs(View, { className: "ml-3 flex-1", children: [_jsxs(View, { className: "flex-row items-center justify-between", children: [_jsx(Text, { className: cn(!read ? 'font-semibold text-foreground' : 'text-foreground'), style: typographyStyle(visual, 'label'), children: title }), _jsxs(View, { className: "flex-row items-center gap-2", children: [_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'caption'), children: time }), !read && showDot && _jsx(View, { className: "h-2 w-2 rounded-full bg-primary" })] })] }), _jsx(Text, { className: "mt-0.5 text-muted-foreground", style: typographyStyle(visual, 'label'), numberOfLines: 2, children: message })] })] }));
+        }, ...props, children: [avatarUrl || avatarFallback ? (_jsxs(Avatar, { className: "h-10 w-10", children: [avatarUrl && _jsx(AvatarImage, { src: avatarUrl }), _jsx(AvatarFallback, { children: avatarFallback })] })) : (icon && (_jsx(View, { "aria-hidden": true, className: "h-10 w-10 items-center justify-center rounded-full bg-muted", children: icon }))), _jsxs(View, { className: "ml-3 flex-1", children: [_jsxs(View, { className: "flex-row items-center justify-between", children: [_jsx(Text, { className: cn(!read ? 'font-semibold text-foreground' : 'text-foreground'), style: typographyStyle(visual, 'label'), children: title }), _jsxs(View, { className: "flex-row items-center gap-2", children: [_jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'caption'), children: time }), !read && showDot && _jsx(View, { className: "h-2 w-2 rounded-full bg-primary" })] })] }), _jsx(Text, { className: "mt-0.5 text-muted-foreground", style: typographyStyle(visual, 'label'), numberOfLines: 2, children: message })] })] }));
 }

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

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useState } from 'react';
-import { View } from 'react-native';
+import { Platform, View } from 'react-native';
 import { Image } from 'expo-image';
 import { Skeleton } from '../../components/skeleton';
 import { cn } from '../../lib/cn';
@@ -56,7 +56,9 @@ const SmartImage = React.forwardRef(({ className, source, alt, skeleton = true,
         onError?.();
     };
     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 } })] }));
+    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, ...(Platform.OS === 'web'
+                    ? null
+                    : { accessible: Boolean(alt), accessibilityRole: 'image' }), accessibilityLabel: 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/bottom-nav.js

@@ -12,7 +12,7 @@ function BottomNavItemComponent({ item, isActive, className, style: styleProp, .
     const interactiveStyle = withInteractivePressableStyle(styleProp, interaction, {
         pressedVariant: 'default',
     });
-    return (_jsxs(Pressable, { accessibilityRole: "tab", accessibilityState: { selected: isActive }, "aria-selected": isActive, className: cn('flex-1 items-center justify-center py-2', className), style: interactiveStyle, ...props, children: [_jsxs(View, { className: "relative", style: !isActive ? { opacity: interaction.inactiveOpacity } : undefined, children: [icon, badge !== undefined && badge > 0 && (_jsx(View, { className: "absolute -right-2 -top-1 h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1", children: _jsx(Text, { className: "font-bold text-destructive-foreground", style: { fontSize: visual.bottomNavBadgeFontSize }, children: badge > 99 ? '99+' : badge }) }))] }), _jsx(Text, { className: cn('mt-1 font-medium', isActive ? 'text-primary' : 'text-muted-foreground'), style: typographyStyle(visual, 'caption'), children: label })] }));
+    return (_jsxs(Pressable, { accessibilityRole: "tab", accessibilityState: { selected: isActive }, "aria-selected": isActive, className: cn('flex-1 items-center justify-center py-2', className), style: interactiveStyle, ...props, children: [_jsxs(View, { className: "relative", style: !isActive ? { opacity: interaction.inactiveOpacity } : undefined, children: [_jsx(View, { "aria-hidden": true, children: icon }), badge !== undefined && badge > 0 && (_jsx(View, { className: "absolute -right-2 -top-1 h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1", children: _jsx(Text, { className: "font-bold text-destructive-foreground", style: { fontSize: visual.bottomNavBadgeFontSize }, children: badge > 99 ? '99+' : badge }) }))] }), _jsx(Text, { className: cn('mt-1 font-medium', isActive ? 'text-primary' : 'text-muted-foreground'), style: typographyStyle(visual, 'caption'), children: label })] }));
 }
 export function BottomNav({ items, activeKey, onSelect, className, ...props }) {
     return (_jsx(View

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

@@ -21,7 +21,7 @@ function DrawerItemRow({ item, active, onSelect, interaction, visual }) {
         paddingVertical: visual.controlPaddingYDefault,
         minHeight: visual.touchTargetMinSize,
     }, interaction, { pressedVariant: 'default' }), [interaction, visual]);
-    return (_jsxs(Pressable, { accessibilityRole: "button", onPress: handlePress, className: cn('flex-row items-center gap-3 mx-1 transition-colors', active && 'bg-primary-soft-subtle'), style: pressStyle, children: [item.icon, _jsx(Text, { className: cn('flex-1 font-semibold tracking-tight', item.destructive ? 'text-destructive' : active ? 'text-primary' : 'text-foreground'), style: { fontSize: visual.drawerItemFontSize }, children: item.label }), item.badge === undefined ? null : (_jsx(View, { className: "bg-primary px-2 py-0.5 items-center", style: { minWidth: visual.drawerBadgeMinWidth, borderRadius: visual.badgeRadius }, children: _jsx(Text, { className: "font-semibold text-primary-foreground", style: { fontSize: visual.navItemBadgeFontSize }, children: item.badge }) }))] }));
+    return (_jsxs(Pressable, { accessibilityRole: "button", onPress: handlePress, className: cn('flex-row items-center gap-3 mx-1 transition-colors', active && 'bg-primary-soft-subtle'), style: pressStyle, children: [_jsx(View, { "aria-hidden": true, children: item.icon }), _jsx(Text, { className: cn('flex-1 font-semibold tracking-tight', item.destructive ? 'text-destructive' : active ? 'text-primary' : 'text-foreground'), style: { fontSize: visual.drawerItemFontSize }, children: item.label }), item.badge === undefined ? null : (_jsx(View, { className: "bg-primary px-2 py-0.5 items-center", style: { minWidth: visual.drawerBadgeMinWidth, borderRadius: visual.badgeRadius }, children: _jsx(Text, { className: "font-semibold text-primary-foreground", style: { fontSize: visual.navItemBadgeFontSize }, children: item.badge }) }))] }));
 }
 function DrawerSectionGap() {
     return _jsx(View, { className: "mb-4" });
@@ -125,5 +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 })] })] })] }));
-    return (_jsx(OverlayHost, { open: mounted, animationType: "none", onRequestClose: onClose, children: drawerTree }));
+    return (_jsx(OverlayHost, { open: mounted, animationType: "none", onRequestClose: visible ? onClose : undefined, children: drawerTree }));
 }

package/dist/blocks/navigation/floating-bottom-nav.js

@@ -13,7 +13,9 @@ function FloatingNavItem({ item, isActive, className, style: styleProp, ...props
         paddingHorizontal: visual.controlPaddingXDefault,
         paddingVertical: visual.controlPaddingYSm,
     };
-    return (_jsxs(Pressable, { accessibilityRole: "tab", accessibilityState: { selected: isActive }, "aria-selected": isActive, className: cn('flex-row items-center gap-2 active:scale-95', isActive && 'bg-primary', className), style: (state) => [pillStyle, typeof styleProp === 'function' ? styleProp(state) : styleProp], ...props, children: [_jsx(View, { className: cn(isActive ? 'text-primary-foreground' : 'text-muted-foreground'), children: icon }), isActive && (_jsx(Text, { className: "font-semibold text-primary-foreground", style: typographyStyle(visual, 'label'), children: label }))] }));
+    return (_jsxs(Pressable, { accessibilityRole: "tab", 
+        // Inactive tabs show only an icon, so the label must still name them.
+        accessibilityLabel: label, accessibilityState: { selected: isActive }, "aria-selected": isActive, className: cn('flex-row items-center gap-2 active:scale-95', isActive && 'bg-primary', className), style: (state) => [pillStyle, typeof styleProp === 'function' ? styleProp(state) : styleProp], ...props, children: [_jsx(View, { "aria-hidden": true, className: cn(isActive ? 'text-primary-foreground' : 'text-muted-foreground'), children: icon }), isActive && (_jsx(Text, { className: "font-semibold text-primary-foreground", style: typographyStyle(visual, 'label'), children: label }))] }));
 }
 export function FloatingBottomNav({ items, activeKey, onSelect, className, ...props }) {
     const visual = useVisualTokens();

package/dist/blocks/navigation/tab-bar.js

@@ -34,7 +34,7 @@ function TabBarItemComponent({ item, isActive, variant, className, style: styleP
     return (_jsxs(Pressable, { accessibilityRole: "tab", accessibilityState: { selected: isActive }, "aria-selected": isActive, className: cn(baseStyles, variantStyles[variant], className), style: (state) => [
             tokenStyle,
             typeof interactiveStyle === 'function' ? interactiveStyle(state) : interactiveStyle,
-        ], ...props, children: [icon && (_jsx(View, { className: isActive && variant === 'pills' ? 'text-primary-foreground' : '', children: icon })), _jsx(Text, { className: cn(textStyles[variant]), style: typographyStyle(visual, 'label'), children: label })] }));
+        ], ...props, children: [icon && (_jsx(View, { "aria-hidden": true, className: isActive && variant === 'pills' ? 'text-primary-foreground' : '', children: icon })), _jsx(Text, { className: cn(textStyles[variant]), style: typographyStyle(visual, 'label'), children: label })] }));
 }
 export function TabBar({ items, activeKey, onSelect, variant = 'default', scrollable = false, className, style, ...props }) {
     const visual = useVisualTokens();

package/dist/components/alert/alert.d.ts

@@ -27,6 +27,13 @@ declare const alertVariants: import("tailwind-variants").TVReturnType<{
     };
 }, undefined>>;
 export interface AlertProps extends ViewProps, VariantProps<typeof alertVariants> {
+    /**
+     * Speak the alert when it appears, for alerts shown in response to an action such as a
+     * failed submit. Android and the web already read it through the live region; iOS has
+     * none, so this announces its text once. Leave it off for alerts that are part of a
+     * screen's content, or every visit would read them aloud.
+     */
+    announce?: boolean;
 }
 declare const Alert: ForwardRefComponent<ViewInstance, AlertProps>;
 export interface AlertTitleProps extends TextProps {

package/dist/components/alert/alert.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React from 'react';
-import { View, Text, } from 'react-native';
+import React, { useEffect } from 'react';
+import { AccessibilityInfo, Platform, View, Text, } from 'react-native';
 import { cn } from '../../lib/cn';
 import { tv } from '../../lib/tv';
 import { useVisualTokens } from '../../lib/visual-tokens';
@@ -20,8 +20,27 @@ const alertVariants = tv({
         variant: 'default',
     },
 });
-const Alert = React.forwardRef(({ className, variant, style, ...props }, ref) => {
+/** The visible text of an alert's children, for the iOS announcement. */
+function textOf(node) {
+    if (typeof node === 'string' || typeof node === 'number')
+        return String(node);
+    if (Array.isArray(node))
+        return node.map(textOf).filter(Boolean).join('. ');
+    if (React.isValidElement(node))
+        return textOf(node.props.children);
+    return '';
+}
+const Alert = React.forwardRef(({ className, variant, style, announce = false, children, ...props }, ref) => {
     const visual = useVisualTokens();
+    useEffect(() => {
+        if (!announce || Platform.OS !== 'ios')
+            return;
+        const message = textOf(children);
+        if (message)
+            AccessibilityInfo.announceForAccessibility(message);
+        // Once, when the alert appears; a re-render must not repeat it.
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- once per alert, by design
+    }, []);
     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.
@@ -32,7 +51,7 @@ const Alert = React.forwardRef(({ className, variant, style, ...props }, ref) =>
                 padding: surfacePadding(visual, 'sm'),
             },
             style,
-        ], ...props }));
+        ], ...props, children: children }));
 });
 Alert.displayName = 'Alert';
 const AlertTitle = React.forwardRef(({ className, style, ...props }, ref) => {

package/dist/components/button/button.d.ts

@@ -97,7 +97,9 @@ declare const buttonTextVariants: import("tailwind-variants").TVReturnType<{
 }, undefined>>;
 export interface ButtonProps extends Omit<PressableProps, 'children' | 'feedback' | 'loading'>, VariantProps<typeof buttonVariants> {
     children?: React.ReactNode;
+    /** Additional Tailwind classes. */
     className?: string;
+    /** Disable the button. */
     disabled?: boolean;
     /** Shows a centered spinner, exposes busy state, and prevents interaction. */
     loading?: boolean;
@@ -115,6 +117,7 @@ declare function ButtonText({ className, variant: variantProp, size: sizeProp, s
 declare namespace ButtonText {
     var displayName: string;
 }
+/** Decorative: the button is named by its text, so an icon glyph must not join that name. */
 declare function ButtonIcon({ className, ...props }: ButtonIconProps): React.JSX.Element;
 declare namespace ButtonIcon {
     var displayName: string;

package/dist/components/button/button.js

@@ -107,8 +107,9 @@ function ButtonText({ className, variant: variantProp, size: sizeProp, style, ..
     return (_jsx(Text, { className: font ? font.className : resolved, style: font ? [typography, font.style, style] : [typography, style], ...props }));
 }
 ButtonText.displayName = 'ButtonText';
+/** Decorative: the button is named by its text, so an icon glyph must not join that name. */
 function ButtonIcon({ className, ...props }) {
-    return _jsx(View, { className: cn('items-center justify-center', className), ...props });
+    return _jsx(View, { "aria-hidden": true, className: cn('items-center justify-center', className), ...props });
 }
 ButtonIcon.displayName = 'ButtonIcon';
 export { Button, ButtonText, ButtonIcon, buttonVariants, buttonTextVariants };

package/dist/components/form-field/form-field.d.ts

@@ -51,8 +51,26 @@ export interface FormFieldState {
     invalid: boolean;
     disabled: boolean;
     required: boolean;
+    /** Set inside a FormField: `FormLabel` takes it as its id and controls point to it. */
+    labelId?: string;
 }
 export declare function useFormFieldState(): FormFieldState;
+interface CallerNaming {
+    accessibilityLabel?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    accessibilityLabelledBy?: string | string[];
+}
+/**
+ * Accessibility props that tie a text control to its FormField: named by the FormLabel
+ * unless the caller names or links it any of the four ways React Native allows, and
+ * required when the field is. Spread before the caller's props. iOS has no labelled-by;
+ * VoiceOver reads the visible label just before the field.
+ */
+export declare function fieldAccessibilityProps(field: FormFieldState, props: CallerNaming): {
+    'aria-labelledby': string | undefined;
+    'aria-required': true | undefined;
+};
 export interface FormFieldProps extends ViewProps, VariantProps<typeof formFieldVariants> {
     invalid?: boolean;
     disabled?: boolean;