@thewhileloop/whileui 3.0.0 → 4.0.0

package/README.md

@@ -27,16 +27,20 @@ Use `npm install` instead of `bun add` if you prefer npm.
 1. **metro.config.js** (wrap with withUniwindConfig):
 
 ```js
+const { getDefaultConfig } = require('expo/metro-config');
 const { withUniwindConfig } = require('uniwind/metro');
 
-module.exports = withUniwindConfig({
+/** @type {import('expo/metro-config').MetroConfig} */
+const config = getDefaultConfig(__dirname);
+
+module.exports = withUniwindConfig(config, {
   cssEntryFile: './global.css',
-})({
-  // your metro config
 });
 ```
 
-> `withUniwindConfig` must be the outermost wrapper. `cssEntryFile` must be a relative path string.
+> `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.
 
 2. **global.css** at app root:
 
@@ -44,6 +48,11 @@ module.exports = withUniwindConfig({
 @import 'tailwindcss';
 @import 'uniwind';
 
+/* Required when WhileUI is installed from npm. Tailwind does not scan
+   node_modules, so without this its class names are never detected and every
+   component renders unstyled. */
+@source './node_modules/@thewhileloop/whileui/dist';
+
 /* WhileUI Noir theme - copy this or create your own */
 @layer theme {
   :root {
@@ -216,7 +225,9 @@ function MyScreen() {
 - **PortalHost:** Add `<PortalHost />` at app root for Select, Popover, Tooltip, HoverCard.
 - **Motion:** Wrap the root in `<MotionProvider>`; use `useMotionPolicy()` for semantic
   durations, the responsive spring, and reduced-motion behavior.
-- **Uniwind:** `withUniwindConfig` must wrap metro config. `global.css` at app root, imported in `App.tsx`.
+- **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
+  `@source './node_modules/@thewhileloop/whileui/dist';` or every component renders unstyled.
 - **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/templates/` (auth, profile); flow patterns in README "Flow Patterns" section.
 
 ## Components
