bitboss-ui 3.0.0-beta.32 → 3.0.0-beta.35

package/dist/ai/BbButton.md

@@ -109,7 +109,7 @@ restate a state:
 	--bg-hover: color-mix(in oklab, var(--bb-primary) 90%, black);
 	--bg-pressed: color-mix(in oklab, var(--bb-primary) 80%, black);
 	--fg: var(--bb-primary-fg);
-	--ring: var(--bb-ring);
+	--ring-color: var(--bb-ring);
 }
 ```
 
@@ -156,10 +156,10 @@ design and never reads the disabled trio — see _Loading and async actions_.)
 Never use a variant name that is neither built-in nor registered in the
 project's `vite.config.*` / `nuxt.config.*`. Unsure what's currently legal in
 a given project (built-ins plus whatever it has registered)? Don't guess from
-an example — the plugin regenerates
-`node_modules/bitboss-ui/button-variants.d.ts` on every build; that file
-**is** the closed, machine-readable list of every legal `variant` value for
-that project, registrations included (see
+an example: the built-ins are `primary`, `outline`, `secondary`, `ghost`,
+`destructive` and `link`, and the project's own names are the
+`ButtonVariantRegistry` entries in its committed `bitboss-ui.d.ts` (the file
+the plugin writes from `buttonVariants`; see
 [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
 variants).
 
@@ -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
@@ -1162,7 +1183,8 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--bg-pressed` | `var(--bg)` | fill while [aria-pressed='true'] |
 | `--fg` | `initial` | label and icons (icons paint currentColor) |
 | `--border-color` | `transparent` | the frame; its width is --bw |
-| `--ring` | `transparent` | focus ring, drawn --bb-ring-size outside the border |
+| `--ring-color` | `transparent` | focus ring colour, per variant |
+| `--ring-size` | `var(--bb-ring-size)` | focus ring width, outside the border |
 | `--bw` | `var(--bb-border-w)` | border width |
 | `--fg-hover` | `var(--fg)` | label and icons on hover (and focus-visible) |
 | `--border-hover` | `var(--border-color)` | the frame on hover (and focus-visible) |

package/dist/ai/BbCalendar.md

