@oxy.so/bloom 3.6.0 → 4.0.0

package/docs/select.mdx

@@ -107,13 +107,13 @@ It used to take a render prop instead, which handed its child a `state` object w
 ```tsx
 <Select value={status} onValueChange={setStatus}>
   <SelectTrigger label="Purchase status">
-    <SelectValue leading={(item) => item && <Badge dot color={(item as Status).tone} />} />
+    <SelectValue leading={(item) => item && <Badge dot tone={(item as Status).tone} />} />
     <SelectIcon />
   </SelectTrigger>
   <SelectContent
     items={STATUSES}
     renderItem={(item) => (
-      <SelectItem value={item.value} label={item.label} leading={<Badge dot color={item.tone} />}>
+      <SelectItem value={item.value} label={item.label} leading={<Badge dot tone={item.tone} />}>
         <SelectItemText>{item.label}</SelectItemText>
       </SelectItem>
     )}

package/docs/settings-list.mdx

@@ -56,7 +56,7 @@ The group renders a rounded card on iOS-style platforms and on web. The first it
 <SettingsListItem
   icon={<MoonIcon />}
   title="Dark mode"
-  rightElement={<Switch value={darkMode} onValueChange={setDarkMode} />}
+  rightElement={<Switch checked={darkMode} onCheckedChange={setDarkMode} />}
 />
 ```
 
@@ -202,9 +202,9 @@ fill.
   title="Notifications"
   footer="Push notifications require an enabled device permission."
 >
-  <SettingsListItem title="Marketing emails" rightElement={<Switch value={mktg} onValueChange={setMktg} />} />
+  <SettingsListItem title="Marketing emails" rightElement={<Switch checked={mktg} onCheckedChange={setMktg} />} />
   <SettingsListDivider />
-  <SettingsListItem title="Product updates" rightElement={<Switch value={prod} onValueChange={setProd} />} />
+  <SettingsListItem title="Product updates" rightElement={<Switch checked={prod} onCheckedChange={setProd} />} />
 </SettingsListGroup>
 ```
 

package/docs/sidebar.mdx

@@ -104,7 +104,7 @@ The logo leads the header beside the collapse (or close) control; `account`, if
 />
 ```
 
-- With a `tree` the header and quick search stay put and only the rows scroll (hidden scrollbar): the primary rows, then 24 below them the tree — its label (body-medium text-secondary) and, 10 below, the folders 4 apart. The footer gains 12 on top.
+- The header, collapse control, mode switcher and quick search stay fixed; only destination rows scroll (hidden scrollbar). With a `tree`: the primary rows, then 24 below them the tree — its label (body-medium text-secondary) and, 10 below, the folders 4 apart. The footer gains 12 on top.
 - A folder row is p 8 with a 20px folder glyph (open while expanded) and the label; its rows are py 5 / pr 8 / pl 36 with the label and a `meta` chip (radius 4, background-tertiary, px 4 / py 1, caption-1-medium), background-secondary-hover while selected or hovered. A curved 1px icon-quaternary connector drops from the folder glyph into each row. The rows' height and opacity ease open and shut together over 300ms; collapsed rows leave the tab order.
 - Quick search filters the tree too: a folder whose label matches keeps every row, otherwise only its matching rows, held open while the query is set. "No results" counts the tree.
 - The tree hides while collapsed.
@@ -116,8 +116,8 @@ Two apps with the same rows should not look like the same app. That difference i
 
 ```tsx
 <Sidebar surface="card" />                    {/* default: the floating panel */}
-<Sidebar surface="plain" size="large" />      {/* a social reader's nav */}
-<Sidebar surface="docked" size="small" />     {/* a workspace column */}
+<Sidebar surface="plain" size="lg" />      {/* a social reader's nav */}
+<Sidebar surface="docked" size="sm" />     {/* a workspace column */}
 ```
 
 `surface` is the panel's EDGE:
@@ -134,9 +134,9 @@ The docked edge is not the card's border: that one is white in light mode, a hig
 
 | size     | square | glyph | label            | expanded | collapsed |
 | -------- | ------ | ----- | ---------------- | -------- | --------- |