@@ -259,18 +270,19 @@ function MyScreen() {
 
 ### Display
 
-| Component       | Variants                                          | Notes                                                                           |
-| --------------- | ------------------------------------------------- | ------------------------------------------------------------------------------- |
-| **Card**        | padding (none, sm, default, lg), unstyled         | Compound: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter |
-| **Badge**       | default, secondary, destructive, outline, success | BadgeText sub-component                                                         |
-| **Alert**       | default, destructive, success, warning            | AlertTitle & AlertDescription                                                   |
-| **Avatar**      | sm, default, lg                                   | AvatarImage + AvatarFallback                                                    |
-| **DataRow**     | default, compact                                  | DataRow, DataRowLeft/Center/Right, DataRowLabel/Description/Value               |
-| **Separator**   | horizontal, vertical                              | Themed divider                                                                  |
-| **Progress**    | sm, default, lg                                   | Value-based progress bar with accessibility                                     |
-| **Spinner**     | sm, default, lg                                   | ActivityIndicator wrapper                                                       |
-| **Skeleton**    | pulse, shimmer                                    | Loading placeholder (pulse = opacity fade, shimmer = sweep)                     |
-| **AspectRatio** | —                                                 | Maintain aspect ratio container                                                 |
+| Component       | Variants                                                | Notes                                                                           |
+| --------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| **Card**        | padding (none, sm, default, lg), unstyled               | Compound: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter |
+| **Badge**       | default, secondary, destructive, outline, success       | BadgeText sub-component                                                         |
+| **FAB**         | default, secondary, destructive, surface; sm/default/lg | Floating action button. `label` required; pass your own icon as children        |
+| **Alert**       | default, destructive, success, warning                  | AlertTitle & AlertDescription                                                   |
+| **Avatar**      | sm, default, lg                                         | AvatarImage + AvatarFallback                                                    |
+| **DataRow**     | default, compact                                        | DataRow, DataRowLeft/Center/Right, DataRowLabel/Description/Value               |
+| **Separator**   | horizontal, vertical                                    | Themed divider                                                                  |
+| **Progress**    | sm, default, lg                                         | Value-based progress bar with accessibility                                     |
+| **Spinner**     | sm, default, lg                                         | ActivityIndicator wrapper                                                       |
+| **Skeleton**    | pulse, shimmer                                          | Loading placeholder (pulse = opacity fade, shimmer = sweep)                     |
+| **AspectRatio** | —                                                       | Maintain aspect ratio container                                                 |
 
 ### Layout
 
@@ -404,6 +416,7 @@ Copy from `apps/showcase/templates/profile/`:
 | **DatePickerModal**      | Bottom sheet modal with calendar, compact trigger |
 | **DatePickerInline**     | Inline calendar for forms or dashboards           |
 | **DateRangePickerModal** | Range selection modal with period marking         |
+| **TimePickerModal**      | Hour and minute wheels in the same bottom sheet   |
 
 **Tokens without a renderer.** `@thewhileloop/whileui/tokens` exports the theme
 and visual contracts, the presets, and `deriveThemeColors(base, scheme)` — give it
@@ -412,6 +425,55 @@ as the default presets. Safe in a build script (no React, RN or Uniwind
 imports); `useThemeColors()` uses it too, so a missing `--color-primary-soft`
 derives from the app's own primary instead of falling back to the default palette.
 
+**Building a product preset.** Use `createThemePreset` rather than a `ThemePreset`
+literal — it takes the 25 base colours per scheme and derives the rest:
+
+```ts
+import { createThemePreset, themePresetToCss } from '@thewhileloop/whileui/tokens';
+
+const preset = createThemePreset({
+  name: 'acme',
+  description: 'Acme brand palette.',
+  light: { background: '...', foreground: '...', primary: '...' /* 25 base keys */ },
+  dark: { background: '...', foreground: '...', primary: '...' },
+  visual: { radiusLg: 12 }, // optional, partial
+});
+
+writeFileSync('theme.generated.css', themePresetToCss(preset));
+```
+
+The literal form asks for all 52 colours per scheme, including every active variant,
+soft variant, overlay, surface, interaction state and shadow. Those are exactly what
+`deriveThemeColors` computes, so hand-writing them produces a second derivation that
+drifts from the library's. Override a derived value by assigning to the result.
+
+### FAB
+
+One primary action, raised above the content. It owns no icon dependency — pass the
+glyph as children and colour it from `useIconColors()`, because icon libraries need a
+concrete colour rather than a class.
+
+```tsx
+import { FAB, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
+
+<FAB label="New group" onPress={create}>
+  <Feather name="plus" size={24} color={icons.primaryForeground} />
+</FAB>;
+```
+
+| Prop        | Type                                             | Default    | Notes                                   |
+| ----------- | ------------------------------------------------ | ---------- | --------------------------------------- |
+| `label`     | `string`                                         | —          | Required. The accessible name           |
+| `variant`   | `default \| secondary \| destructive \| surface` | `default`  |                                         |
+| `size`      | `sm \| default \| lg`                            | `default`  | 48 / 56 / 64 — all clear touch minimums |
+| `placement` | `floating \| floating-left \| inline`            | `floating` | `inline` lets the caller position it    |
+
+`FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never
+needs `hitSlop`.
+
 ## Layout Primitives (Stack, Row)
 
 Use `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.
@@ -592,7 +654,7 @@ The WhileUI token contract is strict for cross-app reuse. Define these in **ever
 - Required core tokens: `background`, `foreground`, `card`, `card-foreground`, `popover`, `popover-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `muted`, `muted-foreground`, `accent`, `accent-foreground`, `destructive`, `destructive-foreground`, `border`, `input`, `ring`
 - Optional status tokens: `success`, `success-foreground`, `warning`, `warning-foreground`, `info`, `info-foreground`
 - Optional effect tokens: `overlay`, `overlay-strong`, `surface-elevated`, `surface-border`, `surface-highlight`, `surface-translucent`, `surface-translucent-border`, `state-hover`, `state-pressed`, `state-disabled`
-- Optional interaction/motion tokens: `--ui-press-opacity`, `--ui-press-opacity-strong`, `--ui-disabled-opacity`, `--ui-disabled-opacity-soft`, `--ui-disabled-opacity-subtle`, `--ui-inactive-opacity`, `--ui-motion-fast`, `--ui-motion-normal`, `--ui-motion-slow`, `--ui-motion-spring-damping`, `--ui-motion-spring-stiffness`, `--ui-motion-spring-mass`, `--ui-drawer-open-duration`, `--ui-drawer-close-duration`, `--ui-blur-intensity-subtle`, `--ui-blur-intensity-medium`, `--ui-blur-intensity-strong`, `--ui-blur-saturation-pct`, `--ui-frosted-highlight-height`, `--ui-frosted-backdrop-blur-intensity`, `--ui-frosted-backdrop-blur-scale`, `--ui-frosted-android-tint-alpha-scale`, `--ui-frosted-android-experimental-blur`, `--ui-drawer-frosted-inset`, `--ui-drawer-frosted-radius`, `--ui-drawer-content-top-padding`
+- Optional visual tokens, generated from a preset: `--ui-blur-intensity-subtle`, `--ui-blur-intensity-medium`, `--ui-blur-intensity-strong`, `--ui-blur-saturation-pct`, `--ui-frosted-highlight-height`, `--ui-frosted-backdrop-blur-intensity`, `--ui-frosted-backdrop-blur-scale`, `--ui-frosted-android-tint-alpha-scale`, `--ui-frosted-android-experimental-blur`, `--ui-drawer-frosted-inset`, `--ui-drawer-frosted-radius`, `--ui-drawer-content-top-padding`
 - Optional scale tokens: spacing (`--spacing`, `--spacing-*`), typography (`--text-*`, `--leading-*`, `--tracking-*`), radius (`--radius-*`), elevation (`--shadow-*`)
 
 Minimal contract example:
@@ -710,53 +772,25 @@ const iconColors = useIconColors();
 
 Input, Textarea, NumericInput, SmartInput, Spinner, and LoadingScreen default to theme colors when you omit `placeholderTextColor` or `spinnerColor`.
 
-### Interaction + Motion Tokens
+### Interaction and motion
 
-WhileUI components also read optional `--ui-*` tokens for deeper control of press feedback, disabled states, and motion timing:
+Press opacity, disabled opacity, motion durations, the responsive spring, and the drawer
+open and close durations are package constants on `INTERACTION_TOKENS`. They are not CSS
+variables and they do not change with a preset. Delete any `--ui-press-*`,
+`--ui-disabled-*`, `--ui-inactive-opacity`, `--ui-motion-*`, or `--ui-drawer-open-duration`
+/ `--ui-drawer-close-duration` declarations from a theme: nothing reads them.
 
-```css
-@theme {
-  --ui-press-opacity: 0.72;
-  --ui-press-opacity-strong: 0.9;
-  --ui-disabled-opacity: 0.5;
-  --ui-disabled-opacity-soft: 0.6;
-  --ui-disabled-opacity-subtle: 0.4;
-  --ui-inactive-opacity: 0.5;
-  --ui-motion-fast: 160;
-  --ui-motion-normal: 220;
-  --ui-motion-slow: 300;
-  --ui-motion-spring-damping: 20;
-  --ui-motion-spring-stiffness: 260;
-  --ui-motion-spring-mass: 0.8;
-  --ui-drawer-open-duration: 300;
-  --ui-drawer-close-duration: 220;
-  --ui-blur-intensity-subtle: 18;
-  --ui-blur-intensity-medium: 22;
-  --ui-blur-intensity-strong: 28;
-  --ui-blur-saturation-pct: 185;
-  --ui-frosted-highlight-height: 0;
-  --ui-frosted-backdrop-blur-intensity: 14;
-  --ui-frosted-backdrop-blur-scale: 0.55;
-  --ui-frosted-android-tint-alpha-scale: 1.22;
-  --ui-frosted-android-experimental-blur: 1;
-  --ui-drawer-frosted-inset: 0;
-  --ui-drawer-frosted-radius: 28;
-  --ui-drawer-content-top-padding: 0;
-}
-```
-
-For custom components, use:
+For a custom control, read that table:
 
 ```tsx
 import { useInteractionTokens, withInteractivePressableStyle } from '@thewhileloop/whileui';
 ```
 
-Wrap the application in `MotionProvider` to coordinate system reduced motion, explicit
-preview overrides, and deterministic animation-free tests. The provider is optional:
-without it `useMotionPolicy` returns the token defaults with Reanimated following the
-system setting, and `--ui-motion-*` overrides are not read. `reduced` preserves
-non-spatial feedback while asking Reanimated to skip motion; `disabled` also resolves
-semantic durations to zero.
+Wrap the application in `MotionProvider` to coordinate system reduced motion, an explicit
+preview mode, and deterministic animation-free tests. The provider is optional. Without
+it `useMotionPolicy` reports the durations and spring from `INTERACTION_TOKENS`, and
+Reanimated follows the system setting. `reduced` preserves non-spatial feedback while asking Reanimated to skip motion;
+`disabled` also resolves semantic durations to zero.
 
 ```tsx
 import { MotionProvider, useMotionPolicy } from '@thewhileloop/whileui';
@@ -974,12 +1008,12 @@ import { Input } from '@thewhileloop/whileui';
 <Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
 ```
 
-| Prop                 | Type                   | Default     | Description                                              |
-| -------------------- | ---------------------- | ----------- | -------------------------------------------------------- |
-| variant              | `'default' \| 'error'` | `'default'` | Input style variant                                      |
-| placeholder          | `string`               | —           | Placeholder text                                         |
-| placeholderTextColor | `string`               | —           | Hex for placeholder; defaults to theme `mutedForeground` |
-| editable             | `boolean`              | `true`      | Whether input is editable                                |
+| Prop                 | Type                              | Default     | Description                                                           |
+| -------------------- | --------------------------------- | ----------- | --------------------------------------------------------------------- |
+| variant              | `'default' \| 'error' \| 'plain'` | `'default'` | Input style; `plain` drops border and fill for a large display figure |
+| placeholder          | `string`                          | —           | Placeholder text                                                      |
+| placeholderTextColor | `string`                          | —           | Hex for placeholder; defaults to theme `mutedForeground`              |
+| editable             | `boolean`                         | `true`      | Whether input is editable                                             |
 
 ## NumericInput
 
@@ -1743,7 +1777,7 @@ const [value, setValue] = useState('');
 | `inputSafeArea`          | `boolean`            | SmartInput safe-area (default `true`)             |
 | `keyboardVerticalOffset` | `number`             | For header offset when keyboard opens             |
 
-## DatePickerModal / DatePickerInline / DateRangePickerModal
+## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal
 
 Date selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.
 
@@ -1753,6 +1787,8 @@ Date selection blocks using react-native-calendars. Theme-aware via `useCalendar
 
 **DateRangePickerModal** — Range selection with period marking. Use `DateRangePickerTrigger` as the trigger content.
 
+**TimePickerModal** — Hour and minute wheels (plus AM/PM under a 12-hour `hourCycle`) in the same bottom sheet, so a form's date and time fields open the same way. `value` is always `HH:MM` in 24-hour form. Each wheel is one `adjustable` element for assistive tech and the keyboard. Use `TimePickerTrigger` as the trigger content.
+
 ```tsx
 import {
   DatePickerModal,
@@ -1760,6 +1796,8 @@ import {
   DatePickerInline,
   DateRangePickerModal,
   DateRangePickerTrigger,
+  TimePickerModal,
+  TimePickerTrigger,
   type DateRange,
 } from '@thewhileloop/whileui';
 
@@ -1789,6 +1827,18 @@ const [range, setRange] = useState<DateRange | null>(null);
   onOpenChange={setRangeOpen}
   trigger={<DateRangePickerTrigger value={range} placeholder="Pick range" />}
 />;
+
+// Time (modal) — "HH:MM", 24-hour, whatever the wheels show
+const [time, setTime] = useState<string | null>(null);
+
+<TimePickerModal
+  value={time}
+  onValueChange={setTime}
+  open={timeOpen}
+  onOpenChange={setTimeOpen}
+  minuteStep={5}
+  trigger={<TimePickerTrigger value={time} placeholder="Pick a time" />}
+/>;
 ```
 
 | Prop                    | Type                                                               | Description                            |
@@ -1799,6 +1849,8 @@ const [range, setRange] = useState<DateRange | null>(null);
 | `trigger`               | `ReactNode`                                                        | Custom trigger (modal variants)        |
 | `minDate` / `maxDate`   | `string`                                                           | YYYY-MM-DD bounds                      |
 | `theme`                 | `CalendarTheme`                                                    | Override calendar colors               |
+| `hourCycle`             | `'h12' \| 'h23'`                                                   | Time picker wheels; defaults to locale |
+| `minuteStep`            | `number`                                                           | Minutes between options (default 1)    |
 | `frosted`               | `boolean`                                                          | Enable frosted surface for modal panel |
 | `blurIntensity`         | `number`                                                           | Override blur amount                   |
 | `blurTintToken`         | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | Tint token for frosted panel           |

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

@@ -2,3 +2,4 @@ export { DatePickerModal, DatePickerTrigger, formatDisplayDate, type DatePickerM
 export { DatePickerInline, type DatePickerInlineProps } from './datepicker-inline';
 export { DateRangePickerModal, DateRangePickerTrigger, formatRangeDisplay, type DateRangePickerModalProps, type DateRange, } from './date-range-picker-modal';
 export { useCalendarTheme, type CalendarTheme } from './use-calendar-theme';
+export { TimePickerModal, TimePickerTrigger, formatDisplayTime, parseTime, type TimePickerModalProps, type HourCycle, } from './time-picker-modal';

package/dist/blocks/datepicker/index.js

@@ -2,3 +2,4 @@ export { DatePickerModal, DatePickerTrigger, formatDisplayDate, } from './datepi
 export { DatePickerInline } from './datepicker-inline';
 export { DateRangePickerModal, DateRangePickerTrigger, formatRangeDisplay, } from './date-range-picker-modal';
 export { useCalendarTheme } from './use-calendar-theme';
+export { TimePickerModal, TimePickerTrigger, formatDisplayTime, parseTime, } from './time-picker-modal';

package/dist/blocks/datepicker/time-picker-modal.d.ts

@@ -0,0 +1,43 @@
+import React from 'react';
+import { type FrostedSurfaceProps } from '../../lib/frosted-surface';
+export type HourCycle = 'h12' | 'h23';
+export interface TimePickerModalProps extends FrostedSurfaceProps {
+    /** Controlled: selected time as `HH:MM`, 24-hour, or null for none. */
+    value?: string | null;
+    /** Controlled: change handler. Always receives `HH:MM` in 24-hour form. */
+    onValueChange?: (time: string | null) => void;
+    /** Modal open state */
+    open: boolean;
+    /** Modal open change handler */
+    onOpenChange: (open: boolean) => void;
+    /** Minutes between options. 1 by default; 5 or 15 for a coarser pick. */
+    minuteStep?: number;
+    /** 12-hour with AM/PM, or 24-hour. Defaults to the device locale's preference. */
+    hourCycle?: HourCycle;
+    /** Trigger element. If not provided, no trigger is rendered. */
+    trigger?: React.ReactNode;
+    /** Title shown in modal header */
+    title?: string;
+    /** Button label for confirm */
+    confirmLabel?: string;
+    className?: string;
+}
+declare function parseTime(value: string | null | undefined): {
+    hour: number;
+    minute: number;
+} | null;
+/** `HH:MM` as the locale writes it — "10:30 PM" or "22:30". */
+declare function formatDisplayTime(value: string | null | undefined, hourCycle?: HourCycle): string;
+/**
+ * A time chosen on two wheels — three with AM/PM — in the same bottom sheet as
+ * `DatePickerModal`, so a form's date and time fields open the same way.
+ */
+export declare function TimePickerModal(props: TimePickerModalProps): React.JSX.Element;
+/** Compact trigger showing the formatted time. Use as TimePickerModal's trigger prop. */
+export declare function TimePickerTrigger({ value, placeholder, hourCycle, className, }: {
+    value?: string | null;
+    placeholder?: string;
+    hourCycle?: HourCycle;
+    className?: string;
+}): React.JSX.Element;
+export { formatDisplayTime, parseTime };

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

@@ -0,0 +1,187 @@
+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 { 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 { useThemeColors } from '../../lib/theme-colors';
+import { useVisualTokens } from '../../lib/visual-tokens';
+import { fieldRecipe, surfacePadding, surfaceRadius, typographyStyle } from '../../lib/recipes';
+import { useFrostedSurface } from '../../lib/frosted-surface';
+const ITEM_HEIGHT = 44;
+/** Rows visible in a wheel. Odd, so one row sits centred under the selection band. */
+const VISIBLE_ROWS = 5;
+const WHEEL_HEIGHT = ITEM_HEIGHT * VISIBLE_ROWS;
+const WHEEL_PADDING = ITEM_HEIGHT * Math.floor(VISIBLE_ROWS / 2);
+const pad2 = (n) => String(n).padStart(2, '0');
+/** The locale's clock, so a US device gets AM/PM and most of the world does not. */
+function localeHourCycle() {
+    try {
+        const cycle = new Intl.DateTimeFormat(undefined, { hour: 'numeric' }).resolvedOptions()
+            .hourCycle;
+        return cycle === 'h11' || cycle === 'h12' ? 'h12' : 'h23';
+    }
+    catch {
+        return 'h23';
+    }
+}
+function parseTime(value) {
+    if (!value)
+        return null;
+    const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+    if (!match)
+        return null;
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    if (hour > 23 || minute > 59)
+        return null;
+    return { hour, minute };
+}
+/** `HH:MM` as the locale writes it — "10:30 PM" or "22:30". */
+function formatDisplayTime(value, hourCycle) {
+    const parsed = parseTime(value);
+    if (!parsed)
+        return 'Select time';
+    const date = new Date(2000, 0, 1, parsed.hour, parsed.minute);
+    return date.toLocaleTimeString(undefined, {
+        hour: 'numeric',
+        minute: '2-digit',
+        ...(hourCycle ? { hour12: hourCycle === 'h12' } : {}),
+    });
+}
+/**
+ * One scrolling column. Scrolls snap to a row, a tap selects a row, and the whole
+ * column is a single adjustable element for assistive tech and the keyboard — sixty
+ * minute rows as sixty tab stops would be nobody's idea of operable.
+ */
+function Wheel({ label, options, selected, onSelect }) {
+    const visual = useVisualTokens();
+    const colors = useThemeColors();
+    const ref = useRef(null);
+    const index = Math.max(0, options.findIndex((option) => option.value === selected));
+    // Keep the band on the selected row when the value changes from outside the wheel
+    // (a tap, a keyboard step, the initial value), not after the user's own scroll.
+    const lastScrolledIndex = useRef(-1);
+    useEffect(() => {
+        if (lastScrolledIndex.current === index)
+            return;
+        lastScrolledIndex.current = index;
+        ref.current?.scrollTo({ y: index * ITEM_HEIGHT, animated: Platform.OS !== 'web' });
+    }, [index]);
+    const settle = useCallback((event) => {
+        const next = Math.round(event.nativeEvent.contentOffset.y / ITEM_HEIGHT);
+        const clamped = Math.min(options.length - 1, Math.max(0, next));
+        lastScrolledIndex.current = clamped;
+        const option = options[clamped];
+        if (option && option.value !== selected)
+            onSelect(option.value);
+    }, [onSelect, options, selected]);
+    const step = useCallback((delta) => {
+        const next = (index + delta + options.length) % options.length;
+        onSelect(options[next].value);
+    }, [index, onSelect, options]);
+    const current = options[index]?.label ?? '';
+    return (_jsxs(View, { accessible: true, accessibilityRole: "adjustable", accessibilityLabel: label, accessibilityValue: { text: current }, accessibilityActions: [{ name: 'increment' }, { name: 'decrement' }], onAccessibilityAction: (event) => {
+            if (event.nativeEvent.actionName === 'increment')
+                step(1);
+            if (event.nativeEvent.actionName === 'decrement')
+                step(-1);
+        }, ...(Platform.OS === 'web'
+            ? {
+                focusable: true,
+                onKeyDown: (event) => {
+                    if (event.nativeEvent.key === 'ArrowUp') {
+                        event.preventDefault();
+                        step(-1);
+                    }
+                    else if (event.nativeEvent.key === 'ArrowDown') {
+                        event.preventDefault();
+                        step(1);
+                    }
+                },
+            }
+            : null), className: cn('flex-1 overflow-hidden', focusRingInset), style: { height: WHEEL_HEIGHT, borderRadius: surfaceRadius(visual, 'lg') }, children: [_jsx(View, { pointerEvents: "none", className: "absolute left-0 right-0 bg-muted", style: {
+                    top: WHEEL_PADDING,
+                    height: ITEM_HEIGHT,
+                    borderRadius: surfaceRadius(visual, 'md'),
+                } }), _jsx(ScrollView, { ref: ref, showsVerticalScrollIndicator: false, snapToInterval: ITEM_HEIGHT, decelerationRate: "fast", nestedScrollEnabled: true, contentContainerStyle: { paddingVertical: WHEEL_PADDING }, contentOffset: { x: 0, y: index * ITEM_HEIGHT }, onMomentumScrollEnd: settle, onScrollEndDrag: Platform.OS === 'web' ? settle : undefined, importantForAccessibility: "no-hide-descendants", accessibilityElementsHidden: true, children: options.map((option) => {
+                    const on = option.value === selected;
+                    return (_jsx(Pressable, { onPress: () => onSelect(option.value), focusable: false, className: "items-center justify-center", style: { height: ITEM_HEIGHT }, children: _jsx(Text, { className: on ? 'font-medium text-foreground' : 'text-muted-foreground', style: {
+                                ...typographyStyle(visual, on ? 'title' : 'body'),
+                                color: on ? colors.foreground : colors.mutedForeground,
+                            }, children: option.label }) }, option.value));
+                }) })] }));
+}
+function TimePickerModalSession({ value, onValueChange, open, onOpenChange, minuteStep = 1, hourCycle: hourCycleProp, trigger, title = 'Select time', confirmLabel = 'Done', className, frosted = false, blurIntensity, blurTintToken, }) {
+    const insets = useSafeAreaInsets();
+    const colors = useThemeColors();
+    const visual = useVisualTokens();
+    const frostedSurface = useFrostedSurface({
+        frosted,
+        blurIntensity,
+        blurTintToken,
+        defaultTintToken: 'surfaceTranslucent',
+        defaultBlurPreset: 'medium',
+    });
+    const hourCycle = hourCycleProp ?? localeHourCycle();
+    const step = Math.min(30, Math.max(1, Math.round(minuteStep)));
+    // The draft opens on the current value, or on the current clock time rounded to the
+    // step, so the first confirm without touching anything records "now".
+    const initial = (() => {
+        const parsed = parseTime(value);
+        if (parsed)
+            return parsed;
+        const now = new Date();
+        return { hour: now.getHours(), minute: Math.floor(now.getMinutes() / step) * step };
+    })();
+    const [hour, setHour] = useState(initial.hour);
+    const [minute, setMinute] = useState(initial.minute);
+    const hours = hourCycle === 'h12'
+        ? Array.from({ length: 12 }, (_, i) => ({ value: i + 1, label: String(i + 1) }))
+        : Array.from({ length: 24 }, (_, i) => ({ value: i, label: pad2(i) }));
+    const minutes = Array.from({ length: Math.ceil(60 / step) }, (_, i) => ({
+        value: i * step,
+        label: pad2(i * step),
+    }));
+    const periods = [
+        { value: 0, label: 'AM' },
+        { value: 1, label: 'PM' },
+    ];
+    const period = hour >= 12 ? 1 : 0;
+    const hour12 = hour % 12 === 0 ? 12 : hour % 12;
+    const handleConfirm = useCallback(() => {
+        onValueChange?.(`${pad2(hour)}:${pad2(minute)}`);
+        onOpenChange(false);
+    }, [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: [
+                            {
+                                borderTopLeftRadius: surfaceRadius(visual, 'xl'),
+                                borderTopRightRadius: surfaceRadius(visual, 'xl'),
+                                paddingBottom: Math.max(insets.bottom, surfacePadding(visual, 'sm')),
+                            },
+                            frostedSurface.surfaceStyle,
+                        ], onPress: (e) => e.stopPropagation(), children: [frostedSurface.overlay, _jsxs(View, { className: "flex-row items-center justify-between border-b border-border", style: {
+                                    paddingHorizontal: surfacePadding(visual, 'sm'),
+                                    paddingVertical: visual.controlPaddingYDefault,
+                                }, children: [_jsx(Text, { accessibilityRole: "header", className: "font-medium text-foreground", style: typographyStyle(visual, 'body'), children: title }), _jsx(Button, { size: "sm", onPress: handleConfirm, children: _jsx(ButtonText, { children: confirmLabel }) })] }), _jsxs(View, { className: "flex-row items-center", style: { padding: surfacePadding(visual, 'sm'), gap: visual.controlPaddingYDefault }, children: [_jsx(Wheel, { label: "Hour", options: hours, selected: hourCycle === 'h12' ? hour12 : hour, onSelect: (next) => setHour(hourCycle === 'h12' ? (next % 12) + (period === 1 ? 12 : 0) : next) }), _jsx(Text, { className: "text-muted-foreground", style: typographyStyle(visual, 'title'), accessibilityElementsHidden: true, importantForAccessibility: "no", children: ":" }), _jsx(Wheel, { label: "Minute", options: minutes, selected: minute, onSelect: setMinute }), hourCycle === 'h12' ? (_jsx(Wheel, { label: "AM or PM", options: periods, selected: period, onSelect: (next) => setHour((hour % 12) + (next === 1 ? 12 : 0)) })) : null] })] }) }) })] }));
+}
+/**
+ * A time chosen on two wheels — three with AM/PM — in the same bottom sheet as
+ * `DatePickerModal`, so a form's date and time fields open the same way.
+ */
+export function TimePickerModal(props) {
+    // Remount per opening so the draft starts from the value each time, as the date
+    // picker does; a draft that outlives a cancel would reopen on the abandoned pick.
+    const sessionKey = props.open ? 'open' : 'closed';
+    return _jsx(TimePickerModalSession, { ...props }, sessionKey);
+}
+/** Compact trigger showing the formatted time. Use as TimePickerModal's trigger prop. */
+export function TimePickerTrigger({ value, placeholder = 'Select time', hourCycle, className, }) {
+    const visual = useVisualTokens();
+    return (_jsxs(View, { className: cn('flex-1 flex-row items-center min-w-0', className), children: [_jsx(Text, { className: cn('flex-1', value ? 'text-foreground' : 'text-muted-foreground'), style: typographyStyle(visual, 'body'), numberOfLines: 1, children: value ? formatDisplayTime(value, hourCycle) : placeholder }), _jsx(View, { className: "ml-2 shrink-0 h-2 w-2 rotate-45 border-b-2 border-r-2 border-muted-foreground" })] }));
+}
+export { formatDisplayTime, parseTime };

