bitboss-ui 3.0.0-beta.26 → 3.0.0-beta.28

package/bin/bitboss-ui-mcp.mjs

@@ -937,7 +937,7 @@ function buildServer() {
 					.boolean()
 					.optional()
 					.describe(
-						'Include reference-only internal components (BbBase*, Common*). Default false — these are not consumer API and should not be recommended.'
+						'Include reference-only internal components (Common*, listbox internals). Default false — these are not consumer API and should not be recommended. BbBaseButton and the BbBase*Icon glyphs are consumer API and are always included.'
 					),
 			},
 		},

package/dist/ai/BbColorInput.md

@@ -14,6 +14,7 @@
 
 | pt part | Lands on | In |
 | --- | --- | --- |
+| `pt:panel` | `pt:panel` of `BbColorPalette` | `BbColorPalette` ([contract](./BbColorPalette.md)) |
 | `pt:sheet` | `pt:sheet` of `BbColorPalette` | `BbColorPalette` ([contract](./BbColorPalette.md)) |
 | `pt:swatch` | `pt:swatch` of `BbColorPalette` | `BbColorPalette` ([contract](./BbColorPalette.md)) |
 | `pt:root` | `div.bb-field` | `CommonField` _(internal)_ |
@@ -504,7 +505,7 @@ the `BbTextInput` guide.
 
 `pt` reaches a named part of the control with a class list — or, in the
 object form, a style and attributes — optionally only while a state is on.
-Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `indicator` (the colour dot that opens the palette), `sheet` (the bottom sheet the color palette opens in on a phone — no node on desktop) and `swatch` (one palette swatch, after the `swatches` prop — a broadcast).
+Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `indicator` (the colour dot that opens the palette), `panel` (the palette box — the popover's painted bubble on desktop, the box inside the sheet on a phone), `sheet` (the bottom sheet the color palette opens in on a phone — no node on desktop) and `swatch` (one palette swatch, after the `swatches` prop — a broadcast).
 States: `errors`, `warnings` (never beside errors), `loading`, `disabled`, `readonly`, `has-value` (written `pt:box:has-value`), on every part; plus `selected` on `swatch` only — the swatch matching the value (`pt:swatch:selected`). A name outside that list is a type error and an
 ESLint error.
 
@@ -663,7 +664,7 @@ of it. The full grammar, the merge rules and the global map are in the
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `box`, `clear`, `description`, `hint`, `icon`, `indicator`, `input`, `label`, `message`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `swatch`. States: `disabled`, `errors`, `has-value`, `loading`, `readonly`, `warnings`, `selected`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `box`, `clear`, `description`, `hint`, `icon`, `indicator`, `input`, `label`, `message`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `swatch`. States: `disabled`, `errors`, `has-value`, `loading`, `readonly`, `warnings`, `selected`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the color palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbSelect`/`BbDatePickerInput`. When unset, falls back to … |
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. Shows an opacity slider and uses `#RRGGBBAA` hex8 format. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
@@ -757,10 +758,10 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbColorInput`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbColorInput`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbColorInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-color-input__input`, `input` → `input.bb-color-input__input`, `indicator` → `button.bb-color-input__indicator`, `suffix` → `span.bb-field-input__suffix`; hands `BbColorPalette` the pt map `{ sheet: 'sheet', swatch: 'swatch' }` (ours → theirs)
+- `BbColorInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-color-input__input`, `input` → `input.bb-color-input__input`, `indicator` → `button.bb-color-input__indicator`, `suffix` → `span.bb-field-input__suffix`; hands `BbColorPalette` the pt map `{ panel: 'panel', sheet: 'sheet', swatch: 'swatch' }` (ours → theirs)
   - `CommonField` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint-text`, `message` → `div.bb-field__errors`, `message` → `div.bb-field__warnings`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
-  - `BbColorPalette` _(public — [contract](./BbColorPalette.md))_ — its own pt parts (`BbColorPalette`): `root` → `div.bb-color-palette__picker`, `swatch` → `button.bb-color-palette__swatch`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs); also mounts `CommonPopover`
+  - `BbColorPalette` _(public — [contract](./BbColorPalette.md))_ — its own pt parts (`BbColorPalette`): `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs); also mounts `CommonPopover`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--close-size`
       - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
 

package/dist/ai/BbColorPalette.md

@@ -14,6 +14,7 @@
 
 | pt part | Lands on | In |
 | --- | --- | --- |
+| `pt:panel` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
 | `pt:sheet` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 
 ## Usage & Guidelines
@@ -556,9 +557,11 @@ styling (a caret, a highlight). Two props gate interaction:
 
 `pt` reaches a named part with a class list — or, in the object form, a
 style and attributes — optionally only while a state is on. Parts: `root`
