@thewhileloop/whileui 4.3.0 → 4.4.0

package/README.md

@@ -477,6 +477,10 @@ const icons = useIconColors();
 `FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never
 needs `hitSlop`.
 
+A floating FAB covers whatever scrolls under it, so a list behind one ends with room for
+it: `contentContainerStyle={{ paddingBottom: fabClearance() }}`, passing the FAB's `size`
+when it is not the default.
+
 ## Layout Primitives (Stack, Row)
 
 Use `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.
@@ -628,9 +632,24 @@ reported, never changed, because a brand colour is a brand decision. The built-i
 `WHILEUI_PRESET_SOFT` and `WHILEUI_PRESET_ATELIER`, go through `themePresetToCss` the same
 way.
 
-Switch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`). A named
-extra theme is registered with `extraThemes: ['name']` in `metro.config.js` and defined
-with `@variant name`. The full token list, with each default, is in `theme-contract.ts`,
+Switch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`), or let
+`useThemeBridge` hold the choice. It returns the chosen `mode`, the `resolvedTheme` on
+screen, `setMode`, `toggleTheme` and `cycleMode`. A sun/moon button calls `toggleTheme`,
+which always flips what is on screen; `cycleMode` steps light → dark → system and suits
+a control that shows all three, because a step into `system` that resolves to the
+current theme looks like a dead tap. Pass an `adapter` to keep the choice across launches:
+
+```tsx
+const { resolvedTheme, toggleTheme } = useThemeBridge({
+  adapter: {
+    loadThemeMode: () => storage.getItem('theme') as ThemeMode | null,
+    saveThemeMode: (mode) => storage.setItem('theme', mode),
+  },
+});
+```
+
+A named extra theme is registered with `extraThemes: ['name']` in `metro.config.js` and
+defined with `@variant name`. The full token list, with each default, is in `theme-contract.ts`,
 and agents can read it from the MCP server's `get_theme_tokens`.
 
 ### Frosted surfaces
@@ -816,24 +835,34 @@ Also accepts the props of React Native's `TextProps`.
 ## Input
 
 ```tsx
-import { Input } from '@thewhileloop/whileui';
+import { Input, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
 
 <Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
+
+<Input
+  placeholder="Search"
+  prefix={<Feather name="search" size={16} color={icons.muted} aria-hidden />}
+/>;
 ```
 
-On web, filled Input, Textarea, NumericInput, and SmartInput surfaces preserve their
-themed background, foreground, and caret when the browser autofills them.
+On iOS and Android, Input, Textarea, NumericInput and SmartInput draw the caret and
+selection in the theme's primary colour; pass `selectionColor` (and `cursorColor` on
+Android) to override it. On web, filled surfaces keep their themed background,
+foreground and caret when the browser autofills them.
 
 <!-- api:Input -->
 
-| Prop           | Type                              | Default     | Description |
-| -------------- | --------------------------------- | ----------- | ----------- |
-| aria-invalid   | `boolean`                         | —           |             |
-| className      | `string`                          | —           |             |
-| prefix         | `React.ReactNode`                 | —           |             |
-| suffix         | `React.ReactNode`                 | —           |             |
-| inputClassName | `string`                          | —           |             |
-| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |             |
+| Prop           | Type                              | Default     | Description                                                                                                                                          |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| aria-invalid   | `boolean`                         | —           |                                                                                                                                                      |
+| className      | `string`                          | —           |                                                                                                                                                      |
+| prefix         | `React.ReactNode`                 | —           | Shown before the text. A decorative icon here needs `aria-hidden`; screen readers otherwise stop on it as a separate element and read out its glyph. |
+| suffix         | `React.ReactNode`                 | —           | Shown after the text: a unit, or a control such as a clear button.                                                                                   |
+| inputClassName | `string`                          | —           |                                                                                                                                                      |
+| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |                                                                                                                                                      |
 
 Also accepts the props of `TextInputProps`.
 <!-- /api:Input -->
