@oxy.so/bloom 4.0.0 → 4.2.0

package/docs/adoption-matrix.mdx

@@ -32,15 +32,15 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ## Totals
 
-- **180 families** in `src/`, **178** published (a subpath, the root barrel, or both). **35** carry a web fork.
+- **204 families** in `src/`, **202** published (a subpath, the root barrel, or both). **35** carry a web fork.
 - Docs, stories and suites are gated as a standard by `src/__tests__/family-coverage.test.ts`; the per-family counts are in the table below.
 
 | contract | applies to | reads | delegated | n/a¹ | adaptation |
 | --- | --- | --- | --- | --- | --- |
-| Field membership | 39 | 18 | 0 | 18 | 3 |
+| Field membership | 46 | 21 | 0 | 20 | 5 |
 | Control presentation | 16 | 8 | 2 | 6 | 0 |
 | Trigger composition | 10 | 8 | 0 | 2 | 0 |
-| Controlled / uncontrolled state | 42 | 34 | 0 | 1 | 7 |
+| Controlled / uncontrolled state | 49 | 40 | 1 | 1 | 7 |
 
 ## What remains — the named adaptations
 
@@ -49,6 +49,8 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 - `listing-actions` — the mortgage calculator’s term picker is a hand-written `radiogroup`; it sits beside `TextFieldInput`s that DO read the contract, so one form has two association models.
 - `listing-editor` — the property-type, offering and address-precision pickers are hand-written `radiogroup`s over cards, for the same reason and with the same cost as `questionnaire`.
 - `questionnaire` — a FORM whose multi-select answers are hand-written `role="checkbox"` rows instead of `Checkbox`, so a `Field` can neither name nor disable them. Not closed here: the rows carry their own card chrome and selection model, so it is a redesign of the answer control rather than an import.
+- `shipment-request` — the load KIND is the same hand-written `radiogroup` over `listing-editor`’s cards. The rest of the form is worse than that, not better: its `TextField`, `Textarea`, `Switch` and `SegmentedControl` all read the contract, so one form has two association models.
+- `vehicle-picker` — a hand-written `radiogroup` over `listing-editor`’s selectable cards — it REUSES that family’s card rather than writing a third one, so it inherits the same gap for the same reason: a `Field` can neither name nor disable the group.
 
 ### Controlled / uncontrolled state
 
@@ -66,6 +68,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 - `address` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `agent-chat` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
+- `carrier-quote` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `chat-composer` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `chat-list` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `chat-people` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
@@ -73,6 +76,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 - `composer-panel` (does-not-apply) — its pills and effort slider are a toolbar of a composer, named by the group they sit in; the panel is never a field.
 - `floating` (does-not-apply) — a MENU row. `checkbox`/`radio` inside a menu is the menu-item semantic, and the menu owns its own name, state and keyboard model (`floating/menu-rows.tsx`).
 - `home-search` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
+- `job-board` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `map-marker` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `media-controls` (does-not-apply) — a transport SCRUBBER (`adjustable`): it is named by the track it plays and lives in a player, not in a field.
 - `message-media` (does-not-apply) — a voice message’s scrubber — same as `media-controls`.
@@ -89,9 +93,9 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 - `chat-people` (does-not-apply) — sizes an avatar row of its own, not a control: there is nothing for a container’s density to mean here, and honouring it would resize a presentation block.
 - `chat-screen` (does-not-apply) — sizes the chat HEADER, which is chrome around the screen rather than a control a container sets the density of.
 - `creator-studio` (does-not-apply) — sizes a studio stat block — a presentation part, whose two sizes happen to be spelled with the same two words as the density pair.
-- `media-header` (does-not-apply) — sizes the media header’s meta row, which is layout of a header rather than a control inside a container.
 - `note-editor` (delegated) — the toolbar passes `size` straight to `ButtonGroup`, which reads the contract — so a `ControlSurface` reaches the formatting row without this family reading anything.
 - `phone-input` (delegated) — passes `size` straight through to `TextField`, which inherits density — so a `ControlSurface` reaches the phone field without this family reading anything.
+- `place-card` (does-not-apply) — its `density` is the CARD’s — a result row against a detail header — not a control’s size, and the only controls it draws are `Button`s, which read nothing by design (`docs/composition.mdx`).
 - `tenancy` (does-not-apply) — sizes a tenancy summary row: a presentation part, for the same reason as `creator-studio` and `chat-people`.
 
 ### Trigger composition
@@ -101,6 +105,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ### Controlled / uncontrolled state
 
+- `map-controls` (delegated) — the layer picker declares `open`/`defaultOpen` and hands both straight to `DropdownMenu`, which reconciles them with the shared hook — so a controlled caller is honoured without this family reconciling anything itself.
 - `textarea` (does-not-apply) — the VALUE belongs to React Native’s `TextInput`, which reconciles `value`/`defaultValue` itself; the only local state is the character count, which is why it is kept for the uncontrolled case alone.
 
 ## Every family
@@ -122,7 +127,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `alert-dialog` | `@oxy.so/bloom/alert-dialog` + barrel | web fork | `alert-dialog.mdx` | yes | 1 |  |  |  |  |
 | `animated-check` | `@oxy.so/bloom/animated-check` + barrel | universal | `animated-check.mdx` | yes | 2 |  |  |  |  |
 | `announcement` | `@oxy.so/bloom/announcement` + barrel | universal | `announcement.mdx` | yes | 1 |  |  |  |  |
-| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | web fork | `app-shell.mdx` | yes | 2 |  |  |  | reads |
+| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | web fork | `app-shell.mdx` | yes | 3 |  |  |  | reads |
 | `appearance` | `@oxy.so/bloom/appearance` + barrel | universal | `appearance.mdx` | yes | 4 |  |  |  |  |
 | `aspect-ratio` | `@oxy.so/bloom/aspect-ratio` + barrel | universal | `aspect-ratio.mdx` | yes | 1 |  |  |  |  |
 | `auth-card` | `@oxy.so/bloom/auth-card` + barrel | universal | `auth-card.mdx` | yes | 1 |  |  |  |  |
