bitboss-ui 3.0.0-beta.31 → 3.0.0-beta.33

package/README.md

@@ -17,9 +17,10 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheet
 ### TypeScript: use `vue-tsc` 3
 
 Use **`vue-tsc` 3 or newer**. Under `vue-tsc` 2 the template type-checker
-silently checks **nothing** about the props of the nine components declared with
-`generic="T"` — `BbSelect`, `BbSelectPopover`, `BbTable`, `BbTabs`,
-`BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup` —
+silently checks **nothing** about the props of the nine public components that
+use `<script setup generic="…">` — `BbSelect`, `BbSelectPopover`, `BbTable`,
+`BbTabs`, `BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`,
+`BbSwitchGroup` —
 because they emit as generic functions rather than `DefineComponent<…>`, a shape
 Vue Language Tools 2 cannot read props out of.
 
@@ -39,7 +40,7 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 | Composable             | Role                                                                  |
 | ---------------------- | --------------------------------------------------------------------- |
-| `useBbConfig`          | Global options for the kit (locale, defaults, etc.).                  |
+| `useBbConfig`          | `setConfig()` patches the one runtime-editable kit option: `locale`.  |
 | `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
 | `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
 | `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
@@ -116,15 +117,15 @@ For the public **Bb\*** components, the package exports matching **props**, **ev
 **For AI coding agents:**
 
 The same knowledge base the npm package ships is served publicly over a CDN, so
-an agent can read it before anything is installed. `@alpha` tracks the latest
-v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.5`) for stable
+an agent can read it before anything is installed. `@beta` tracks the latest
+v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-beta.32`) for stable
 links. Sizes grow with the catalogue — treat them as the current order of
 magnitude, not a contract.
 
-- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
-- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (~19 KB) — link index into every document.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (~190 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (~22 KB) — link index into every document.
 - [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
-- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (~4.3 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -142,24 +143,24 @@ This package is developed and maintained by [BitBoss](https://www.bitboss.it/),
 
 ## Installation
 
-**v3 is a prerelease: the `@alpha` tag is required.** A bare
+**v3 is a prerelease: the `@beta` tag is required.** A bare
 `npm install bitboss-ui` resolves to the v2 line, which has no build plugin and
 no `dist/ai` knowledge base — if you are following the v3 docs, that install
 will not work.
 
 ```bash
-npm install bitboss-ui@alpha
+npm install bitboss-ui@beta
 ```
 
 ```bash
-pnpm add bitboss-ui@alpha
+pnpm add bitboss-ui@beta
 ```
 
 ```bash