package/dist/components/fab/fab.d.ts

@@ -0,0 +1,87 @@
+import React from 'react';
+import { View, type PressableInstance, type ViewProps } from 'react-native';
+import { type PressableProps } from '../pressable';
+import { type VariantProps } from '../../lib/tv';
+import type { ForwardRefComponent } from '../../lib/ref-types';
+declare const fabVariants: import("tailwind-variants").TVReturnType<{
+    variant: {
+        default: "bg-primary";
+        secondary: "bg-secondary";
+        destructive: "bg-destructive";
+        surface: "border border-border bg-card";
+    };
+    size: {
+        default: "h-14 w-14";
+        sm: "h-12 w-12";
+        lg: "h-16 w-16";
+    };
+    placement: {
+        /** Positioned by the caller — inside a toolbar, a row, anywhere. */
+        inline: "";
+        /** Floating over the nearest positioned ancestor, bottom-right. */
+        floating: "absolute bottom-6 right-6";
+        'floating-left': "absolute bottom-6 left-6";
+    };
+}, undefined, "items-center justify-center rounded-full", {
+    variant: {
+        default: "bg-primary";
+        secondary: "bg-secondary";
+        destructive: "bg-destructive";
+        surface: "border border-border bg-card";
+    };
+    size: {
+        default: "h-14 w-14";
+        sm: "h-12 w-12";
+        lg: "h-16 w-16";
+    };
+    placement: {
+        /** Positioned by the caller — inside a toolbar, a row, anywhere. */
+        inline: "";
+        /** Floating over the nearest positioned ancestor, bottom-right. */
+        floating: "absolute bottom-6 right-6";
+        'floating-left': "absolute bottom-6 left-6";
+    };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+    variant: {
+        default: "bg-primary";
+        secondary: "bg-secondary";
+        destructive: "bg-destructive";
+        surface: "border border-border bg-card";
+    };
+    size: {
+        default: "h-14 w-14";
+        sm: "h-12 w-12";
+        lg: "h-16 w-16";
+    };
+    placement: {
+        /** Positioned by the caller — inside a toolbar, a row, anywhere. */
+        inline: "";
+        /** Floating over the nearest positioned ancestor, bottom-right. */
+        floating: "absolute bottom-6 right-6";
+        'floating-left': "absolute bottom-6 left-6";
+    };
+}, undefined>>;
+export interface FabProps extends Omit<PressableProps, 'children'>, VariantProps<typeof fabVariants> {
+    /**
+     * What the action does, for screen readers. Required: a FAB is an icon with no
+     * text, so without this it announces as an unlabelled button.
+     */
+    label: string;
+    /** The glyph. Icon libraries need a concrete colour, so read it from `useIconColors`. */
+    children?: React.ReactNode;
+    className?: string;
+}
+/**
+ * A floating action button: one primary action, raised above the content.
+ *
+ * It owns no icon dependency. `@expo/vector-icons` and friends need hex colours
+ * rather than classes, so the caller passes the glyph and colours it from
+ * `useIconColors()` or `useThemeColors()`.
+ */
+declare const FAB: ForwardRefComponent<PressableInstance, FabProps>;
+export interface FabGroupProps extends ViewProps {
+    className?: string;
+}
+/** Stacks secondary actions above a FAB, bottom-aligned. */
+declare const FABGroup: ForwardRefComponent<React.ComponentRef<typeof View>, FabGroupProps>;
+export { FAB, FABGroup, fabVariants };