@@ -138,15 +143,19 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `calendar` | `@oxy.so/bloom/calendar` + barrel | universal | `calendar.mdx` | yes | 1 |  |  |  | reads |
 | `call-ui` | `@oxy.so/bloom/call-ui` + barrel | universal | `call-ui.mdx` | yes | 1 |  |  |  |  |
 | `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 3 |  |  |  |  |
+| `card-form` | `@oxy.so/bloom/card-form` + barrel | universal | `card-form.mdx` | yes | 2 | reads |  |  | reads |
 | `carousel` | `@oxy.so/bloom/carousel` + barrel | universal | `carousel.mdx` | yes | 1 |  |  |  |  |
+| `carrier-quote` | `@oxy.so/bloom/carrier-quote` + barrel | universal | `carrier-quote.mdx` | yes | 1 | n/a¹ |  |  | reads |
+| `cart-panel` | `@oxy.so/bloom/cart-panel` + barrel | universal | `cart-panel.mdx` | yes | 1 |  |  |  |  |
 | `category-bar` | `@oxy.so/bloom/category-bar` + barrel | universal | `category-bar.mdx` | yes | 2 |  |  |  |  |
-| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 29 |  |  |  | **adaptation** |
+| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 30 |  |  |  | **adaptation** |
 | `chat-composer` | `@oxy.so/bloom/chat-composer` + barrel | universal | `chat-composer.mdx` | yes | 2 | n/a¹ | n/a¹ |  | reads |
 | `chat-indicators` | `@oxy.so/bloom/chat-indicators` + barrel | universal | `chat-indicators.mdx` | yes | 1 |  |  |  |  |
 | `chat-list` | `@oxy.so/bloom/chat-list` + barrel | universal | `chat-list.mdx` | yes | 2 | n/a¹ |  |  | **adaptation** |
 | `chat-people` | `@oxy.so/bloom/chat-people` + barrel | universal | `chat-people.mdx` | yes | 1 | n/a¹ | n/a¹ |  |  |
 | `chat-screen` | `@oxy.so/bloom/chat-screen` + barrel | universal | `chat-screen.mdx` | yes | 2 |  | n/a¹ |  | reads |
 | `checkbox` | `@oxy.so/bloom/checkbox` + barrel | universal | `checkbox.mdx` | yes | 4 | reads |  |  |  |
+| `checkout-summary` | `@oxy.so/bloom/checkout-summary` + barrel | universal | `checkout-summary.mdx` | yes | 1 |  |  |  |  |
 | `chip` | `@oxy.so/bloom/chip` + barrel | universal | `chip.mdx` | yes | 5 |  |  |  |  |
 | `code` | `@oxy.so/bloom/code` + barrel | universal | `code.mdx` | yes | 3 |  |  |  |  |
 | `command` | `@oxy.so/bloom/command` + barrel | web fork | `command.mdx` | yes | 1 | n/a¹ |  |  | reads |
@@ -156,21 +165,25 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `connection-dots` | `@oxy.so/bloom/connection-dots` + barrel | web fork | `connection-dots.mdx` | yes | 1 |  |  |  |  |
 | `connection-status` | `@oxy.so/bloom/connection-status` + barrel | web fork | `connection-status.mdx` | yes | 1 |  |  |  |  |
 | `contact-card` | `@oxy.so/bloom/contact-card` + barrel | universal | `contact-card.mdx` | yes | 1 |  |  |  |  |
-| `content-panel` | `@oxy.so/bloom/content-panel` + barrel | web fork | `content-panel.mdx` | yes | 6 |  |  |  |  |
+| `content-panel` | `@oxy.so/bloom/content-panel` + barrel | web fork | `content-panel.mdx` | yes | 8 |  |  |  |  |
 | `context-menu` | `@oxy.so/bloom/context-menu` + barrel | web fork | `context-menu.mdx` | yes | 2 |  |  | reads |  |
 | `control-surface` | `@oxy.so/bloom/control-surface` + barrel | universal | `composition.mdx` | yes | 3 |  | reads |  |  |
 | `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 3 |  | n/a¹ |  | **adaptation** |
 | `data-table` | `@oxy.so/bloom/data-table` + barrel | universal | `data-table.mdx` | yes | 3 |  |  |  | reads |
 | `date-picker` | `@oxy.so/bloom/date-picker` + barrel | universal | `date-picker.mdx` | yes | 4 | reads | reads |  | reads |
+| `delivery-slot` | `@oxy.so/bloom/delivery-slot` + barrel | universal | `delivery-slot.mdx` | yes | 2 | reads |  |  |  |
 | `design-tokens` | `@oxy.so/bloom/design-tokens` + barrel | universal | `design-tokens.mdx` | yes | 3 |  |  |  |  |
 | `dialog` | `@oxy.so/bloom/dialog` + barrel | web fork | `dialog.mdx` | yes | 13 |  |  |  |  |
+| `directions` | `@oxy.so/bloom/directions` + barrel | universal | `directions.mdx` | yes | 2 |  |  |  |  |
 | `divider` | `@oxy.so/bloom/divider` + barrel | universal | `divider.mdx` | yes | 1 |  |  |  |  |
 | `dot-grid-meter` | `@oxy.so/bloom/dot-grid-meter` + barrel | universal | `dot-grid-meter.mdx` | yes | 2 |  |  |  |  |
 | `dropdown-menu` | `@oxy.so/bloom/dropdown-menu` + barrel | web fork | `dropdown-menu.mdx` | yes | 4 |  |  | reads | reads |