-| `small`  | 30     | 18    | `body-2-medium`  | 232      | 46        |
-| `medium` | 36     | 20    | `body-medium`    | 260      | 52        |
-| `large`  | 44     | 24    | `title-3-medium` | 300      | 60        |
+| `sm`  | 30     | 18    | `body-2-medium`  | 232      | 46        |
+| `md` | 36     | 20    | `body-medium`    | 260      | 52        |
+| `lg`  | 44     | 24    | `title-3-medium` | 300      | 60        |
 
 The collapsed width is never an independent number: it is the square plus the panel's collapsed padding on both sides plus its two borders, so the icon column stays centred at every size. A row outside a sidebar takes `size` itself; inside one it inherits the panel's.
 
@@ -149,7 +149,7 @@ The collapsed width is never an independent number: it is the square plus the pa
 
 ## Collapse
 
-`collapsed` / `defaultCollapsed` / `onCollapsedChange`. The panel morphs between the size's two widths (260 → 52 at `medium`) in 300ms while labels, badges and the shortcut hint collapse (max-width, opacity, 3px blur on web) and the icons stay put. `mobile` is always expanded and shows a close button. `fluid` fills the container while expanded. Reduced motion snaps.
+`collapsed` / `defaultCollapsed` / `onCollapsedChange`. The panel morphs between the size's two widths (260 → 52 at `md`) in 300ms while labels, badges and the shortcut hint collapse (max-width, opacity, 3px blur on web) and the icons stay put. `mobile` is always expanded and shows a close button. `fluid` fills the container while expanded. Reduced motion snaps.
 
 After expanding, the account trigger's hover pill stays off until the pointer leaves it, so a stationary pointer does not light it up.
 