package/dist/components/fab/fab.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { View } from 'react-native';
+import { Pressable } from '../pressable';
+import { cn } from '../../lib/cn';
+import { tv } from '../../lib/tv';
+import { useVisualTokens } from '../../lib/visual-tokens';
+import { shadowStyle } from '../../lib/recipes';
+import { useThemeColors } from '../../lib/theme-colors';
+const fabVariants = tv({
+    base: 'items-center justify-center rounded-full',
+    variants: {
+        variant: {
+            default: 'bg-primary',
+            secondary: 'bg-secondary',
+            destructive: 'bg-destructive',
+            surface: 'border border-border bg-card',
+        },
+        size: {
+            // 56 and 40 are Material's FAB and small-FAB sizes. Both clear the iOS 44pt
+            // and Android 48dp minimums on their own, so a FAB never needs hitSlop.
+            default: 'h-14 w-14',
+            sm: 'h-12 w-12',
+            lg: 'h-16 w-16',
+        },
+        placement: {
+            /** Positioned by the caller — inside a toolbar, a row, anywhere. */
+            inline: '',
+            /** Floating over the nearest positioned ancestor, bottom-right. */
+            floating: 'absolute bottom-6 right-6',
+            'floating-left': 'absolute bottom-6 left-6',
+        },
+    },
+    defaultVariants: {
+        variant: 'default',
+        size: 'default',
+        placement: 'floating',
+    },
+});
+/**
+ * A floating action button: one primary action, raised above the content.
+ *
+ * It owns no icon dependency. `@expo/vector-icons` and friends need hex colours
+ * rather than classes, so the caller passes the glyph and colours it from
+ * `useIconColors()` or `useThemeColors()`.
+ */
+const FAB = React.forwardRef(({ className, variant, size, placement, label, children, style, ...props }, ref) => {
+    const visual = useVisualTokens();
+    const colors = useThemeColors();
+    return (_jsx(Pressable, { ref: ref, accessibilityRole: "button", accessibilityLabel: label, className: cn(fabVariants({ variant, size, placement }), className), style: (state) => [
+            shadowStyle(visual, colors, 'lg'),
+            typeof style === 'function' ? style(state) : style,
+        ], ...props, children: children }));
+});
+FAB.displayName = 'FAB';
+/** Stacks secondary actions above a FAB, bottom-aligned. */
+const FABGroup = React.forwardRef(({ className, ...props }, ref) => (_jsx(View, { ref: ref, className: cn('absolute bottom-6 right-6 items-end gap-3', className), ...props })));
+FABGroup.displayName = 'FABGroup';
+export { FAB, FABGroup, fabVariants };

