bitboss-ui 3.0.0-beta.32 → 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/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/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
@@ -674,7 +677,6 @@ map are in the [passthrough guide](./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. |

package/dist/ai/BbCheckboxGroup.md

@@ -148,12 +148,12 @@ control.
 	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-3">
 		<BbCheckboxGroup
 			v-model="addons"
-			input-direction="vertical"
 			:item-props="{ description: 'summary' }"
 			item-text="name"
 			item-value="id"
 			:items="catalog"
 			legend="Add-ons"
+			list-layout="vertical"
 			name="addons"
 		>
 			<!-- The group's OWN description, under the legend. A slot, so it can
@@ -265,9 +265,9 @@ choice out. Pair it with a `hint` that states the limit.
 			v-model="topics"
 			compact
 			hint="You can change these anytime."
-			input-direction="horizontal"
 			:items="allTopics"
 			legend="Topics"
+			list-layout="horizontal"
 			:max="3"
 			name="topics"
 			persistent-hint
@@ -354,11 +354,18 @@ disabling it.
 
 ### Layout and density
 
-- `input-direction` (`'horizontal' | 'vertical'`) arranges the **options**
-  within the fieldset — a row for compact filter bars, a stack for readability.
-- `direction` arranges the **legend against the options block** (the outer
-  label/control split): `'auto'`, `'horizontal'`, `'vertical'`, or a
-  proportional pattern like `'xx xxxxxx'`.
+- `list-layout` arranges the **options** within the fieldset: `'horizontal'`
+  (the default — a wrapping row, for compact filter bars), `'vertical'` (a
+  stack, each row its own width), `'vertical-stretch'` (a stack, each row as
+  wide as the list) or `'tiles'` (equal-size boxes that wrap as the field
+  narrows; `pt:list="[--tile-min-width:160px]"` sets how narrow one gets).
+- `item-layout` arranges **each row** — its input against its label — with the
+  same keywords as `layout`; `item-reverse` swaps the two. A settings list is
+  `list-layout="vertical-stretch" item-layout="label-fill" item-reverse`: the
+  label takes the row, the input sits at the trailing edge.
+- `layout` arranges the **legend against the options block** (the outer
+  split): `'auto'`, `'horizontal'`, `'vertical'`, `'label-fill'`,
+  `'input-fill'`, or a proportional pattern like `'xx xxxxxx'`.
 - `compact` tightens per-option spacing for dense groups.
 - `input-position` / `legend-position` (`'left' | 'center' | 'right'`) align the
   options and the legend text within their columns.
@@ -368,6 +375,238 @@ disabling it.
 - `hide-legend` keeps the legend for assistive tech but hides it visually;
   `hide-label` hides the individual option labels (dense composites only).
 
+#### Layout recipes
+
+Three ready compositions, each driven by `list-layout` / `item-layout` with
+`pt` only for the look.
+
+A **filter facet** — every row as wide as the panel, the label cell filling it
+so the count sits on the trailing edge:
+
+**Filter facet with counts**
+
+```vue
+<template>
+	<div class="w-64 rounded-(--bb-radius) border bg-(--bb-panel) p-1.5">
+		<div class="flex items-center justify-between px-2 pt-1 pb-1.5">
+			<span class="text-sm font-medium">Status</span>
+			<BbButton
+				:disabled="!statuses.length"
+				size="xs"
+				variant="ghost"
+				@click="statuses = []"
+				>Clear</BbButton
+			>
+		</div>
+		<BbCheckboxGroup
+			v-model="statuses"
+			hide-legend
+			item-layout="label-fill"
+			item-text="name"
+			item-value="id"
+			:items="options"
+			legend="Status"
+			list-layout="vertical-stretch"
+			name="status"
+			pt:item="rounded-[calc(var(--bb-radius)-4px)] px-2 py-1.5 hover:bg-(--bb-muted)"
+			pt:label="text-sm"
+			pt:list="[--row-gap:0px]"
+		>
+			<template #label="{ item }">
+				<span class="flex items-baseline justify-between gap-3">
+					<span>{{ item.name }}</span>
+					<span class="text-xs text-(--bb-text-muted) tabular-nums">{{
+						item.count
+					}}</span>
+				</span>
+			</template>
+		</BbCheckboxGroup>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbCheckboxGroup } from 'bitboss-ui';
+
+type Status = { id: string; name: string; count: number };
+
+// A filter facet. `list-layout="vertical-stretch"` makes every row as wide as
+// the panel (the whole row is the hit area, so the hover wash reads as one
+// target) and `item-layout="label-fill"` hands the label cell the free space,
+// so a flex row inside the `#label` slot pushes the count to the trailing
+// edge. The visible heading is our own, beside the Clear action; the legend
+// stays for assistive tech (`hide-legend`).
+const options: Status[] = [
+	{ id: 'draft', name: 'Draft', count: 12 },
+	{ id: 'open', name: 'Open', count: 48 },
+	{ id: 'overdue', name: 'Overdue', count: 7 },
+	{ id: 'paid', name: 'Paid', count: 214 },
+	{ id: 'void', name: 'Void', count: 3 },
+];
+
+const statuses = ref<string[]>(['open', 'overdue']);
+</script>
+```
+
+A **weekday picker** — seven equal toggles with the box hidden
+(`pt:icon="hidden"`; an empty `#icon` slot would fall back to the box), the
+checked day painted, the hint reading the choice back:
+
+**Weekday picker**
+
+```vue
+<template>
+	<div class="max-w-md">
+		<BbCheckboxGroup
+			v-model="days"
+			:hint="summary"
+			item-layout="vertical"
+			item-text="short"
+			item-value="id"
+			:items="weekdays"
+			legend="Send reminders on"
+			list-layout="tiles"
+			name="reminder-days"
+			persistent-hint
+			pt:icon="hidden"
+			pt:item="justify-items-center gap-0 rounded-(--bb-radius) border py-2 hover:bg-(--bb-muted)"
+			pt:item:checked="border-(--bb-primary) bg-(--bb-primary) hover:bg-(--bb-primary-hover)"
+			pt:item:focus-visible="ring-2 ring-(--bb-primary-ring)"
+			pt:label="text-sm font-medium"
+			pt:label:checked="text-(--bb-primary-fg)"
+			pt:list="[--gap:6px] [--tile-min-width:0px]"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbCheckboxGroup } from 'bitboss-ui';
+
+type Weekday = { id: number; short: string; long: string };
+
+// Seven equal toggles: `list-layout="tiles"` with `--tile-min-width: 0` keeps
+// them on one line, `item-layout="vertical"` stacks the (hidden) glyph cell
+// over the label so the label centres. `pt:icon="hidden"` removes the box —
+// an empty `#icon` slot would not: Vue renders a slot's fallback when the
+// slot is empty. The native input stays, so Tab / Space / screen readers work
+// as on any checkbox. The label cell paints its own colour, so the checked
+// text colour goes on `pt:label:checked`, not on `pt:item`.
+const weekdays: Weekday[] = [
+	{ id: 1, short: 'Mon', long: 'Monday' },
+	{ id: 2, short: 'Tue', long: 'Tuesday' },
+	{ id: 3, short: 'Wed', long: 'Wednesday' },
+	{ id: 4, short: 'Thu', long: 'Thursday' },
+	{ id: 5, short: 'Fri', long: 'Friday' },
+	{ id: 6, short: 'Sat', long: 'Saturday' },
+	{ id: 7, short: 'Sun', long: 'Sunday' },
+];
+
+const days = ref<number[]>([1, 3, 5]);
+
+// The hint reads the choice back in words.
+const summary = computed(() => {
+	const picked = [...days.value].sort((a, b) => a - b);
+	if (!picked.length) return 'No reminders will be sent.';
+	if (picked.length === 7) return 'Every day.';
+	if (picked.join() === '1,2,3,4,5') return 'Every weekday.';
+	if (picked.join() === '6,7') return 'Weekends only.';
+	const names = picked.map((id) => weekdays[id - 1]!.long);
+	return `Every ${names.join(', ').replace(/, ([^,]*)$/, ' and $1')}.`;
+});
+</script>
+```
+
+**Priced cards** — equal tiles that wrap, the box in the corner
+(`item-layout="label-fill" item-reverse`), the price pinned to the bottom edge
+by a stretched `pt:label`, a running total under the grid:
+
+**Add-on cards with a total**
+
+```vue
+<template>
+	<div class="grid max-w-2xl gap-2">
+		<BbCheckboxGroup
+			v-model="selected"
+			description="Billed monthly with your plan. Cancel any add-on at renewal."
+			item-layout="label-fill"
+			item-reverse
+			item-text="name"
+			item-value="id"
+			:items="addons"
+			legend="Add-ons"
+			list-layout="tiles"
+			name="addons"
+			pt:item="items-start rounded-(--bb-radius) border p-3.5 hover:border-(--bb-text-faint)"
+			pt:item:checked="border-(--bb-primary) ring-1 ring-(--bb-primary) hover:border-(--bb-primary)"
+			pt:label="flex flex-col gap-0.5 self-stretch"
+			pt:list="[--gap:10px] [--row-gap:10px] [--tile-min-width:240px]"
+		>
+			<template #label="{ item }">
+				<span class="text-sm font-medium">{{ item.name }}</span>
+				<span class="text-xs leading-snug text-(--bb-text-muted)">{{
+					item.detail
+				}}</span>
+				<span class="mt-auto pt-3 text-sm tabular-nums"
+					>€{{ item.price
+					}}<span class="text-xs text-(--bb-text-muted)"> / month</span></span
+				>
+			</template>
+		</BbCheckboxGroup>
+		<div class="flex items-baseline justify-between border-t pt-2 text-sm">
+			<span class="text-(--bb-text-muted)"
+				>{{ selected.length }} of {{ addons.length }} selected</span
+			>
+			<span class="font-medium tabular-nums">€{{ total }} / month</span>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbCheckboxGroup } from 'bitboss-ui';
+
+type Addon = { id: string; name: string; detail: string; price: number };
+
+// Priced cards. `list-layout="tiles"` makes equal boxes (every row as tall as
+// the tallest) that wrap when the field narrows — `--tile-min-width: 240px`
+// gives two columns here and one on a phone. `item-layout="label-fill"` +
+// `item-reverse` puts the text first and the box in the corner. To pin the
+// price to the card's bottom edge, `pt:label` stretches the label cell to the
+// row's height and makes it a column; the price takes `mt-auto`.
+const addons: Addon[] = [
+	{
+		id: 'sso',
+		name: 'Single sign-on',
+		detail: 'SAML and OIDC for every workspace.',
+		price: 9,
+	},
+	{
+		id: 'audit',
+		name: 'Audit log',
+		detail: 'Every change, kept for two years.',
+		price: 6,
+	},
+	{
+		id: 'guests',
+		name: 'Guest seats',
+		detail: 'Ten read-only collaborators.',
+		price: 4,
+	},
+	{
+		id: 'support',
+		name: 'Priority support',
+		detail: 'Answers within four working hours.',
+		price: 12,
+	},
+];
+
+const selected = ref<string[]>(['sso', 'audit']);
+const total = computed(() =>
+	addons
+		.filter((addon) => selected.value.includes(addon.id))
+		.reduce((sum, addon) => sum + addon.price, 0)
+);
+</script>
+```
+
 ### Legend, description and validation
 
 The `legend` is the group's accessible name — always set it. `description` is
@@ -471,11 +710,11 @@ Read-only, with no cleanup code.
 		<BbRadioGroup
 			v-model="role"
 			compact
-			input-direction="horizontal"
 			item-text="label"
 			item-value="id"
 			:items="roles"
 			legend="Token role"
+			list-layout="horizontal"
 			name="token-role"
 		/>
 		<BbCheckboxGroup
@@ -599,8 +838,8 @@ row's own `disabled` — the states a standalone control has. A name outside
 that list is a type error and an ESLint error.
 
 Digest cadence as option tiles: `pt:item` is a broadcast over every row,
-`pt:item:checked` resolves per row. `flex-1` is what shares the row — size
-the group itself (`class="w-full"`), not a nested width.
+`pt:item:checked` resolves per row. `flex-1` is what shares the row — the
+list already spans the field, so the tiles do too.
 
 **Text-only tiles:** hide the box with `pt:icon="hidden"`. An empty `#icon`
 slot does not remove it: the default box is the slot's fallback and renders