-(the palette — canvas, sliders, swatches; the same node in the popover and in
-the sheet), `sheet` (the bottom sheet around it on a phone — no node on
-desktop) and `swatch` (one swatch, named after the `swatches` prop — a
+(the floating element — the bottom sheet on a phone), `panel` (the palette box you
+see: the popover's painted bubble on desktop, the box inside the sheet on a
+phone — canvas, sliders, swatches; `pt:panel="px-1"`
+tightens its padding), `sheet` (the bottom sheet on a phone only, applied
+after `root`) and `swatch` (one swatch, named after the `swatches` prop — a
 broadcast). States: `open`, and
 `selected` per swatch (the one matching the value). The canvas and the sliders
 are not parts.
@@ -733,7 +736,7 @@ The full grammar, the merge rules and the global map are in the
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`, `sheet`, `swatch`. States: `open`, `selected`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `panel`, `root`, `sheet`, `swatch`. States: `open`, `selected`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click listeners are attached programmatically to the referenced element — mirroring the BbDropdown activator API. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbPopover`/`BbDropdown`/`BbDatePicker`. When unset, falls back … |
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. The picker shows an opacity slider and emits `#RRGGBBAA` hex8 values. |
@@ -774,7 +777,7 @@ The full grammar, the merge rules and the global map are in the
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbColorPalette`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbColorPalette`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbColorPalette` _(this component)_ — its own template binds: `root` → `div.bb-color-palette__picker`, `swatch` → `button.bb-color-palette__swatch`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs)
+- `BbColorPalette` _(this component)_ — its own template binds: `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs)
   - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--close-size`
     - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
   - Also mounts `CommonPopover`

package/dist/ai/BbConfirm.md

@@ -72,6 +72,13 @@ Mounting a second host renders every dialog twice
 (nothing warns you). Mounting none is worse: `await confirm(...)` never settles
 and the caller hangs.
 
+**Areas with their own look.** The dialog takes the passthrough scope and the
+tokens of the place its HOST is mounted. When the app is split into areas that
+each wrap their pages in `<BbPtScope>` ([passthrough guide](./guides/passthrough.md) § Named scopes),
+mount one `<BbConfirm />` inside each area's layout, within its scope, and none
+at the app root — which holds only if **every** page renders inside exactly one
+of those layouts, so there is still one host at a time.
+
 ```vue
 <template>
 	<RouterView />
@@ -87,9 +94,12 @@ import { BbConfirm } from 'bitboss-ui';
 standalone example has no app root to mount it in.** In a real app the host is
 already mounted at the root; a page that calls `confirm()` mounts nothing.
 