@@ -1007,18 +1036,21 @@ import {
 </SegmentedControl>;
 ```
 
+When the labels do not fit a phone, `wrap="scroll"` keeps them on one row at full width
+and scrolls sideways, instead of wrapping or truncating them.
+
 <!-- api:SegmentedControl -->
 
-| Prop          | Type                      | Default     | Description                |
-| ------------- | ------------------------- | ----------- | -------------------------- |
-| value         | `string`                  | —           |                            |
-| defaultValue  | `string`                  | `''`        |                            |
-| onValueChange | `(value: string) => void` | —           |                            |
-| variant       | `'default' \| 'pill'`     | `'default'` | Pill = rounded-full items. |
-| wrap          | `boolean \| 'auto'`       | `true`      |                            |
-| size          | `'default' \| 'compact'`  | `'default'` |                            |
-| disabled      | `boolean`                 | `false`     |                            |
-| className     | `string`                  | —           |                            |
+| Prop          | Type                            | Default     | Description                                                                                                                                                                                                                                                                |
+| ------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value         | `string`                        | —           |                                                                                                                                                                                                                                                                            |
+| defaultValue  | `string`                        | `''`        |                                                                                                                                                                                                                                                                            |
+| onValueChange | `(value: string) => void`       | —           |                                                                                                                                                                                                                                                                            |
+| variant       | `'default' \| 'pill'`           | `'default'` | Pill = rounded-full items.                                                                                                                                                                                                                                                 |
+| wrap          | `boolean \| 'auto' \| 'scroll'` | `'auto'`    | `true` wraps segments onto more rows; `false` keeps one row and shares its width. `'scroll'` keeps one row with each segment as wide as its label and scrolls sideways when they do not fit — for labels a phone cannot show in full. `'auto'` wraps above three segments. |
+| size          | `'default' \| 'compact'`        | `'default'` |                                                                                                                                                                                                                                                                            |
+| disabled      | `boolean`                       | `false`     |                                                                                                                                                                                                                                                                            |
+| className     | `string`                        | —           |                                                                                                                                                                                                                                                                            |
 
 Also accepts the props of `ViewProps`.
 <!-- /api:SegmentedControl -->
@@ -1333,6 +1365,10 @@ selected values stay on one line and truncate without displacing the trigger che
 For popover presentation on web, the options panel matches the trigger width, caps
 itself to the collision-available viewport, and wraps long option labels inside it.
 
+Opening a Select, or a Popover, closes the on-screen keyboard first, so options opened
+from a form are never hidden behind it. Both draw in a portal, where the platform would
+otherwise leave the keyboard up; the Modal-hosted overlays close it on their own.
+
 `SelectContent` supports optional frosted props:
 
 <!-- api:SelectContent -->

package/dist/agent/catalog.json

@@ -1,11 +1,11 @@
 {
   "package": "@thewhileloop/whileui",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "guides": {
     "quickReference": "## Quick Reference (AI / Code Generation)\n\n- **Full-screen:** `AppShell` + `Header` in `header` + `BottomNav` in `bottomNav` + content in `children`\n- **No-jump loading:** keep `AppShell` mounted, set `loading` + `skeleton` (e.g., `PageSkeleton`/`ScreenSkeleton`)\n- **Layout:** `Stack` (vertical), `Row` (horizontal) — both support `gap`, `align`, `justify`\n- **Auth callbacks:** Auth templates use objects: `onSubmit({ email, password })`, `onSubmit({ firstName, lastName, email, password })`, etc. Copy templates from `apps/showcase/catalog/templates/auth/`.\n- **PortalHost:** Add `<PortalHost />` at app root for Select, Popover, Tooltip, HoverCard.\n  Inside any WhileUI overlay they render into that overlay's layer without configuration.\n- **Motion:** Wrap the root in `<MotionProvider>`; use `useMotionPolicy()` for semantic\n  durations, the responsive spring, and reduced-motion behavior.\n- **Metro:** `withWhileUIMetro(config, { cssEntryFile: './global.css' })` from\n  `@thewhileloop/whileui/metro` — wraps Uniwind and keeps icon fonts loading on device.\n  `global.css` at app root, imported in `App.tsx`. Installing from npm also needs\n  `@source './node_modules/@thewhileloop/whileui/dist';` or every component renders unstyled.\n- **States:** `LoadingState`, `EmptyState` and `ErrorState` share one shape; `ErrorState`\n  takes `onRetry`. `Text variant=\"eyebrow\"` is the muted section label above a title.\n- **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/catalog/templates/` (auth, profile); flow patterns in README \"Flow Patterns\" section.\n\n### Composition grammar\n\n- Start with one page canvas and flat sections. Add a `Surface` only when grouping or\n  elevation communicates something; do not wrap every section in a card.\n- Use `level=\"base\"` for grouped content, `raised` for selectable or floating regions,\n  and `overlay` for content above the page. Avoid nesting more than one surfaced level.\n- Express hierarchy through `Text` variants before custom font-size classes. Keep one\n  primary action per region and constrain long-form content with `Container`.\n- Forms use `FormField`; its disabled and invalid state flows into `Input`, `Textarea`,\n  `NumericInput`, and `Select`. Pass a control prop only to override that inherited state.\n- Chat mechanics belong to `ChatConversation` + `SmartInput`. Message payloads, tools,\n  reasoning, approvals, sources, and action rows are application-owned compositions.\n- Import Markdown and code rendering from their optional subpaths. Do not make the root\n  package pay for content rendering when the screen does not use it.",
     "compositionGrammar": "### Composition grammar\n\n- Start with one page canvas and flat sections. Add a `Surface` only when grouping or\n  elevation communicates something; do not wrap every section in a card.\n- Use `level=\"base\"` for grouped content, `raised` for selectable or floating regions,\n  and `overlay` for content above the page. Avoid nesting more than one surfaced level.\n- Express hierarchy through `Text` variants before custom font-size classes. Keep one\n  primary action per region and constrain long-form content with `Container`.\n- Forms use `FormField`; its disabled and invalid state flows into `Input`, `Textarea`,\n  `NumericInput`, and `Select`. Pass a control prop only to override that inherited state.\n- Chat mechanics belong to `ChatConversation` + `SmartInput`. Message payloads, tools,\n  reasoning, approvals, sources, and action rows are application-owned compositions.\n- Import Markdown and code rendering from their optional subpaths. Do not make the root\n  package pay for content rendering when the screen does not use it.",
     "installation": "## Installation\n\n```bash\nbun add @thewhileloop/whileui\nbun add react@^19.3.0 react-native@^0.88.0 uniwind@^1.12.2 tailwindcss@^4.0.0 react-native-reanimated react-native-safe-area-context react-native-screens\n# Only if you use Select, Popover, Tooltip, or HoverCard:\nbun add @rn-primitives/portal @rn-primitives/hooks @rn-primitives/slot @rn-primitives/select @rn-primitives/popover @rn-primitives/tooltip @rn-primitives/hover-card\n# Only if you import @thewhileloop/whileui/markdown:\nbun add markdown-it\n```\n\nUse `npm install` instead of `bun add` if you prefer npm.\n\n### Setup Uniwind (required)\n\n1. **metro.config.js** (wrap with `withWhileUIMetro`):\n\n```js\nconst { getDefaultConfig } = require('expo/metro-config');\nconst { withWhileUIMetro } = require('@thewhileloop/whileui/metro');\n\n/** @type {import('expo/metro-config').MetroConfig} */\nconst config = getDefaultConfig(__dirname);\n\nmodule.exports = withWhileUIMetro(config, {\n  cssEntryFile: './global.css',\n});\n```\n\n> `withWhileUIMetro` calls Uniwind's `withUniwindConfig(config, options)` for you — same\n> options, config first, `cssEntryFile` a relative path — and keeps `expo-asset`,\n> `expo-font` and `@expo/vector-icons` on the real `react-native`. Without that, Uniwind's\n> import rewrite leaves every icon glyph silently missing on iOS and Android while web\n> renders fine. Pass `exemptFromUniwindRewrite: ['pkg']` for any other package that\n> imports a `react-native` export Uniwind's wrapper lacks. It must be the outermost wrapper.\n\n2. **global.css** at app root, imported from `App.tsx`:\n\n```css\n@import 'tailwindcss';\n@import 'uniwind';\n\n/* Required when installed from npm: Tailwind does not scan node_modules, so without\n   this line every component renders unstyled. */\n@source './node_modules/@thewhileloop/whileui/dist';\n\n/* Then your theme: generate it (Theming, below) rather than writing tokens by hand. */\n```\n\n3. **App.tsx**:\n\n```tsx\nimport './global.css';\nimport { MotionProvider, PortalHost } from '@thewhileloop/whileui';\nimport { Button, ButtonText } from '@thewhileloop/whileui';\n\nexport default function App() {\n  return (\n    <MotionProvider>\n      {/* Your app content */}\n      <PortalHost />\n    </MotionProvider>\n  );\n}\n```\n\n`PortalHost` (last child of the root) is where Select, Popover, Tooltip and HoverCard\nrender. Inside a Dialog, Sheet, menu or picker they use that overlay's own layer\nautomatically, and Android back or Escape closes the innermost layer first. Pass\n`portalHost` only to target a host you placed yourself, such as in a modal screen your\nnavigator presents.\n\n### Vite + React Native Web + WhileUI setup\n\nUse the WhileUI Vite compatibility helper when your app includes portal-based primitives.\n\n1. Install Vite + RN web basics:\n\n```bash\nbun add react-dom react-native-web\nbun add -d vite @vitejs/plugin-react\n```\n\n2. `vite.config.ts`:\n\n```ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport { withWhileUIViteCompat } from '@thewhileloop/whileui/vite';\n\nexport default defineConfig(withWhileUIViteCompat({ plugins: [react()] }));\n```\n\n3. Keep `PortalHost` at app root when using Select/Popover/Tooltip/HoverCard.\n\nTroubleshooting:\n\n| Symptom                                                  | Likely cause                                              | Fix                                                                                                 |\n| -------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| `Unexpected token <` from `@rn-primitives/*/dist/*.mjs`  | rn-primitives ships raw JSX in dist for some packages     | Use `withWhileUIViteCompat(...)` in `vite.config.ts`                                                |\n| `className` rejected on RN primitives in consumer TS app | RN `className` augmentation not loaded from package entry | Import components from `@thewhileloop/whileui` (or side-effect import the package entry before use) |\n| Theme token resolves differently on native/web           | Missing `--app-color-*` fallback for non-RN-native values | Add `--app-color-*` fallbacks in `global.css` for any `oklch(...)` token used by native APIs        |",
-    "theming": "## Theming\n\nA theme is a set of CSS variables in `global.css`, in OKLCH, with a `light` and a `dark`\nvariant. Every component reads the same contract, so a theme must define **every** token\nin both modes: a missing one silently falls back to an unstyled value at runtime.\n\n### Generate a theme\n\n`themeFromSeeds` builds a complete light and dark theme from three colours, and\n`themePresetToCss` writes every token, including the hex fallbacks React Native APIs need,\nready to paste into `global.css`:\n\n```ts\nimport { checkThemeContrast, themeFromSeeds, themePresetToCss } from '@thewhileloop/whileui/tokens';\n\nconst theme = themeFromSeeds({\n  name: 'studio',\n  description: 'Bone paper and burnt amber',\n  light: { background: '#f0ede9', foreground: '#13161c', primary: '#b65400' },\n  // optional: `dark` seeds (otherwise a dark page with the brand lifted to read on it),\n  // `overrides` for any base colour, `visual` for radius and density tokens\n});\n\ncheckThemeContrast(theme.light).filter((c) => !c.pass);\n// [{ pair: 'primary on background', ratio: 4.23, min: 4.5, pass: false }, …]\nconst css = themePresetToCss(theme); // paste into global.css\n```\n\nSeeds are kept as given; the colours it derives (muted text, text on each fill, status\ncolours) are tuned to WCAG AA. `checkThemeContrast` checks any palette, hand-written ones\nincluded: every text pairing at 4.5:1 and the focus ring at 3:1. A failing seed is\nreported, never changed, because a brand colour is a brand decision. The built-in presets,\n`WHILEUI_PRESET_SOFT` and `WHILEUI_PRESET_ATELIER`, go through `themePresetToCss` the same\nway.\n\nSwitch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`). A named\nextra theme is registered with `extraThemes: ['name']` in `metro.config.js` and defined\nwith `@variant name`. The full token list, with each default, is in `theme-contract.ts`,\nand agents can read it from the MCP server's `get_theme_tokens`.\n\n### Frosted surfaces\n\nCards and overlays take `frosted`, `blurIntensity` and `blurTintToken`\n(`'surfaceElevated' | 'surfaceTranslucent' | 'card' | 'popover'`). Without a blur view\nthey tint only; register `expo-blur` once for real blur:\n\n```tsx\nimport { BlurView } from 'expo-blur';\nimport { registerFrostedBlurView } from '@thewhileloop/whileui';\n\nregisterFrostedBlurView(BlurView);\n```\n\nFor a frosted look across a whole theme, make `surface-elevated`, `surface-border` and\n`surface-highlight` translucent, in your light and dark variants or in a separate theme.\nThe tuning tokens:\n\n| Token                                                                     | Default      | Effect                                                         |\n| ------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------- |\n| `--ui-blur-intensity-subtle` / `-medium` / `-strong`                      | 18 / 26 / 34 | The three blur presets                                         |\n| `--ui-frosted-android-tint-alpha-scale`                                   | 1.18         | Android needs denser tint; `1` matches iOS and web             |\n| `--ui-frosted-android-experimental-blur`                                  | 1            | Uses `expo-blur`'s experimental Android blur; `0` turns it off |\n| `--ui-frosted-highlight-height`                                           | 2            | Top sheen in px; `0` removes it                                |\n| `--ui-blur-saturation-pct`                                                | 145          | Web saturation multiplier                                      |\n| `--ui-frosted-backdrop-blur-intensity`, `-scale`                          | 22, 0.72     | Backdrop blur, and its ratio when a component overrides blur   |\n| `--ui-drawer-frosted-inset`, `-radius`, `--ui-drawer-content-top-padding` | 10, 34, 0    | Frosted drawer shell                                           |\n\n### Colours for React Native APIs\n\nIcons, `ActivityIndicator` and other native APIs need hex or rgb, not OKLCH.\n`useThemeColors()` returns the whole palette as React Native colours, falling back to the\n`--app-color-*` tokens a generated theme includes; `useIconColors()` is the subset icons\nuse, with `muted` mapped to `mutedForeground`.\n\n```tsx\nconst icons = useIconColors();\n<Feather name=\"heart\" size={20} color={icons.muted} />;\n```\n\nInput, Textarea, NumericInput, SmartInput, Spinner and LoadingScreen pick theme colours\nwhen you omit `placeholderTextColor` or `spinnerColor`.\n\n### Interaction and motion\n\nPress opacity, disabled opacity, motion durations, the responsive spring, and the drawer\nopen and close durations are package constants on `INTERACTION_TOKENS`. They are not CSS\nvariables, so a theme does not change them.\n\nFor a custom control, read that table:\n\n```tsx\nimport { useInteractionTokens, withInteractivePressableStyle } from '@thewhileloop/whileui';\n```\n\nWrap the application in `MotionProvider` to coordinate system reduced motion, an explicit\npreview mode, and deterministic animation-free tests. The provider is optional. Without\nit `useMotionPolicy` reports the durations and spring from `INTERACTION_TOKENS`, and\nReanimated follows the system setting. `reduced` preserves non-spatial feedback while asking Reanimated to skip motion;\n`disabled` also resolves semantic durations to zero.\n\n```tsx\nimport { MotionProvider, useMotionPolicy } from '@thewhileloop/whileui';\n\n<MotionProvider mode=\"system\">{/* application */}</MotionProvider>;\n\nconst motion = useMotionPolicy();\nmotion.durations.normal;\nmotion.springs.responsive;\n```"
+    "theming": "## Theming\n\nA theme is a set of CSS variables in `global.css`, in OKLCH, with a `light` and a `dark`\nvariant. Every component reads the same contract, so a theme must define **every** token\nin both modes: a missing one silently falls back to an unstyled value at runtime.\n\n### Generate a theme\n\n`themeFromSeeds` builds a complete light and dark theme from three colours, and\n`themePresetToCss` writes every token, including the hex fallbacks React Native APIs need,\nready to paste into `global.css`:\n\n```ts\nimport { checkThemeContrast, themeFromSeeds, themePresetToCss } from '@thewhileloop/whileui/tokens';\n\nconst theme = themeFromSeeds({\n  name: 'studio',\n  description: 'Bone paper and burnt amber',\n  light: { background: '#f0ede9', foreground: '#13161c', primary: '#b65400' },\n  // optional: `dark` seeds (otherwise a dark page with the brand lifted to read on it),\n  // `overrides` for any base colour, `visual` for radius and density tokens\n});\n\ncheckThemeContrast(theme.light).filter((c) => !c.pass);\n// [{ pair: 'primary on background', ratio: 4.23, min: 4.5, pass: false }, …]\nconst css = themePresetToCss(theme); // paste into global.css\n```\n\nSeeds are kept as given; the colours it derives (muted text, text on each fill, status\ncolours) are tuned to WCAG AA. `checkThemeContrast` checks any palette, hand-written ones\nincluded: every text pairing at 4.5:1 and the focus ring at 3:1. A failing seed is\nreported, never changed, because a brand colour is a brand decision. The built-in presets,\n`WHILEUI_PRESET_SOFT` and `WHILEUI_PRESET_ATELIER`, go through `themePresetToCss` the same\nway.\n\nSwitch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`), or let\n`useThemeBridge` hold the choice. It returns the chosen `mode`, the `resolvedTheme` on\nscreen, `setMode`, `toggleTheme` and `cycleMode`. A sun/moon button calls `toggleTheme`,\nwhich always flips what is on screen; `cycleMode` steps light → dark → system and suits\na control that shows all three, because a step into `system` that resolves to the\ncurrent theme looks like a dead tap. Pass an `adapter` to keep the choice across launches:\n\n```tsx\nconst { resolvedTheme, toggleTheme } = useThemeBridge({\n  adapter: {\n    loadThemeMode: () => storage.getItem('theme') as ThemeMode | null,\n    saveThemeMode: (mode) => storage.setItem('theme', mode),\n  },\n});\n```\n\nA named extra theme is registered with `extraThemes: ['name']` in `metro.config.js` and\ndefined with `@variant name`. The full token list, with each default, is in `theme-contract.ts`,\nand agents can read it from the MCP server's `get_theme_tokens`.\n\n### Frosted surfaces\n\nCards and overlays take `frosted`, `blurIntensity` and `blurTintToken`\n(`'surfaceElevated' | 'surfaceTranslucent' | 'card' | 'popover'`). Without a blur view\nthey tint only; register `expo-blur` once for real blur:\n\n```tsx\nimport { BlurView } from 'expo-blur';\nimport { registerFrostedBlurView } from '@thewhileloop/whileui';\n\nregisterFrostedBlurView(BlurView);\n```\n\nFor a frosted look across a whole theme, make `surface-elevated`, `surface-border` and\n`surface-highlight` translucent, in your light and dark variants or in a separate theme.\nThe tuning tokens:\n\n| Token                                                                     | Default      | Effect                                                         |\n| ------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------- |\n| `--ui-blur-intensity-subtle` / `-medium` / `-strong`                      | 18 / 26 / 34 | The three blur presets                                         |\n| `--ui-frosted-android-tint-alpha-scale`                                   | 1.18         | Android needs denser tint; `1` matches iOS and web             |\n| `--ui-frosted-android-experimental-blur`                                  | 1            | Uses `expo-blur`'s experimental Android blur; `0` turns it off |\n| `--ui-frosted-highlight-height`                                           | 2            | Top sheen in px; `0` removes it                                |\n| `--ui-blur-saturation-pct`                                                | 145          | Web saturation multiplier                                      |\n| `--ui-frosted-backdrop-blur-intensity`, `-scale`                          | 22, 0.72     | Backdrop blur, and its ratio when a component overrides blur   |\n| `--ui-drawer-frosted-inset`, `-radius`, `--ui-drawer-content-top-padding` | 10, 34, 0    | Frosted drawer shell                                           |\n\n### Colours for React Native APIs\n\nIcons, `ActivityIndicator` and other native APIs need hex or rgb, not OKLCH.\n`useThemeColors()` returns the whole palette as React Native colours, falling back to the\n`--app-color-*` tokens a generated theme includes; `useIconColors()` is the subset icons\nuse, with `muted` mapped to `mutedForeground`.\n\n```tsx\nconst icons = useIconColors();\n<Feather name=\"heart\" size={20} color={icons.muted} />;\n```\n\nInput, Textarea, NumericInput, SmartInput, Spinner and LoadingScreen pick theme colours\nwhen you omit `placeholderTextColor` or `spinnerColor`.\n\n### Interaction and motion\n\nPress opacity, disabled opacity, motion durations, the responsive spring, and the drawer\nopen and close durations are package constants on `INTERACTION_TOKENS`. They are not CSS\nvariables, so a theme does not change them.\n\nFor a custom control, read that table:\n\n```tsx\nimport { useInteractionTokens, withInteractivePressableStyle } from '@thewhileloop/whileui';\n```\n\nWrap the application in `MotionProvider` to coordinate system reduced motion, an explicit\npreview mode, and deterministic animation-free tests. The provider is optional. Without\nit `useMotionPolicy` reports the durations and spring from `INTERACTION_TOKENS`, and\nReanimated follows the system setting. `reduced` preserves non-spatial feedback while asking Reanimated to skip motion;\n`disabled` also resolves semantic durations to zero.\n\n```tsx\nimport { MotionProvider, useMotionPolicy } from '@thewhileloop/whileui';\n\n<MotionProvider mode=\"system\">{/* application */}</MotionProvider>;\n\nconst motion = useMotionPolicy();\nmotion.durations.normal;\nmotion.springs.responsive;\n```"
   },
   "components": [
     {
@@ -69,7 +69,7 @@
       "category": "Form Controls",
       "kind": "package",
       "summary": "TextInput wrapper with themed styling",
-      "docs": "## Input\n\n```tsx\nimport { Input } from '@thewhileloop/whileui';\n\n<Input placeholder=\"Email\" variant=\"default\" value={value} onChangeText={setValue} />;\n```\n\nOn web, filled Input, Textarea, NumericInput, and SmartInput surfaces preserve their\nthemed background, foreground, and caret when the browser autofills them.\n\n\n| Prop           | Type                              | Default     | Description |\n| -------------- | --------------------------------- | ----------- | ----------- |\n| aria-invalid   | `boolean`                         | —           |             |\n| className      | `string`                          | —           |             |\n| prefix         | `React.ReactNode`                 | —           |             |\n| suffix         | `React.ReactNode`                 | —           |             |\n| inputClassName | `string`                          | —           |             |\n| variant        | `'default' \\| 'error' \\| 'plain'` | `'default'` |             |\n\nAlso accepts the props of `TextInputProps`."
+      "docs": "## Input\n\n```tsx\nimport { Input, useIconColors } from '@thewhileloop/whileui';\nimport { Feather } from '@expo/vector-icons';\n\nconst icons = useIconColors();\n\n<Input placeholder=\"Email\" variant=\"default\" value={value} onChangeText={setValue} />;\n\n<Input\n  placeholder=\"Search\"\n  prefix={<Feather name=\"search\" size={16} color={icons.muted} aria-hidden />}\n/>;\n```\n\nOn iOS and Android, Input, Textarea, NumericInput and SmartInput draw the caret and\nselection in the theme's primary colour; pass `selectionColor` (and `cursorColor` on\nAndroid) to override it. On web, filled surfaces keep their themed background,\nforeground and caret when the browser autofills them.\n\n\n| Prop           | Type                              | Default     | Description                                                                                                                                          |\n| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| aria-invalid   | `boolean`                         | —           |                                                                                                                                                      |\n| className      | `string`                          | —           |                                                                                                                                                      |\n| prefix         | `React.ReactNode`                 | —           | Shown before the text. A decorative icon here needs `aria-hidden`; screen readers otherwise stop on it as a separate element and read out its glyph. |\n| suffix         | `React.ReactNode`                 | —           | Shown after the text: a unit, or a control such as a clear button.                                                                                   |\n| inputClassName | `string`                          | —           |                                                                                                                                                      |\n| variant        | `'default' \\| 'error' \\| 'plain'` | `'default'` |                                                                                                                                                      |\n\nAlso accepts the props of `TextInputProps`."
     },
     {
       "name": "NumericInput",
@@ -132,7 +132,7 @@
       "category": "Form Controls",
       "kind": "package",
       "summary": "Uses `SelectOption` type `{value, label}`. Includes SelectGroup, SelectLabel, SelectSeparator",
-      "docs": "## Select\n\n```tsx\nimport {\n  Select,\n  SelectTrigger,\n  SelectValue,\n  SelectContent,\n  SelectItem,\n} from '@thewhileloop/whileui';\n\n<Select value={value} onValueChange={setValue}>\n  <SelectTrigger>\n    <SelectValue placeholder=\"Select...\" />\n  </SelectTrigger>\n  <SelectContent frosted blurIntensity={24} blurTintToken=\"surfaceTranslucent\">\n    <SelectItem label=\"Option 1\" value=\"1\" />\n    <SelectItem label=\"Option 2\" value=\"2\" />\n  </SelectContent>\n</Select>;\n```\n\nFocused and pressed options use the subtle interaction-state tokens; the primary token\nmarks the selected indicator without replacing the option's foreground colour. Long\nselected values stay on one line and truncate without displacing the trigger chevron.\nFor popover presentation on web, the options panel matches the trigger width, caps\nitself to the collision-available viewport, and wraps long option labels inside it.\n\n`SelectContent` supports optional frosted props:\n\n\n| Prop          | Type                                                               | Default       | Description                          |\n| ------------- | ------------------------------------------------------------------ | ------------- | ------------------------------------ |\n| className     | `string`                                                           | —             |                                      |\n| portalHost    | `string`                                                           | —             |                                      |\n| insets        | `{ top?: number; bottom?: number; left?: number; right?: number }` | —             |                                      |\n| frosted       | `boolean`                                                          | `false`       | Enable the optional frosted overlay. |\n| blurIntensity | `number`                                                           | subtle preset | Override blur amount directly.       |\n| blurTintToken | `FrostedTintToken`                                                 | `'popover'`   | Tint token used for frosted mode.    |\n\nAlso accepts the props of the underlying primitive.\n\n`SelectContent` keeps its listbox inside the safe area by default; pass `insets` only to\nchange that margin. A list taller than the screen scrolls inside the listbox on every\nplatform. Inside a Dialog, Sheet or other WhileUI overlay it renders in that\noverlay's layer automatically. Option values must be non-empty strings: the web\nprimitive rejects `\"\"`, so model \"none\" as an explicit value such as `'none'`."
+      "docs": "## Select\n\n```tsx\nimport {\n  Select,\n  SelectTrigger,\n  SelectValue,\n  SelectContent,\n  SelectItem,\n} from '@thewhileloop/whileui';\n\n<Select value={value} onValueChange={setValue}>\n  <SelectTrigger>\n    <SelectValue placeholder=\"Select...\" />\n  </SelectTrigger>\n  <SelectContent frosted blurIntensity={24} blurTintToken=\"surfaceTranslucent\">\n    <SelectItem label=\"Option 1\" value=\"1\" />\n    <SelectItem label=\"Option 2\" value=\"2\" />\n  </SelectContent>\n</Select>;\n```\n\nFocused and pressed options use the subtle interaction-state tokens; the primary token\nmarks the selected indicator without replacing the option's foreground colour. Long\nselected values stay on one line and truncate without displacing the trigger chevron.\nFor popover presentation on web, the options panel matches the trigger width, caps\nitself to the collision-available viewport, and wraps long option labels inside it.\n\nOpening a Select, or a Popover, closes the on-screen keyboard first, so options opened\nfrom a form are never hidden behind it. Both draw in a portal, where the platform would\notherwise leave the keyboard up; the Modal-hosted overlays close it on their own.\n\n`SelectContent` supports optional frosted props:\n\n\n| Prop          | Type                                                               | Default       | Description                          |\n| ------------- | ------------------------------------------------------------------ | ------------- | ------------------------------------ |\n| className     | `string`                                                           | —             |                                      |\n| portalHost    | `string`                                                           | —             |                                      |\n| insets        | `{ top?: number; bottom?: number; left?: number; right?: number }` | —             |                                      |\n| frosted       | `boolean`                                                          | `false`       | Enable the optional frosted overlay. |\n| blurIntensity | `number`                                                           | subtle preset | Override blur amount directly.       |\n| blurTintToken | `FrostedTintToken`                                                 | `'popover'`   | Tint token used for frosted mode.    |\n\nAlso accepts the props of the underlying primitive.\n\n`SelectContent` keeps its listbox inside the safe area by default; pass `insets` only to\nchange that margin. A list taller than the screen scrolls inside the listbox on every\nplatform. Inside a Dialog, Sheet or other WhileUI overlay it renders in that\noverlay's layer automatically. Option values must be non-empty strings: the web\nprimitive rejects `\"\"`, so model \"none\" as an explicit value such as `'none'`."
     },
     {
       "name": "Label",
@@ -146,7 +146,7 @@
       "category": "Form Controls",
       "kind": "package",
       "summary": "SegmentedControl, SegmentedControlItem, SegmentedControlItemText with wrapping layout support",
-      "docs": "## SegmentedControl\n\n```tsx\nimport {\n  SegmentedControl,\n  SegmentedControlItem,\n  SegmentedControlItemText,\n} from '@thewhileloop/whileui';\n\n<SegmentedControl value={unit} onValueChange={setUnit} variant=\"pill\" wrap>\n  <SegmentedControlItem value=\"metric\">\n    <SegmentedControlItemText>Metric</SegmentedControlItemText>\n  </SegmentedControlItem>\n  <SegmentedControlItem value=\"imperial\">\n    <SegmentedControlItemText>Imperial</SegmentedControlItemText>\n  </SegmentedControlItem>\n</SegmentedControl>;\n```\n\n\n| Prop          | Type                      | Default     | Description                |\n| ------------- | ------------------------- | ----------- | -------------------------- |\n| value         | `string`                  | —           |                            |\n| defaultValue  | `string`                  | `''`        |                            |\n| onValueChange | `(value: string) => void` | —           |                            |\n| variant       | `'default' \\| 'pill'`     | `'default'` | Pill = rounded-full items. |\n| wrap          | `boolean \\| 'auto'`       | `true`      |                            |\n| size          | `'default' \\| 'compact'`  | `'default'` |                            |\n| disabled      | `boolean`                 | `false`     |                            |\n| className     | `string`                  | —           |                            |\n\nAlso accepts the props of `ViewProps`."
+      "docs": "## SegmentedControl\n\n```tsx\nimport {\n  SegmentedControl,\n  SegmentedControlItem,\n  SegmentedControlItemText,\n} from '@thewhileloop/whileui';\n\n<SegmentedControl value={unit} onValueChange={setUnit} variant=\"pill\" wrap>\n  <SegmentedControlItem value=\"metric\">\n    <SegmentedControlItemText>Metric</SegmentedControlItemText>\n  </SegmentedControlItem>\n  <SegmentedControlItem value=\"imperial\">\n    <SegmentedControlItemText>Imperial</SegmentedControlItemText>\n  </SegmentedControlItem>\n</SegmentedControl>;\n```\n\nWhen the labels do not fit a phone, `wrap=\"scroll\"` keeps them on one row at full width\nand scrolls sideways, instead of wrapping or truncating them.\n\n\n| Prop          | Type                            | Default     | Description                                                                                                                                                                                                                                                                |\n| ------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| value         | `string`                        | —           |                                                                                                                                                                                                                                                                            |\n| defaultValue  | `string`                        | `''`        |                                                                                                                                                                                                                                                                            |\n| onValueChange | `(value: string) => void`       | —           |                                                                                                                                                                                                                                                                            |\n| variant       | `'default' \\| 'pill'`           | `'default'` | Pill = rounded-full items.                                                                                                                                                                                                                                                 |\n| wrap          | `boolean \\| 'auto' \\| 'scroll'` | `'auto'`    | `true` wraps segments onto more rows; `false` keeps one row and shares its width. `'scroll'` keeps one row with each segment as wide as its label and scrolls sideways when they do not fit — for labels a phone cannot show in full. `'auto'` wraps above three segments. |\n| size          | `'default' \\| 'compact'`        | `'default'` |                                                                                                                                                                                                                                                                            |\n| disabled      | `boolean`                       | `false`     |                                                                                                                                                                                                                                                                            |\n| className     | `string`                        | —           |                                                                                                                                                                                                                                                                            |\n\nAlso accepts the props of `ViewProps`."
     },
     {
       "name": "Toggle",
@@ -188,7 +188,7 @@
       "category": "Display",
       "kind": "package",
       "summary": "Floating action button. `label` required; pass your own icon as children",
-      "docs": "### FAB\n\nOne primary action, raised above the content. It owns no icon dependency — pass the\nglyph as children and colour it from `useIconColors()`, because icon libraries need a\nconcrete colour rather than a class.\n\n```tsx\nimport { FAB, useIconColors } from '@thewhileloop/whileui';\nimport { Feather } from '@expo/vector-icons';\n\nconst icons = useIconColors();\n\n<FAB label=\"New group\" onPress={create}>\n  <Feather name=\"plus\" size={24} color={icons.primaryForeground} />\n</FAB>;\n```\n\n| Prop        | Type                                             | Default    | Notes                                   |\n| ----------- | ------------------------------------------------ | ---------- | --------------------------------------- |\n| `label`     | `string`                                         | —          | Required. The accessible name           |\n| `variant`   | `default \\| secondary \\| destructive \\| surface` | `default`  |                                         |\n| `size`      | `sm \\| default \\| lg`                            | `default`  | 48 / 56 / 64 — all clear touch minimums |\n| `placement` | `floating \\| floating-left \\| inline`            | `floating` | `inline` lets the caller position it    |\n\n`FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never\nneeds `hitSlop`."
+      "docs": "### FAB\n\nOne primary action, raised above the content. It owns no icon dependency — pass the\nglyph as children and colour it from `useIconColors()`, because icon libraries need a\nconcrete colour rather than a class.\n\n```tsx\nimport { FAB, useIconColors } from '@thewhileloop/whileui';\nimport { Feather } from '@expo/vector-icons';\n\nconst icons = useIconColors();\n\n<FAB label=\"New group\" onPress={create}>\n  <Feather name=\"plus\" size={24} color={icons.primaryForeground} />\n</FAB>;\n```\n\n| Prop        | Type                                             | Default    | Notes                                   |\n| ----------- | ------------------------------------------------ | ---------- | --------------------------------------- |\n| `label`     | `string`                                         | —          | Required. The accessible name           |\n| `variant`   | `default \\| secondary \\| destructive \\| surface` | `default`  |                                         |\n| `size`      | `sm \\| default \\| lg`                            | `default`  | 48 / 56 / 64 — all clear touch minimums |\n| `placement` | `floating \\| floating-left \\| inline`            | `floating` | `inline` lets the caller position it    |\n\n`FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never\nneeds `hitSlop`.\n\nA floating FAB covers whatever scrolls under it, so a list behind one ends with room for\nit: `contentContainerStyle={{ paddingBottom: fabClearance() }}`, passing the FAB's `size`\nwhen it is not the default."
     },
     {
       "name": "Alert",

package/dist/agent/llms-components.txt

@@ -1,4 +1,4 @@
-# WhileUI 4.3.0
+# WhileUI 4.4.0
 
 > React Native components and blocks for iOS, Android and web, styled with Uniwind and
 > themed through a typed token contract. Package: `@thewhileloop/whileui`.
@@ -247,23 +247,33 @@ Also accepts the props of `PressableProps`.
 ## Input
 
 ```tsx
-import { Input } from '@thewhileloop/whileui';
+import { Input, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
 
 <Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
+
+<Input
+  placeholder="Search"
+  prefix={<Feather name="search" size={16} color={icons.muted} aria-hidden />}
+/>;
 ```
 
-On web, filled Input, Textarea, NumericInput, and SmartInput surfaces preserve their
-themed background, foreground, and caret when the browser autofills them.
+On iOS and Android, Input, Textarea, NumericInput and SmartInput draw the caret and
+selection in the theme's primary colour; pass `selectionColor` (and `cursorColor` on
+Android) to override it. On web, filled surfaces keep their themed background,
+foreground and caret when the browser autofills them.
 
 
-| Prop           | Type                              | Default     | Description |
-| -------------- | --------------------------------- | ----------- | ----------- |
-| aria-invalid   | `boolean`                         | —           |             |
-| className      | `string`                          | —           |             |
-| prefix         | `React.ReactNode`                 | —           |             |
-| suffix         | `React.ReactNode`                 | —           |             |
-| inputClassName | `string`                          | —           |             |
-| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |             |
+| Prop           | Type                              | Default     | Description                                                                                                                                          |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| aria-invalid   | `boolean`                         | —           |                                                                                                                                                      |
+| className      | `string`                          | —           |                                                                                                                                                      |
+| prefix         | `React.ReactNode`                 | —           | Shown before the text. A decorative icon here needs `aria-hidden`; screen readers otherwise stop on it as a separate element and read out its glyph. |
+| suffix         | `React.ReactNode`                 | —           | Shown after the text: a unit, or a control such as a clear button.                                                                                   |
+| inputClassName | `string`                          | —           |                                                                                                                                                      |
+| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |                                                                                                                                                      |
 
 Also accepts the props of `TextInputProps`.
 
@@ -516,6 +526,10 @@ selected values stay on one line and truncate without displacing the trigger che
 For popover presentation on web, the options panel matches the trigger width, caps
 itself to the collision-available viewport, and wraps long option labels inside it.
 
+Opening a Select, or a Popover, closes the on-screen keyboard first, so options opened
+from a form are never hidden behind it. Both draw in a portal, where the platform would
+otherwise leave the keyboard up; the Modal-hosted overlays close it on their own.
+
 `SelectContent` supports optional frosted props:
 
 
@@ -578,17 +592,20 @@ import {
 </SegmentedControl>;
 ```
 
+When the labels do not fit a phone, `wrap="scroll"` keeps them on one row at full width
+and scrolls sideways, instead of wrapping or truncating them.
 
-| Prop          | Type                      | Default     | Description                |
-| ------------- | ------------------------- | ----------- | -------------------------- |
-| value         | `string`                  | —           |                            |
-| defaultValue  | `string`                  | `''`        |                            |
-| onValueChange | `(value: string) => void` | —           |                            |
-| variant       | `'default' \| 'pill'`     | `'default'` | Pill = rounded-full items. |
-| wrap          | `boolean \| 'auto'`       | `true`      |                            |
-| size          | `'default' \| 'compact'`  | `'default'` |                            |
-| disabled      | `boolean`                 | `false`     |                            |
-| className     | `string`                  | —           |                            |
+
+| Prop          | Type                            | Default     | Description                                                                                                                                                                                                                                                                |
+| ------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value         | `string`                        | —           |                                                                                                                                                                                                                                                                            |
+| defaultValue  | `string`                        | `''`        |                                                                                                                                                                                                                                                                            |
+| onValueChange | `(value: string) => void`       | —           |                                                                                                                                                                                                                                                                            |
+| variant       | `'default' \| 'pill'`           | `'default'` | Pill = rounded-full items.                                                                                                                                                                                                                                                 |
+| wrap          | `boolean \| 'auto' \| 'scroll'` | `'auto'`    | `true` wraps segments onto more rows; `false` keeps one row and shares its width. `'scroll'` keeps one row with each segment as wide as its label and scrolls sideways when they do not fit — for labels a phone cannot show in full. `'auto'` wraps above three segments. |
+| size          | `'default' \| 'compact'`        | `'default'` |                                                                                                                                                                                                                                                                            |
+| disabled      | `boolean`                       | `false`     |                                                                                                                                                                                                                                                                            |
+| className     | `string`                        | —           |                                                                                                                                                                                                                                                                            |
 
 Also accepts the props of `ViewProps`.
 
@@ -744,6 +761,10 @@ const icons = useIconColors();
 `FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never
 needs `hitSlop`.
 
+A floating FAB covers whatever scrolls under it, so a list behind one ends with room for
+it: `contentContainerStyle={{ paddingBottom: fabClearance() }}`, passing the FAB's `size`
+when it is not the default.
+
 ---
 
 - **Alert** (Display) — AlertTitle & AlertDescription

package/dist/agent/llms-full.txt

@@ -477,6 +477,10 @@ const icons = useIconColors();
 `FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never
 needs `hitSlop`.
 
+A floating FAB covers whatever scrolls under it, so a list behind one ends with room for
+it: `contentContainerStyle={{ paddingBottom: fabClearance() }}`, passing the FAB's `size`
+when it is not the default.
+
 ## Layout Primitives (Stack, Row)
 
 Use `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.
@@ -624,9 +628,24 @@ reported, never changed, because a brand colour is a brand decision. The built-i
 `WHILEUI_PRESET_SOFT` and `WHILEUI_PRESET_ATELIER`, go through `themePresetToCss` the same
 way.
 
-Switch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`). A named
-extra theme is registered with `extraThemes: ['name']` in `metro.config.js` and defined
-with `@variant name`. The full token list, with each default, is in `theme-contract.ts`,
+Switch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`), or let
+`useThemeBridge` hold the choice. It returns the chosen `mode`, the `resolvedTheme` on
+screen, `setMode`, `toggleTheme` and `cycleMode`. A sun/moon button calls `toggleTheme`,
+which always flips what is on screen; `cycleMode` steps light → dark → system and suits
+a control that shows all three, because a step into `system` that resolves to the
+current theme looks like a dead tap. Pass an `adapter` to keep the choice across launches:
+
+```tsx
+const { resolvedTheme, toggleTheme } = useThemeBridge({
+  adapter: {
+    loadThemeMode: () => storage.getItem('theme') as ThemeMode | null,
+    saveThemeMode: (mode) => storage.setItem('theme', mode),
+  },
+});
+```
+
+A named extra theme is registered with `extraThemes: ['name']` in `metro.config.js` and
+defined with `@variant name`. The full token list, with each default, is in `theme-contract.ts`,
 and agents can read it from the MCP server's `get_theme_tokens`.
 
 ### Frosted surfaces
@@ -806,23 +825,33 @@ Also accepts the props of React Native's `TextProps`.
 ## Input
 
 ```tsx
-import { Input } from '@thewhileloop/whileui';
+import { Input, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
 
 <Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
+
+<Input
+  placeholder="Search"
+  prefix={<Feather name="search" size={16} color={icons.muted} aria-hidden />}
+/>;
 ```
 
-On web, filled Input, Textarea, NumericInput, and SmartInput surfaces preserve their
-themed background, foreground, and caret when the browser autofills them.
+On iOS and Android, Input, Textarea, NumericInput and SmartInput draw the caret and
+selection in the theme's primary colour; pass `selectionColor` (and `cursorColor` on
+Android) to override it. On web, filled surfaces keep their themed background,
+foreground and caret when the browser autofills them.
 
 
-| Prop           | Type                              | Default     | Description |
-| -------------- | --------------------------------- | ----------- | ----------- |
-| aria-invalid   | `boolean`                         | —           |             |
-| className      | `string`                          | —           |             |
-| prefix         | `React.ReactNode`                 | —           |             |
-| suffix         | `React.ReactNode`                 | —           |             |
-| inputClassName | `string`                          | —           |             |
-| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |             |
+| Prop           | Type                              | Default     | Description                                                                                                                                          |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| aria-invalid   | `boolean`                         | —           |                                                                                                                                                      |
+| className      | `string`                          | —           |                                                                                                                                                      |
+| prefix         | `React.ReactNode`                 | —           | Shown before the text. A decorative icon here needs `aria-hidden`; screen readers otherwise stop on it as a separate element and read out its glyph. |
+| suffix         | `React.ReactNode`                 | —           | Shown after the text: a unit, or a control such as a clear button.                                                                                   |
+| inputClassName | `string`                          | —           |                                                                                                                                                      |
+| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |                                                                                                                                                      |
 
 Also accepts the props of `TextInputProps`.
 