+| `earnings` | `@oxy.so/bloom/earnings` + barrel | universal | `earnings.mdx` | yes | 1 |  |  |  | reads |
+| `empty-state` | `@oxy.so/bloom/empty-state` + barrel | universal | `empty-state.mdx` | yes | 1 |  |  |  |  |
 | `error-boundary` | `@oxy.so/bloom/error-boundary` + barrel | universal | `error-boundary.mdx` | yes | 1 |  |  |  |  |
 | `eviction` | `@oxy.so/bloom/eviction` + barrel | universal | `eviction.mdx` | yes | 1 |  |  |  |  |
-| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 3 |  |  |  |  |
-| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 6 | reads |  |  |  |
+| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 4 |  |  |  |  |
+| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 9 | reads |  |  |  |
 | `file-upload` | `@oxy.so/bloom/file-upload` + barrel | universal | `file-upload.mdx` | yes | 3 | reads |  |  |  |
 | `fill` | `@oxy.so/bloom/fill` + barrel | universal | `fill.mdx` | yes | 1 |  |  |  |  |
 | `floating` | internal | universal | — | — | 14 | n/a¹ |  | reads | reads |
@@ -182,60 +195,73 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `hooks` | `@oxy.so/bloom/hooks` + barrel | universal | `hooks.mdx` | yes | 9 |  |  |  | reads |
 | `hover-card` | `@oxy.so/bloom/hover-card` + barrel | web fork | `hover-card.mdx` | yes | 2 |  |  | reads | reads |
 | `icon-circle` | `@oxy.so/bloom/icon-circle` + barrel | universal | `icon-circle.mdx` | yes | 1 |  |  |  |  |
-| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 41 |  |  |  |  |
+| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 47 |  |  |  |  |
 | `image-aspect-ratio-cache` | `@oxy.so/bloom/image-aspect-ratio-cache` + barrel | universal | `image-aspect-ratio-cache.mdx` | yes | 1 |  |  |  |  |
 | `image-resolver` | `@oxy.so/bloom/image-resolver` + barrel | universal | `image-resolver.mdx` | yes | 7 |  |  |  |  |
 | `important-alerts-card` | `@oxy.so/bloom/important-alerts-card` + barrel | universal | `important-alerts-card.mdx` | yes | 1 |  |  |  |  |
 | `input-group` | `@oxy.so/bloom/input-group` + barrel | universal | `input-group.mdx` | yes | 3 | reads |  |  |  |
 | `input-otp` | `@oxy.so/bloom/input-otp` + barrel | universal | `input-otp.mdx` | yes | 2 | reads |  |  | **adaptation** |
 | `item` | `@oxy.so/bloom/item` + barrel | universal | `item.mdx` | yes | 2 |  |  |  |  |
+| `job-board` | `@oxy.so/bloom/job-board` + barrel | universal | `job-board.mdx` | yes | 1 | n/a¹ |  |  | reads |
 | `kbd` | `@oxy.so/bloom/kbd` + barrel | universal | `kbd.mdx` | yes | 1 |  |  |  |  |
 | `label` | `@oxy.so/bloom/label` + barrel | universal | `label.mdx` | yes | 1 |  |  |  |  |
-| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 5 |  |  |  |  |
+| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 7 |  |  |  |  |
 | `lead-score` | `@oxy.so/bloom/lead-score` + barrel | universal | `lead-score.mdx` | yes | 1 |  |  |  |  |
 | `link-preview` | `@oxy.so/bloom/link-preview` + barrel | universal | `link-preview.mdx` | yes | 2 |  |  |  |  |
 | `list` | `@oxy.so/bloom/list` + barrel | web fork | `list.mdx` | yes | 2 |  |  |  |  |
 | `listing-actions` | `@oxy.so/bloom/listing-actions` + barrel | universal | `listing-actions.mdx` | yes | 2 | **adaptation** |  |  | reads |
-| `listing-card` | `@oxy.so/bloom/listing-card` + barrel | universal | `listing-card.mdx` | yes | 3 |  |  |  |  |
+| `listing-card` | `@oxy.so/bloom/listing-card` + barrel | universal | `listing-card.mdx` | yes | 4 |  |  |  |  |
 | `listing-details` | `@oxy.so/bloom/listing-details` + barrel | universal | `listing-details.mdx` | yes | 4 |  |  |  | reads |
 | `listing-editor` | `@oxy.so/bloom/listing-editor` + barrel | universal | `listing-editor.mdx` | yes | 1 | **adaptation** |  |  | reads |
 | `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 2 |  |  |  |  |
+| `location-puck` | `@oxy.so/bloom/location-puck` + barrel | universal | `location-puck.mdx` | yes | 1 |  |  |  |  |
 | `lyrics` | `@oxy.so/bloom/lyrics` + barrel | universal | `lyrics.mdx` | yes | 2 |  |  |  |  |
 | `mail-compose` | `@oxy.so/bloom/mail-compose` + barrel | universal | `mail-compose.mdx` | yes | 2 | reads |  |  | reads |
 | `mail-list` | `@oxy.so/bloom/mail-list` + barrel | universal | `mail-list.mdx` | yes | 2 |  |  |  |  |
 | `mail-thread` | `@oxy.so/bloom/mail-thread` + barrel | universal | `mail-thread.mdx` | yes | 1 |  |  |  | reads |
+| `map-attribution` | `@oxy.so/bloom/map-attribution` + barrel | universal | `map-attribution.mdx` | yes | 1 |  |  |  |  |
+| `map-controls` | `@oxy.so/bloom/map-controls` + barrel | universal | `map-controls.mdx` | yes | 1 |  |  |  | delegated |
 | `map-marker` | `@oxy.so/bloom/map-marker` + barrel | universal | `map-marker.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `media-card` | `@oxy.so/bloom/media-card` + barrel | universal | `media-card.mdx` | yes | 4 |  |  |  |  |
 | `media-controls` | `@oxy.so/bloom/media-controls` + barrel | universal | `media-controls.mdx` | yes | 3 | n/a¹ |  |  |  |
 | `media-flight` | `@oxy.so/bloom/media-flight` | web fork | `media-flight.mdx` | yes | 3 |  |  |  |  |