-The component itself takes no props: everything — content, buttons, size,
-behavior — travels in the message you pass to `confirm()`. At least one of
-`title`, `text`, `portal` should be set (dev warning otherwise).
+The component itself takes almost no props: everything — content, buttons,
+behavior — travels in the message you pass to `confirm()`. The one exception is
+`size`, a host-wide default width every confirm inherits unless its message
+sets its own (see [Size, fullscreen and focus](#size-fullscreen-and-focus)).
+At least one of `title`, `text`, `portal` should be set (dev warning
+otherwise).
 
 ### The destructive flow
 
@@ -636,6 +646,8 @@ standard footer and resolve from inside the slot with its `yes` / `no` helpers.
 
 - `size` picks a maximum-width preset (`'xs'` … `'2xl'`, resolvable through
   the plugin config's `dialogDefaultSizes`); default confirms are compact.
+  To widen every confirm at once, set the same `size` on the host instead —
+  `<BbConfirm size="lg" />` — and let individual messages override it.
 - `fullscreen: true` takes over the whole screen; `fullscreen: 'mobile'`
   restricts that to small viewports.
 - `focusTarget` is a CSS selector focused after opening (default: the first
@@ -768,6 +780,7 @@ The full grammar, the merge rules and the global map are in the
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `action`, `close`, `content`, `footer`, `header`, `root`, `sheet`, `text`, `title`. States: `open`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `size` | `keyof Sizes \| undefined` |  |  | Default maximum width for every confirm this host renders, as one of the dialog presets (`'xs'` – `'2xl'`). A per-call `size` in the message wins. When neither is set the dialog falls back to the `BbDialog` default. |
 
 ## Events
 

package/dist/ai/BbDatePicker.md

@@ -17,6 +17,7 @@
 | `pt:arrow` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
 | `pt:month` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
 | `pt:year` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
+| `pt:panel` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
 | `pt:sheet` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 
 ## Usage & Guidelines
@@ -208,6 +209,12 @@ props with `offCanvasProps`). Position the desktop popover with `placement`,
 `offset`, `padding`, `boundary`, and `disableFlip` — the same knobs as the other
 overlays. Escape and backdrop clicks close it; focus returns to the activator.
 
+The sheet can be **dragged down to dismiss** and shows **no ✕** — picking,
+drag, backdrop tap and Escape close it. The time wheels and the year list are
+no-drag zones: a swipe there scrolls the list and never moves the sheet, even at
+its top. `offCanvasProps` is spread over those defaults: `{ hideClose: false }`
+brings the ✕ back, `{ draggable: false }` pins the sheet.
+
 ### The `v-bb-date` directive
 
 For the leanest case — a date cell in a table where you don't want a component
@@ -252,8 +259,11 @@ into, `BbDatePickerInput` when there is.
 
 `pt` reaches a named part with a class list — or, in the object form, a
 style and attributes — optionally only while a state is on. Parts: `root`
-(the calendar panel, in the popover and in the sheet alike), `sheet` (the
-bottom sheet around it on a phone — no node on desktop), `header` (the
+(the floating element — the bottom sheet on a phone), `panel` (the calendar box you
+see: the popover's painted bubble on desktop, the box inside the sheet on a
+phone — it also carries the sizing tokens, so
+`pt:panel="[--pad-x:2px]"` tightens the padding and the grid width follows), `sheet` (the
+bottom sheet on a phone only, applied after `root`), `header` (the
 navigation bar), `arrow` (the previous / next buttons), `month` and `year`
 (the heading buttons), `column-header` (each weekday letter), `day` (one whole
 day cell) and `day-button` (the button inside it), `month-item` and
@@ -355,7 +365,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `arrow`, `column-header`, `day`, `day-button`, `header`, `month`, `month-item`, `root`, `sheet`, `year`, `year-item`. States: `active`, `disabled`, `highlighted`, `in-range`, `open`, `outside`, `range-end`, `range-start`, `selected`, `today`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `arrow`, `column-header`, `day`, `day-button`, `header`, `month`, `month-item`, `panel`, `root`, `sheet`, `year`, `year-item`. States: `active`, `disabled`, `highlighted`, `in-range`, `open`, `outside`, `range-end`, `range-start`, `selected`, `today`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click + ARIA are attached programmatically to the referenced element — mirroring the `BbColorPalette` activator API. |
 | `activeSegment` | `BbDatePickerSegment \| undefined` |  |  | Which end the time rail edits in range + `type="datetime"` (`v-model:active-segment`). Standalone use manages this internally; an embedding host (the date input) drives it from its focused field. Ignored outside range + datetime. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
@@ -372,7 +382,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. |
 | `modelValue` | `string \| string[] \| null` |  | yes | v-model value. `null` for empty, a single string for single selection, or a two-element `[start, end]` array when `range` is true. The string shape follows `type`: `YYYY-MM-DD` when `floating` (`YYYY-MM` for `month`, `YYYY` for `year`), oth… |
 | `multiple` | `boolean \| undefined` | `false` |  | Enables multi-selection: every pick toggles a value in or out of a sorted array, and the panel stays open until it is dismissed. Works in whatever `type` selects — days, months or years — and requires an array `modelValue` (use `[]` for emp… |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when adaptive on mobile. |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). Spread over the defaults: the sheet is `draggable` (the time wheels and the year list never drag it) and hides its ✕ … |
 | `offset` | `number \| undefined` | `4` |  | Space the popover keeps from the activator. |
 | `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page. |
 | `placement` | `Placement \| undefined` |  |  | Position of the popover relative to the activator/anchor. |
@@ -410,14 +420,16 @@ Set these on the element, or on a class you put on it, to retune this component
 
 | Property | Set on | Default | What it is |
 | --- | --- | --- | --- |
-| `--cell` | `.bb-date-picker__grid` | `28px` | Cell size drives all grid math: 224px ÷ 7 = 32px exactly |
-| `--pad-x` | `.bb-date-picker__grid` | `6px` |  |
-| `--pad-y` | `.bb-date-picker__grid` | `8px` |  |
-| `--nav-button-h` | `.bb-date-picker__grid` | `24px` |  |
+| `--cell` | `.bb-date-picker__panel` | `28px` | Cell size drives all grid math: 224px ÷ 7 = 32px exactly |
+| `--pad-x` | `.bb-date-picker__panel` | `6px` |  |
+| `--pad-y` | `.bb-date-picker__panel` | `8px` |  |
+| `--nav-button-h` | `.bb-date-picker__panel` | `24px` |  |
+| `--day-slot-allowance` | `.bb-date-picker__panel` | `0px` | Allowance for the day slot append area - needed for the slot to be visible |
+| `--unit-row` | `.bb-date-picker__panel` | `calc(var(--cell) * 1.25)` | Row pitch for the coarse grids (month/year), where a "row" is one of four month rows rather than a week. Roomier than --cell because twelve months in a 4×3 grid have space the 6×7 day grid does not. |
 | `--weeks` | `.bb-date-picker__grid` | `6` |  |
-| `--day-slot-allowance` | `.bb-date-picker__grid` | `0px` | Allowance for the day slot append area - needed for the slot to be visible |
-| `--unit-row` | `.bb-date-picker__grid` | `calc(var(--cell) * 1.25)` | Row pitch for the coarse grids (month/year), where a "row" is one of four month rows rather than a week. Roomier than --cell because twelve months in a 4×3 grid have space the 6×7 day grid does not. |
-| `--sheet-cell` | `.bb-date-picker__calendar--sheet` | `40px` | Declared on the container so the time rail (the calendar's sibling) can align its wheels to the same column grid. |
+| `--sheet-cell` | `.bb-date-picker__panel--sheet` | `40px` | Declared on the container so the time rail (the calendar's sibling) can align its wheels to the same column grid. |
+| `--cell` | `.bb-date-picker__panel--sheet` | `var(--sheet-cell)` | One touch scale for the whole sheet: 40px day cells (36px marks), and a nav row to match — on the panel, where the tokens live. |
+| `--nav-button-h` | `.bb-date-picker__panel--sheet` | `40px` |  |
 
 ## Component tree
 
@@ -428,7 +440,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbDatePicker`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbDatePicker`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbDatePicker` _(this component)_ — its own template binds: `root` → `div.bb-date-picker__calendar`, `header` → `div.bb-date-picker__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-date-picker__date`, `day-button` → `button.bb-date-picker__date-button`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs)
+- `BbDatePicker` _(this component)_ — its own template binds: `header` → `div.bb-date-picker__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-date-picker__date`, `day-button` → `button.bb-date-picker__date-button`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs)
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - `CommonTimeSelector` _(internal — not importable, reach it through `BbDatePicker`)_ — documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
   - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--close-size`

package/dist/ai/BbDatePickerInput.md

@@ -14,7 +14,7 @@
 
 | pt part | Lands on | In |
 | --- | --- | --- |
-| `pt:panel` | `pt:root` of `BbDatePicker` | `BbDatePicker` ([contract](./BbDatePicker.md)) |
+| `pt:panel` | `pt:panel` of `BbDatePicker` | `BbDatePicker` ([contract](./BbDatePicker.md)) |
 | `pt:sheet` | `pt:sheet` of `BbDatePicker` | `BbDatePicker` ([contract](./BbDatePicker.md)) |
 | `pt:header` | `pt:header` of `BbDatePicker` | `BbDatePicker` ([contract](./BbDatePicker.md)) |
 | `pt:arrow` | `pt:arrow` of `BbDatePicker` | `BbDatePicker` ([contract](./BbDatePicker.md)) |
@@ -206,6 +206,13 @@ An incomplete date is never emitted: the model updates only once a segment
 parses to a real date, and a half-typed segment is restored to the last coherent
 value when focus leaves the control.
 
+Native attributes that describe typing — `spellcheck`, `autocapitalize`,
+`autocorrect`, `enterkeyhint` — and `form` go to **every segment** (each one
+is a real `<input>` that posts its own `<name>-<field>`); `maxlength`,
+`pattern` and `list` are not routed, because each segment sets its own length
+and parses its own digits. Any other attribute lands on the field root; a
+`pt:input` attribute reaches every segment and wins over the routed ones.
+
 ### Bounds & per-day gating
 
 `min` and `max` (each a `YYYY-MM-DD` string) constrain the selectable window;
@@ -543,8 +550,10 @@ The picker adapts to touch vs pointer, and you can steer that explicitly:
 - **`adaptive`** (defaults to the project's `config.adaptive`): on mobile the
   calendar opens in a bottom `BbOffCanvas` sheet instead of a floating popover.
   The surface is **latched** when the panel opens, so a mid-session resize never
-  swaps a live popover into a sheet. Forward sheet options via `offCanvasProps`
-  (e.g. `title`, `size`, `persistent`, `draggable`). Set `:adaptive="false"` to
+  swaps a live popover into a sheet. The sheet drags down to dismiss and shows
+  no ✕ (the time wheels and the year list never drag it). Forward sheet options
+  via `offCanvasProps`, spread over those defaults (e.g. `title`, `size`,
+  `persistent`, `{ hideClose: false }` to bring the ✕ back). Set `:adaptive="false"` to
   force the floating popover on every viewport (deterministic in tests).
 - **`disableWriting`**: block typing so the calendar is the only way in. Use
   `'mobile'` / `'desktop'` to disable typing on just one platform.
@@ -707,7 +716,7 @@ the `BbTextInput` guide.
 
 `pt` reaches a named part of the control with a class list — or, in the
 object form, a style and attributes — optionally only while a state is on.
-Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `panel` (the calendar, in the popover and in the sheet alike), `sheet` (the bottom sheet around it on a phone only) and the calendar's own parts, forwarded to it: `header`, `arrow`, `month`, `year`, `column-header`, `day` (the whole cell), `day-button` (the mark inside it), `month-item` and `year-item` — the `BbDatePicker` guide describes each node. `input` is every segment field; the calendar trigger is chrome.
+Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `panel` (the calendar box you see — the popover's painted bubble on desktop, the box inside the sheet on a phone; it carries the sizing tokens, so `pt:panel="[--pad-x:2px]"` tightens it), `sheet` (the bottom sheet on a phone only) and the calendar's own parts, forwarded to it: `header`, `arrow`, `month`, `year`, `column-header`, `day` (the whole cell), `day-button` (the mark inside it), `month-item` and `year-item` — the `BbDatePicker` guide describes each node. `input` is every segment field; the calendar trigger is chrome.
 States: `errors`, `warnings` (never beside errors), `loading`, `disabled`, `readonly`, `has-value` (written `pt:box:has-value`). Plus `open` (the calendar is showing), and the calendar's per-node states: `selected`, `disabled`, `today`, `outside`, `range-start` / `range-end` / `in-range` and `highlighted` on the cells, `active` on `month` / `year`. A name outside that list is a type error and an
 ESLint error.
 
@@ -871,7 +880,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
 | `modelValue` | `string \| string[] \| null` |  | yes | Used by v-model. Can be null, a single string, or an array of strings based on whether a range or single date is needed. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). Spread over the defaults: the sheet is `draggable` (the time wheels and the year list never drag it) and hides its ✕ … |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
@@ -942,8 +951,8 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbDatePickerInput`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbDatePickerInput`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbDatePickerInput` _(this component)_ — its own template binds: `input` → `input.bb-segmented-field__field`, `suffix` → `span.bb-field-input__suffix`; hands `BbDatePicker` the pt map `{ panel: 'root', sheet: 'sheet', header: 'header', arrow: 'arrow', month: 'month', year: 'year', 'column-header': 'column-header', day: 'day', 'day-button': 'day-button', 'month-item': 'month-item', 'year-item': 'year-item', }` (ours → theirs)
-  - `BbDatePicker` _(public — [contract](./BbDatePicker.md))_ — its own pt parts (`BbDatePicker`): `root` → `div.bb-date-picker__calendar`, `header` → `div.bb-date-picker__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-date-picker__date`, `day-button` → `button.bb-date-picker__date-button`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs); documented CSS variables: `--cell`, `--day-slot-allowance`, `--unit-row`, `--sheet-cell`; also mounts `CommonPopover`, `ScaleFade`, `Slide`, `DatePickerMonthPanel`, `DatePickerYearPanel`
+- `BbDatePickerInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-segmented-field__field`, `input` → `input.bb-segmented-field__field`, `suffix` → `span.bb-field-input__suffix`; hands `BbDatePicker` the pt map `{ panel: 'panel', sheet: 'sheet', header: 'header', arrow: 'arrow', month: 'month', year: 'year', 'column-header': 'column-header', day: 'day', 'day-button': 'day-button', 'month-item': 'month-item', 'year-item': 'year-item', }` (ours → theirs)
+  - `BbDatePicker` _(public — [contract](./BbDatePicker.md))_ — its own pt parts (`BbDatePicker`): `header` → `div.bb-date-picker__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-date-picker__date`, `day-button` → `button.bb-date-picker__date-button`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs); documented CSS variables: `--cell`, `--day-slot-allowance`, `--unit-row`, `--sheet-cell`, `--cell`; also mounts `CommonPopover`, `ScaleFade`, `Slide`, `DatePickerMonthPanel`, `DatePickerYearPanel`
     - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
     - `CommonTimeSelector` _(internal — not importable, reach it through `BbDatePicker`)_ — documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--close-size`

package/dist/ai/BbDropdownButton.md

@@ -484,7 +484,10 @@ the menu becomes on a phone, only), `item` (every entry), and `item-text` /
 `item-icon` / `item-description` (an entry's label, its icons and its muted
 second line) — all handed to the `BbDropdown` under the same words, so
 `pt:panel:open`, `pt:item:disabled` and `pt:item-text` resolve there, on the
-flyout and on the phone sheet alike. States: `loading`, `disabled`, `open`.
+flyout and on the phone sheet alike. States: `loading`, `disabled`, `open` on
+every part, and `selected` (a selectable group's checked entry) on the entry
+parts only — `pt:item:selected` is the menu's word, `pt:root:selected` a type
+error.
 
 The Save split on INV-2048, restyled through those parts: the brand token on
 `pt:icon` (the main button's glyph — the chevron is chrome), muted
@@ -592,7 +595,7 @@ The full grammar, the merge rules and the global map are in the
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `icon`, `item`, `item-description`, `item-icon`, `item-text`, `panel`, `root`, `sheet`, `spinner`, `text`. States: `disabled`, `loading`, `open`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `icon`, `item`, `item-description`, `item-icon`, `item-text`, `panel`, `root`, `sheet`, `spinner`, `text`. States: `disabled`, `loading`, `open`, `selected`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
 | `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
 | `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async actions (enabled by default). Only affects the main action button: the split toggle half still mirrors the dropdown's internal async-action loading state. |

package/dist/ai/BbPtScope.md

@@ -0,0 +1,136 @@
+# BbPtScope
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Layout & Utility**
+- Description: Renderless provider that switches on a named passthrough scope (`ptScopes` in the plugin config) for its subtree — a backoffice and a member area with different looks in one app.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbPtScope.md](./source/BbPtScope.md)
+
+## Usage & Guidelines
+
+### When to use
+
+The global passthrough map (`bitbossUi({ pt })`) styles every instance in the
+app. When the app has **areas with different looks** — a backoffice next to a
+member webapp, per-tenant areas, a marketing section beside the product — give
+each area a named map in `ptScopes` and wrap the area in `<BbPtScope>`:
+
+```ts
+// bitboss-ui.pt.ts
+import { definePt } from 'bitboss-ui/vite';
+
+export const pt = definePt({
+	BbTextInput: { label: 'text-xs font-medium' },
+});
+
+export const ptScopes = {
+	webapp: definePt({
+		BbTextInput: { label: 'text-white/60' },
+		BbButton: { root: 'rounded-full' },
+	}),
+	backoffice: definePt({
+		BbButton: { root: 'rounded-md' },
+	}),
+};
+```
+
+```vue
+<!-- WebappLayout.vue -->
+<template>
+	<BbPtScope name="webapp">
+		<slot />
+	</BbPtScope>
+</template>
+
+<script setup lang="ts">
+import { BbPtScope } from 'bitboss-ui';
+</script>
+```
+
+Everything rendered inside the scope — however deep — resolves the `webapp`
+entries on top of the global map. Outside it, nothing changes.
+
+### Order and nesting
+
+For each part, the sources merge in this order:
+
+1. the global map (`pt`),
+2. every active scope, outermost `<BbPtScope>` first,
+3. the instance's `class`, `pt` object and `pt:*` attributes.
+
+Nested scopes **add up**: an inner scope merges after the outer one, it never
+hides it. Everything goes through the same merge and class deduper as the rest
+of `pt`, so a conflicting utility on an instance replaces the scope's.
+
+```vue
+<template>
+	<BbPtScope name="webapp">
+		<!-- the scope's `rounded-full`, then this instance's `rounded-none` wins -->
+		<BbButton pt:root="rounded-none">Save</BbButton>
+	</BbPtScope>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbPtScope } from 'bitboss-ui';
+</script>
+```
+
+### The name is typed
+
+`name` is a `BbPtScopeName`: the plugin generates the union of your `ptScopes`
+keys (`'webapp' | 'backoffice'`) when the dev server or a build runs, so a
+misspelt scope is a `vue-tsc` error. Every component name and key inside a
+scope is checked against the library's manifest at build time, exactly like
+the global map. `name` is reactive: switching it restyles the subtree.
+
+### Overlays, directives, toasts and confirms
+
+The scope follows the **component tree**, not the DOM:
+
+- A dialog, sheet, popover, dropdown or picker opened inside the scope resolves
+  it wherever it paints.
+- `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-date`, `v-bb-time` and `v-bb-color`
+  resolve the scope around the component whose **template** they are written
+  in. A directive written directly in `<BbPtScope>`'s slot, in the same
+  template as the scope, sees the scope above it instead — keep the scope in a
+  layout or a parent component.
+- `<BbToast>` and `<BbConfirm>` render every message where the **host** is
+  mounted. For toasts and confirms in the area's look, mount one of each inside
+  each area's layout, within its scope, and none at the app root — valid only
+  when every page renders inside exactly one of those layouts (see
+  [Agent Contract § Global Host Rule](./guides/agent-contract.md)).
+
+### When NOT to use it
+
+- **One look for the whole app** — that is the global `pt` map.
+- **Colours, radii, sizes for a subtree** — those are tokens: a `.bb-theme`
+  island ([design tokens](./guides/design-tokens.md)). A scope restyles parts;
+  an area usually wants both.
+- **One instance** — use `pt:*` on that instance.
+
+### Works well with
+
+- `BbToast` / `BbConfirm` — mount their hosts inside each scoped area layout.
+- The [passthrough guide](./guides/passthrough.md) — grammar, merging and the
+  full parts table.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `BbPtScopeName` |  | yes | The scope to switch on for everything inside: a key of the plugin's `ptScopes` option (`BbPtScopeName`, generated from your config). Nested scopes add up: the outer scope's entries apply first, the inner scope's after them. Reactive — chang… |
+
+## Events
+
+- None.
+
+## Slots
+
+- `default` — scope: `any` — The subtree the scope applies to. Rendered as is — no wrapper element.
+
+## See Also
+
+- [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).
+- [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).

package/dist/ai/BbSelect.md

@@ -14,7 +14,7 @@
 
 | pt part | Lands on | In |
 | --- | --- | --- |
-| `pt:panel` | `pt:root` of `BbSelectPopover` | `BbSelectPopover` ([contract](./BbSelectPopover.md)) |
+| `pt:panel` | `pt:panel` of `BbSelectPopover` | `BbSelectPopover` ([contract](./BbSelectPopover.md)) |
 | `pt:sheet` | `pt:sheet` of `BbSelectPopover` | `BbSelectPopover` ([contract](./BbSelectPopover.md)) |
 | `pt:option` | `pt:option` of `BbSelectPopover` | `BbSelectPopover` ([contract](./BbSelectPopover.md)) |
 | `pt:item-text` | `pt:item-text` of `BbSelectPopover` | `BbSelectPopover` ([contract](./BbSelectPopover.md)) |
@@ -1576,7 +1576,7 @@ the `BbTextInput` guide.
 
 `pt` reaches a named part of the control with a class list — or, in the
 object form, a style and attributes — optionally only while a state is on.
-Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `panel` (the options surface — the sheet on mobile), `sheet` (that bottom sheet on a phone only, applied after `panel`) `option` (one listbox option, a broadcast), `item-text` (that option's label), `item-icon` (its `itemProps` prepend / append icons — never the field's `icon`) and `item-description` (its muted second line from `itemProps.description` — never the field's `description`), all with the option's `selected` / `disabled`; a custom `#option` slot replaces the label and description. `input` is the activator — the thing you act on to enter the value; the chevron and the clear ✕ are chrome.
+Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `panel` (the options box you see — the popover's painted bubble on desktop, the box inside the sheet on a phone), `sheet` (the bottom sheet on a phone only), `option` (one listbox option, a broadcast), `item-text` (that option's label), `item-icon` (its `itemProps` prepend / append icons — never the field's `icon`) and `item-description` (its muted second line from `itemProps.description` — never the field's `description`), all with the option's `selected` / `disabled`; a custom `#option` slot replaces the label and description. `input` is the activator — the thing you act on to enter the value; the chevron and the clear ✕ are chrome.
 States: `errors`, `warnings` (never beside errors), `loading`, `disabled`, `readonly`, `has-value` (written `pt:box:has-value`). Plus `open` (the options surface is showing) and `selected`, resolved per option. A name outside that list is a type error and an
 ESLint error.
 
