bitboss-ui 3.0.0-beta.52 → 3.0.0-beta.53

package/bin/bitboss-ui-mcp.mjs

@@ -2724,16 +2724,24 @@ function listChanges({
 			guide: doc.guide,
 			count: all.length,
 			releases,
+			// Zero counts are left out (a missing key is 0): the map grows by a
+			// release each beta and must stay one small answer (beta.53 hit the
+			// 3 000-char budget with every bucket spelling out its zeros).
 			perRelease: Object.fromEntries(
-				Object.entries(perRelease).sort(([a], [b]) =>
-					a === 'unreleased'
-						? 1
-						: b === 'unreleased'
-							? -1
-							: compareVersions(a, b)
-				)
+				Object.entries(perRelease)
+					.sort(([a], [b]) =>
+						a === 'unreleased'
+							? 1
+							: b === 'unreleased'
+								? -1
+								: compareVersions(a, b)
+					)
+					.map(([at, bucket]) => [
+						at,
+						Object.fromEntries(Object.entries(bucket).filter(([, n]) => n > 0)),
+					])
 			),
-			hint: 'Counts only. What a bump breaks: list_changes({ since: "<your version>" }), one line per change; from v2: since: "2". One component: { component: "BbSelect" }. Full rows: detail: "rows".',
+			hint: 'Counts only (a missing count is 0). What a bump breaks: list_changes({ since: "<your version>" }), one line per change; from v2: since: "2". One component: { component: "BbSelect" }. Full rows: detail: "rows".',
 		};
 	}
 

package/dist/ai/BbBadge.md

@@ -70,7 +70,8 @@ For a small, closed status set (paid / pending / overdue, plan tiers), register
 the soft palette from
 [design language guide](./guides/design-language.md) § Using color
 (`soft-gray` / `soft-blue` / `soft-green` / `soft-amber` / `soft-red`) and style
-`.bb-badge--<name>` in your project stylesheet. Never invent `variant="success"`
+`.bb-badge--<name>` in your project stylesheet. Type a status map as
+`Record<Status, BadgeVariantType>`. Never invent `variant="success"`
 — that name is not built-in and ships no CSS. The example below uses the soft
 names: in your app it type-checks only after the `badgeVariants` registration
 and renders styled only with that CSS — both are in the linked section.
@@ -863,7 +864,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon (`icon` or `prepend:icon`; the `append:icon` when it is the only one; else the leading slot), as `BbButton` does, with a hidden loading announcement. |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
 | `size` | `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` \| `'2xl'` | `"md"` |  | Preset size of the badge. |
-| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--fg`). `'none'` renders no variant class — an escape hatch for a one-off look set through `--bg` / `--fg` on the element. |
+| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Status colours are a registration (vite plugin `badgeVariants`, the `soft-*` palette in design-language.md) styled as `.bb-badge--<variant>`. `'none'` renders no variant class: set `--bg` / `--fg` on the element. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbColorPalette.md

@@ -447,8 +447,9 @@ The float itself is tuned with the popover props:
   unless you set `disable-flip`.
 - `offset` (default 4) — gap between anchor and popover; `padding` (default 6) —
   minimum space kept from the viewport edge.
-- `boundary` — constrain the popover inside an element (ref or CSS selector),
-  e.g. a scrolling panel.
+- `boundary` — keep the popover inside an element (ref or CSS selector)
+  alongside its trigger, e.g. a scrolling panel's width; it may open past the
+  edge away from the trigger, and only the viewport flips it.
 - `transition-duration` (default 250ms) and `eager` — render the palette content
   before it is first shown (useful for SSR/measurement; off by default so the
   body mounts lazily).
@@ -757,7 +758,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbPopover`/`BbDropdown`/`BbDatePicker`. When unset, falls back to the global `config.adaptive`. |
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. The picker shows an opacity slider and emits `#RRGGBBAA` hex8 values. |
 | `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator element when omitted, allowing the popover to be anchored to a larger container (e.g. the full input row) while a smaller element (e.g. a color dot) remains the click target. |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element: it stays inside it alongside its trigger (sideways for a popover above or below); away from the trigger it may pass the edge, and it flips at the viewport only. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disable all interaction (activator and palette). |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the palette panel at mount instead of on the first open (the phone sheet's too). |

package/dist/ai/BbDatePicker.md

@@ -416,7 +416,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
 | `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator when omitted (anchor to a larger row while a smaller element stays the click target). |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector: sideways only, alongside the trigger; it flips at the viewport. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the calendar. |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
 | `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |

package/dist/ai/BbDropdown.md

@@ -1600,7 +1600,11 @@ const items: BbDropdownItem[] = [
   `placement` is `'cursor'`.
 - `offset` (gap from the anchor), `padding` (minimum space kept from the
   viewport edge), and `boundary` (an element, component ref, or CSS selector
-  that confines the panel) tune positioning; `eager` pre-renders the panel
+  the panel stays inside alongside its trigger; it may still open past the
+  edge away from the trigger, and only the viewport flips it) tune positioning.
+  Pass `boundary` a `useTemplateRef` or a selector, not `$refs.x`: `$refs` is
+  not reactive, so a menu in a table cell rendered before the ref was set keeps
+  no boundary until that row happens to re-render. `eager` pre-renders the panel
   before first open; `transitionDuration` controls the open/close animation.
 - The menu closes itself on outside click/focus, on `Escape`, when another
   dropdown opens, and when the activator scrolls out of view. `disabled`
@@ -2170,7 +2174,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | An external activator element or component ref: the activator slot is not rendered, and the listeners and ARIA (`aria-haspopup` / `aria-expanded` / `aria-controls`) are attached to it; don't add your own. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom sheet that drills into submenus one level at a time instead of hover flyouts; slots and selection are unchanged. Unset: the global `config.adaptive`. |
 | `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `the activator element` |  | The element the panel positions against when it should differ from the activator (a wrapper the activator is part of); an HTMLElement or component ref. It also drives a percentage `width`. Ignored with `placement="cursor"`. |
-| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the dropdown within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Keeps the panel inside this element alongside its trigger (sideways for a menu above or below); away from the trigger it may pass the edge, and only the viewport flips it. An HTMLElement, a component ref or a CSS selector: a `useTemplateRef`, never `$refs.x` (not reactive). |
 | `compact` | `boolean \| undefined` | `false` |  | Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet rows 44px → 36px (a sheet row stays a touch target). The label size does not change. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too), and keeps its rows after a close. Without it the rows mount on each open and go once the menu has closed. |

package/dist/ai/BbForm.md

@@ -125,21 +125,26 @@ import {
 	useBbFormContext,
 } from 'bitboss-ui';
 
-const signup = z
-	.object({
-		// An emptied text field holds `null`: the type's message covers it.
-		name: z.string('Enter your name').trim().min(1, 'Enter your name'),
-		// A transform: `@submit` receives the lower-cased address.
-		email: z.email('Enter a valid email').toLowerCase(),
-		password: z.string('Choose a password').min(8, 'At least 8 characters'),
-		confirm: z.string('Repeat the password'),
-		terms: z.literal(true, 'Accept the terms to continue'),
-	})
-	// A cross-field rule: `path` puts the message on the second field.
-	.refine((form) => form.password === form.confirm, {
-		message: 'The passwords do not match',
-		path: ['confirm'],
-	});
+const fields = z.object({
+	// An emptied text field holds `null`: the type's message covers it.
+	name: z.string('Enter your name').trim().min(1, 'Enter your name'),
+	// A transform: `@submit` receives the lower-cased address.
+	email: z.email('Enter a valid email').toLowerCase(),
+	password: z.string('Choose a password').min(8, 'At least 8 characters'),
+	confirm: z.string('Repeat the password'),
+	terms: z.literal(true, 'Accept the terms to continue'),
+});
+
+// A cross-field rule: `path` puts the message on the second field, `when`
+// runs it as soon as the two passwords parse (zod otherwise skips it while
+// any other field fails).
+const signup = fields.refine((form) => form.password === form.confirm, {
+	message: 'The passwords do not match',
+	path: ['confirm'],
+	when: (payload) =>
+		fields.pick({ password: true, confirm: true }).safeParse(payload.value)
+			.success,
+});
 
 const form = useBbFormContext('signup');
 const created = ref<z.output<typeof signup> | null>(null);
@@ -165,7 +170,9 @@ What you get from the one prop:
   `name="lines[0][qty]"` (brackets read as dots). A field with no `name` is
   named after its label, `Full name` → `fullname`, so schema-driven forms set
   `name` on every field. A cross-field rule