-| `media-header` | `@oxy.so/bloom/media-header` + barrel | universal | `media-header.mdx` | yes | 3 |  | n/a¹ |  |  |
+| `media-header` | `@oxy.so/bloom/media-header` + barrel | universal | `media-header.mdx` | yes | 3 |  |  |  |  |
 | `media-inset-border` | `@oxy.so/bloom/media-inset-border` + barrel | universal | `media-inset-border.mdx` | yes | 1 |  |  |  |  |
 | `media-player` | `@oxy.so/bloom/media-player` + barrel | universal | `media-player.mdx` | yes | 3 |  |  |  |  |
 | `media-shelf` | `@oxy.so/bloom/media-shelf` + barrel | universal | `media-shelf.mdx` | yes | 1 |  |  |  |  |
+| `menu-item` | `@oxy.so/bloom/menu-item` + barrel | universal | `menu-item.mdx` | yes | 1 |  |  |  |  |
 | `menubar` | `@oxy.so/bloom/menubar` + barrel | web fork | `menubar.mdx` | yes | 2 |  |  | reads | reads |
 | `message-bubble` | `@oxy.so/bloom/message-bubble` + barrel | universal | `message-bubble.mdx` | yes | 1 |  |  |  |  |
 | `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `motion` | `@oxy.so/bloom/motion` + barrel | web fork | `motion.mdx` | yes | 2 |  |  |  |  |
 | `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 3 | n/a¹ |  |  |  |
+| `navigation-banner` | `@oxy.so/bloom/navigation-banner` + barrel | universal | `navigation-banner.mdx` | yes | 1 |  |  |  |  |
 | `note-card` | `@oxy.so/bloom/note-card` + barrel | universal | `note-card.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `note-editor` | `@oxy.so/bloom/note-editor` + barrel | universal | `note-editor.mdx` | yes | 1 | n/a¹ | delegated |  |  |
 | `notification` | `@oxy.so/bloom/notification` + barrel | universal | `notification.mdx` | yes | 3 |  |  |  |  |
 | `notification-center` | `@oxy.so/bloom/notification-center` + barrel | universal | `notification-center.mdx` | yes | 3 |  |  |  | reads |
 | `offering-badge` | `@oxy.so/bloom/offering-badge` + barrel | universal | `offering-badge.mdx` | yes | 3 |  |  |  |  |
+| `order-confirmation` | `@oxy.so/bloom/order-confirmation` + barrel | universal | `order-confirmation.mdx` | yes | 1 |  |  |  |  |
 | `order-status` | `@oxy.so/bloom/order-status` + barrel | universal | `order-status.mdx` | yes | 1 |  |  |  |  |
 | `outline-nav` | `@oxy.so/bloom/outline-nav` + barrel | universal | `outline-nav.mdx` | yes | 1 |  |  |  |  |
 | `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 7 |  |  |  |  |
 | `page-header` | `@oxy.so/bloom/page-header` + barrel | universal | `page-header.mdx` | yes | 2 |  | reads |  |  |
 | `pagination` | `@oxy.so/bloom/pagination` + barrel | universal | `pagination.mdx` | yes | 1 |  |  |  |  |
 | `patient-info-card` | `@oxy.so/bloom/patient-info-card` + barrel | universal | `patient-info-card.mdx` | yes | 1 |  |  |  |  |
+| `payment-method` | `@oxy.so/bloom/payment-method` + barrel | universal | `payment-method.mdx` | yes | 2 | reads |  |  |  |
+| `payment-status` | `@oxy.so/bloom/payment-status` + barrel | universal | `payment-status.mdx` | yes | 1 |  |  |  |  |
 | `phone-input` | `@oxy.so/bloom/phone-input` | universal | `phone-input.mdx` | yes | 2 | reads | delegated |  | reads |
 | `pipeline` | `@oxy.so/bloom/pipeline` + barrel | universal | `pipeline.mdx` | yes | 1 |  |  |  | reads |
+| `place-card` | `@oxy.so/bloom/place-card` + barrel | universal | `place-card.mdx` | yes | 2 |  | n/a¹ |  |  |
+| `place-details` | `@oxy.so/bloom/place-details` + barrel | universal | `place-details.mdx` | yes | 1 |  |  |  | reads |
+| `place-list` | `@oxy.so/bloom/place-list` + barrel | universal | `place-list.mdx` | yes | 1 |  |  |  |  |
 | `place-reviews` | `@oxy.so/bloom/place-reviews` + barrel | universal | `place-reviews.mdx` | yes | 1 |  |  |  | reads |
 | `popover` | `@oxy.so/bloom/popover` + barrel | web fork | `popover.mdx` | yes | 7 |  |  | reads | reads |
 | `portal` | `@oxy.so/bloom/portal` + barrel | web fork | `portal.mdx` | yes | 15 |  |  |  |  |
 | `pressable-scale` | `@oxy.so/bloom/pressable-scale` + barrel | universal | `pressable-scale.mdx` | yes | 1 |  |  |  |  |
-| `price-breakdown` | `@oxy.so/bloom/price-breakdown` + barrel | universal | `price-breakdown.mdx` | yes | 1 |  |  |  | reads |
+| `price-breakdown` | `@oxy.so/bloom/price-breakdown` + barrel | universal | `price-breakdown.mdx` | yes | 3 |  |  |  | reads |
 | `progressive-blur` | `@oxy.so/bloom/progressive-blur` + barrel | web fork | `progressive-blur.mdx` | yes | 1 |  |  |  |  |
+| `proof-of-delivery` | `@oxy.so/bloom/proof-of-delivery` + barrel | universal | `proof-of-delivery.mdx` | yes | 1 |  |  |  | reads |
 | `property-insights` | `@oxy.so/bloom/property-insights` + barrel | universal | `property-insights.mdx` | yes | 4 |  |  |  | reads |
 | `provider` | `@oxy.so/bloom/provider` | universal | `provider.mdx` | yes | 1 |  |  |  |  |
 | `questionnaire` | `@oxy.so/bloom/questionnaire` + barrel | universal | `questionnaire.mdx` | yes | 1 | **adaptation** |  |  | **adaptation** |
