@oxy.so/bloom 3.6.0 → 4.1.0

package/docs/shipment-request.mdx

@@ -0,0 +1,139 @@
+---
+title: Shipment request
+description: Describing a job for a carrier — what is being moved, how big and how heavy, the photos, and the options that change the price — as one column of sections built from the families that already own each part.
+order: 134
+---
+
+# Shipment request
+
+```tsx
+import {
+  ShipmentRequestForm,
+  ShipmentLoadPicker,
+  ShipmentOptionsList,
+} from '@oxy.so/bloom/shipment-request';
+
+<ShipmentRequestForm
+  route={{ stops, onSwap, onAddStop, onRemoveStop }}
+  load={load}
+  onLoadChange={setLoad}
+  loadProps={{ notes: true }}
+  photos={{ photos, onReorder, onRemove, onAdd }}
+  options={{ extras, selectedExtras, onExtrasChange, accessOptions, access, onAccessChange }}
+  price={{ lines, total }}
+  footer={<Button variant="primary" size="large" fullWidth onPress={submit}>Ask for quotes</Button>}
+/>
+```
+
+Three components: the **form** is the register and the order, the **load picker**
+and the **options list** are the two halves of it that are this family's own.
+Either half works on its own — a sheet that only asks for the load does not have
+to mount a form.
+
+## What the form draws, and what it does not
+
+`ShipmentRequestForm` draws **nothing of its own**. Every section is an existing
+Bloom family handed its props unchanged:
+
+| section | component | subpath |
+| --- | --- | --- |
+| Where it goes | `RouteStops` | `@oxy.so/bloom/route-stops` |
+| The load | `ShipmentLoadPicker` | this family |
+| Photos | `SortablePhotoGrid` | `@oxy.so/bloom/sortable-media` |
+| Options | `ShipmentOptionsList` | this family |
+| Price | `PriceSummary` | `@oxy.so/bloom/price-breakdown` |
+
+The sections are drawn with `FilterSection`, so the inset, the heading rhythm and
+the rule between two sections are the ones a Bloom filter sheet already uses —
+there is one set of numbers, not two.
+
+The one decision the form makes is the **order**, and it is the order a carrier
+needs the questions answered in: where, what, what it looks like, what changes
+the price, what the price currently is. The price is last on purpose — the
+options that move the number and the number itself end up on one screen.
+
+**A section whose props are absent is not drawn.** `photos`, `options` and
+`price` are each optional, and a job that needs no photograph should not be asked
+for one. The route and the load are not optional: a shipment with neither is not
+a request.
+
+**The last section has no rule under it**, and the `footer` sits below it with
+none either. A divider separates two things; there is nothing after the last one.
+
+## The load picker
+
+Four questions and an optional fifth, each drawn in the control that fits the
+shape of its answer:
+
+- **kind** — one answer out of five, each with a sentence explaining what it
+  covers, so it is a column of selectable cards (the same card the listing editor
+  builds its pickers from). Not chips: a chip has no room for the sentence, and
+  the sentence is what stops someone filing a mattress under "parcel".
+- **size** — a `SegmentedControl` of single letters, with the **chosen** rung's
+  sentence under the control. Four sentences never fit in one control at phone
+  width; a control whose every option carries its own sentence is a list.
+- **weight** — a `TextField` whose unit is a `TextFieldSuffix`.
+- **quantity** — a `StepperRow` from 1.
+- **notes** — an auto-resizing `Textarea`, only when `notes` is set.
+
+### The value arrives whole
+
+`onValueChange` is called with the next `ShipmentLoad`, never with a patch. A
+form that merges patches in five places has five chances to drop a field; this
+one has none. It costs the caller a spread and buys a value that cannot be
+half-applied.
+
+### The unit is not part of the value
+
+`weight` holds digits and at most one dot. `sanitizeWeight` accepts a comma and
+emits a dot (half of Europe types one, and no app wants to parse both), strips
+the unit, and turns a leading separator into `0.`. The "kg" beside the field is
+drawn and announced; it is never stored. An app parses a number, not a sentence.
+
+`isShipmentLoadComplete(load)` is the same decision the picker makes about
+whether every control has been answered, exported so a submit button can be
+disabled from it rather than from a second copy of it. It is **not** validation:
+an app that prices a job has its own rules, and `errors` is where their messages
+go.
+
+## The options list
+
+Three groups, and the control is the difference between them:
+
+- **extras** are independent of one another, so each is a settings row with a
+  `Switch` and its own price at the end. "And also this" is a switch.
+- **access** — one of ground floor, stairs and lift is true, so they are a
+  `radiogroup` of chips and choosing one unchooses the rest.
+- **windows** — the same, over collection times.
+
+**The interactive chips are `size="xl"`** — 32 drawn, 44 under a thumb through
+`Chip`'s own `hitSlop`. The smaller rungs are for labels; a single-choice control
+at phone width is not one.
+
+**The row is not the control.** A pressable row wrapping a switch is two targets
+for one answer, and on web the outer one is a button containing a checkbox. The
+switch is the only thing that toggles.
+
+**A switch draws no text**, so each one is named with its row's title, its
+description and its price. A caption beside a switch is a sibling on both
+platforms — neither associates the two — so a screen reader reading only the
+control announces "switch, off" without this.
+
+## Money
+
+Every amount in this family is a **pre-formatted string**: `"+€12.00"`,
+`"Included"`, `"−€3.00"`. Nothing here parses, sums, converts or rounds. The
+running total is `PriceSummary`'s job, and the app computes it.
+
+## Traps
+
+- **`SHIPMENT_REQUEST_GEOMETRY` has no section numbers.** They belong to
+  `FilterSection`, which draws them. A second copy here would drift from the one
+  on screen.
+- **The form measures nothing itself.** The load picker measures its own width
+  (480) to decide whether the weight field sits beside the quantity; the form
+  does not, because every section it draws already decides its own layout.
+- **`kinds` is a prop, and the five defaults are opinions.** They are the five
+  that change how a job is priced and carried, not a taxonomy of objects. There
+  is deliberately no "Other": a marketplace that cannot name what it is carrying
+  cannot quote it, and `notes` is where an unusual load is described.