-  reaches the right field through its `path` (`path: ['confirm']` above).
+  reaches the right field through its `path` (`path: ['confirm']` above);
+  its `when` lets it run while other fields still fail (a zod object
+  refinement is skipped until the whole object parses).
 - **Submit is gated** by the schema, async refinements included, exactly as it
   is by field rules.
 - **`@submit` receives the schema's output.** Transforms and coercions have
@@ -1176,7 +1183,8 @@ first (`JSON.parse(JSON.stringify(form.values.value))`).
 
 ### `resetForm()` clears the fields, and your model
 
-Resetting publishes the new value back through each field's
+`resetForm()` is the slot's name; from outside the form the same reset is
+`useBbFormContext(id).reset()` (the handle has no `resetForm`). Resetting publishes the new value back through each field's
 `update:modelValue` (and writes it into the object bound with `:model`), so
 the control, the form's own state and whatever ref you bound all agree
 afterwards.

package/dist/ai/BbHoverCard.md

@@ -463,7 +463,7 @@ value written in `<script>` is typed as `BbHoverCardProps['pt']`.
 | --- | --- | --- | --- | --- |
 | `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: `content`, `footer`, `header`, `panel`, `root`. States: `open`. 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`. In `<script>` a `pt` value is typed `BbHoverCardProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and the hover / focus listeners are attached programmatically to the referenced element. |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the card within a bounding element. When provided, the card will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the card within a bounding element: it stays inside it alongside its trigger (sideways for a card above or below); away from the trigger it may pass the edge, and it flips at the viewport only. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `delay` | `number \| undefined` | `350` |  | Milliseconds the pointer (or keyboard focus) rests on the activator before the card shows; longer than BbTooltip's, so passing over does not open it. Closing has a fixed grace (guide § Timing and the safe zone). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. Disabling an open card closes it. |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the card's content at mount instead of on the first open. |

package/dist/ai/BbPopover.md

@@ -472,8 +472,10 @@ Fine-tune the geometry with:
 - `offset` — gap (px) between the activator and the panel (default `4`).
 - `padding` — minimum gap (px) the panel keeps from the page edge (default
   `10`).
-- `boundary` — an element, ref, or CSS selector that constrains the panel so it
-  never escapes a scrolling region or sidebar.
+- `boundary` — an element, ref, or CSS selector the panel stays inside
+  alongside its trigger (a sidebar's width, a table's). Away from the trigger
+  it may pass the edge: a panel under a table's last row opens below it
+  rather than flipping, and only the viewport flips it.
 
 `BbPopover` is a floating **panel**, not a speech bubble — it never renders an
 arrow. Reach for `BbTooltip` when you want an arrow pointing back at the trigger
@@ -871,7 +873,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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: `content`, `footer`, `header`, `panel`, `root`, `sheet`. States: `open`. 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`. In `<script>` a `pt` value is typed `BbPopoverProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and click events are attached programmatically to the referenced element. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile (below `config.mobileMaxWidth`), renders as a bottom sheet instead of a floating panel, with the same `header`, `default` and `footer` slots. `width` is ignored there: size the sheet with `offCanvasProps`. Unset: the global `config.adaptive`. |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. When provided, the popover will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element: it stays inside it alongside its trigger (sideways for a popover above or below); away from the trigger it may pass the edge, and it flips at the viewport only. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the panel's content at mount instead of on the first open (the phone sheet's too). |
 | `focusTarget` | `string \| undefined` |  |  | Selector for the element that receives focus after opening. Defaults to the first focusable element inside the popover. |

package/dist/ai/BbSelectPopover.md

@@ -1758,7 +1758,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `ariaDescribedby` | `string \| string[] \| undefined` |  |  | Space-separated IDREF(s) that describe this field for assistive technologies. Accepts either a string or array of ids. |
 | `ariaInvalid` | `boolean \| undefined` | `undefined` |  | Explicit invalid state for accessibility semantics. Falls back to `hasErrors` when not provided. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the popover search input. |
-| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover to a specific boundary element. |
+| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover to a specific boundary element: it stays inside it alongside its trigger (sideways for a popover above or below); away from the trigger it may pass the edge, and it flips at the viewport only. |
 | `clearable` | `boolean \| undefined` | `false` |  | Shows a clear button in the search field, in the lens' place while there is a query or a selection; it resets both. None without a search field. Leave it off when the activator already clears (as BbSelect's does). |
 | `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
 | `dependencies` | `unknown[] \| undefined` | `[]` |  | Additional dependencies that trigger item reloading when changed. |