package/dist/components/fab/index.d.ts

@@ -0,0 +1 @@
+export { FAB, FABGroup, fabVariants, type FabProps, type FabGroupProps } from './fab';

package/dist/components/fab/index.js

@@ -0,0 +1 @@
+export { FAB, FABGroup, fabVariants } from './fab';

package/dist/components/input/input.d.ts

@@ -6,16 +6,22 @@ declare const inputVariants: import("tailwind-variants").TVReturnType<{
     variant: {
         default: "border-border";
         error: "border-destructive";
+        /** No border, no fill — for one large figure that is the screen's subject. */
+        plain: "border-transparent bg-transparent";
     };
 }, undefined, "w-full border-border bg-muted text-foreground", {
     variant: {
         default: "border-border";
         error: "border-destructive";
+        /** No border, no fill — for one large figure that is the screen's subject. */
+        plain: "border-transparent bg-transparent";
     };
 }, undefined, import("tailwind-variants").TVReturnTypeLike<{
     variant: {
         default: "border-border";
         error: "border-destructive";
+        /** No border, no fill — for one large figure that is the screen's subject. */
+        plain: "border-transparent bg-transparent";
     };
 }, undefined>>;
 export interface InputProps extends TextInputProps, VariantProps<typeof inputVariants> {

package/dist/components/input/input.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React from 'react';
+import React, { useState } from 'react';
 import { View, TextInput } from 'react-native';
 import { cn } from '../../lib/cn';
-import { focusRing } from '../../lib/focus-ring';
+import { focusFieldWrapper } from '../../lib/focus-ring';
 import { tv } from '../../lib/tv';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
@@ -14,29 +14,41 @@ const inputVariants = tv({
         variant: {
             default: 'border-border',
             error: 'border-destructive',
+            /** No border, no fill — for one large figure that is the screen's subject. */
+            plain: 'border-transparent bg-transparent',
         },
     },
     defaultVariants: {
         variant: 'default',
     },
 });