@@ -989,17 +1018,20 @@ import {
 </SegmentedControl>;
 ```
 
+When the labels do not fit a phone, `wrap="scroll"` keeps them on one row at full width
+and scrolls sideways, instead of wrapping or truncating them.
+
 
-| Prop          | Type                      | Default     | Description                |
-| ------------- | ------------------------- | ----------- | -------------------------- |
-| value         | `string`                  | —           |                            |
-| defaultValue  | `string`                  | `''`        |                            |
-| onValueChange | `(value: string) => void` | —           |                            |
-| variant       | `'default' \| 'pill'`     | `'default'` | Pill = rounded-full items. |
-| wrap          | `boolean \| 'auto'`       | `true`      |                            |
-| size          | `'default' \| 'compact'`  | `'default'` |                            |
-| disabled      | `boolean`                 | `false`     |                            |
-| className     | `string`                  | —           |                            |
+| Prop          | Type                            | Default     | Description                                                                                                                                                                                                                                                                |
+| ------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value         | `string`                        | —           |                                                                                                                                                                                                                                                                            |
+| defaultValue  | `string`                        | `''`        |                                                                                                                                                                                                                                                                            |
+| onValueChange | `(value: string) => void`       | —           |                                                                                                                                                                                                                                                                            |
+| variant       | `'default' \| 'pill'`           | `'default'` | Pill = rounded-full items.                                                                                                                                                                                                                                                 |
+| wrap          | `boolean \| 'auto' \| 'scroll'` | `'auto'`    | `true` wraps segments onto more rows; `false` keeps one row and shares its width. `'scroll'` keeps one row with each segment as wide as its label and scrolls sideways when they do not fit — for labels a phone cannot show in full. `'auto'` wraps above three segments. |
+| size          | `'default' \| 'compact'`        | `'default'` |                                                                                                                                                                                                                                                                            |
+| disabled      | `boolean`                       | `false`     |                                                                                                                                                                                                                                                                            |
+| className     | `string`                        | —           |                                                                                                                                                                                                                                                                            |
 
 Also accepts the props of `ViewProps`.
 
@@ -1299,6 +1331,10 @@ selected values stay on one line and truncate without displacing the trigger che
 For popover presentation on web, the options panel matches the trigger width, caps
 itself to the collision-available viewport, and wraps long option labels inside it.
 
+Opening a Select, or a Popover, closes the on-screen keyboard first, so options opened
+from a form are never hidden behind it. Both draw in a portal, where the platform would
+otherwise leave the keyboard up; the Modal-hosted overlays close it on their own.
+
 `SelectContent` supports optional frosted props:
 
 

package/dist/agent/llms.txt

@@ -1,4 +1,4 @@
-# WhileUI 4.3.0
+# WhileUI 4.4.0
 
 > React Native components and blocks for iOS, Android and web, styled with Uniwind and
 > themed through a typed token contract. Package: `@thewhileloop/whileui`.

package/dist/blocks/layout/smart-input.js

@@ -8,7 +8,7 @@ import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
 import { webAutofillField } from '../../lib/web-autofill';
-import { controlRecipe, shadowStyle, surfaceRadius, typographyStyle } from '../../lib/recipes';
+import { controlRecipe, shadowStyle, surfaceRadius, textCursorColors, typographyStyle, } from '../../lib/recipes';
 // The examples list is joined into one string so it can be an effect dependency without
 // re-running on every render. A NUL byte cannot appear in a placeholder.
 const SEPARATOR = '\0';
@@ -144,5 +144,5 @@ export const SmartInput = forwardRef(function SmartInput({ leftSlot, centerSlot,
                     { maxHeight: visual.smartInputMaxHeight },
                     !editable ? { opacity: interaction.disabledOpacity } : null,
                     style,
-                ], className: cn('flex-1 text-foreground placeholder:text-muted-foreground', focusRing, variant === 'bar' && 'border-border bg-muted', variant === 'bar' && webAutofillField, variant === 'card' && 'bg-transparent', inputClassName), multiline: true, submitBehavior: submitBehavior, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, placeholder: placeholderState.placeholder, value: value, defaultValue: defaultValue, onChangeText: placeholderState.onChangeText, editable: editable, ...props }), _jsx(SmartInputSlot, { children: rightSlot })] }));
+                ], className: cn('flex-1 text-foreground placeholder:text-muted-foreground', focusRing, variant === 'bar' && 'border-border bg-muted', variant === 'bar' && webAutofillField, variant === 'card' && 'bg-transparent', inputClassName), multiline: true, submitBehavior: submitBehavior, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...textCursorColors(colors), placeholder: placeholderState.placeholder, value: value, defaultValue: defaultValue, onChangeText: placeholderState.onChangeText, editable: editable, ...props }), _jsx(SmartInputSlot, { children: rightSlot })] }));
 });

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

@@ -61,6 +61,18 @@ declare const fabVariants: import("tailwind-variants").TVReturnType<{
         'floating-left': "absolute bottom-6 left-6";
     };
 }, undefined>>;
+/** The `size` classes in points, and the `floating` placement's `bottom-6` inset. */
+declare const FAB_SIZE: {
+    readonly default: 56;
+    readonly sm: 48;
+    readonly lg: 64;
+};
+/**
+ * Bottom padding that keeps a floating FAB off the last row of a scrolling screen: its
+ * inset from the edge, its height and a gap. Nothing stops the FAB covering content, so a
+ * list under one ends with `contentContainerStyle={{ paddingBottom: fabClearance() }}`.
+ */
+export declare function fabClearance(size?: keyof typeof FAB_SIZE): number;
 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

package/dist/components/fab/fab.js

@@ -17,8 +17,8 @@ const fabVariants = tv({
             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.
+            // 56, 48 and 64pt, as FAB_SIZE below. 56 is Material's FAB size; all three 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',
@@ -37,6 +37,18 @@ const fabVariants = tv({
         placement: 'floating',
     },
 });
+/** The `size` classes in points, and the `floating` placement's `bottom-6` inset. */
+const FAB_SIZE = { default: 56, sm: 48, lg: 64 };
+const FAB_EDGE_INSET = 24;
+const FAB_CONTENT_GAP = 16;
+/**
+ * Bottom padding that keeps a floating FAB off the last row of a scrolling screen: its
+ * inset from the edge, its height and a gap. Nothing stops the FAB covering content, so a
+ * list under one ends with `contentContainerStyle={{ paddingBottom: fabClearance() }}`.
+ */
+export function fabClearance(size = 'default') {
+    return FAB_EDGE_INSET + FAB_SIZE[size] + FAB_CONTENT_GAP;
+}
 /**
  * A floating action button: one primary action, raised above the content.
  *

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

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

package/dist/components/fab/index.js

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

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

@@ -27,7 +27,12 @@ declare const inputVariants: import("tailwind-variants").TVReturnType<{
 export interface InputProps extends TextInputProps, VariantProps<typeof inputVariants> {
     'aria-invalid'?: boolean;
     className?: string;
+    /**
+     * Shown before the text. A decorative icon here needs `aria-hidden`; screen readers
+     * otherwise stop on it as a separate element and read out its glyph.
+     */
     prefix?: React.ReactNode;
+    /** Shown after the text: a unit, or a control such as a clear button. */
     suffix?: React.ReactNode;
     inputClassName?: string;
 }

package/dist/components/input/input.js

@@ -7,7 +7,7 @@ import { tv } from '../../lib/tv';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
-import { typographyStyle } from '../../lib/recipes';
+import { textCursorColors, typographyStyle } from '../../lib/recipes';
 import { webAutofillField } from '../../lib/web-autofill';
 import { fieldAccessibilityProps, useFormFieldState } from '../form-field/form-field';
 const inputVariants = tv({
@@ -47,7 +47,7 @@ const Input = React.forwardRef(({ className, prefix, suffix, inputClassName, var
                     ...typographyStyle(visual, 'label'),
                     minHeight: visual.controlHeightDefault - 2,
                     paddingVertical: visual.controlPaddingYDefault,
-                }, editable: effectiveEditable, "aria-invalid": ariaInvalid ?? field.invalid, placeholderTextColor: placeholderTextColor ?? colors.placeholder, onFocus: (event) => {
+                }, editable: effectiveEditable, "aria-invalid": ariaInvalid ?? field.invalid, placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...textCursorColors(colors), onFocus: (event) => {
                     setFocused(true);
                     onFocus?.(event);
                 }, onBlur: (event) => {

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

@@ -7,7 +7,7 @@ import { tv } from '../../lib/tv';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens, withInteractivePressableStyle } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
-import { typographyStyle } from '../../lib/recipes';
+import { textCursorColors, typographyStyle } from '../../lib/recipes';
 import { webAutofillField } from '../../lib/web-autofill';
 import { fieldAccessibilityProps, useFormFieldState } from '../form-field/form-field';
 const numericInputVariants = tv({
@@ -177,7 +177,7 @@ const NumericInput = React.forwardRef(({ className, inputClassName, prefix, suff
                     }, onBlur: (event) => {
                         setFocused(false);
                         model.handleBlur(event);
-                    }, keyboardType: "decimal-pad", editable: effectiveEditable, "aria-invalid": ariaInvalid ?? field.invalid, 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 })] }));
+                    }, keyboardType: "decimal-pad", editable: effectiveEditable, "aria-invalid": ariaInvalid ?? field.invalid, placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...textCursorColors(colors), ...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/popover/popover.js

@@ -1,8 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
 import { Platform, StyleSheet } from 'react-native';
+import { useComposedRefs } from '@rn-primitives/hooks';
 import * as PopoverPrimitive from '@rn-primitives/popover';
 import { cn } from '../../lib/cn';
+import { useDismissKeyboardOnOpen } from '../../lib/dismiss-keyboard-on-open';
 import { useFrostedSurface } from '../../lib/frosted-surface';
 import { useNestedOverlay, useOverlayPortalTarget } from '../../lib/overlay-host';
 import { useOverlayInsets } from '../../lib/overlay-insets';
@@ -12,7 +14,13 @@ import { shadowStyle, surfacePadding, surfaceRadius } from '../../lib/recipes';
 function Popover({ onOpenChange, children }) {
     return _jsx(PopoverPrimitive.Root, { onOpenChange: onOpenChange, children: children });
 }
-const PopoverTrigger = React.forwardRef(({ className, ...props }, ref) => (_jsx(PopoverPrimitive.Trigger, { ref: ref, className: cn(className), ...props })));
+const PopoverTrigger = React.forwardRef(({ className, ...props }, ref) => {
+    const { open, setTriggerPosition } = PopoverPrimitive.useRootContext();
+    const triggerRef = React.useRef(null);
+    const composedRef = useComposedRefs(triggerRef, ref);
+    useDismissKeyboardOnOpen(open, triggerRef, setTriggerPosition);
+    return _jsx(PopoverPrimitive.Trigger, { ref: composedRef, className: cn(className), ...props });
+});
 PopoverTrigger.displayName = 'PopoverTrigger';
 const PopoverContent = React.forwardRef(({ className, align = 'center', sideOffset = 4, insets, portalHost, children, style, frosted = false, blurIntensity, blurTintToken, ...props }, ref) => {
     const frostedSurface = useFrostedSurface({

package/dist/components/segmented-control/segmented-control.d.ts

@@ -9,6 +9,11 @@ declare const segmentedControlVariants: import("tailwind-variants").TVReturnType
         true: "flex-wrap justify-center gap-1";
         false: "flex-nowrap gap-1";
     };
+    /** Sized to its segments inside a horizontal scroll view. */
+    scroll: {
+        true: "w-auto";
+        false: "";
+    };
     size: {
         default: "";
         compact: "";
@@ -22,6 +27,11 @@ declare const segmentedControlVariants: import("tailwind-variants").TVReturnType
         true: "flex-wrap justify-center gap-1";
         false: "flex-nowrap gap-1";
     };
+    /** Sized to its segments inside a horizontal scroll view. */
+    scroll: {
+        true: "w-auto";
+        false: "";
+    };
     size: {
         default: "";
         compact: "";
@@ -35,6 +45,11 @@ declare const segmentedControlVariants: import("tailwind-variants").TVReturnType
         true: "flex-wrap justify-center gap-1";
         false: "flex-nowrap gap-1";
     };
+    /** Sized to its segments inside a horizontal scroll view. */
+    scroll: {
+        true: "w-auto";
+        false: "";
+    };
     size: {
         default: "";
         compact: "";
@@ -61,6 +76,11 @@ declare const segmentedControlItemVariants: import("tailwind-variants").TVReturn
         true: "grow-0";
         false: "flex-1";
     };
+    /** As wide as its label, so segments overflow into the scroll view rather than shrink. */
+    scroll: {
+        true: "flex-none";
+        false: "";
+    };
 }, undefined, "min-w-0 flex-row items-center justify-center", {
     variant: {
         default: "";
@@ -82,6 +102,11 @@ declare const segmentedControlItemVariants: import("tailwind-variants").TVReturn
         true: "grow-0";
         false: "flex-1";
     };
+    /** As wide as its label, so segments overflow into the scroll view rather than shrink. */
+    scroll: {
+        true: "flex-none";
+        false: "";
+    };
 }, undefined, import("tailwind-variants").TVReturnTypeLike<{
     variant: {
         default: "";
@@ -103,6 +128,11 @@ declare const segmentedControlItemVariants: import("tailwind-variants").TVReturn
         true: "grow-0";
         false: "flex-1";
     };
+    /** As wide as its label, so segments overflow into the scroll view rather than shrink. */
+    scroll: {
+        true: "flex-none";
+        false: "";
+    };
 }, undefined>>;
 declare const segmentedControlItemTextVariants: import("tailwind-variants").TVReturnType<{
     selected: {
@@ -138,7 +168,14 @@ export interface SegmentedControlProps extends ViewProps {
     onValueChange?: (value: string) => void;
     /** Pill = rounded-full items. */
     variant?: 'default' | 'pill';
-    wrap?: boolean | 'auto';
+    /**
+     * `true` wraps segments onto more rows; `false` keeps one row and shares its width.
+     * `'scroll'` keeps one row with each segment as wide as its label and scrolls
+     * sideways when they do not fit — for labels a phone cannot show in full.
+     * `'auto'` wraps above three segments.
+     * @default 'auto'
+     */
+    wrap?: boolean | 'auto' | 'scroll';
     size?: 'default' | 'compact';
     disabled?: boolean;
     className?: string;

package/dist/components/segmented-control/segmented-control.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
-import { Pressable, Text, View, } from 'react-native';
+import { Pressable, ScrollView, Text, View, } from 'react-native';
 import { cn } from '../../lib/cn';
 import { focusRingInset } from '../../lib/focus-ring';
 import { tv } from '../../lib/tv';
@@ -19,6 +19,11 @@ const segmentedControlVariants = tv({
             true: 'flex-wrap justify-center gap-1',
             false: 'flex-nowrap gap-1',
         },
+        /** Sized to its segments inside a horizontal scroll view. */
+        scroll: {
+            true: 'w-auto',
+            false: '',
+        },
         size: {
             default: '',
             compact: '',
@@ -27,6 +32,7 @@ const segmentedControlVariants = tv({
     defaultVariants: {
         variant: 'default',
         wrap: true,
+        scroll: false,
         size: 'default',
     },
 });
@@ -53,6 +59,11 @@ const segmentedControlItemVariants = tv({
             true: 'grow-0',
             false: 'flex-1',
         },
+        /** As wide as its label, so segments overflow into the scroll view rather than shrink. */
+        scroll: {
+            true: 'flex-none',
+            false: '',
+        },
     },
     defaultVariants: {
         variant: 'default',
@@ -60,6 +71,7 @@ const segmentedControlItemVariants = tv({
         size: 'default',
         disabled: false,
         wrap: true,
+        scroll: false,
     },
 });
 const segmentedControlItemTextVariants = tv({
@@ -105,6 +117,7 @@ const SegmentedControlContext = createContext({
     variant: 'default',
     size: 'default',
     wrap: true,
+    scroll: false,
     disabled: false,
 });
 const SegmentedControlItemContext = createContext({
@@ -117,7 +130,8 @@ function SegmentedControl({ value: controlledValue, defaultValue = '', onValueCh
     const [internalValue, setInternalValue] = useState(defaultValue);
     const value = controlledValue ?? internalValue;
     const itemCount = useMemo(() => React.Children.toArray(children).filter((child) => React.isValidElement(child)).length, [children]);
-    const shouldWrap = wrap === 'auto' ? itemCount > 3 : wrap;
+    const scroll = wrap === 'scroll';
+    const shouldWrap = wrap === 'auto' ? itemCount > 3 : wrap === true;
     const handleValueChange = useCallback((nextValue) => {
         if (disabled || value === nextValue) {
             return;
@@ -125,11 +139,20 @@ function SegmentedControl({ value: controlledValue, defaultValue = '', onValueCh
         setInternalValue(nextValue);
         onValueChange?.(nextValue);
     }, [disabled, onValueChange, value]);
-    const contextValue = useMemo(() => ({ value, onValueChange: handleValueChange, variant, size, wrap: shouldWrap, disabled }), [disabled, handleValueChange, shouldWrap, size, value, variant]);
-    return (_jsx(SegmentedControlContext.Provider, { value: contextValue, children: _jsx(View, { className: cn(segmentedControlVariants({ variant, wrap: shouldWrap, size }), className), style: [getSegmentedContainerStyle(visual, colors, variant), styleProp], accessibilityRole: "radiogroup", ...props, children: children }) }));
+    const contextValue = useMemo(() => ({
+        value,
+        onValueChange: handleValueChange,
+        variant,
+        size,
+        wrap: shouldWrap,
+        scroll,
+        disabled,
+    }), [disabled, handleValueChange, scroll, shouldWrap, size, value, variant]);
+    const group = (_jsx(View, { className: cn(segmentedControlVariants({ variant, wrap: shouldWrap, scroll, size }), className), style: [getSegmentedContainerStyle(visual, colors, variant), styleProp], accessibilityRole: "radiogroup", ...props, children: children }));
+    return (_jsx(SegmentedControlContext.Provider, { value: contextValue, children: scroll ? (_jsx(ScrollView, { horizontal: true, showsHorizontalScrollIndicator: false, children: group })) : (group) }));
 }
 function SegmentedControlItem({ value: itemValue, className, children, disabled: itemDisabled, style: styleProp, ...props }) {
-    const { value, onValueChange, variant, size, wrap, disabled } = useContext(SegmentedControlContext);
+    const { value, onValueChange, variant, size, wrap, scroll, disabled } = useContext(SegmentedControlContext);
     const selected = value === itemValue;
     const finalDisabled = disabled || Boolean(itemDisabled);
     const interaction = useInteractionTokens();
@@ -150,6 +173,7 @@ function SegmentedControlItem({ value: itemValue, className, children, disabled:
                 size,
                 disabled: finalDisabled,
                 wrap,
+                scroll,
             }), focusRingInset, className), onPress: () => onValueChange(itemValue), accessibilityRole: "radio", 
             // A radio is checked, not selected. `selected` maps to `aria-selected`, which is
             // not a valid attribute on `role="radio"` — assistive technology could not tell

package/dist/components/select/select.js

@@ -1,10 +1,12 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
 import { Platform, ScrollView, StyleSheet, useWindowDimensions, View, } from 'react-native';
+import { useComposedRefs } from '@rn-primitives/hooks';
 import * as SelectPrimitive from '@rn-primitives/select';
 import { FullWindowOverlay as RNFullWindowOverlay } from 'react-native-screens';
 import { Text } from '../text';
 import { cn } from '../../lib/cn';
+import { useDismissKeyboardOnOpen } from '../../lib/dismiss-keyboard-on-open';
 import { focusRing } from '../../lib/focus-ring';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
 import { useFrostedSurface } from '../../lib/frosted-surface';
@@ -26,7 +28,11 @@ const SelectTrigger = React.forwardRef(({ className, children, style: styleProp,
     const visual = useVisualTokens();
     const field = useFormFieldState();
     const effectiveDisabled = disabled ?? field.disabled;
-    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', field.invalid && 'border-destructive', focusRing, effectiveDisabled && '', className), 
+    const { open, setTriggerPosition } = SelectPrimitive.useRootContext();
+    const triggerRef = React.useRef(null);
+    const composedRef = useComposedRefs(triggerRef, ref);
+    useDismissKeyboardOnOpen(open, triggerRef, setTriggerPosition);
+    return (_jsxs(SelectPrimitive.Trigger, { ref: composedRef, className: cn('border-border bg-muted flex w-full flex-row items-center justify-between gap-2 shadow-sm active:bg-state-pressed', field.invalid && 'border-destructive', focusRing, effectiveDisabled && '', className), 
         // 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

@@ -7,7 +7,7 @@ import { tv } from '../../lib/tv';
 import { useThemeColors } from '../../lib/theme-colors';
 import { useInteractionTokens } from '../../lib/interaction-tokens';
 import { useVisualTokens } from '../../lib/visual-tokens';
-import { typographyStyle } from '../../lib/recipes';
+import { textCursorColors, typographyStyle } from '../../lib/recipes';
 import { webAutofillField } from '../../lib/web-autofill';
 import { fieldAccessibilityProps, useFormFieldState } from '../form-field/form-field';
 const textareaVariants = tv({
@@ -48,7 +48,7 @@ const Textarea = React.forwardRef(({ className, size = 'default', placeholderTex
         paddingVertical: visual.controlPaddingYDefault,
         ...(!effectiveEditable ? { opacity: interaction.disabledOpacity } : null),
     };
-    return (_jsx(TextInput, { ref: ref, ...fieldAccessibilityProps(field, props), className: cn(textareaVariants({ size }), field.invalid && 'border-destructive', focusField, webAutofillField, className), style: style, multiline: true, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, editable: effectiveEditable, "aria-invalid": ariaInvalid ?? field.invalid, ...props }));
+    return (_jsx(TextInput, { ref: ref, ...fieldAccessibilityProps(field, props), className: cn(textareaVariants({ size }), field.invalid && 'border-destructive', focusField, webAutofillField, className), style: style, multiline: true, textAlignVertical: "top", placeholderTextColor: placeholderTextColor ?? colors.placeholder, ...textCursorColors(colors), editable: effectiveEditable, "aria-invalid": ariaInvalid ?? field.invalid, ...props }));
 });
 Textarea.displayName = 'Textarea';
 export { Textarea, textareaVariants };

package/dist/index.d.ts

@@ -30,7 +30,7 @@ export { OTPInput, otpCellVariants, type OTPInputProps } from './components/otp-
 export { FormField, FormLabel, FormControl, FormHint, FormMessage, useFormFieldState, formFieldVariants, formControlVariants, type FormFieldProps, type FormLabelProps, type FormControlProps, type FormHintProps, type FormMessageProps, type FormFieldState, } 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 { FAB, FABGroup, fabClearance, 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

@@ -30,7 +30,7 @@ export { OTPInput, otpCellVariants } from './components/otp-input';
 export { FormField, FormLabel, FormControl, FormHint, FormMessage, useFormFieldState, 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 { FAB, FABGroup, fabClearance, 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/dismiss-keyboard-on-open.d.ts

@@ -0,0 +1,16 @@
+import { type RefObject } from 'react';
+import type { LayoutPosition } from '@rn-primitives/hooks';
+interface Measurable {
+    measure: (callback: (x: number, y: number, width: number, height: number, pageX: number, pageY: number) => void) => void;
+}
+/**
+ * Closes the keyboard when a portal overlay opens, then measures its trigger again.
+ *
+ * `Select` and `Popover` draw in a portal rather than a Modal, so iOS and Android leave the
+ * keyboard up and it covers the lower half of the content. Closing it moves any
+ * keyboard-avoiding screen, which leaves the trigger away from where it was measured on
+ * press, so the position is taken again once the keyboard has gone. Modal-hosted overlays
+ * need none of this: the platform closes the keyboard when the Modal's window takes focus.
+ */
+export declare function useDismissKeyboardOnOpen(open: boolean, triggerRef: RefObject<Measurable | null>, setTriggerPosition: (position: LayoutPosition) => void): void;
+export {};

package/dist/lib/dismiss-keyboard-on-open.js

@@ -0,0 +1,22 @@
+import { useEffect } from 'react';
+import { Keyboard, Platform } from 'react-native';
+/**
+ * Closes the keyboard when a portal overlay opens, then measures its trigger again.
+ *
+ * `Select` and `Popover` draw in a portal rather than a Modal, so iOS and Android leave the
+ * keyboard up and it covers the lower half of the content. Closing it moves any
+ * keyboard-avoiding screen, which leaves the trigger away from where it was measured on
+ * press, so the position is taken again once the keyboard has gone. Modal-hosted overlays
+ * need none of this: the platform closes the keyboard when the Modal's window takes focus.
+ */
+export function useDismissKeyboardOnOpen(open, triggerRef, setTriggerPosition) {
+    useEffect(() => {
+        if (!open || Platform.OS === 'web' || !Keyboard.isVisible())
+            return;
+        const subscription = Keyboard.addListener('keyboardDidHide', () => {
+            triggerRef.current?.measure((_x, _y, width, height, pageX, pageY) => setTriggerPosition({ width, height, pageX, pageY }));
+        });
+        Keyboard.dismiss();
+        return () => subscription.remove();
+    }, [open, triggerRef, setTriggerPosition]);
+}

package/dist/lib/recipes.d.ts

@@ -22,6 +22,26 @@ export declare function surfacePadding(visual: VisualTokens, padding?: SurfacePa
 export declare function surfaceRadius(visual: VisualTokens, radius?: 'sm' | 'md' | 'lg' | 'xl'): number;
 export declare function surfaceRecipe(visual: VisualTokens, options?: SurfaceRecipeOptions): ViewStyle;
 export declare function shadowStyle(visual: VisualTokens, colors: ThemeColors, tier: ShadowTier): ViewStyle;
+/**
+ * Caret and selection colours for a text field: the theme's primary, where React Native
+ * would otherwise use the platform blue. iOS tints the caret, handles and highlight from
+ * `selectionColor` alone. Android paints `selectionColor` as the highlight at full
+ * strength, which would hide the selected text, so it gets a translucent highlight and
+ * the caret and handles take the solid colour. The web keeps the browser's caret.
+ */
+export declare function textCursorColors(colors: ThemeColors): {
+    cursorColor: string;
+    selectionHandleColor: string;
+    selectionColor: string;
+} | {
+    selectionColor: string;
+    cursorColor?: undefined;
+    selectionHandleColor?: undefined;
+} | {
+    cursorColor?: undefined;
+    selectionHandleColor?: undefined;
+    selectionColor?: undefined;
+};
 export declare function typographyStyle(visual: VisualTokens, role: TypographyRole): TextStyle;
 export declare function useControlRecipe(size?: ControlSize): ViewStyle;
 export declare function useFieldRecipe(size?: ControlSize): ViewStyle;

package/dist/lib/recipes.js

@@ -108,17 +108,34 @@ export function shadowStyle(visual, colors, tier) {
                 offsetX: 0,
                 offsetY,
                 blurRadius: radius * 2,
-                color: shadowColorWithOpacity(colors.shadow, opacity),
+                color: colorWithOpacity(colors.shadow, opacity),
             },
         ],
     };
 }
-function shadowColorWithOpacity(color, opacity) {
+function colorWithOpacity(color, opacity) {
     const parsed = parse(color);
     if (!parsed)
         return color;
     return formatRgb({ ...parsed, alpha: opacity });
 }
+/**
+ * Caret and selection colours for a text field: the theme's primary, where React Native
+ * would otherwise use the platform blue. iOS tints the caret, handles and highlight from
+ * `selectionColor` alone. Android paints `selectionColor` as the highlight at full
+ * strength, which would hide the selected text, so it gets a translucent highlight and
+ * the caret and handles take the solid colour. The web keeps the browser's caret.
+ */
+export function textCursorColors(colors) {
+    if (Platform.OS === 'android') {
+        return {
+            cursorColor: colors.primary,
+            selectionHandleColor: colors.primary,
+            selectionColor: colorWithOpacity(colors.primary, 0.3),
+        };
+    }
+    return Platform.OS === 'ios' ? { selectionColor: colors.primary } : {};
+}
 // Component-owned text sizes. Font family/weight stays on className
 // (font-medium etc.) so app font mappings keep working.
 export function typographyStyle(visual, role) {

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

@@ -14,10 +14,19 @@ export interface UseThemeBridgeOptions {
     adapter?: ThemeBridgeAdapter;
 }
 export interface UseThemeBridgeResult {
+    /** The chosen mode, `system` included. */
     mode: ThemeMode;
+    /** The theme on screen: `light`, `dark`, or a registered custom theme. */
     resolvedTheme: string;
     setMode: (mode: ThemeMode) => void;
+    /**
+     * Steps light → dark → system. For a control that shows all three modes; a two-state
+     * sun/moon button wants `toggleTheme`, because a step into `system` that resolves to
+     * the theme already on screen looks like a tap that did nothing.
+     */
     cycleMode: () => void;
+    /** Switches to the opposite of the theme on screen: dark from light, light from anything else. */
+    toggleTheme: () => void;
 }
 export declare function applyThemeMode(mode: ThemeMode): void;
 export declare function resolveThemeMode(adapter?: ThemeBridgeAdapter, fallback?: ThemeMode): Promise<ThemeMode>;

package/dist/lib/theme-bridge.js

@@ -101,12 +101,14 @@ export function useThemeBridge({ initialMode = 'system', adapter, } = {}) {
         dispatch({ type: 'select', mode });
     }, []);
     const cycleMode = useCallback(() => dispatch({ type: 'cycle' }), []);
+    const toggleTheme = useCallback(() => dispatch({ type: 'select', mode: theme === 'light' ? 'dark' : 'light' }), [theme]);
     return useMemo(() => ({
         mode: state.mode,
         resolvedTheme: theme,
         setMode,
         cycleMode,
-    }), [cycleMode, setMode, state.mode, theme]);
+        toggleTheme,
+    }), [cycleMode, setMode, state.mode, theme, toggleTheme]);
 }
 function ControlledThemeBridge({ mode, adapter, }) {
     useEffect(() => {

package/package.json

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