package/dist/ai/BbTable.md

@@ -373,7 +373,7 @@ scope in `#<key>:header`. With it each name gets its own scope, as on `BbTable`.
 **Add beside a header instead of replacing it** with
 `#<key>:header:prepend` / `#<key>:header:append` — rendered before / after the
 column's existing header content (the label + sort control, or your own
-`#<key>:header` replacement), so a resize grip or reorder handle no longer
+`#<key>:header` replacement), so a resize handle or reorder handle no longer
 costs you the built-in sort button. The table-wide pair `#header:prepend` /
 `#header:append` applies one template to every data column's header (never the
 structural select/actions cells); both forms receive the header scope above
@@ -953,6 +953,20 @@ a native `<input>` / `<select>`:
 <BbTable :items="filteredItems" :columns="columns" caption="Invoices" />
 ```
 
+```ts
+// An emptied (or cleared) BbTextInput writes `null`, not '' — type it so.
+const search = ref<string | null>('');
+const statuses = ref<string[]>([]);
+const filteredItems = computed(() => {
+	const q = search.value?.trim().toLowerCase() ?? '';
+	return invoices.value.filter(
+		(row) =>
+			(!q || row.client.toLowerCase().includes(q)) &&
+			(!statuses.value.length || statuses.value.includes(row.status))
+	);
+});
+```
+
 Pick the shape by where the rows come from:
 
 | Your situation                         | The filter mechanism                                                                     |
@@ -1172,7 +1186,7 @@ const sortedInvoices = computed(() => {
 A custom `#<key>:header` slot replaces the built-in sort button, but its scope
 hands you `sortOrder` and `toggleSort` so your header can keep sorting alive
 (render your own button and call `toggleSort`). To merely add something next
-to the control — a resize grip, a filter icon — use
+to the control — a resize handle, a filter icon — use
 `#<key>:header:prepend/append` instead and keep the built-in button (see
 "Custom cells and headers"). The column-level `sorted`
 field only seeds the header's `aria-sort` when no live model entry exists — it
@@ -1477,7 +1491,11 @@ user can select); one the model names explicitly still shows ticked.
 
 To drive a toolbar that lives **outside** the table subtree, give the table an
 `id` and read `useBbTableContext(id).selected` — the handle mirrors the