@@ -1665,6 +1665,12 @@ The full grammar, the merge rules and the global map are in the
 
 ### Gotchas and constraints
 
+- **A `form` attribute goes to the hidden inputs** — the select's value
+  channel — so a select rendered outside its `<form>` still posts with it
+  (`form="checkout"`). No other native attribute is routed: the activator is a
+  button, not a text field, so `spellcheck` and friends have nothing to land
+  on and stay on the field root like any attribute.
+
 - **Clicking the selected option does not clear a single select** — it re-picks
   it and closes the panel. Add `clearable` for an explicit clear button; a
   required status field should not empty itself because someone clicked twice.
@@ -1863,11 +1869,11 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbSelect`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbSelect`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbSelect` _(this component)_ — its own template binds: `input` → `input.bb-select__activator`; hands `BbSelectPopover` the pt map `{ panel: 'root', sheet: 'sheet', option: 'option', 'item-text': 'item-text', 'item-icon': 'item-icon', 'item-description': 'item-description', }` (ours → theirs)
+- `BbSelect` _(this component)_ — its own template binds: `input` → `input.bb-select__activator`, `controlAttrs` → `input`; hands `BbSelectPopover` the pt map `{ panel: 'panel', sheet: 'sheet', option: 'option', 'item-text': 'item-text', 'item-icon': 'item-icon', 'item-description': 'item-description', }` (ours → theirs)
   - `CommonField` _(internal — not importable, reach it through `BbSelect`)_ — `BbSelect`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint-text`, `message` → `div.bb-field__errors`, `message` → `div.bb-field__warnings`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbSelect`)_ — `BbSelect`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
   - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`; documented CSS variables: `--bg`, `--fg`, `--border-width`, `--ring`, `--min-size-md`, `--min-size`, `--elev`, `--radius`, `--font-size`, `--icon-size`, `--gap`, `--padding-inline`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