@@ -163,4 +163,32 @@ Both menus are `Popover`s: beside the rail (team bottom-aligned, account top-ali
 
 ## Colour
 
-Panel background-secondary with a card-coloured hairline and a three-layer sidebar shadow; rows and chips from the neutral ramp; the selected row from the accent ramp (500 → 600). Initials tints: `neutral`, `blue` (accent), `lime` (success), `pink` (the accent rotated to pink).
+Panel `backgroundSecondary` (`--surface`) with `borderLight` and the existing three-layer shadow. Rows use `backgroundTertiary`; selected navigation uses the paired `primary`/`primaryForeground` roles, and its badge uses `secondary`/`secondaryForeground`. Initials retain the public names `neutral`, `blue`, `lime`, and `pink`: their colours now come from neutral, primary, success, and tertiary semantic pairs respectively, rather than generated ramps or rotated hues.
+
+### Mode switcher in a collapsed panel
+
+Collapsed modes use the sidebar's icon-square size: 30/36/44px for `sm/md/lg`.
+The track adds 4px around those squares and stays centered, extending into the
+panel's horizontal inset. Its selected thumb remains square, the glyph stays
+centered, and hidden labels leave no gap. Expanded mode rows retain their 32px
+height.
+
+### Scroll overflow cues
+
+Each internal scroll region paints a 40px fade in its own surface color at an
+edge only when more content exists beyond it. The initial content and viewport
+measurements reveal the bottom cue before the first scroll. At the top there is
+no top fade; at the bottom there is no bottom fade. Content that fits has neither.
+Resizing or filtering updates these cues without changing content padding.
+The decorative overlays ignore pointer input and are excluded from accessibility.
+
+### Collapse motion
+
+Panel width and horizontal padding, navigation gaps, labels, mode-switcher
+geometry, header controls and footer surfaces follow the same 300ms collapse
+progress. Reversing the control continues from its current position. Reduced
+motion applies the target layout immediately. Mode selection has its own
+indicator timing; its position is calculated from the current animated row
+height so selection and collapse can happen together.
+
+The panel scroll viewport extends behind the bottom half of the last fixed header control (up to 20px). The top fade begins there, while compensating content padding preserves the initial row spacing. Fixed controls remain above the fade and available throughout scrolling.

package/docs/slider.mdx

@@ -44,13 +44,13 @@ import { Slider } from '@oxy.so/bloom/slider';
 The slider, in Bloom's colours.
 
 - **Track region** 32 tall, with 32 more reserved above it while `showTooltip` is on (the default — pass `showTooltip={false}` where the bubble would crowd a row).
-- **Rail** 6 tall, full pill, neutral-200 with an inset shade (dark: neutral-800); hovering the track darkens it a stop.
+- **Rail** 6 tall, full pill, the shared secondary surface with an inset shade; hovering uses the tertiary surface.
 - **Fill** an accent-500 → accent-600 left-to-right gradient with a white top highlight.
-- **Thumb** 20, white, 1px neutral-200 border, a soft drop plus inset highlight, holding an 8px accent dot. Hover darkens the border; dragging turns it accent with an accent-tinted shadow and brightens the dot. The thumb does not scale on press — no Bloom control scales on press.
+- **Thumb** 20, themed card fill, 1px semantic hairline, a soft drop plus inset highlight, holding an 8px accent dot. Hover darkens the border; dragging turns it accent with an accent-tinted shadow and brightens the dot. The thumb does not scale on press — no Bloom control scales on press.
 - **Bubble** 28 tall, min 32 wide, radius 8, `caption-1-medium` text, with an 8px arrow whose tip sits 4.5px below the bubble; it lifts 2px with a deeper shadow while dragging or focused. A press focuses the thumb, so the bubble stays lifted after the drag until focus moves on.
 - **Label** `body-medium`, 8px above the track.
 - **Cursor** (web) `grab` over a thumb, `grabbing` while dragging, `not-allowed` when disabled.
-- **Disabled** 50% opacity. Keyboard focus rings the thumb: a 2px accent ring outside a 2px white offset (`ring-offset-2`, white in both modes).
+- **Disabled** 50% opacity. Keyboard focus rings the thumb: a 2px accent ring outside a 2px page-coloured offset (`ring-offset-2`, scoped in both modes).
 
 ## The two callbacks are the whole API
 

package/docs/social-button.mdx

@@ -52,8 +52,8 @@ Apple, GitHub and X draw their marks in near-black, which vanishes on a dark sur
 
 | `size` | Height | Width | Padding | Glyph |
 | --- | --- | --- | --- | --- |
-| `medium` (default) | 36 | 300 | 12 | 18 |
-| `small` | 32 | 250 | 10 | 16 |
+| `md` (default) | 36 | 300 | 12 | 18 |
+| `sm` | 32 | 250 | 10 | 16 |
 
 The fixed width lines a column of providers up without a wrapper; `fullWidth` fills the container instead. `iconOnly` makes it square (a circle — every Bloom button-like control is a full pill). Label is `body-medium` and truncates.
 

package/docs/swipe-row.mdx

@@ -0,0 +1,130 @@
+---
+title: Swipe Row
+description: The one drag affordance behind a list row — the panes, the thresholds, who gets the gesture at all, and the second path the actions need.
+order: 64
+---
+
+# Swipe Row
+
+`SwipeRow` is the drag behind a row. It is the library's ONE implementation of
+that gesture: `chat-list` and `mail-list` both compose it, and a third family
+that wants actions behind a row composes it too rather than writing a fourth
+pan handler.
+
+```tsx
+import { SwipeRow, useSwipeAvailable } from '@oxy.so/bloom';
+
+<SwipeRow
+  actions={{
+    left: [{ key: 'archive', label: 'Archive', icon: RiArchiveLine, tone: 'accent' }],
+    right: [
+      { key: 'snooze', label: 'Snooze', icon: RiTimeLine },
+      { key: 'delete', label: 'Delete', icon: RiDeleteBinLine, tone: 'negative' },
+    ],
+  }}
+  onAction={(key) => run(key)}
+>
+  <MyRow />
+</SwipeRow>;
+```
+
+## The sides name the EDGE, not the finger
+
+`left` is uncovered by dragging RIGHT, because the pane is anchored to the left
+edge and grows from it. `right` is uncovered by dragging left. Every mail and
+messaging convention is written that way round, and naming the panes after the
+direction of travel instead would make `left` the one on the right.
+
+## The geometry, and why each number is where it is
+
+| | |
+| --- | --- |
+| pane width | 76 per action (`actionWidth`) |
+| commits at | 40% of the pane's full width |
+| tap slop | 10 |
+| snap | 160ms, dropped under reduced motion |
+| activation | 12 horizontal; FAILS past 12 vertical |
+
+The row travels with the finger, clamped to the pane's full width, and snaps to
+whichever end is nearer once the commit fraction is crossed — so a half-hearted
+drag never leaves a row stuck ajar. Under the tap slop the whole thing is a tap
+and the row springs straight back.
+
+Activation is what keeps a list scrollable: the pan claims the touch only past
+12px of HORIZONTAL travel and fails outright past 12px of vertical, so a
+scroll that wanders sideways stays a scroll.
+
+The panes are laid UNDER the row and grow with it. The row is what moves; the
+action underneath is revealed, not pushed in from outside. Each button keeps its
+full width the whole time and is CLIPPED by the growing pane, so the label never
+squashes as the row travels.
+
+## Colour
+
+Pass nothing and the panes come from the theme: `negative` and `accent` are the
+SOLID pairs a filled button uses, `neutral` is the subtle default pair — the one
+fill that reads as a surface behind the row rather than as a second control.
+Nothing is derived, appended or eyeballed.
+
+A family that already resolved its own palette passes `paint` instead, so its
+panes match the rest of its rows exactly. That is what `chat-list` does.
+
+## Who gets the gesture
+
+`useSwipeAvailable()` — every touch pointer, on any platform:
+
+```tsx
+const swipe = useSwipeAvailable();
+return swipe ? <SwipeRow …>{row}</SwipeRow> : row;
+```
+
+It is the POINTER, not the platform. A web build runs on a phone as readily as
+on a desktop, so the question `(pointer: coarse)` answers is the right one, and
+it is a hook rather than a constant because the answer changes without a reload
+— a tablet with a keyboard folio attached and detached is the same document.
+Where there is no `matchMedia` at all (SSR, a test renderer, an old browser) it
+answers no, and the calling family's pointer affordance is what shows.
+
+## A SWIPE IS NOT REACHABLE BY KEYBOARD OR BY A SCREEN READER
+
+This is the part that is easy to ship without. A drag has no tab stop, no role
+and no announced name; a reader who cannot perform the gesture cannot archive
+the message, and nothing on the screen says an action exists.
+
+`SwipeRow` does the one thing it can do from inside: while a pane is CLOSED it
+is hidden from assistive technology entirely (`aria-hidden` plus
+`importantForAccessibility`), rather than leaving 0-wide invisible buttons in
+the tab order for the focus ring to disappear into. Opening a pane reveals it.
+
+**The second path is the caller's, and it is not optional.** The two families
+here answer it like this:
+
+- **A pointer** gets the actions as real buttons: `chat-list`'s hover rail and
+  `mail-list`'s `actions` rail. Both appear on `:focus-within` as well as on
+  hover, so they are in the tab order and a keyboard reaches them.
+- **A touch reader** gets `accessibilityActions` on the row itself — the rotor
+  path, which is the platform's own answer to "this control has actions I cannot
+  gesture for". `MailRow` passes every rail and pane action through it, once per
+  key. `chat-list` does NOT, today: on native its swipe actions are reachable by
+  the gesture alone, which is a gap recorded rather than a decision.
+
+Do not invent a third affordance for this. A row that already has a menu should
+put the same actions in it.
+
+## What it does not do
+
+- **It does not decide WHETHER to swipe.** The caller asks
+  `useSwipeAvailable()` (or is told by a prop) and renders the row bare
+  otherwise — which is what keeps a mouse from getting a gesture it cannot
+  discover.
+- **It paints exactly one colour.** Its children are the row, whole; it adds
+  the panes, the clip, the transform — and an opaque `background` under the
+  travelling layer, because the panes are BEHIND the row and a transparent row
+  lets the delete pane read through its own subject line. It defaults to the
+  theme's page colour; a row on a card passes that card's fill.
+- **It does not size the row.** Pass `height` for a fixed row and the container
+  takes it exactly; omit it and the panes stretch to whatever the child turns
+  out to be, which is what a row with a MINIMUM height needs.
+- **It does not open programmatically.** There is no `open` prop: an app that
+  opens a row nobody touched has drawn a menu, and a menu is a different
+  component.

package/docs/switch.mdx

@@ -14,8 +14,8 @@ intent you confirm later with a Save button.
 import { Switch } from '@oxy.so/bloom/switch';
 
 <Switch
-  value={pushEnabled}
-  onValueChange={setPushEnabled}
+  checked={pushEnabled}
+  onCheckedChange={setPushEnabled}
   accessibilityLabel="Push notifications"
 />
 ```
@@ -24,10 +24,10 @@ import { Switch } from '@oxy.so/bloom/switch';
 
 | prop                 | decides                                       |
 | -------------------- | --------------------------------------------- |
-| `value`              | on or off — the component is fully controlled  |
-| `onValueChange`      | receives the **opposite** of the current value |
+| `checked`              | on or off — the component is fully controlled  |
+| `onCheckedChange`      | receives the **opposite** of the current value |
 | `disabled`           | dims it and takes it out of the tab order      |
-| `size`               | `default` (44×26) or `sm` (36×22)              |
+| `size`               | `xs` (30×18), `sm` (36×22), `md` (44×26), `lg` (52×30)              |
 | `accessibilityLabel` | what it announces as — see below               |
 
 There is no uncontrolled mode. A switch whose state the caller does not own is a
@@ -52,8 +52,8 @@ So the row below needs the label even though the words are already on screen:
   title="Push notifications"
   rightElement={
     <Switch
-      value={push}
-      onValueChange={setPush}
+      checked={push}
+      onCheckedChange={setPush}
       accessibilityLabel="Push notifications"
     />
   }
@@ -102,3 +102,7 @@ silently overwritten.
 
 Neither of these is visible to a prop-level test. Assert the rendered
 attribute.
+
+## Compatibility
+
+The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.

package/docs/tab-bar.mdx

@@ -298,6 +298,8 @@ The gesture joins the bar's gesture race only when you pass the prop. Without it
 
 ## Laying out around the bar
 
+For a complete screen, prefer `AppShell` or `Screen` with `BottomBar`: navigation and the primary action share one row, blur and motion signal. The standalone `TabBar` below remains useful for custom compositions. `embedded` removes its positioning and safe-area ownership; `minimizeProgress` can share a screen motion value. Width is measured from the actual parent on layout.
+
 The bar floats over your content (`position: absolute`), so nothing accounts for it. `useTabBarFootprint()` returns the space it physically occupies above the bottom of the window — its own height plus its own bottom offset, and nothing else:
 
 ```tsx
@@ -315,9 +317,6 @@ export default function Feed() {
         // The last row clears the pill by 12pt — that gap is yours, not Bloom's.
         contentContainerStyle={{ paddingBottom: footprint + 12 }}
       />
-      {/* A FAB anchored by `bottom` already carries its own gap: sit it right
-          on top of the footprint. */}
-      <Fab style={{ position: 'absolute', right: 16, bottom: footprint }} />
     </>
   );
 }