@@ -246,14 +272,15 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `rating` | `@oxy.so/bloom/rating` + barrel | universal | `rating.mdx` | yes | 3 | reads |  |  |  |
 | `recent-hires-card` | `@oxy.so/bloom/recent-hires-card` + barrel | universal | `recent-hires-card.mdx` | yes | 1 |  |  |  |  |
 | `route-stops` | `@oxy.so/bloom/route-stops` + barrel | universal | `route-stops.mdx` | yes | 1 |  |  |  |  |
-| `screen` | `@oxy.so/bloom/screen` + barrel | universal | `screen.mdx` | yes | 4 |  |  |  |  |
+| `screen` | `@oxy.so/bloom/screen` + barrel | universal | `screen.mdx` | yes | 5 |  |  |  |  |
 | `scroll` | `@oxy.so/bloom/scroll` + barrel | web fork | `scroll.mdx` | yes | 5 |  |  |  |  |
 | `search` | `@oxy.so/bloom/search` + barrel | universal | `search.mdx` | yes | 1 |  |  |  |  |
 | `segmented-control` | `@oxy.so/bloom/segmented-control` + barrel | universal | `segmented-control.mdx` | yes | 3 | reads |  |  |  |
 | `select` | `@oxy.so/bloom/select` + barrel | web fork | `select.mdx` | yes | 6 | reads |  | reads |  |
 | `settings-list` | `@oxy.so/bloom/settings-list` + barrel | universal | `settings-list.mdx` | yes | 5 |  |  |  |  |
 | `settings-modal` | `@oxy.so/bloom/settings-modal` + barrel | universal | `settings-modal.mdx` | yes | 1 |  |  |  | reads |
-| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 2 | n/a¹ |  |  | reads |
+| `shipment-request` | `@oxy.so/bloom/shipment-request` + barrel | universal | `shipment-request.mdx` | yes | 1 | **adaptation** |  |  |  |
+| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 5 | n/a¹ |  |  | reads |
 | `skeleton` | `@oxy.so/bloom/skeleton` + barrel | universal | `skeleton.mdx` | yes | 1 |  |  |  |  |
 | `slider` | `@oxy.so/bloom/slider` + barrel | universal | `slider.mdx` | yes | 4 | reads |  |  |  |
 | `social-button` | `@oxy.so/bloom/social-button` + barrel | universal | `social-button.mdx` | yes | 1 |  |  |  |  |
@@ -263,7 +290,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `stay-filters` | `@oxy.so/bloom/stay-filters` + barrel | universal | `stay-filters.mdx` | yes | 4 | n/a¹ |  |  |  |
 | `stay-search` | `@oxy.so/bloom/stay-search` + barrel | universal | `stay-search.mdx` | yes | 4 |  |  |  |  |
 | `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 3 | reads |  |  |  |
-| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 57 |  |  |  |  |
+| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 64 |  |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
 | `surfaces` | `@oxy.so/bloom/surfaces` + barrel | web fork | `alert.mdx` | yes | 2 |  |  |  |  |
 | `swipe-row` | `@oxy.so/bloom/swipe-row` + barrel | universal | `swipe-row.mdx` | yes | 1 |  |  |  |  |
@@ -277,13 +304,15 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 3 |  | n/a¹ |  |  |
 | `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 13 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 276 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 287 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |
 | `track-list` | `@oxy.so/bloom/track-list` + barrel | universal | `track-list.mdx` | yes | 2 |  |  |  | **adaptation** |
 | `typography` | `@oxy.so/bloom/typography` + barrel | universal | `typography.mdx` | yes | 7 |  |  |  |  |
 | `user-hover-card` | `@oxy.so/bloom/user-hover-card` + barrel | universal | `user-hover-card.mdx` | yes | 4 |  |  |  |  |
+| `vehicle-picker` | `@oxy.so/bloom/vehicle-picker` + barrel | universal | `vehicle-picker.mdx` | yes | 1 | **adaptation** |  |  |  |
+| `vendor-card` | `@oxy.so/bloom/vendor-card` + barrel | universal | `vendor-card.mdx` | yes | 1 |  |  |  |  |
 | `web-search` | `@oxy.so/bloom/web-search` + barrel | universal | `web-search.mdx` | yes | 1 |  |  |  |  |
 | `wizard` | `@oxy.so/bloom/wizard` + barrel | universal | `wizard.mdx` | yes | 1 |  |  |  |  |
 | `zoomable-media-gallery` | `@oxy.so/bloom/zoomable-media-gallery` | universal | `zoomable-media-gallery.mdx` | yes | 2 |  |  |  |  |

package/docs/app-shell.mdx

@@ -62,11 +62,29 @@ in Chrome at 1440: after scrolling 406px the nav stayed at `y = 121` and the
 aside at `y = 16` while the content moved from `16` to `-390`.
 
 `panel` wraps the centre column in a [`ContentPanel`](/docs/bloom/main/content-panel),
-so the page background reads as a gutter around a framed surface; `framedFrom`
-is forwarded.
+so the page background reads as a gutter around a framed surface. With navigation,
+its frame follows the same breakpoint as the in-flow sidebar/rail. Once navigation
+moves to the bottom, the reading column fills the compact layout. An explicit
+`framedFrom` overrides this coordination; a panel without navigation retains
+ContentPanel’s own responsive default.
+
+`panelColorPreset` scopes the central reading column to a Bloom color preset.
+Navigation and right-hand widgets retain the app theme, as does the panel’s outer
+mask. Changing the preset does not remount the routed content.
+
+This prevents a frameless panel beside a still-visible rail: the social template
+uses 700px for both, instead of independently changing the panel at 768px. Resizing
+keeps the same content node mounted and does not replace the document scroller.
 
 **The panel occupies the screen either way — what differs is what scrolls.**
 