@@ -613,10 +852,9 @@ whenever the slot is empty.
 	<div class="w-full max-w-md rounded-(--bb-radius) border p-3">
 		<BbCheckboxGroup
 			v-model="cadence"
-			class="w-full"
-			input-direction="horizontal"
 			:items="items"
 			legend="Cadence"
+			list-layout="horizontal"
 			name="cadence"
 			pt:item="flex-1 rounded-(--bb-radius) border border-(--bb-border) px-3 py-2"
 			pt:item:checked="border-(--bb-primary) bg-(--bb-muted)"
@@ -709,7 +947,6 @@ and the global map are in the [passthrough guide](./guides/passthrough.md).
 | `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
 | `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
 | `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` |  |  | 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. |
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
 | `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… |
@@ -719,15 +956,18 @@ and the global map are in the [passthrough guide](./guides/passthrough.md).
 | `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
-| `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
 | `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. |
+| `itemLayout` | `FieldLayout \| undefined` | `'auto'` |  | How each row's input and label sit together — the keywords of `layout`: `'auto'`, `'vertical'` (the input above the label), `'horizontal'` (50/50), `'label-fill'` (the label takes the row's free space — pair it with `list-layout="vertical-s… |
 | `itemProps` | `BbOptionGroupItemProps<T> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Option groups accept one field: - `description` — a muted line under the option label, beside the control; it may wrap. Either… |
+| `itemReverse` | `boolean \| undefined` | `false` |  | Swaps each row's input and label from their natural order (input first), in every `item-layout`. `reverse` swaps the legend and the options instead. |
 | `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
 | `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
 | `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
+| `layout` | `FieldLayout \| undefined` |  |  | 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… |
 | `legend` | `string` |  | yes | Text content of the legend. |
 | `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for option groups (checkbox, radio or switch) — there is … |
 | `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `listLayout` | `ListLayout \| undefined` | `'horizontal'` |  | How the rows sit inside the list: `'horizontal'` (on a line, wrapping, each row its own size), `'vertical'` (stacked, each row its own size), `'vertical-stretch'` (stacked, each row as wide as the list) or `'tiles'` (equal-size boxes, wrapp… |
 | `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
 | `max` | `number \| undefined` |  |  | Maximum number of selected items. |
 | `modelValue` | `any` |  | yes | Used by v-model. Can be an array of any serializable type. |
@@ -815,6 +1055,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | --- | --- | --- |
 | `--gap` | `24px` | Space between rows on one line. |
 | `--row-gap` | `10px` | Space between wrapped lines. |
+| `--tile-min-width` | `96px` | How narrow a tile may get before the tiles wrap (`tiles` only). |
 
 ## Component tree