@@ -468,7 +468,7 @@ box carries no role of its own and only the grid inside is announced.
 `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'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
+tokens, so `pt:root="[--px:2px]"` tightens the padding and the grid width
 follows), `header` (the navigation bar), `arrow` (the previous / next
 buttons), `month` and `year` (the heading buttons), `columnHeader` (each
 weekday letter), `day` (one whole day cell) and `dayButton` (the button
@@ -547,7 +547,7 @@ the page is `BbDatePicker`.
 
 | Part | What it is |
 | --- | --- |
-| `root` | The calendar's box: the grid and, with `type="datetime"`, the time rail beside it. A consumer `class` lands here. It carries the sizing tokens — `pt:root="[--cell:36px]"` widens the whole calendar, `pt:root="[--pad-x:2px]"` tightens its padding — and the grid's width follows. |
+| `root` | The calendar's box: the grid and, with `type="datetime"`, the time rail beside it. A consumer `class` lands here. It carries the sizing tokens — `pt:root="[--cell:36px]"` widens the whole calendar, `pt:root="[--px:2px]"` tightens its padding — and the grid's width follows. |
 | `header` | The navigation bar: the previous / next arrows and the month / year headings. |
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
@@ -593,9 +593,10 @@ Set these on the element, or on a class you put on it, to retune this component
 
 | Property | Set on | Default | What it is |
 | --- | --- | --- | --- |
+| `--bg` | `.bb-calendar__button-menu` | `var(--bb-panel)` |  |
 | `--cell` | `.bb-calendar` | `28px` | Cell size drives all grid math: 224px ÷ 7 = 32px exactly |
-| `--pad-x` | `.bb-calendar` | `6px` |  |
-| `--pad-y` | `.bb-calendar` | `8px` |  |
+| `--px` | `.bb-calendar` | `6px` |  |
+| `--py` | `.bb-calendar` | `8px` |  |
 | `--nav-button-h` | `.bb-calendar` | `24px` |  |
 | `--day-slot-allowance` | `.bb-calendar` | `0px` | Allowance for the day slot append area - needed for the slot to be visible |
 | `--unit-row` | `.bb-calendar` | `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. |

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)"
@@ -705,11 +943,10 @@ and the global map are in the [passthrough guide](./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`, `item`, `itemDescription`, `label`, `legend`, `list`, `message`, `root`. States: `disabled`, `errors`, `hasValue`, `loading`, `readonly`, `warnings`, `checked`, `focused`, `focusVisible`. 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. |
-| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-label-spacing-y` for `--bb-label-spacing-y-compact`, so tune a compact group's label gap with the `-compact` token, not the base one. |
 | `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
 

package/dist/ai/BbColorInput.md

@@ -392,7 +392,7 @@ The full common-field surface applies:
   visible, no edits, picker blocked), `loading` (progress styling on the
   wrapper), `required`, `autofocus`, `placeholder`, `name` and `autocomplete`
   (defaults to `off`) for form plumbing.
-- **Layout** — `compact` for a denser control; `direction`
+- **Layout** — `compact` for a denser control; `layout`
   (`horizontal` | `vertical` | `auto`, or a pattern like `xx xxxxx` splitting
   label/input columns) and `reverse` to swap label and input order.
 - **Icons & slots** — `prepend:icon`/`append:icon` add `lucide:*` icons inside
@@ -671,9 +671,8 @@ of it. The full grammar, the merge rules and the global map are in the
 | `autocomplete` | `string \| undefined` | `"off"` |  | Guides the browser as to the type of information expected in the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
-| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-input-h`, `--bb-input-py` and `--bb-label-spacing-y` for their `-compact` twins on the field, so a `--bb-input-h` you set on the component is ignored while `compact` is on: size a compact field with `--bb-input-… |
 | `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. |
 | `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… |
 | `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
@@ -685,6 +684,7 @@ of it. The full grammar, the merge rules and the global map are in the
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelMode` | `"outside" \| "floating" \| "inside" \| undefined` |  |  | Label rendering mode: `outside` places the label above the input, `floating` overlays it on the field and shrinks it when a value is set, `inside` keeps it inside the field. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `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… |
 | `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
 | `modelValue` | `string \| null` | `null` | yes | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
@@ -796,8 +796,8 @@ Set these on the element, or on a class you put on it, to retune this component
 - `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`): `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ panel: 'root', 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`, `--handle-w`, `--handle-h`, `--handle-bg`, `--close-size`
+  - `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 `{ panel: 'root', sheet: 'root' }` (ours → theirs); documented CSS variables: `--edge`; 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`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
       - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
 
 ## See Also

package/dist/ai/BbColorPalette.md

@@ -787,6 +787,14 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `activator` — scope: `BbColorPaletteActivatorSlotProps` — Custom activator element. Apply `v-bind="props"` to the element you want to use as the trigger — this wires up the ref callback that lets BbColorPalette track the element.
 
+## CSS custom properties
+
+Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+
+| Property | Default | What it is |
+| --- | --- | --- |
+| `--edge` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The swatch's own edge: a text-tone hairline, so a pale swatch reads on a light panel AND a deep one (green-900, indigo-900) on a dark panel — a fixed black 8% vanished there. |
+
 ## Component tree
 
 `BbColorPalette` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbColorPalette`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
@@ -797,7 +805,7 @@ States are listed in precedence order: when two are on at once and their entries
 - 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: `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ panel: 'root', 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`, `--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`
   - Also mounts `CommonPopover`
 

package/dist/ai/BbConfirm.md

@@ -32,7 +32,8 @@
 | `--bg-pressed` | `pt:action` | `BbButton` | fill while [aria-pressed='true'] |
 | `--fg` | `pt:action` | `BbButton` | label and icons (icons paint currentColor) |
 | `--border-color` | `pt:action` | `BbButton` | the frame; its width is --bw |
-| `--ring` | `pt:action` | `BbButton` | focus ring, drawn --bb-ring-size outside the border |
+| `--ring-color` | `pt:action` | `BbButton` | focus ring colour, per variant |
+| `--ring-size` | `pt:action` | `BbButton` | focus ring width, outside the border |
 | `--bw` | `pt:action` | `BbButton` | border width |
 | `--fg-hover` | `pt:action` | `BbButton` | label and icons on hover (and focus-visible) |
 | `--border-hover` | `pt:action` | `BbButton` | the frame on hover (and focus-visible) |
@@ -78,7 +79,9 @@ row show only the second, and the first silently answers "no". If you need both
 questions asked, `await` the first before opening the second.
 Mounting a second host renders every dialog twice
 (nothing warns you). Mounting none is worse: `await confirm(...)` never settles
-and the caller hangs.
+and the caller hangs. A host that unmounts while its dialog is open (a layout
+the user navigated out of) gets one second to come back; after that the open
+confirm resolves `false` without running a callback, so it never 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
@@ -832,8 +835,8 @@ States are listed in precedence order: when two are on at once and their entries
 - `BbConfirm` _(this component)_ — its own template binds: `text` → `div.bb-confirm__text`, `action` → `BbButton`; hands `BbDialog` the pt map `passthrough.forward(DIALOG_PARTS, BB_DIALOG_PT.states)` (ours → theirs)
   - `BbDialog` _(public — [contract](./BbDialog.md))_ — its own pt parts (`BbDialog`): `header` → `div.bb-dialog__header`, `title` → `span.bb-dialog__title`, `description` → `p.bb-dialog__description`, `close` → `CloseButton`, `content` → `div.bb-dialog__body`, `footer` → `div.bb-dialog__footer`; hands `BbOffCanvas` the pt map `{ root: 'root', header: 'header', title: 'title', description: 'description', content: 'content', footer: 'footer', close: 'close', sheet: 'root', }` (ours → theirs); documented CSS variables: `--px`, `--close-size`
     - `CloseButton` _(internal — not importable, reach it through `BbDialog`)_ — documented CSS variables: `--size`, `--p`
-    - `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`; also mounts `CloseButton`
-  - `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`, `BbSpinner`
+    - `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`; also mounts `CloseButton`
+  - `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-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
     - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
 
 ## See Also