+In document mode the painted surface has a viewport minimum height, subtracting
+the shell insets and any measured external top bar. Short pages fill the frame;
+long pages keep growing with the document. Header and bottom-bar clearance inside
+the surface count toward that minimum, so empty pages do not gain extra scroll.
+Reveal drawers move the bottom-bar and FAB slots with the page in both document
+and fixed modes; the shell remains their sole safe-area and measurement owner.
+
 - `scroll="document"` (the default): the page scrolls, and the panel's frame is
   a screen-tall sticky rectangle pinned at the shell's own `gutter`, so the
   panel reads as a surface filling the window while the content moves inside
@@ -75,17 +93,15 @@ is forwarded.
   content behind it travels from 16 to −830. (The inset is what makes that
   true: at the 8px default the frame would sit above the panel's real top edge
   and snap down on the first scroll.)
-- `scroll="fixed"` / `"container"`: the shell bounds the panel, so the panel IS
-  the box — it closes at the bottom like the rail beside it, the header is
-  pinned inside it, and only the routed content scrolls, under the frame. The
-  document never moves at all.
+- `scroll="container"`: the panel fills the frame and owns a `ScrollView` below its pinned header.
+- `scroll="fixed"`: the panel fills the frame with a plain flex view. The child navigator, virtualized list or canvas owns scrolling and reads the shared occupied bottom edge for its own clearance. The shell never nests a `ScrollView` around it or pads its navigator a second time.
 
 Both are right; they are different apps. A feed with the address bar collapsing
 on a phone and real anchor links wants `document`; a workspace whose regions
-each keep their own position wants `fixed`. The panel's content is inset by `gutter` — without it the page sits
-ON the frame, and a radius-28 corner clips whatever is in it (the heading loses
-its first letter). So `contentWidth` is the COLUMN's width, and the reading
-measure inside a panel is that minus two gutters. Do not render your own
+each keep their own position wants `fixed`. The panel adds no content padding:
+`gutter` controls the outside frame, while each screen owns its title and body
+insets. `contentWidth` is the full column width. Only measured bottom chrome
+clearance is reserved automatically. Do not render your own
 `ContentPanel` inside this one; it trips the nesting guard.
 
 ### `canvas`
@@ -205,12 +221,20 @@ Both bars are MEASURED, and the content column reserves exactly their height, so
 the last row of a feed is never hidden behind them. Measured in Chrome at 390,
 scrolled to the page end: last item bottom `768`, action top `784`, bar top `844`.
 
+With a content panel, the reserved clearance stays inside its painted surface.
+In the compact full-width layout, bottom chrome also inherits that panel fill,
+so its fading backdrop does not introduce a strip of the outer page color.
+
 `topBarVisibility` / `bottomBarVisibility` are `compact` (the default — only
 while the nav is a drawer, the phone case the slots exist for) or `always`, for
 a bar that is part of the app at every width.
 
 ## Breakpoints an app can name itself
 
+For centred feed layouts, `navigationGap` and `asideGap` control the gaps on
+either side of the reading column independently of the panel's `gutter`.
+Set both to the same value for symmetric columns.
+
 Every `*From` prop takes a named tier (`sm` 640 · `md` 768 · `lg` 1024 · `xl` 1280) **or a width in pixels**, because a real app's layout rarely lands on the tiers. A feed whose side column earns its place at 990 and whose rail goes in flow at 500 says so:
 
 ```tsx
@@ -313,7 +337,7 @@ overlapping another, and no console error.
 ```
 
 A second column on the right of the page (`dashboard` and `feed`; `split` has
-its `info` pane instead and `focus` has no second column at all). From `asideFrom` (`xl`, 1280; or `md` / `lg`) it sits beside the content at `asideWidth` (320), pinned like the sidebar — with document scroll it is sticky and scrolls its own overflow, so give it `flex: 1` content if it should fill the height. Below the breakpoint it is stacked after the content (`asideCollapse="stack"`, the default) or dropped (`"hidden"`). Under `drawer="reveal"` it slides with the page.
+its `info` pane instead and `focus` has no second column at all). From `asideFrom` (`xl`, 1280; or `md` / `lg`) it sits beside the content at `asideWidth` (320), pinned like the sidebar — with document scroll it stays in natural document flow. A tall aside scrolls with the page until its lower edge is visible, then sticks; it does not capture wheel gestures in a nested ScrollView. Container and fixed modes retain bounded aside scrolling. Below the breakpoint it is stacked after the content (`asideCollapse="stack"`, the default) or dropped (`"hidden"`). Under `drawer="reveal"` it slides with the page.
 
 ## Eight shells, one component
 
@@ -515,4 +539,38 @@ transition the animated width resets explicitly to `auto`: returning an empty
 style or an undefined width retained the old width in the browser, leaving a
 260px space after the sidebar itself collapsed to 52px.
 