-  - `BbSelectPopover` _(public — [contract](./BbSelectPopover.md))_ — its own pt parts (`BbSelectPopover`): `input` → `input.bb-select-popover__search-input`, `clear` → `ClearableButton`, `root` → `BbOffCanvas`, `root` → `CommonPopover`, `header` → `div.bb-select-popover__header`, `footer` → `div.bb-select-popover__footer`; hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', sheet: 'root' }` (ours → theirs); also mounts `BbBadge`, `BbIcon`, `ClearableButton`, `CommonPopover`, `ErrorIcon`, `WarningIcon`, `BbSmoothHeight`
+  - `BbSelectPopover` _(public — [contract](./BbSelectPopover.md))_ — its own pt parts (`BbSelectPopover`): `input` → `input.bb-select-popover__search-input`, `clear` → `ClearableButton`, `root` → `BbOffCanvas`, `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-select-popover__header`, `footer` → `div.bb-select-popover__footer`; hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', sheet: 'root' }` (ours → theirs); also mounts `BbBadge`, `BbIcon`, `ClearableButton`, `CommonPopover`, `ErrorIcon`, `WarningIcon`, `BbSmoothHeight`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--close-size`
       - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
     - `ListBox` _(internal — not importable, reach it through `BbSelectPopover`)_