package/docs/tag-field.mdx

@@ -0,0 +1,130 @@
+---
+title: TagField
+description: Tags as an input — removable chips, a caret after them, a suggestion listbox, a ceiling, and full Field membership.
+order: 108
+---
+
+# TagField
+
+Tags as an input. A CRM's skills, a task app's labels, a document's access list
+and a notes app's tags are the same control, so **nothing in this family says
+"note"** — the day it learns about one domain it stops being usable by the other
+three.
+
+```tsx
+import { Field, TagField } from '@oxy.so/bloom';
+
+<Field label="Tags" description="Anything you will want to search for later." error={error}>
+  <TagField value={tags} onChange={setTags} suggestions={vocabulary} placeholder="Add a tag" />
+</Field>
+```
+
+## Geometry
+
+**The field IS a `text-field` box, not something that resembles one.** The fill,
+the 10px radius, the 2px inset ring, the hover and focus rings, the invalid tint
+and the disabled tint are all `text-field/shared.ts`'s, resolved through
+`useTextFieldPalette()` for the surface this field actually lands on. An empty
+`TagField` and an empty `TextFieldInput` in the same form are the same object.
+
+|  |  |
+| --- | --- |
+| height, empty | 36 (`medium`) / 32 (`small`) — the text field's rung, exactly |
+| shell inset | 4 above and below the chips; it **grows** as they wrap |
+| chips | `Chip` at the rung that fills that inner height: 28 (`large`) / 24 |
+| input | flexes to the end of the last line, 120 minimum, caret at 8 + 4 |
+| suggestion panel | the menu surface: 16px corner, hairline, dropdown shadow |
+| suggestion row | 36 tall on a 10px corner, the menu row highlight when active |
+
+**The ring is an OVERLAY, not a border on the flex box.** `TextField` paints its
+shell as an absolutely positioned child and this field copies that element,
+because a 2px border would take its width out of the content box: with the chips
+and the caret inside it, an empty tag field came out 40 tall beside a 36-tall
+text field in the same form. That chrome is the one thing here that is copied
+rather than reused — `text-field` exports its palette and its geometry, but not
+the shell as a part.
+
+The input flexing to the end of the line is deliberate: a press in the empty part
+of that line lands on the caret itself. The whole shell is a hit area for it too,
+through the same web `onClick` the text field's shell carries.
+
+**The placeholder is drawn whenever the CARET is empty**, not only when the
+field is. A box of chips with no visible caret and no prompt does not read as an
+input at all, which is how this control once came to look like a container with
+pills in it.
+
+## It is a Field member
+
+`useFieldMembership()` resolves the four things a form asks of a control, each
+with a direction that is silently wrong the other way round: the **name** defers
+to the field (`??`), `disabled` and `invalid` **combine** with it (`||`), the
+**id** is the caller's then the field's, and `aria-describedby` is an id **list**
+so the field's error is joined to the control's own hint rather than replacing
+it. The full rule is in [Composition](/docs/composition) §Field.
+
+The label placement is `stacked`: `TagField`'s own `label` says the same thing a
+`Field`'s label above the box says, so the field wins.
+
+## The three decisions that a render tree cannot show you
+
+All of these live in `shared.ts`, pure and exported, because each fails
+**invisibly**: a duplicate that is added anyway renders a perfectly ordinary
+second chip.
+
+**A duplicate is rejected quietly.** No error, no shake, no hint. The tag is
+already there, so the field is already in the state the typist asked for, and
+telling them off for it is noise. The comparison is case-insensitive —
+"Design" and "design" are one tag to everybody except a string comparison.
+
+**Being full is the one refusal with a consequence**, so it is the one reported
+back (`onMaxReached`) and the one the hint names. At the ceiling the input stops
+accepting; it is not hidden, because a disappearing caret reads as a bug.
+
+**Suggestions exclude what is committed**, and match on a case-insensitive
+**substring** rather than a prefix: tag vocabularies are compound ("Q3 planning",
+"planning — legacy") and a prefix match hides the entry the typist was after.
+
+## Input
+
+- **A comma commits, wherever it comes from.** It is handled in the text change
+  rather than in a key event, so it works on both platforms and a pasted
+  `"a, b, c"` becomes three tags instead of one string with commas in it.
+- **Enter commits** the highlighted suggestion if there is one, otherwise the
+  typed text.
+- **Backspace on an empty caret removes the last chip**, on both platforms.
+- **Arrow keys and Escape move through the suggestions on web.** Native gets no
+  arrow keys from a soft keyboard, so the list is a press target there.
+
+The suggestion list is a real `listbox` of `option` rows with `aria-selected`,
+and the input is a `combobox` carrying `aria-expanded`, `aria-controls` and
+`aria-activedescendant`. It is painted in the **menu vocabulary** — the panel
+surface, hairline and dropdown shadow of `floating/menu-palette.ts`, the 16px
+panel corner and the 36-tall rows on a 10px corner every Bloom menu and select
+draws — so a consumer reads it as the same kind of surface a `DropdownMenu`
+opens. It sits **inline under the field** rather than in an overlay: nothing here
+needs to escape a clipping ancestor, and an inline list is one less stacking
+decision.
+
+## Traps
+
+- **`normalize` runs before every comparison**, so it is where any other answer
+  to "are these the same tag?" goes — case-sensitivity, diacritics folding, a
+  slug. The default only trims.
+- **`allowCreate={false}` makes it a picker**, and a picker with no `suggestions`
+  accepts nothing at all. That is the honest behaviour, not a bug to route
+  around.
+- **Each chip's × is `Chip`'s own**, named after the tag through `closeLabel`
+  (`labels.remove`). A row of removable pills whose buttons are all called
+  "Remove" gives a screen reader no way to say which one it is about. The ×
+  therefore carries a NAME rather than a testID of its own — find it the way
+  `mail-compose`'s suite does, inside `<testID>-chip-<tag>` by its label.
+- **A suggestion row must not take focus, twice over.** It is `tabIndex={-1}`,
+  because the combobox holds focus and points at the active row with
+  `aria-activedescendant`; and it cancels the mousedown's default, because
+  otherwise the press blurs the caret, `focused` goes false, the list unmounts
+  under the pointer and the click lands on nothing. Measured in Chrome: every
+  suggestion unclickable while the keyboard path worked perfectly. Neither is
+  visible in a render tree, and `focusable={false}` does NOT do the first one —
+  react-native-web's `Pressable` still emits `tabindex="0"`.
+- **`value` is controlled.** There is no uncontrolled mode, because the
+  interesting half of this control is what the app does with the list.