-The adaptive entry point is selected when `navigation`, `navigationPlacement`, `primaryAction`, or `scroll="auto" | "external"` is supplied. Existing layout calls keep their `dashboard`, `feed`, `split`, `focus`, and `canvas` engine, document/container/fixed scrolling, slots and drawer behavior. Both paths render the same Sidebar, PageHeader and themed surfaces.
+The navigation convenience entry point is selected when `navigation`, `navigationPlacement`, `primaryAction`, or `scroll="auto" | "external"` is supplied. On web it defaults to `scroll="document"` and adapts navigation/actions into the same layout engine used by `dashboard`, `feed`, `split`, `focus`, and `canvas`: aside, width, drawer and slot props remain effective. Native defaults to `scroll="auto"`. Explicit `auto` keeps the animated adaptive container for navigation-only shells. Supplying a layout variant, aside, list or info pane uses the layout engine instead: `auto` becomes container scrolling, and `external` a fixed frame whose child owns scrolling. Document scrolling shares Screen navigation motion with the bottom bar and FAB. Explicit slots override the generated bottom bar or floating action, including `null` to suppress one. A primary action remains a separate floating action when a custom bottom bar replaces the generated bar. The focus variant never generates navigation.
+
+For a centered feed whose navigation belongs beside the reading column, use
+`navigationAlign="content"`. The shell centers navigation, content and the visible
+aside as one group; `"edge"` preserves the existing edge-aligned layout.
+
+
+### Header width inside a panel
+
+In a centered `panel` layout, the header spans the full ContentPanel width. The
+shell leaves body padding to the screen; PageHeader owns the insets of its title
+and action islands. Padding a shared header/body wrapper shortened the scrim by
+one gutter on each side (32px total at gutter16), leaving scrolling content
+visible beside it. Both document and bounded panel layouts use this separation.
+The real-browser mask check also asserts the header’s left/right edges match the
+panel at rest and during scroll.
+
+`navigationGap` controls the space between the sidebar and content independently of
+`gutter` and the aside gap. The social template uses `navigationGap={0}` to bring
+plain navigation up to the reading panel while retaining the panel frame insets.
+
+A document-scrolling, content-aligned shell with a plain sidebar and no top bar
+has no root padding. The sidebar spans the viewport; the reading/context group
+owns the vertical gutter, which still supplies the panel mask and header inset.
+The social template uses an 8px gutter, matching the compact framed layout.
+
+A feed can use `drawer="reveal"` on compact screens: the page slides aside to reveal the same sidebar, as in AI Chat. Its document scroll and desktop column layout remain unchanged. Put `AppShellMenuButton` in a custom header’s `leading` slot; it hides automatically when navigation is in flow.
+
+
+The `bottomBar` slot publishes its measured footprint through the shared bottom-edge registry. Measurement includes the slot’s safe-area padding; embedded bars must not add that inset again. Native feeds and separately positioned FABs can read `useBottomEdgeInset()` without importing the navigation component. Claims combine by maximum, not addition, and disappear when the slot unmounts. The slot never reads its own claim to size itself; repeated equal layout measurements do not trigger another height callback.
+
+For fullscreen video or a child scroller that accounts for the occupied bottom edge itself,
+set `reserveBottomBarSpace={false}`. The visible bar still publishes its measured height
+through the shared edge registry; document/container content receives no duplicate bar padding.
+`scroll="fixed"` always leaves scrolling and clearance to the child navigator or list.

package/docs/bottom-bar.mdx

@@ -31,3 +31,11 @@ available platform material. `maxWidth` defaults to 560 points.
 
 The universal entry uses no Apple-only peers. The specialized `tab-bar` subpath
 continues to provide its native enhancements independently.
+
+`actionPlacement="auto"` (default) moves the action above and to the right when placing it beside the tabs would leave less than 56 points per destination. `beside` retains the horizontal arrangement; `above` always lifts it. The action uses the same scroll-driven visibility in both placements. Its measured height plus a 10-point gap joins the reserved footprint, so the final content remains reachable.
+
+## Pager and shell composition
+
+`activeProgress` accepts a shared continuous item index from a swipe pager. `value` remains the settled semantic destination; use an unmatched value when a pushed route has no selection. `onValueLongPress(value)` handles destination actions such as account switching.
+
+Inside an `AppShell` bottom-bar slot, the shell owns measurement and the bottom safe area. `BottomBar` automatically consumes that ownership, so the inset is applied once. Standalone bars retain their own edge claim and inset.

package/docs/card-form.mdx