package/dist/ai/BbSelectPopover.md

@@ -16,6 +16,7 @@
 | --- | --- | --- |
 | `pt:clear` | the root of `ClearableButton` | `ClearableButton` _(internal)_ |
 | `pt:root` | the root of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
+| `pt:panel` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
 | `pt:root` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
 | `pt:header` | `pt:header` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 | `pt:footer` | `pt:footer` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
@@ -1326,18 +1327,18 @@ floating popover everywhere.
 
 `pt` reaches a named part of the popover with a class list — or, in the
 object form, a style and attributes — optionally only while a state is on.
-Parts: `root` (the flyout — the sheet on mobile), `sheet` (the bottom sheet the surface becomes on a phone — only that sheet, never the desktop surface; applied after `root`, so it wins a conflict there), `input` (the search
+Parts: `root` (the floating element — the sheet on a phone), `panel` (the options box you see: the popover's painted bubble on desktop, the box inside the sheet on a phone), `sheet` (the bottom sheet the surface becomes on a phone — only that sheet, never the desktop surface; applied after `root`, so it wins a conflict there), `input` (the search
 field), `option` (every listbox option, a broadcast resolved per option), `item-text` (that option's label), `item-icon` (its `itemProps` icons) and `item-description` (its muted second line, `itemProps.description`) — all with the option's states; a custom `#option` slot replaces the label and description,
 `header`, `footer`. States: `open`, and `selected` / `disabled` per option.
 `BbSelect` forwards its own `panel` / `sheet` / `option` here.
 
 The filter-pill assignee picker above, restyled through those parts: mono on
 the search `pt:input`, a muted wash on the chosen option
-(`pt:option:selected` is per node), a primary ring on `pt:root:open` (the
-flyout — the sheet on mobile). The activator is yours; don't restyle it
+(`pt:option:selected` is per node), a primary ring on `pt:panel:open` (the
+options box — the box inside the sheet on a phone). The activator is yours; don't restyle it
 through `pt`.
 
-**pt:input / pt:option:selected / pt:root:open — assignee pill**
+**pt:input / pt:option:selected / pt:panel:open — assignee pill**
 
 ```vue
 <template>
@@ -1355,7 +1356,7 @@ through `pt`.
 			:items="teammates"
 			pt:input="font-mono text-sm"
 			pt:option:selected="bg-(--bb-muted) font-semibold"
-			pt:root:open="ring-1 ring-(--bb-primary)"
+			pt:panel:open="ring-1 ring-(--bb-primary)"
 			width="240px"
 		>
 			<template #activator="{ props }">
@@ -1385,7 +1386,7 @@ type Teammate = {
 
 // Same filter-pill assignee picker as `AssigneePicker.vue`, restyled through
 // passthrough: mono on the search `pt:input`, a muted wash on the chosen
-// option (`pt:option:selected` is per node), a primary ring on `pt:root:open`
+// option (`pt:option:selected` is per node), a primary ring on `pt:panel:open`
 // (the flyout — the sheet on mobile).
 const teammates: Teammate[] = [
 	{ id: 'ada', fullName: 'Ada Lovelace' },
@@ -1524,7 +1525,7 @@ in the [passthrough guide](./guides/passthrough.md).
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `clear`, `footer`, `header`, `input`, `item-description`, `item-icon`, `item-text`, `option`, `root`, `sheet`. States: `disabled`, `open`, `selected`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `clear`, `footer`, `header`, `input`, `item-description`, `item-icon`, `item-text`, `option`, `panel`, `root`, `sheet`. States: `disabled`, `open`, `selected`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. The sheet reuses the same search field and options list, adding a representation of the current sele… |
 | `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `null` |  | Override the element used for popover positioning and width measurement. Useful when the focusable activator is narrower than its visual container (e.g. a button inside a wrapper). Falls back to `activatorEl` when omitted. |
@@ -1616,7 +1617,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbSelectPopover`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbSelectPopover`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbSelectPopover` _(this component)_ — its own template binds: `input` → `input.bb-select-popover__search-input`, `clear` → `ClearableButton`, `root` → `BbOffCanvas`, `root` → `CommonPopover`, `header` → `div.bb-select-popover__header`, `footer` → `div.bb-select-popover__footer`; hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', sheet: 'root' }` (ours → theirs)
+- `BbSelectPopover` _(this component)_ — its own template binds: `input` → `input.bb-select-popover__search-input`, `clear` → `ClearableButton`, `root` → `BbOffCanvas`, `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-select-popover__header`, `footer` → `div.bb-select-popover__footer`; hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', sheet: 'root' }` (ours → theirs)
   - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`; documented CSS variables: `--bg`, `--fg`, `--border-width`, `--ring`, `--min-size-md`, `--min-size`, `--elev`, `--radius`, `--font-size`, `--icon-size`, `--gap`, `--padding-inline`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
   - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--close-size`
     - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`