-const Input = React.forwardRef(({ className, prefix, suffix, inputClassName, variant, editable = true, placeholderTextColor, ...props }, ref) => {
+const Input = React.forwardRef(({ className, prefix, suffix, inputClassName, variant, editable = true, placeholderTextColor, onFocus, onBlur, ...props }, ref) => {
     const colors = useThemeColors();
     const interaction = useInteractionTokens();
     const visual = useVisualTokens();
-    return (_jsxs(View, { className: cn('flex-row items-center border-border bg-muted', inputVariants({ variant }), className), style: [
+    // The border is on this wrapper and the focus is on the TextInput inside it, so the
+    // wrapper learns about focus from the events rather than a pseudo-class.
+    const [focused, setFocused] = useState(false);
+    const plain = variant === 'plain';
+    return (_jsxs(View, { className: cn('flex-row items-center border-border bg-muted', inputVariants({ variant }), focused && !plain && focusFieldWrapper, className), style: [
             {
                 minHeight: visual.controlHeightDefault,
-                borderWidth: visual.borderWidthControl,
+                borderWidth: plain ? 0 : visual.borderWidthControl,
                 borderRadius: visual.radiusLg,
-                paddingHorizontal: visual.controlPaddingXDefault,
+                paddingHorizontal: plain ? 0 : visual.controlPaddingXDefault,
             },
             !editable ? { opacity: interaction.disabledOpacity } : undefined,
-        ], children: [prefix && (_jsx(View, { style: { paddingRight: Math.max(8, Math.round(visual.controlPaddingXDefault * 0.5)) }, children: prefix })), _jsx(TextInput, { ref: ref, className: cn('flex-1 text-foreground placeholder:text-muted-foreground', focusRing, inputClassName), style: {
+        ], children: [prefix && (_jsx(View, { style: { paddingRight: Math.max(8, Math.round(visual.controlPaddingXDefault * 0.5)) }, children: prefix })), _jsx(TextInput, { ref: ref, className: cn('flex-1 text-foreground placeholder:text-muted-foreground web:outline-none', inputClassName), style: {
                     ...typographyStyle(visual, 'label'),
                     minHeight: visual.controlHeightDefault - 2,
                     paddingVertical: visual.controlPaddingYDefault,
-                }, editable: editable, placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...props }), suffix && (_jsx(View, { style: { paddingLeft: Math.max(8, Math.round(visual.controlPaddingXDefault * 0.5)) }, children: suffix }))] }));
+                }, editable: editable, placeholderTextColor: placeholderTextColor ?? colors.placeholder, onFocus: (event) => {
+                    setFocused(true);
+                    onFocus?.(event);
+                }, onBlur: (event) => {
+                    setFocused(false);
+                    onBlur?.(event);
+                }, ...props }), suffix && (_jsx(View, { style: { paddingLeft: Math.max(8, Math.round(visual.controlPaddingXDefault * 0.5)) }, children: suffix }))] }));
 });
 Input.displayName = 'Input';
 export { Input, inputVariants };

package/dist/components/numeric-input/numeric-input.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useCallback, useMemo, useState } from 'react';
 import { Platform, Pressable, Text, TextInput, View, } from 'react-native';
 import { cn } from '../../lib/cn';
-import { focusRing } from '../../lib/focus-ring';
+import { focusFieldWrapper } from '../../lib/focus-ring';
 import { tv } from '../../lib/tv';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
@@ -135,10 +135,12 @@ function NumericSteppers({ visible, inset, size, radius, model, interaction, vis
         return null;
     return (_jsxs(View, { className: "shrink-0 flex-row items-center", style: { gap: inset, paddingLeft: Math.max(6, inset) }, children: [_jsx(NumericStepperButton, { delta: -1, enabled: model.canDecrease, label: "Decrease value", symbol: "\u2212", size: size, radius: radius, model: model, interaction: interaction, visual: visual }), _jsx(NumericStepperButton, { delta: 1, enabled: model.canIncrease, label: "Increase value", symbol: "+", size: size, radius: radius, model: model, interaction: interaction, visual: visual })] }));
 }
-const NumericInput = React.forwardRef(({ className, inputClassName, prefix, suffix, value, defaultValue, onValueChange, min, max, step = 1, showSteppers = false, unstyled = false, variant = 'default', size = 'default', editable = true, placeholderTextColor, onBlur, style: styleProp, ...props }, ref) => {
+const NumericInput = React.forwardRef(({ className, inputClassName, prefix, suffix, value, defaultValue, onValueChange, min, max, step = 1, showSteppers = false, unstyled = false, variant = 'default', size = 'default', editable = true, placeholderTextColor, onFocus, onBlur, style: styleProp, ...props }, ref) => {
     const colors = useThemeColors();
     const interaction = useInteractionTokens();
     const visual = useVisualTokens();
+    // The border is on the wrapper and the focus on the field inside it.
+    const [focused, setFocused] = useState(false);
     const model = useNumericInputModel({
         value,
         defaultValue,
@@ -154,7 +156,7 @@ const NumericInput = React.forwardRef(({ className, inputClassName, prefix, suff
     const stepInset = Math.max(3, Math.round(controlHeight * 0.1));
     const stepSize = controlHeight - stepInset * 2;
     const stepRadius = Math.max(3, Math.min(visual.radiusMd, Math.round(stepSize / 3)));
-    return (_jsxs(View, { className: cn(numericInputVariants({ variant, size }), unstyled && 'bg-transparent', className), style: [
+    return (_jsxs(View, { className: cn(numericInputVariants({ variant, size }), unstyled && 'bg-transparent', focused && !unstyled && focusFieldWrapper, className), style: [
             {
                 // Definite height (not minHeight) so inner elements can center reliably.
                 height: controlHeight,
@@ -164,7 +166,13 @@ const NumericInput = React.forwardRef(({ className, inputClassName, prefix, suff
                 paddingRight: unstyled ? 0 : showSteppers ? stepInset : 0,
             },
             !editable ? { opacity: interaction.disabledOpacity } : undefined,
-        ], children: [_jsx(NumericAffix, { side: "prefix", visual: visual, children: prefix }), _jsx(View, { className: "min-w-0 flex-1", style: Platform.OS === 'web' ? { minWidth: 0, flex: 1 } : undefined, children: _jsx(TextInput, { ref: ref, className: cn(numericInputTextVariants({ size }), 'w-full', focusRing, inputClassName), style: numericInputTextStyle(visual, size, unstyled, styleProp), value: model.textValue, onChangeText: model.handleTextChange, onBlur: model.handleBlur, keyboardType: "decimal-pad", editable: editable, placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...props }) }), _jsx(NumericAffix, { side: "suffix", visual: visual, children: suffix }), _jsx(NumericSteppers, { visible: showSteppers, inset: stepInset, size: stepSize, radius: stepRadius, model: model, interaction: interaction, visual: visual })] }));
+        ], children: [_jsx(NumericAffix, { side: "prefix", visual: visual, children: prefix }), _jsx(View, { className: "min-w-0 flex-1", style: Platform.OS === 'web' ? { minWidth: 0, flex: 1 } : undefined, children: _jsx(TextInput, { ref: ref, className: cn(numericInputTextVariants({ size }), 'w-full web:outline-none', inputClassName), style: numericInputTextStyle(visual, size, unstyled, styleProp), value: model.textValue, onChangeText: model.handleTextChange, onFocus: (event) => {
+                        setFocused(true);
+                        onFocus?.(event);
+                    }, onBlur: (event) => {
+                        setFocused(false);
+                        model.handleBlur(event);
+                    }, keyboardType: "decimal-pad", editable: editable, placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...props }) }), _jsx(NumericAffix, { side: "suffix", visual: visual, children: suffix }), _jsx(NumericSteppers, { visible: showSteppers, inset: stepInset, size: stepSize, radius: stepRadius, model: model, interaction: interaction, visual: visual })] }));
 });
 NumericInput.displayName = 'NumericInput';
 export { NumericInput, numericInputVariants, numericInputTextVariants };

package/dist/components/select/select.js

@@ -19,11 +19,6 @@ const SelectTrigger = React.forwardRef(({ className, children, style: styleProp,
     const interaction = useInteractionTokens();
     const visual = useVisualTokens();
     return (_jsxs(SelectPrimitive.Trigger, { ref: ref, className: cn('border-border bg-muted flex w-full flex-row items-center justify-between gap-2 shadow-sm active:bg-state-pressed', focusRing, props.disabled && '', className), 
-        // Pass an array unless the caller actually gave a callback. On web this primitive
-        // is wrapped in a Slot that merges `style` by object spread, which turns a
-        // function into `{}` and silently drops every style — the trigger rendered 24px
-        // tall with no padding, border or radius. A callback is still honoured on native,
-        // where dropping it was the original bug.
         // Flattened, not an array. On web this primitive is merged through a Slot that
         // spreads `style`, and spreading an array yields { 0: …, 1: … } — numeric keys
         // that reach the DOM as indexed style properties and throw. The Select rendered

package/dist/components/textarea/textarea.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import React from 'react';
 import { TextInput, } from 'react-native';
 import { cn } from '../../lib/cn';
-import { focusRing } from '../../lib/focus-ring';
+import { focusField } from '../../lib/focus-ring';
 import { tv } from '../../lib/tv';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
@@ -44,7 +44,7 @@ const Textarea = React.forwardRef(({ className, size = 'default', placeholderTex
         paddingVertical: visual.controlPaddingYDefault,
         ...(props.editable === false ? { opacity: interaction.disabledOpacity } : null),
     };
-    return (_jsx(TextInput, { ref: ref, className: cn(textareaVariants({ size }), focusRing, className), style: style, multiline: true, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...props }));
+    return (_jsx(TextInput, { ref: ref, className: cn(textareaVariants({ size }), focusField, className), style: style, multiline: true, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...props }));
 });
 Textarea.displayName = 'Textarea';
 export { Textarea, textareaVariants };

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { PortalHost } from './lib/portal';
 export { ThemeBridge, applyThemeMode, resolveThemeMode, syncThemeMode, useThemeBridge, type ThemeMode, type ThemeBridgeAdapter, type ThemeBridgeProps, type UseThemeBridgeOptions, type UseThemeBridgeResult, } from './lib/theme-bridge';
 export { useThemeColors, useThemeTokens, useIconColors, type ThemeColors, } from './lib/theme-colors';
 export { THEME_TOKEN_SPECS, THEME_TOKEN_GROUPS, WHILEUI_LIGHT_THEME_COLORS, WHILEUI_DARK_THEME_COLORS, type ThemeTokenGroup, type ThemeTokenKey, type ThemeTokenSpec, } from './lib/theme-contract';
-export { useInteractionTokens, withInteractivePressableStyle, type InteractionTokens, type InteractivePressableOptions, type PressedVariant, type DisabledVariant, } from './lib/interaction-tokens';
+export { INTERACTION_TOKENS, useInteractionTokens, withInteractivePressableStyle, type InteractionTokens, type InteractivePressableOptions, type PressedVariant, type DisabledVariant, } from './lib/interaction-tokens';
 export { MotionProvider, useMotionPolicy, type MotionMode, type MotionDuration, type MotionSpring, type MotionSpringConfig, type MotionPolicy, type MotionProviderProps, } from './lib/motion-policy';
 export { useVisualTokens, type VisualTokens } from './lib/visual-tokens';
 export { VISUAL_TOKEN_SPECS, VISUAL_TOKEN_GROUPS, type VisualTokenGroup, type VisualTokenKey, type VisualTokenKind, type VisualTokenSpec, } from './lib/visual-token-contract';
@@ -28,6 +28,7 @@ export { OTPInput, otpCellVariants, type OTPInputProps } from './components/otp-
 export { FormField, FormLabel, FormControl, FormHint, FormMessage, formFieldVariants, formControlVariants, type FormFieldProps, type FormLabelProps, type FormControlProps, type FormHintProps, type FormMessageProps, } from './components/form-field';
 export { LabeledField, LabeledFieldControl, type LabeledFieldProps, type LabeledFieldControlProps, } from './components/labeled-field';
 export { Badge, BadgeText, badgeVariants, badgeTextVariants, type BadgeProps, type BadgeTextProps, } from './components/badge';
+export { FAB, FABGroup, fabVariants, type FabProps, type FabGroupProps } from './components/fab';
 export { Alert, AlertTitle, AlertDescription, alertVariants, type AlertProps, type AlertTitleProps, type AlertDescriptionProps, } from './components/alert';
 export { Switch, type SwitchProps } from './components/switch';
 export { Checkbox, type CheckboxProps } from './components/checkbox';

package/dist/index.js

@@ -7,7 +7,7 @@ export { PortalHost } from './lib/portal';
 export { ThemeBridge, applyThemeMode, resolveThemeMode, syncThemeMode, useThemeBridge, } from './lib/theme-bridge';
 export { useThemeColors, useThemeTokens, useIconColors, } from './lib/theme-colors';
 export { THEME_TOKEN_SPECS, THEME_TOKEN_GROUPS, WHILEUI_LIGHT_THEME_COLORS, WHILEUI_DARK_THEME_COLORS, } from './lib/theme-contract';
-export { useInteractionTokens, withInteractivePressableStyle, } from './lib/interaction-tokens';
+export { INTERACTION_TOKENS, useInteractionTokens, withInteractivePressableStyle, } from './lib/interaction-tokens';
 export { MotionProvider, useMotionPolicy, } from './lib/motion-policy';
 export { useVisualTokens } from './lib/visual-tokens';
 export { VISUAL_TOKEN_SPECS, VISUAL_TOKEN_GROUPS, } from './lib/visual-token-contract';
@@ -28,6 +28,7 @@ export { OTPInput, otpCellVariants } from './components/otp-input';
 export { FormField, FormLabel, FormControl, FormHint, FormMessage, formFieldVariants, formControlVariants, } from './components/form-field';
 export { LabeledField, LabeledFieldControl, } from './components/labeled-field';
 export { Badge, BadgeText, badgeVariants, badgeTextVariants, } from './components/badge';
+export { FAB, FABGroup, fabVariants } from './components/fab';
 export { Alert, AlertTitle, AlertDescription, alertVariants, } from './components/alert';
 export { Switch } from './components/switch';
 export { Checkbox } from './components/checkbox';

package/dist/lib/focus-ring.d.ts

@@ -23,3 +23,13 @@ export declare const focusRing = "web:outline-none web:focus-visible:ring-2 web:
  * would be clipped by the parent or collide with a neighbour.
  */
 export declare const focusRingInset = "web:outline-none web:focus-visible:ring-2 web:focus-visible:ring-ring";
+/**
+ * For text fields. Browsers treat every focus on a text field as keyboard focus, so a
+ * `:focus-visible` ring fires on a tap too — and an offset ring around a rounded field
+ * reads as a second, squarer border. A field shows focus the way the platforms do:
+ * its own border takes the ring colour. The class carries the colour; a field whose
+ * border lives on a wrapper (`Input`, `NumericInput`) applies it there from focus state.
+ */
+export declare const focusField = "web:outline-none web:focus-visible:border-ring";
+/** The wrapper half of `focusField`: the border colour while the inner field has focus. */
+export declare const focusFieldWrapper = "border-ring";

package/dist/lib/focus-ring.js

@@ -23,3 +23,13 @@ export const focusRing = 'web:outline-none web:focus-visible:ring-2 web:focus-vi
  * would be clipped by the parent or collide with a neighbour.
  */
 export const focusRingInset = 'web:outline-none web:focus-visible:ring-2 web:focus-visible:ring-ring';
+/**
+ * For text fields. Browsers treat every focus on a text field as keyboard focus, so a
+ * `:focus-visible` ring fires on a tap too — and an offset ring around a rounded field
+ * reads as a second, squarer border. A field shows focus the way the platforms do:
+ * its own border takes the ring colour. The class carries the colour; a field whose
+ * border lives on a wrapper (`Input`, `NumericInput`) applies it there from focus state.
+ */
+export const focusField = 'web:outline-none web:focus-visible:border-ring';
+/** The wrapper half of `focusField`: the border colour while the inner field has focus. */
+export const focusFieldWrapper = 'border-ring';

package/dist/lib/interaction-tokens.d.ts

@@ -1,5 +1,28 @@
 import { type PressableProps } from 'react-native';
-/** Motion values used when a `--ui-motion-*` token is absent, and by the provider-less motion policy. */
+/**
+ * Press, disabled, and motion timing for the whole package.
+ *
+ * These are not theme tokens. A generated preset does not emit them, and reading the
+ * matching `--ui-*` variables warned in every app on that preset while resolving to
+ * these same numbers. One table, no CSS lookup.
+ */
+export declare const INTERACTION_TOKENS: {
+    readonly pressOpacity: 0.82;
+    readonly pressOpacityStrong: 0.92;
+    readonly disabledOpacity: 0.46;
+    readonly disabledOpacitySoft: 0.56;
+    readonly disabledOpacitySubtle: 0.36;
+    readonly inactiveOpacity: 0.54;
+    readonly motionFast: 140;
+    readonly motionNormal: 200;
+    readonly motionSlow: 280;
+    readonly motionSpringDamping: 20;
+    readonly motionSpringStiffness: 260;
+    readonly motionSpringMass: 0.8;
+    readonly drawerOpenDuration: 260;
+    readonly drawerCloseDuration: 180;
+};
+/** Motion slice of {@link INTERACTION_TOKENS}, for the provider-less policy. */
 export declare const MOTION_TOKEN_DEFAULTS: {
     readonly motionFast: 140;
     readonly motionNormal: 200;

package/dist/lib/interaction-tokens.js

@@ -1,55 +1,37 @@
-import { useCSSVariable } from 'uniwind';
-function parseNumber(value, fallback) {
-    if (value === undefined || value === null)
-        return fallback;
-    const parsed = Number.parseFloat(String(value));
-    return Number.isFinite(parsed) ? parsed : fallback;
-}
-function clampOpacity(value) {
-    return Math.max(0, Math.min(1, value));
-}
-/** Motion values used when a `--ui-motion-*` token is absent, and by the provider-less motion policy. */
-export const MOTION_TOKEN_DEFAULTS = {
+/**
+ * Press, disabled, and motion timing for the whole package.
+ *
+ * These are not theme tokens. A generated preset does not emit them, and reading the
+ * matching `--ui-*` variables warned in every app on that preset while resolving to
+ * these same numbers. One table, no CSS lookup.
+ */
+export const INTERACTION_TOKENS = {
+    pressOpacity: 0.82,
+    pressOpacityStrong: 0.92,
+    disabledOpacity: 0.46,
+    disabledOpacitySoft: 0.56,
+    disabledOpacitySubtle: 0.36,
+    inactiveOpacity: 0.54,
     motionFast: 140,
     motionNormal: 200,
     motionSlow: 280,
     motionSpringDamping: 20,
     motionSpringStiffness: 260,
     motionSpringMass: 0.8,
+    drawerOpenDuration: 260,
+    drawerCloseDuration: 180,
+};
+/** Motion slice of {@link INTERACTION_TOKENS}, for the provider-less policy. */
+export const MOTION_TOKEN_DEFAULTS = {
+    motionFast: INTERACTION_TOKENS.motionFast,
+    motionNormal: INTERACTION_TOKENS.motionNormal,
+    motionSlow: INTERACTION_TOKENS.motionSlow,
+    motionSpringDamping: INTERACTION_TOKENS.motionSpringDamping,
+    motionSpringStiffness: INTERACTION_TOKENS.motionSpringStiffness,
+    motionSpringMass: INTERACTION_TOKENS.motionSpringMass,
 };
 export function useInteractionTokens() {
-    const [pressOpacity, pressOpacityStrong, disabledOpacity, disabledOpacitySoft, disabledOpacitySubtle, inactiveOpacity, motionFast, motionNormal, motionSlow, motionSpringDamping, motionSpringStiffness, motionSpringMass, drawerOpenDuration, drawerCloseDuration,] = useCSSVariable([
-        '--ui-press-opacity',
-        '--ui-press-opacity-strong',
-        '--ui-disabled-opacity',
-        '--ui-disabled-opacity-soft',
-        '--ui-disabled-opacity-subtle',
-        '--ui-inactive-opacity',
-        '--ui-motion-fast',
-        '--ui-motion-normal',
-        '--ui-motion-slow',
-        '--ui-motion-spring-damping',
-        '--ui-motion-spring-stiffness',
-        '--ui-motion-spring-mass',
-        '--ui-drawer-open-duration',
-        '--ui-drawer-close-duration',
-    ]);
-    return {
-        pressOpacity: clampOpacity(parseNumber(pressOpacity, 0.82)),
-        pressOpacityStrong: clampOpacity(parseNumber(pressOpacityStrong, 0.92)),
-        disabledOpacity: clampOpacity(parseNumber(disabledOpacity, 0.46)),
-        disabledOpacitySoft: clampOpacity(parseNumber(disabledOpacitySoft, 0.56)),
-        disabledOpacitySubtle: clampOpacity(parseNumber(disabledOpacitySubtle, 0.36)),
-        inactiveOpacity: clampOpacity(parseNumber(inactiveOpacity, 0.54)),
-        motionFast: Math.max(0, Math.round(parseNumber(motionFast, MOTION_TOKEN_DEFAULTS.motionFast))),
-        motionNormal: Math.max(0, Math.round(parseNumber(motionNormal, MOTION_TOKEN_DEFAULTS.motionNormal))),
-        motionSlow: Math.max(0, Math.round(parseNumber(motionSlow, MOTION_TOKEN_DEFAULTS.motionSlow))),
-        motionSpringDamping: Math.max(0, parseNumber(motionSpringDamping, MOTION_TOKEN_DEFAULTS.motionSpringDamping)),
-        motionSpringStiffness: Math.max(0, parseNumber(motionSpringStiffness, MOTION_TOKEN_DEFAULTS.motionSpringStiffness)),
-        motionSpringMass: Math.max(0.01, parseNumber(motionSpringMass, MOTION_TOKEN_DEFAULTS.motionSpringMass)),
-        drawerOpenDuration: Math.max(0, Math.round(parseNumber(drawerOpenDuration, 260))),
-        drawerCloseDuration: Math.max(0, Math.round(parseNumber(drawerCloseDuration, 180))),
-    };
+    return INTERACTION_TOKENS;
 }
 function resolveDisabledOpacity(tokens, variant) {
     if (variant === 'none')

package/dist/lib/motion-policy.js

@@ -4,8 +4,8 @@ import { AccessibilityInfo } from 'react-native';
 import { ReduceMotion, useReducedMotion } from 'react-native-reanimated';
 import { MOTION_TOKEN_DEFAULTS, useInteractionTokens } from './interaction-tokens';
 // Without a provider, components still render and Reanimated still follows the system
-// setting. Only `--ui-motion-*` overrides and the non-Reanimated reduced-motion paths
-// need `MotionProvider` at the root.
+// setting. The provider is what switches the non-Reanimated paths to reduced or
+// disabled motion. Durations and the spring come from `INTERACTION_TOKENS` either way.
 const DEFAULT_MOTION_POLICY = {
     mode: 'system',
     reduceMotion: false,

package/dist/lib/theme-presets.d.ts

@@ -1,4 +1,5 @@
 import { type ThemeColors } from './theme-contract';
+import { type ThemeBaseColors } from './theme-derive';
 import { type VisualTokens } from './visual-token-contract';
 /**
  * Canonical full-package theme presets.
@@ -15,6 +16,31 @@ export interface ThemePreset {
     /** Visual token overrides; unset keys keep contract fallbacks. */
     visual: Partial<VisualTokens>;
 }
+/**
+ * Build a preset from the 25 base colors, deriving the other 27.
+ *
+ * Prefer this to writing a `ThemePreset` literal. `visual` has always been
+ * `Partial`, but `light` and `dark` are the full 52-key `ThemeColors`, so the
+ * literal form asks an author for every active variant, soft variant, overlay,
+ * surface, interaction state and shadow — values `deriveThemeColors` already
+ * computes from the palette. Nothing in the literal's type points at that helper,
+ * and the predictable result is a hand-written derivation that drifts from the
+ * library's own. The Atelier preset below is 110 lines for this reason.
+ *
+ * Override a derived value by spreading the result:
+ *
+ * ```ts
+ * const preset = createThemePreset({ name, description, light, dark });
+ * preset.dark.overlay = 'rgba(0, 0, 0, 0.9)';
+ * ```
+ */
+export declare function createThemePreset(input: {
+    name: string;
+    description: string;
+    light: ThemeBaseColors;
+    dark: ThemeBaseColors;
+    visual?: Partial<VisualTokens>;
+}): ThemePreset;
 export declare const WHILEUI_PRESET_SOFT: ThemePreset;
 export declare const WHILEUI_PRESET_ATELIER: ThemePreset;
 export declare const WHILEUI_THEME_PRESETS: readonly ThemePreset[];

package/dist/lib/theme-presets.js

@@ -1,5 +1,33 @@
 import { THEME_TOKEN_SPECS, WHILEUI_DARK_THEME_COLORS, WHILEUI_LIGHT_THEME_COLORS, } from './theme-contract';
+import { deriveThemeColors } from './theme-derive';
 import { VISUAL_TOKEN_SPECS } from './visual-token-contract';
+/**
+ * Build a preset from the 25 base colors, deriving the other 27.
+ *
+ * Prefer this to writing a `ThemePreset` literal. `visual` has always been
+ * `Partial`, but `light` and `dark` are the full 52-key `ThemeColors`, so the
+ * literal form asks an author for every active variant, soft variant, overlay,
+ * surface, interaction state and shadow — values `deriveThemeColors` already
+ * computes from the palette. Nothing in the literal's type points at that helper,
+ * and the predictable result is a hand-written derivation that drifts from the
+ * library's own. The Atelier preset below is 110 lines for this reason.
+ *
+ * Override a derived value by spreading the result:
+ *
+ * ```ts
+ * const preset = createThemePreset({ name, description, light, dark });
+ * preset.dark.overlay = 'rgba(0, 0, 0, 0.9)';
+ * ```
+ */
+export function createThemePreset(input) {
+    return {
+        name: input.name,
+        description: input.description,
+        light: deriveThemeColors(input.light, 'light'),
+        dark: deriveThemeColors(input.dark, 'dark'),
+        visual: input.visual ?? {},
+    };
+}
 // Rounded, airy, frosted. Matches the contract fallbacks.
 export const WHILEUI_PRESET_SOFT = {
     name: 'soft',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thewhileloop/whileui",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "WhileUI Native — Copy-paste components for React Native. You own the code.",
   "license": "MIT",
   "repository": {