-yarn add bitboss-ui@alpha
+yarn add bitboss-ui@beta
 ```
 
-Verify with `npm ls bitboss-ui` — it must report `3.0.0-alpha.*`.
+Verify with `npm ls bitboss-ui` — it must report `3.0.0-beta.*`.
 
 ---
 
@@ -501,17 +502,17 @@ A standard `llms.txt` discovery file is also published at:
 
 ### Knowledge-base layout
 
-| Path                                  | Contents                                  |
-| ------------------------------------- | ----------------------------------------- |
-| `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next  |
-| `dist/ai/index.md`                    | Full catalogue + agent rules              |
-| `dist/ai/components.json`             | Machine-readable API (props/events/slots) |
-| `dist/ai/<ComponentName>.md`          | Guide-first contract per component        |
-| `dist/ai/composables/<name>.md`       | Composable docs                           |
-| `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                     |
-| `dist/ai/guides/*-playbook.md`        | Coherence / fetch / options / inline-edit |
-| `dist/ai/guides/migration/`           | v2 → v3 upgrade corpus                    |
-| `dist/ai/recipes/{vue,nuxt,inertia}/` | Page-level assemblies (11 × 3)            |
+| Path                                  | Contents                                                                             |
+| ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next                                             |
+| `dist/ai/index.md`                    | Full catalogue + agent rules                                                         |
+| `dist/ai/components.json`             | Machine-readable API (props/events/slots)                                            |
+| `dist/ai/<ComponentName>.md`          | Guide-first contract per component                                                   |
+| `dist/ai/composables/<name>.md`       | Composable docs                                                                      |
+| `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                                                                |
+| `dist/ai/guides/*-playbook.md`        | Coherence / fetch / options / inline-edit                                            |
+| `dist/ai/guides/migration/`           | v2 → v3 upgrade corpus                                                               |
+| `dist/ai/recipes/{vue,nuxt,inertia}/` | Page-level assemblies (9 vue / 9 nuxt / 10 inertia; Ownership Atlas is inertia-only) |
 
 ### Package exports
 
@@ -571,8 +572,8 @@ To make a report actionable, include:
 - whether it reproduces in dev, in a production build, or only under SSR
 - the smallest component snippet that shows it
 
-v3 ships as a prerelease (`npm i bitboss-ui@alpha`). Expect breaking changes
-between alphas; each one is recorded in the migration guides under
+v3 ships as a prerelease (`npm i bitboss-ui@beta`). Expect breaking changes
+between prereleases; each one is recorded in the migration guides under
 [`ai/guides/migration/`](ai/guides/migration/).
 
 ---

package/dist/ai/BbAsterisk.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Other**
-- Description: Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
+- Description: Presentational required-field marker (red "*"). No behaviour props/slots/events (only `pt`); placed in custom label content.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbAsterisk.md](./source/BbAsterisk.md)
 
@@ -13,7 +13,8 @@
 ### When to use
 
 `BbAsterisk` is the small red `*` that marks a field as required. It is purely
-presentational — it has no props, slots, or events, and it does not read
+presentational — it has no behaviour props, slots, or events (only `pt` to
+restyle its root), and it does not read
 `required` or drive validation. You render it yourself wherever you build custom
 label content, so the marker matches the library's styling (`--bb-danger`).
 

package/dist/ai/BbAvatar.md

@@ -648,6 +648,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--bg` | `.bb-avatar` | `var(--bb-primary)` | fallback surface (an image covers it) |
 | `--fg` | `.bb-avatar` | `var(--bb-primary-fg)` | Initials; the built-in icon is an 80/20 mix of this toward --bg |
 | `--default-icon-size` | `.bb-avatar` | `clamp(14px, calc(var(--size) * 0.7), 48px)` | Built-in fallback icon: 70% of the avatar, floored at 14px and capped at 48px. `--size` is the avatar's own box, set inline from the `size` prop. |
+| `--elev` | `.bb-avatar` | `var(--bb-elev-sm)` | The theme's resting lift on small chrome (Q44.15), declared here so an ancestor's `--elev` cannot reach in; `--elev: none` flattens one. |
 | `--size` | `.bb-avatar__default-icon` | `var(--default-icon-size)` |  |
 
 ## Component tree

package/dist/ai/BbBadge.md

@@ -891,11 +891,11 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-width` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
 | `--border-color` | `.bb-badge` | `transparent` |  |
 | `--ring` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring, per variant |
-| `--min-size-md` | `.bb-badge` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--font-size` | `.bb-badge` | `10px` | label |
+| `--font-size` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
 | `--padding-inline` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |

package/dist/ai/BbBadgeButton.md

@@ -87,11 +87,11 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-width` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
 | `--border-color` | `.bb-badge` | `transparent` |  |
 | `--ring` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring, per variant |
-| `--min-size-md` | `.bb-badge` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--font-size` | `.bb-badge` | `10px` | label |
+| `--font-size` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
 | `--padding-inline` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |

package/dist/ai/BbBaseCheckboxIcon.md

@@ -157,7 +157,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 ### Restyling with passthrough
 
 `pt` reaches the one part with a class list — or, in the object form, a
-style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focus-visible` — each
+style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focusVisible` — each
 true exactly while the glyph paints it, so they follow its own rules:
 `warnings` is off while `errors` is on.
 
@@ -202,7 +202,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`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `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: `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the box and draws the checkmark). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
 | `focused` | `boolean \| undefined` | `false` |  | Whether the paired native input has focus — any focus, mouse included. Paints `--focused`, the hook the `focused` passthrough state aliases (T19); draws nothing by itself — the ring stays on `focusVisible`. |
@@ -231,7 +231,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events
 

package/dist/ai/BbBaseRadioIcon.md

@@ -171,7 +171,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 ### Restyling with passthrough
 
 `pt` reaches the one part with a class list — or, in the object form, a
-style and attributes. Part: `root` (the drawn glyph). States: `checked`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focus-visible` — each
+style and attributes. Part: `root` (the drawn glyph). States: `checked`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focusVisible` — each
 true exactly while the glyph paints it, so they follow its own rules:
 `warnings` is off while `errors` is on.
 
@@ -217,7 +217,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`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `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: `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (grows the inner dot). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
 | `focused` | `boolean \| undefined` | `false` |  | Whether the paired native input has focus — any focus, mouse included. Paints `--focused`, the hook the `focused` passthrough state aliases (T19); draws nothing by itself — the ring stays on `focusVisible`. |
@@ -244,7 +244,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events
 

package/dist/ai/BbBaseSwitchIcon.md

@@ -167,7 +167,7 @@ from an ancestor — so `--w` set on a wrapper `div` is simply ignored
 ### Restyling with passthrough
 
 `pt` reaches the one part with a class list — or, in the object form, a
-style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focus-visible` — each
+style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focusVisible` — each
 true exactly while the glyph paints it, so they follow its own rules:
 `warnings` is off while `errors` is on.
 
@@ -213,7 +213,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`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `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: `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the track and slides the thumb to the end). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted track, not-allowed cursor). Purely visual. |
 | `focused` | `boolean \| undefined` | `false` |  | Whether the paired native input has focus — any focus, mouse included. Paints `--focused`, the hook the `focused` passthrough state aliases (T19); draws nothing by itself — the ring stays on `focusVisible`. |
@@ -242,7 +242,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events
 

package/dist/ai/BbBreadcrumbs.md

@@ -726,7 +726,7 @@ States are listed in precedence order: when two are on at once and their entries
     - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbBaseButton`, `BbIcon`, `CommonPopover`, `BbDropdownList`
       - `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`, `--r`, `--font-size`, `--icon-size`, `--gap`, `--padding-inline`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
     - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
-      - `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`, `--handle-w`, `--handle-h`, `--handle-bg`, `--close-size`
+      - `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`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
         - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
       - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbBaseButton`, `BbSpinner`
   - Also mounts `BbIcon`

package/dist/ai/BbButton.md

@@ -590,7 +590,9 @@ Escape hatches, when the default isn't right:
   handler opens a dialog and you don't want a spinner flash).
 - `interactive-while-loading` — keeps the button clickable while it shows the
   loading state, for controls that must stay interactive (this is how the
-  `BbDropdownButton` caret stays usable while the primary action runs).
+  `BbDropdownButton` caret stays usable while the primary action runs). The
+  soft-disable is dropped whole: no `aria-disabled`, the button stays in the tab
+  order, and the pointer still reaches it.
 
 The visually-hidden loading announcement is localized via the plugin's `locale`
 option. `disabled` and `loading` are independent props, and setting both is
@@ -848,6 +850,25 @@ never instead of it. The full grammar, the merge rules and the global map are
 in the [passthrough guide](./guides/passthrough.md); a look several
 buttons share is a `variant`, not a `pt`.
 
+**Padding, radius, font size and gap are the button's own.** `root` declares
+`padding-left` / `padding-right`, `border-radius`, `font-size` and `gap`,
+reading them from the active locals `--px`, `--r`, `--fs` and `--gap`, which
+the size class (`.bb-button--md` by default) sets. So in the default,
+unlayered build `pt:root="px-6 rounded-lg text-lg gap-2"` changes nothing, and
+`p-4` half-applies (top and bottom only) — measured in
+[Installation](./guides/installation-and-plugin-setup.md) § _What "the utility
+loses" actually means_. An arbitrary-property class (`[--r:12px]`) loses the
+same way: the size class out-specifies it. The object prop above, like any
+such class, only lands with `cssLayers: TAILWIND_V4_LAYERS`, where every
+utility wins. What works in every build:
+
+- a different `size` step, which moves height, padding, font, radius and icon
+  together;
+- the locals as an inline style, which nothing in the sheet outranks —
+  `:pt:root="{ style: { '--r': '9999px', '--px': '20px' } }"`;
+- a utility with Tailwind's important suffix (`px-6!`, `[--r:12px]!`), or a
+  rule of your own on `.bb-button` that out-specifies the size class.
+
 ### Works well with
 
 - `BbDropdownButton` — escalate to it when a primary action grows close

package/dist/ai/BbCalendar.md

@@ -470,20 +470,20 @@ and attributes — optionally only while a state is on. Parts: `root` (the
 calendar's box, where a consumer `class` lands too; it carries the sizing
 tokens, so `pt:root="[--pad-x:2px]"` tightens the padding and the grid width
 follows), `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 `year-item` (one button of the month / year
+buttons), `month` and `year` (the heading buttons), `columnHeader` (each
+weekday letter), `day` (one whole day cell) and `dayButton` (the button
+inside it), `monthItem` and `yearItem` (one button of the month / year
 panel).
 
 States: `root` is `disabled` while the calendar is; `arrow` is `disabled` at a
 `min` / `max` bound; `month` and `year` are `active` while their panel is
-open. The cells resolve per node — on `day` and `day-button`: `selected`,
+open. The cells resolve per node — on `day` and `dayButton`: `selected`,
 `disabled`, `today`, `outside` (a day of the previous or next month),
-`range-start` / `range-end` / `in-range` (a committed range) and `highlighted`
+`rangeStart` / `rangeEnd` / `inRange` (a committed range) and `highlighted`
 (the keyboard cursor). The panel items carry the same set without `today` and
 `outside`.
 
-`day` is the whole cell and `day-button` the rounded mark inside it: a
+`day` is the whole cell and `dayButton` the rounded mark inside it: a
 background on `pt:day` paints the full cell square, so restyle the mark on
 `pt:day-button`. The time rail is not a part.
 
@@ -522,7 +522,7 @@ the page is `BbDatePicker`.
 
 | 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`, `year`, `year-item`. States: `active`, `disabled`, `highlighted`, `in-range`, `outside`, `range-end`, `range-start`, `selected`, `today`. What each one is: _Passthrough parts and states_ below. `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`, `columnHeader`, `day`, `dayButton`, `header`, `month`, `monthItem`, `root`, `year`, `yearItem`. States: `active`, `disabled`, `highlighted`, `inRange`, `outside`, `rangeEnd`, `rangeStart`, `selected`, `today`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `activeSegment` | `BbCalendarSegment \| 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. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables every cell, the navigation and the time rail. |
@@ -552,22 +552,22 @@ the page is `BbDatePicker`.
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
 | `year` | The year heading button; it opens the year panel. |
-| `column-header` | Each weekday letter above the grid — a broadcast. |
-| `day` | One whole day cell — a broadcast resolved per day. A background here paints the full cell square; restyle the round mark on `day-button`. |
-| `day-button` | The button inside a day cell — the mark that shows selection. A broadcast resolved per day. |
-| `month-item` | One month button of the month panel (the home grid of `type="month"`) — a broadcast resolved per month. |
-| `year-item` | One year button of the year list — a broadcast resolved per year. |
+| `columnHeader` | Each weekday letter above the grid — a broadcast. |
+| `day` | One whole day cell — a broadcast resolved per day. A background here paints the full cell square; restyle the round mark on `dayButton`. |
+| `dayButton` | The button inside a day cell — the mark that shows selection. A broadcast resolved per day. |
+| `monthItem` | One month button of the month panel (the home grid of `type="month"`) — a broadcast resolved per month. |
+| `yearItem` | One year button of the year list — a broadcast resolved per year. |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
 
 | State | When it is on |
 | --- | --- |
-| `outside` | Per node, on `day` / `day-button`: a day of the previous or next month, shown to fill the grid. |
-| `today` | Per node, on `day` / `day-button`: today. |
-| `in-range` | Per node, on the cells (`day`, `day-button`, `month-item`, `year-item`): inside a committed range, between its ends. |
+| `outside` | Per node, on `day` / `dayButton`: a day of the previous or next month, shown to fill the grid. |
+| `today` | Per node, on `day` / `dayButton`: today. |
+| `inRange` | Per node, on the cells (`day`, `dayButton`, `monthItem`, `yearItem`): inside a committed range, between its ends. |
 | `selected` | Per node, on the cells: a chosen day, month or year. |
-| `range-start` | Per node, on the cells: a committed range's first day, month or year. |
-| `range-end` | Per node, on the cells: a committed range's last day, month or year. |
+| `rangeStart` | Per node, on the cells: a committed range's first day, month or year. |
+| `rangeEnd` | Per node, on the cells: a committed range's last day, month or year. |
 | `disabled` | Component-wide while the calendar is `disabled`. Also per node: on the cells, one outside `min` / `max` or refused by `selectable`; on `arrow`, at a bound or while the month / year panel is open. |
 | `active` | Per node, on `month` / `year`: its panel is open. |
 | `highlighted` | Per node, on the cells: the keyboard cursor. |
@@ -610,7 +610,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 `BbCalendar`'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 `BbCalendar`'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`.
 
-- `BbCalendar` _(this component)_ — its own template binds: `header` → `div.bb-calendar__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__date`, `day-button` → `button.bb-calendar__date-button`
+- `BbCalendar` _(this component)_ — its own template binds: `header` → `div.bb-calendar__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__date`, `dayButton` → `button.bb-calendar__date-button`
   - `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 `BbCalendar`)_ — documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
   - Also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`

package/dist/ai/BbCheckbox.md

@@ -476,12 +476,15 @@ const toggleAll = (checked: boolean) => {
 </script>
 ```
 
-### Layout: direction, alignment, `reverse`
+### Layout: `layout`, alignment, `reverse`
 
-- `direction` defaults to `'auto'` (label and box size to their content, on one
+- `layout` defaults to `'auto'` (label and box size to their content, on one
   line). `'horizontal'` splits label/box 50-50; `'vertical'` stacks them; a
   two-token pattern like `"x xxxxxxx"` splits proportionally by token length —
   the first token sizes the **visually first** element, the second the other.
+  `'label-fill'` hands the label the free space and keeps the box at its own
+  size; with `reverse` that is the settings row — label on the left, box on
+  the trailing edge. `'input-fill'` is the other way round.
 - The box renders **before** the label by default — the conventional checkbox
   arrangement. Setting `reverse` swaps the label in front of the box. It is an
   ordinary opt-in boolean: unset and `:reverse="false"` both give box-first,
@@ -490,7 +493,7 @@ const toggleAll = (checked: boolean) => {
   invisible from outside. Earlier revisions of this guide described that
   negation as a consumer-facing quirk — it is not.)
 - `input-position` / `label-position` (`'left' | 'center' | 'right'`) align box
-  and label text inside their columns — useful with percentage directions.
+  and label text inside their columns — useful with ratio layouts.
 - `hide-label` keeps the label for screen readers but hides it visually — only
   for dense composites where visible text lives elsewhere.
 - `id` is auto-generated for the label→input wiring; pass your own only when
@@ -670,11 +673,10 @@ map are 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: `description`, `hint`, `icon`, `label`, `message`, `root`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `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: `description`, `hint`, `icon`, `label`, `message`, `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
-| `direction` | `InputDirection \| undefined` | `"auto"` |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
 | `falseValue` | `any` |  |  | Value of the input when unchecked. It handles any kind of serializable object. |
@@ -687,6 +689,7 @@ map are in the [passthrough guide](./guides/passthrough.md).
 | `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `layout` | `FieldLayout \| undefined` | `"auto"` |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'` (the label takes the free space, the input keeps its size), `'input-fill'` (the other way round), or a two-word ratio pattern like `'xx… |
 | `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
@@ -721,7 +724,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events