@@ -0,0 +1,185 @@
+---
+title: Card form
+description: Entering a card — six boxes, grouping that never moves the caret, a scheme detected from the caller's own table, and a loud statement of what Bloom does not do with the value.
+order: 138
+---
+
+# Card form
+
+**Read this part first.**
+
+`card-form` is an INPUT SURFACE. It draws boxes, groups digits, keeps the caret where the
+person put it, and shows a message under a box. It does not:
+
+- **validate a live card.** The only two checks it offers are arithmetic: an accepted
+  digit count, and the Luhn check digit. Neither says a card exists, has funds or will be
+  accepted — only a processor can say that.
+- **store anything.** No cache, no ref that outlives the render, no `AsyncStorage`, no
+  `localStorage`.
+- **log anything.** There is no `console` call in this family.
+- **open a connection.** There is no network code in this family, and no prop that takes a
+  URL, a key or a token.
+- **ship a table of schemes.** No names, no prefixes, no ranges, no artwork.
+
+The value is the app's, and it goes to the app's own payment SDK. If you are building a
+screen that sends a card number somewhere, the sending is yours: put this in front of it
+and nothing else.
+
+```tsx
+import { CardForm } from '@oxy.so/bloom/card-form';
+
+<CardForm
+  value={value}
+  onValueChange={setValue}
+  schemes={MY_PROCESSORS_SCHEMES}
+  errors={{ number: 'That is one digit short.' }}
+  fields={{ name: true, postcode: true }}
+  accessibilityLabel="Card details"
+/>
+```
+
+## The caret rule
+
+Re-grouping a string while someone is editing the MIDDLE of it is what makes a card field
+feel broken: the value changes ahead of the caret, the platform puts the caret back at the
+end, and the next keystroke lands in the wrong place. Both platforms do it, and **no test
+of a controlled input can see it** — the value is right, and only the selection is wrong.
+
+So grouping is applied only to an edit at the END, which is the case where the caret
+belongs at the end anyway:
+
+```
+typing on, backspacing off the tail   → re-grouped
+an edit anywhere else                 → handed back exactly as typed
+leaving the box                       → re-grouped once
+```
+
+Two consequences worth knowing:
+
+- **no trailing separator, ever.** A group that ended in a space would need two backspaces
+  to lose one digit, because the first would delete a separator the formatter immediately
+  puts back.
+- **an edit past the accepted length is refused outright**, not truncated. Returning a
+  truncated value would move the caret too.
+
+`applyCardNumberEdit`, `applyCardExpiryEdit`, `normaliseCardNumber` and
+`normaliseCardExpiry` are exported and pure, so an app that draws its own box can keep the
+same behaviour.
+
+## The scheme table is the app's
+
+```tsx
+const SCHEMES = [
+  { id: 'x', name: 'Aurora', prefixes: ['7'], lengths: [16], groups: [4, 4, 4, 4] },
+  { id: 'y', name: 'Meridian', prefixes: [['81', '85']], lengths: [15], groups: [4, 6, 5],
+    securityCodeLength: 4, securityCodeLabel: 'Card code' },
+];
+```
+
+A prefix is a string, or a `[from, to]` pair of equal-length strings for a range. Matching
+is over the SHORTER of the typed digits and the prefix, so a scheme is recognised from the
+first digit — the point being that the mark appears while the number is still going in.
+
+The **first** match in the caller's array wins, so an app that wants a house scheme to beat
+a general one puts it first.
+
+Given no table, the form groups in fours, accepts sixteen digits and asks for a
+three-digit code. That is a neutral default, not a claim about any real scheme.
+
+The detected scheme drives the grouping, the accepted lengths, the security code's length
+and what the security code is CALLED, and it is reported through `onSchemeChange` — by id,
+so a caller that rebuilds its array each render does not get a change that did not happen.
+
+## The mark above the box
+
+The detected scheme is drawn with `payment-method`'s `PaymentMethodMark`, at the end of the
+number box's label row. That means the same rule applies here: **a neutral glyph and the
+scheme's name as text, never a logo**, unless the app supplies `image` on the scheme
+because it has the rights. `docs/payment-method.mdx` argues it at length.
+
+## The expiry is never checked against a clock
+
+`cardExpiryIsWellFormed` means four digits and a month between 01 and 12. It does **not**
+mean the card is still in date: this family never reads a clock, the same rule
+`price-breakdown` holds for money. The app knows what "now" means for its own billing, and
+a component that decided would be wrong for every app in a different timezone.
+
+On blur a lone month of 2–9 gets its leading zero, because nobody means September when
+they type "9" and tab away. A lone `1` is left alone — it is as likely to be the start of
+October.
+
+## Every box is a `Field` member on its own
+
+`CardFormNumber`, `CardFormExpiry`, `CardFormSecurityCode`, `CardFormName`,
+`CardFormPostcode` and `CardFormCountry` each read `useFieldMembership()`, so any one of
+them can go in a `Field` and take its label, id, description, error, required and disabled
+state.
+
+```tsx
+<Field label="Card number" error={numberError}>
+  <CardFormNumber value={number} onValueChange={setNumber} />
+</Field>
+```
+
+**A `Field` around the WHOLE form must be `multiple`.** A single-control field publishes
+one control id, and six inputs carrying one id is invalid HTML with an error announced six
+times. `multiple` makes the field a labelled `group`, publishes no id, and each box keeps
+its own — which is the shape this form is.
+
+A box also takes its own `error`, drawn under it and JOINED into `aria-describedby` rather
+than replacing the field's, because that attribute is an id list.
+
+### Why the primitive is handed a re-published context
+
+`TextFieldInput` and `SelectTrigger` read the enclosing `Field` themselves, and
+`TextFieldInput` resolves its name as `field.labelText ?? label` — a chain with no step for
+a name the CALLER wrote. Left alone, a box's `accessibilityLabel` would be outranked by the
+container's label, which is the one direction the composition contract says must never be
+reversed, and the rule would be resolved twice on two different inputs.
+
+So a box resolves membership once, through `useCardFormPart`, and re-publishes the answer
+to the primitive inside it: the same id, the same described ids with its own message
+already joined, the same invalid, required and disabled state — and no `labelText`, because
+the name has been decided and the primitive must not decide it again.
+
+It is a re-publication, not a shadow. Everything the field said still reaches the control,
+and the state that RESTRICTS has already been combined with `||`, so nothing inside can
+re-enable itself.
+
+## The layout
+
+```
+number               full width; the detected mark at the end of its label row
+expiry · code        one line, equal halves, 12 apart
+name                 full width, when fields.name (default on)
+country · postcode   one line, when either is asked for
+```
+
+The pair rows are `flexBasis: 0` rather than a minimum width, so a narrow container shrinks
+them evenly instead of overflowing: a card form is drawn in a sheet as often as on a page.
+
+`fields.postcode` and `fields.country` default OFF. Ask for a billing address only where it
+is actually asked for — most of the world does not use one, and a required postcode box is
+a wall for anyone whose country has no postcodes.
+
+## Small decisions worth naming
+
+- **The number box has no placeholder.** A placeholder in a card number box is a string of
+  digits that looks like a card number, which is the one thing a box holding card numbers
+  should not draw.
+- **The security code is not masked by default.** It is three or four characters, typed
+  once, from a card the person is holding; masking it hides typos without hiding anything
+  from anyone else. `secureSecurityCode` turns it on for the apps whose rules require it.
+- **The postcode is not tidied.** Not uppercased, not stripped of spaces, not validated:
+  postcodes are alphanumeric in most of the world and spaced differently in all of it.
+- **The name is never reformatted.** A name is not a number.
+- **`autoComplete`/`textContentType` are set**, so the platform's own card filler works.
+  That is the OS filling a box, and no different from typing.
+
+## Known gap
+
+`CardFormCountry` is Bloom's `Select`. Inside a `Field`, its trigger takes the field's
+wiring the way every select trigger does — but the country box's own `error` cannot be added
+to that trigger's `aria-describedby`, because `SelectTrigger` takes no such prop. The
+message is drawn; it is not announced as part of the control. Put a country message on the
+enclosing `Field` instead. This is a gap in `select`, not one this family can close.