package/docs/sidebar.mdx

@@ -1,6 +1,6 @@
 ---
 title: Sidebar
-description: The floating app rail — account switcher, quick search, navigation with counters, theme toggle, secondary rows and a team menu — collapsible to a 60px icon rail.
+description: The floating app rail — account switcher, quick search, navigation with counters, theme toggle, secondary rows and a team menu — collapsible to an icon rail sized for its controls.
 order: 82
 ---
 
@@ -24,6 +24,28 @@ import { RiHomeLine, RiSettings4Line } from '@oxy.so/bloom/icons';
 
 Give it a height (it fills `100%`); its width is its own.
 
+## Primary action
+
+Use `primaryAction` for the sidebar's main command. Bloom reuses `Fab` with its action tone and controlled `collapsed` state,
+50px tall and full-width when expanded, a 50px circle with a 26px glyph when collapsed or in
+`variant="rail"`. It stays outside the scrolling destinations so long navigation
+lists do not push it out of reach. The expanded label follows the sidebar's existing
+collapse animation and reduced-motion setting; the button keeps one focus target.
+
+```tsx
+import { Sidebar } from '@oxy.so/bloom/sidebar';
+import { RiAddLine } from '@oxy.so/bloom/icons/RiAddLine';
+
+<Sidebar
+  items={navigation}
+  primaryAction={{ label: 'New post', icon: RiAddLine, onPress: openComposer, disabled: saving }}
+/>
+```
+
+`label` supplies the accessible name in every layout; `icon` is a Bloom icon
+component. `onPress` owns the command and is never called while `disabled` is true.
+The sidebar does not create a composer or any other application-specific UI.
+
 ## Parts
 
 | export | |
@@ -49,7 +71,7 @@ Give it a height (it fills `100%`); its width is its own.
 />
 ```
 
-- `icon` — the mark, centred in a 36 × 36 box (the collapsed column), so it stays put while the sidebar collapses. Size it yourself; 24–28px reads right.
+- `icon` — the mark, centred in a 36px-high box whose width follows the shared icon lane, so it aligns with navigation at both endpoints. Size it yourself; 24–28px reads right.
 - `wordmark` — beside the mark, folded away while collapsed. A string renders as the product name in `headline-semibold`; pass an SVG or image for a drawn wordmark.
 - `href` makes it a real anchor on web; `onPress` a button (with both, `onPress` wins so a router can navigate — pass it on native, where there is no anchor). With neither it is decoration, named by `accessibilityLabel` or a string `wordmark`.
 - Give a mark, a wordmark or both. Wordmark only disappears when collapsed.
@@ -104,7 +126,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 +138,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,11 +156,11 @@ 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` | 40     | 22    | `headline-medium` | 260      | 56        |
+| `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.
+The table describes a card without a primary action. Runtime collapsed width is the icon lane plus 7px padding on each side and the borders actually painted: card adds2px, docked1px, plain0px. The lane is the row square, or at least50px when `primaryAction` is present (total66/65/64px respectively). Navigation and search retain their30/40/44px circles, centred in the wider lane; their icons are not enlarged. Logo, collapse control, modes, theme and account controls share that centre. Expanded navigation retains its2px inset, and the primary action uses the same edges. A row outside a sidebar takes `size` itself; inside one it inherits the panel's.
 
 `AppShell` passes both through (`sidebar={{ surface, size }}`) and treats `docked` as what it is — it gives up its left and vertical padding around that column and lets it run the full height, so the hairline is the separator instead of a gutter.
 
@@ -149,7 +171,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 +185,50 @@ 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/40/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.
+
+
+### Custom persistent footer
+
+`footer` adds content below the existing bottom controls, outside destination scrolling. Pass a node or `({ collapsed }) => ReactNode`. A rail reports `collapsed: true`; a mobile panel reports `false`, even when its controlled `collapsed` prop is true. Desktop panels report their current rendered state.
+
+```tsx
+<Sidebar
+  items={items}
+  footer={({ collapsed }) => (
+    <ProfileButton compact={collapsed} onPress={openAccount} />
+  )}
+/>
+```
+
+`ProfileButton` above is an application component: the app retains authentication, account selection and menu behavior. The slot adds no account behavior and does not replace `account`, theme, secondary navigation, team or plan controls. Omit `account` if your footer replaces the built-in account switcher. Footer content should fit the compact rail width and provide an accessible name when it hides its label.
+
+Navigation items accept `onLongPress` for secondary touch actions, in both panel and rail. Keep the same action available in a keyboard-accessible menu; long press alone is not discoverable or keyboard accessible.

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.