-table's selection both ways, so a bulk-action bar needs no prop drilling. As
+table's selection both ways, so a bulk-action bar needs no prop drilling.
+Count from `all` and `unselected` too: the header checkbox is select-all,
+which leaves `selected` empty (see [§ Single select, select-all and
+limits](#single-select-select-all-and-limits)), so a bar that reads
+`selected` alone vanishes while every row shows ticked. As
 everywhere in the library, the destructive bulk action is gated by
 `useConfirm` before it touches the data.
 
@@ -1566,14 +1584,27 @@ const selected = ref<string[]>([]);
 
 // Same id as the table — the handle mirrors the table's selection both ways.
 const ctx = useBbTableContext('member-selection', { selected: [] });
-const selectedCount = computed(() => ctx.selected.value?.length ?? 0);
-const clear = () => (ctx.selected.value = []);
+// The header checkbox is "select all": it sets `all` and leaves `selected`
+// empty (built for "all across pages"), with the rows unticked since in
+// `unselected`. A client-side table reads the chosen rows from both.
+const chosenIds = computed<string[]>(() =>
+	ctx.all.value
+		? members.value
+				.map((member) => member.id)
+				.filter((id) => !ctx.unselected.value.includes(id))
+		: (ctx.selected.value ?? [])
+);
+const selectedCount = computed(() => chosenIds.value.length);
+const clear = () => {
+	ctx.all.value = false;
+	ctx.selected.value = [];
+};
 
 const { confirm } = useConfirm();
 
 // Destructive bulk action: `await` the decision, act only on a yes.
 const removeSelected = async () => {
-	const ids: string[] = ctx.selected.value ?? [];
+	const ids = chosenIds.value;
 	const ok = await confirm({
 		title: `Delete ${ids.length} ${ids.length === 1 ? 'member' : 'members'}?`,
 		text: 'They will lose access to this workspace immediately.',
@@ -1981,7 +2012,7 @@ _detail about the row_ rather than _children of it_.
 
 ### Reordering rows
 
-`reorderable-rows` adds a slim grip at the start of every row: the user drags
+`reorderable-rows` adds a slim drag handle at the start of every row: the user drags
 a row to a new place and the table reports the move with **`reorder:rows`**.
 The table never reorders `items` itself. Your handler splices the array, and
 saves the order if it should outlive the page:
@@ -1993,8 +2024,8 @@ saves the order if it should outlive the page:
 	<div class="flex max-w-2xl flex-col gap-3">
 		<!-- The table only REPORTS the move: `reorder:rows` says which item went
 		     from where to where, and the handler below splices the array and
-		     saves the order. Drag a row by its grip (or anywhere on it with a
-		     mouse), or focus a grip and use Space, the arrow keys and Space. -->
+		     saves the order. Drag a row by its handle (or anywhere on it with a
+		     mouse), or focus a handle and use Space, the arrow keys and Space. -->
 		<div
 			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
@@ -2108,11 +2139,11 @@ function move({ from, to }: { from: number; to: number }) {
   `items` (`items.indexOf(item)` finds it); `from` and `to` index the `items`
   the table holds. Remove at `from`, insert at `to`. A drop where the row
   already was emits nothing.
-- **Mouse and pen** drag from the grip, or from anywhere on the row once the
+- **Mouse and pen** drag from the handle, or from anywhere on the row once the
   pointer has moved 5px. A press on a control inside the row never starts a
   drag (a button, a link, an input, the select checkbox, anything with a
   widget role or `draggable`), and a press that sets off sideways selects text
-  instead. **Touch** drags from the grip only, at once (no long-press), so a
+  instead. **Touch** drags from the handle only, at once (no long-press), so a
   finger on the row still scrolls. The click that ends a drag is not a row
   click: no `click:row`, no highlight.
 - **While it drags**, a copy of the row follows the pointer with its real cell
@@ -2121,10 +2152,10 @@ function move({ from, to }: { from: number; to: number }) {
   Near the top or bottom edge the nearest scroll container scrolls, `virtual`
   tables included, and the rows that scroll in are targets; the wheel scrolls
   too.
-- **Keyboard:** the grip is a button. Space or Enter picks the row up, ↑ / ↓ /
+- **Keyboard:** the drag handle is a button. Space or Enter picks the row up, ↑ / ↓ /
   Home / End move it, Space or Enter drops it, Esc or Tab cancels. Under
-  `keyboard-navigation`, Space or Enter on the grip's cell picks it up at once.
-- **Accessibility:** each grip is named "Move row" + the row's label (its
+  `keyboard-navigation`, Space or Enter on the handle's cell picks it up at once.
+- **Accessibility:** each drag handle is named "Move row" + the row's label (its
   cell in the `rowHeader: true` column, else the first column) and described by the keyboard
   instructions. A polite live region announces the pick-up, each position
   ("Position 3 of 6"), the drop and a cancel.
@@ -2137,10 +2168,16 @@ function move({ from, to }: { from: number; to: number }) {
 - **Server pages:** the indexes are into the page the table holds. For the
   whole list, add the page's offset (`(page - 1) * perPage + from`). Moving a
   row to another page is not supported.
-- **Sorting:** the grips stay enabled while a column sort is active, so a move
-  is reported against the sorted rows. What that means for your stored order
-  is your app's call (clear the sort first, or hide reordering while sorted).
-- **Pinning and RTL:** the grip column is structural, like the select column:
+- **Sorting:** the drag handles stay enabled while a column sort is active, and a
+  move is reported against the sorted rows, the order the user sees. This is
+  easy to get wrong: splicing your stored array changes nothing a sort shows,
+  so the row snaps back. Give the drop a meaning the sort can show. Sorted by
+  a rank the drag edits (priority, position), write the new ranks in the order
+  the user now sees and the sort reproduces the drop. Sorted by something the
+  drag cannot change (a name, a date), turn the drag handles off for that sort
+  (`:reorderable-rows="!sort.length || sort[0][0] === 'priority'"`) rather
+  than snapping back or clearing the user's sort behind their back.
+- **Pinning and RTL:** the drag handle column is structural, like the select column:
   it never appears in `order` and never moves, it pins with the first
   left-pinned column, and in RTL it sits at the logical start (the right
   edge).
@@ -2148,7 +2185,7 @@ function move({ from, to }: { from: number; to: number }) {
   goes on while its row is still there, and cancels cleanly, announced, when
   it is gone. Expanding or collapsing one of the table's own rows cancels it.
   While `loading`, no new drag starts.
-- **No grips** with a custom `#tbody`.
+- **No drag handles** with a custom `#tbody`.
 - **Styling:** `pt:dragHandle` takes a class list or an object (no per-row
   function).
 
@@ -2196,6 +2233,13 @@ put, and both columns are reported. A table that inherits its widths from a
 parent (`inherit-column-widths`) renders no handles — its tracks are the
 parent's.
 
+**Lock one column with `resizable: false`** on its definition, the way
+`reorderable: false` locks its place: its header has no handle, Alt+←/→ on
+it does nothing, and a neighbour's Shift+drag resizes the neighbour alone. Use
+it for control columns sized to their content (an expand chevron, a row
+number at `width: 'max-content'`). The lock stops the user, not your code: a
+`width` you set still applies.
+
 **Resizable columns reporting widths back into the definition**
 
 ```vue
@@ -2342,7 +2386,7 @@ above it. The mechanics:
 			</template>
 
 			<template #expand="{ item }">
-				<div class="bg-(--bb-muted) px-1 py-1">
+				<div class="bg-(--bb-muted) py-1">
 					<BbTable
 						:caption="`Line items of ${item.number}`"
 						:columns="lineColumns"
@@ -2478,7 +2522,42 @@ Two rules keep them honest:
 2. **Never add nest padding on the body only.** Padding the child's body
    (`.bb-table__body`) but not its header (or vice versa) reintroduces exactly
    the offset the snap just removed. Put the inset on the nest container, where
-   both row groups inherit it.
+   both row groups inherit it, and keep it **vertical** (`py-1`): the child
+   inherits the parent's track widths, not their positions, so horizontal
+   padding moves every column off its rail by that much and pushes the child
+   past the parent's edge into its scroll.
+
+#### Indenting nested levels
+
+Two CSS tokens on the **root** table step each nested level in, the way a
+tree reads, while every other column stays on the parent's columns:
+
+- `--indent` — the step per level (a length; `0px` by default, no indent).
+- `--indent-at` — where the step goes: `drag-handle`, `select` (the default) or
+  `content`.
+
+```css
+.services-table {
+	--indent: 24px;
+	--indent-at: select;
+}
+```
+
+| `--indent-at` | Stays in one column at every level | Steps in per level                       |
+| ------------- | ---------------------------------- | ---------------------------------------- |
+| `drag-handle` | nothing before the content         | the drag handle, the select, the content |
+| `select`      | the drag handle                    | the select and the content               |
+| `content`     | the drag handle and the select     | the first column's content               |
+
+Each nested level adds one step before the anchor and takes it from its
+first content column, so Status, Total or any other column never moves and
+level three lands two steps in by itself. A missing anchor falls through: no
+drag handle column behaves as `select`, no select column as `content`. Set the tokens
+on the root table (nested tables inherit them), or on one nested table to
+change the anchor from that level down. `--indent-at` is read when the table
+measures (mount, resize): set it in CSS, not from an animation. A nested
+table also carries `--depth` (1, 2, …) for styling by level, e.g. a group bar:
+`border-inline-start: calc(var(--depth) * 2px) solid var(--bb-primary)`.
 
 ### Row highlight (master–detail)
 
@@ -3883,8 +3962,13 @@ for a preset that fits any row type (never `<any>`), not an imported
 - `loading-text` is `sr-only` — it is announced, never painted. The visible
   loading signal is the skeleton (or your `#loading` slot). It defaults to the
   localized `common.loadingText`, so an unset value still announces.
-- Row selection labels default to every cell's content inside the locale's
-  "select" template (`Select {0}`, `{0} auswählen`). `accessible-label` overrides that per row — it is called
+- Row selection labels default to the row's **name** inside the locale's
+  "select" template (`Select {0}`, `{0} auswählen`): its `rowHeader` cells,
+  else its first column ("Select INV-1041"), the same name the drag handle
+  uses. Not every cell: a name tells rows apart, and a screen reader reads the
+  other cells with their headers in table navigation. Mark the identity
+  column `rowHeader` when it is not the first (a receipt thumbnail leads).
+  `accessible-label` overrides that per row — it is called
   `(columns, item)` with the mapped cells (in **render** order — look them up
   by `key`, never by position) and the raw record, and whatever it returns
   becomes the checkbox's label.
@@ -3939,8 +4023,9 @@ for a preset that fits any row type (never `<any>`), not an imported
   (`role="rowheader"`), and a screen reader reading across a row, or down
   another column, announces that name with each value — "Ada Lovelace,
   ada@x.io" instead of a bare "ada@x.io". The cells look the same.
-  `accessible-label` is a different thing: it only names each row's
-  selection checkbox. The column:
+  It also names the row's selection checkbox and drag handle ("Select Ada
+  Lovelace", "Move row Ada Lovelace"); `accessible-label` overrides only the
+  checkbox. The column:
   `{ key: 'name', label: 'Name', rowHeader: true }`.
 
 - Set `item-value` so selection, expansion and highlight track rows by stable
@@ -4004,7 +4089,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | 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: `body`, `caption`, `cell`, `cellColumnHeader`, `dragHandle`, `dragIcon`, `firstRow`, `foot`, `head`, `headerRow`, `lastRow`, `root`, `row`, `selectIcon`, `sortIcon`, `table`. States: `disabled`, `empty`, `expanded`, `highlighted`, `indeterminate`, `loading`, `selected`, `sorted`, `sortedDesc`. 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`. In `<script>` a `pt` value is typed `BbTableProps<Row>['pt']` (`BbTableProps['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `accessibleLabel` | `((columns: MappedCell[], item: any) => string) \| undefined` |  |  | Function that accepts the columns and the current item as arguments and returns a label to be used for accessibility purposes. The cells arrive in RENDER order (they follow `order`, so the label reads like the row) — look a cell up by `key`, never by position. |
+| `accessibleLabel` | `((columns: MappedCell[], item: any) => string) \| undefined` |  |  | The row's selection checkbox label, from `(columns, item)`. Unset: the row's name in the locale's select template (its `rowHeader` cells, else its first column: "Select INV-1041"). The cells arrive in render order: look one up by `key`, never by position. |
 | `actionsText` | `string \| undefined` |  |  | Label used in the header of the actions column. |
 | `align` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Text alignment of the columns. |
 | `caption` | `string \| undefined` |  |  | Caption that describes the content of the table. Used for accessibility purposes. |
@@ -4046,7 +4131,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `perPage` | `string \| number \| undefined` |  |  | Rows per page, for `aria-rowindex` and a paired `BbPagination`. Doesn't slice `items`. Unset, an array `items` infers it from its length; an explicit value wins. Numeric strings are coerced. |
 | `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
 | `reorderable` | `boolean \| undefined` | `false` |  | Lets the user reorder the data columns: drag a header, or Shift+←/→ on a focused header. Every move writes `v-model:order`; a column panel that only writes `order` does not need it. `select` / `actions` and a custom `#thead` never move. |
-| `reorderableRows` | `boolean \| undefined` | `false` |  | Adds a grip at the start of each row: the user drags a row, or lifts it with Space / Enter and the arrow keys, and `reorder:rows` reports `{ item, from, to }`. The table never reorders `items`: splice it in the handler. |
+| `reorderableRows` | `boolean \| undefined` | `false` |  | Adds a drag handle at the start of each row: the user drags a row, or lifts it with Space / Enter and the arrow keys, and `reorder:rows` reports `{ item, from, to }`. The table never reorders `items`: splice it in the handler. |
 | `resizable` | `boolean \| undefined` | `false` |  | Lets the user resize the data columns (drag a header's trailing edge, or Alt+←/→; double-click resets). Each commit fires `resize:column(key, width)` once: write the width back into the column definition to keep it. Ignored when inheriting widths. |
 | `rowClass` | `BbTableRowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data row. Can also be a function of the row's item for dynamic values. |
 | `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` |  |  | Defines whether the table is selectable. Can be a global boolean that affects all rows or a function that accepts an item and returns a boolean that only affects that item. |
@@ -4081,7 +4166,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `lastRow` | The row of `#<key>:last` cells, after the data rows (a totals row: `pt:lastRow="font-semibold"`). |
 | `selectIcon` | The selection glyph: each row's checkbox (radio with single selection) and the select-all checkbox — resolved per node. Not rendered when the `select` / `select:header` slots replace them. |
 | `dragIcon` | The move glyph on the chip that follows a column drag (`reorderable`). |
-| `dragHandle` | Each row's grip button (`reorderable-rows`), resolved with its row's states. A class list or an object; no per-row function. |
+| `dragHandle` | Each row's drag handle button (`reorderable-rows`), resolved with its row's states. A class list or an object; no per-row function. |
 | `foot` | The footer row group (the `tfoot` slot's container). |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
@@ -4150,6 +4235,13 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--actions-spacing` | `.bb-table` | `8px` |  |
 | `--offset-start` | `.bb-table` | `0px` | Raw structural edge offset measured by the component (the parent's select/actions track width). Default 0 keeps every calc at its base. |
 | `--offset-end` | `.bb-table` | `0px` |  |
+| `--ig` | `.bb-table` | `0px` | Nested indent locals (see `indentAnchor` in BbTable.vue): the step lands on ONE cell's leading padding. Reset on every table so a parent's step never inherits into a child's cells; the modifier picks the anchor. |
+| `--is` | `.bb-table` | `0px` |  |
+| `--ic` | `.bb-table` | `0px` |  |
+| `--depth` | `.bb-table` | `0` | Nesting depth (0 at the root) and the parent-region floors of the own structural tracks, both set inline by the component on nested tables; declared here so a parent's values never inherit into a child. |
+| `--min-g` | `.bb-table` | `0px` |  |
+| `--min-s` | `.bb-table` | `0px` |  |
+| `--min-a` | `.bb-table` | `0px` |  |
 | `--offset-internal-start` | `.bb-table` | `var(--offset-start)` | Routing of that offset. By default it is "internal": added to the first/last cell padding and folded into the first/last column width. Swap internal↔external (set internal to 0 and external to the raw offset) to pad the whole table instead of the edge cells. |
 | `--offset-internal-end` | `.bb-table` | `var(--offset-end)` |  |
 | `--offset-external-start` | `.bb-table` | `0px` |  |

package/dist/ai/BbTimePicker.md

@@ -289,7 +289,7 @@ typeahead. Always pass a `label` when the trigger is an unlabelled cell or icon.
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column; emitted values stay 24-hour. |
 | `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator when omitted (anchor to a larger row while a smaller element stays the click target). |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector: sideways only, alongside the trigger; it flips at the viewport. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the columns. |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
 | `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |

package/dist/ai/BbTooltip.md

@@ -597,7 +597,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `panel`, `root`. States: `open`. 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`. In `<script>` a `pt` value is typed `BbTooltipProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
 | `arrowPadding` | `number \| undefined` | `10` |  | Space the arrow will maintain to the edge of the tooltip bubble. Useful when the floating element has border radius so it won't appear broken |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the tooltip within a bounding element. When provided, the tooltip will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the tooltip within a bounding element: it stays inside it alongside its trigger (sideways for a tooltip above or below); away from the trigger it may pass the edge, and it flips at the viewport only. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `delay` | `number \| undefined` | `100` |  | Milliseconds a pointer rests on the activator before the tooltip shows (`0`: at once). Keyboard focus shows it at once, and so does a pointer arriving while another tooltip shows or within 300 ms of one closing. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the tooltip's popover and content at mount instead of on the first open. The description screen readers hear exists from mount either way. |

package/dist/ai/CommonPopover.md

@@ -18,7 +18,7 @@
 | --- | --- | --- | --- | --- |
 | `anchor` | `any` |  |  | The element the popover positions itself relative to. Accepts an HTMLElement, a Vue component ref, or a virtual element with a `getBoundingClientRect` method. |
 | `arrowPadding` | `number \| undefined` |  |  | Space the arrow will maintain to the edge of the dropdown. Useful when the floating element has border radius so it won't appear broken |
-| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover's placement (`flip` / `shift` keep it inside); it never clamps the size, so a short boundary never collapses the bubble: use `overflowBoundary` for that. An HTMLElement, a component ref or a CSS selector. |
+| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Keeps the popover inside this element alongside its anchor (sideways above or below, vertically beside it); away from the anchor it may pass the edge, and only the viewport flips it. It never clamps the size (that is `overflowBoundary`). An HTMLElement, component ref or selector. |
 | `bubbleAttrs` | `Record<string, unknown> \| ((space: CommonPopoverAvailableSpace) => Record<string, unknown>) \| undefined` |  |  | Attributes bound on the bubble (`class`, `style`, `inert`, …) after its own class, so the owner can make the bubble its layout container. The function form receives the default slot's free space (for a height cap). |
 | `dialog` | `boolean \| undefined` | `false` |  | Renders the popover as a `<dialog>` element (modal overlay) instead of a `<span>` with the Popover API. |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |