bitboss-ui 3.0.0-beta.56 → 3.0.0-beta.58

package/README.md

@@ -599,6 +599,30 @@ script, a switch bound to the same ref and your own components are never
 reported. `BbAccordion` wires all of it for you.
 `bitboss-ui check` reports the same as `collapsible-trigger-aria`.
 
+#### A dialog opened through a ref: `prefer-v-bb-dialog`
+
+A `ref(false)` whose only jobs are a `BbDialog` / `BbOffCanvas` `v-model` and
+`@click="open = true"` is wiring the library does for you.
+`bitboss-ui/prefer-v-bb-dialog` (warn, a suggestion) reports it and points at
+the id form, where the trigger also gets `aria-haspopup`, `aria-expanded`,
+`aria-controls` and focus back:
+
+```vue
+<template>
+	<BbButton v-bb-dialog="'create-label'">New label</BbButton>
+	<BbDialog id="create-label" title="Create label">…</BbDialog>
+</template>
+```
+
+`--fix` rewrites it only when nothing else uses the ref: it drops the
+declaration (and the `ref` import once unused), turns the `v-model` into an
+`id` and each click into `v-bb-dialog` (`v-bb-off-canvas` on a `BbOffCanvas`).
+A ref the code also writes (`open = false` in a Cancel, `open.value = false`
+after a save) is reported without a fix: those closes become the slots'
+`close` / `complete`. A ref anything reads (`v-if="open"`, `watch(open)`, a
+toggle) is never reported, since the page needs the state.
+`bitboss-ui check` reports the same as `prefer-v-bb-dialog` (a warning).
+
 #### A rule nobody registered: `no-unregistered-rule`
 
 A string rule is a vee-validate rule name, and vee-validate knows only the

package/bin/bitboss-ui-mcp.mjs

@@ -1161,6 +1161,19 @@ function getComponent({
 		const type = (manifest.types ?? []).find((t) => t.name === name);
 		if (type) {
 			const use = type.usedBy?.[0];
+			// Q74.1: a component's own Props type is that component's props.
+			const propsOf =
+				type.component && name === `${type.component}Props`
+					? type.component
+					: null;
+			// Q74.2: `fields` stand in for a declaration that adds nothing.
+			const shape = type.definition
+				? '`definition` above is the type itself'
+				: type.fields
+					? '`fields` above are its shape'
+					: propsOf
+						? `Its fields are ${possessive(propsOf)} props: get_component('${propsOf}')`
+						: 'It is described above';
 			return {
 				found: true,
 				kind: 'type',
@@ -1179,9 +1192,10 @@ function getComponent({
 				...(type.fields ? { fields: type.fields } : {}),
 				// A union of private members: each member's fields (Q51.21).
 				...(type.members ? { members: type.members } : {}),
+				...(propsOf ? { propsOf } : {}),
 				import: `import type { ${type.replacedBy ?? name} } from 'bitboss-ui';`,
 				hint: use
-					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. \`definition\` above is the type itself; call get_component('${use.component}') to see it in use.`
+					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. ${shape}; call get_component('${use.component}') to see it in use.`
 					: 'A type, not a component — import it for the value you pass, never write it as a tag.',
 			};
 		}
@@ -2124,7 +2138,11 @@ function docIndex() {
 					? `accepted values ${type.values.join(' | ')}`
 					: type.fields
 						? `object shape, fields ${type.fields.join('; ')}`
-						: String(type.definition ?? '')) +
+						: type.definition
+							? String(type.definition)
+							: type.component && type.name === `${type.component}Props`
+								? `the props of ${type.component}`
+								: '') +
 				`. import type { ${type.name} } from 'bitboss-ui'.`,
 			read: { tool: 'get_component', args: { name: type.name } },
 		});
@@ -2533,6 +2551,8 @@ const ROW_FIELDS =
  * as their hand-written `summary`; `detail: 'rows'` → the full rows as before.
  */
 const CHANGES_PAGE = 60;
+/** The lines' share of a page (the envelope adds ~1K): keeps it under 8K. */
+const CHANGES_PAGE_CHARS = 6000;
 
 function changeLine(row, focus) {
 	// 16 form controls in full is ~250 chars of the line; the component filter
@@ -2554,6 +2574,66 @@ function changeLine(row, focus) {
 	return `${row.id} ${row.summary ?? firstSentence(row.description, 160)}`;
 }
 
+/**
+ * One page of `[release, line]` pairs, grouped by release: it ends at
+ * CHANGES_PAGE lines or CHANGES_PAGE_CHARS of them, so its size holds however
+ * long the lines grow; the rest is a cursor away.
+ */
+function pageLines(lines, cursor) {
+	const start = Math.max(0, Number(cursor ?? 0) || 0);
+	let end = start;
+	for (let used = 0; end < lines.length && end - start < CHANGES_PAGE; end++) {
+		used += lines[end][1].length + 3;
+		if (used > CHANGES_PAGE_CHARS && end > start) break;
+	}
+	const byRelease = {};
+	for (const [release, line] of lines.slice(start, end))
+		(byRelease[release] ??= []).push(line);
+	return {
+		byRelease,
+		more:
+			end < lines.length
+				? { nextCursor: String(end), remaining: lines.length - end }
+				: {},
+	};
+}
+
+/**
+ * Q74.4: what the releases in range ADDED, as `[release, "area · what"]`,
+ * oldest first; `unreleased` only when `until` is open. A component keeps
+ * the lines of its own area (BbDialog → `dialog`) and those whose commits
+ * touched its folder (a family scope: `inputs`).
+ */
+function addedPairs(doc, { since, until, component }) {
+	const area = component
+		? String(component).replace(/^Bb/, '').toLowerCase()
+		: null;
+	return Object.entries(doc.added ?? {})
+		.filter(([at]) => {
+			if (at === 'unreleased') return until == null;
+			if (since != null && compareVersions(at, String(since)) <= 0)
+				return false;
+			if (until != null && compareVersions(at, String(until)) > 0) return false;
+			return true;
+		})
+		.flatMap(([at, entries]) =>
+			entries
+				.map((entry) =>
+					typeof entry === 'string' ? { text: entry, components: [] } : entry
+				)
+				.filter(
+					({ text, components }) =>
+						!area ||
+						text.split(' · ')[0] === area ||
+						components.includes(String(component))
+				)
+				.map(({ text }) => [at, text])
+		);
+}
+
+const ADDED_HINT =
+	'Fixes are not tracked. What the range added, one line per feature: list_changes({ since, kind: "added" }).';
+
 function changeLines(rows, cursor, withClassMap = false, focus) {
 	const lines = [];
 	const classRenames = {};
@@ -2574,18 +2654,12 @@ function changeLines(rows, cursor, withClassMap = false, focus) {
 					? -1
 					: compareVersions(a, b)
 	);
+	const page = pageLines(lines, cursor);
+	// The class map rides on the first page only.
 	const start = Math.max(0, Number(cursor ?? 0) || 0);
-	const page = lines.slice(start, start + CHANGES_PAGE);
-	const byRelease = {};
-	for (const [release, line] of page) (byRelease[release] ??= []).push(line);
 	return {
-		changes: byRelease,
-		...(start + CHANGES_PAGE < lines.length
-			? {
-					nextCursor: String(start + CHANGES_PAGE),
-					remaining: lines.length - start - CHANGES_PAGE,
-				}
-			: {}),
+		changes: page.byRelease,
+		...page.more,
 		...(Object.keys(classRenames).length && start === 0 && !withClassMap
 			? {
 					classRenames: `${Object.keys(classRenames).length} .bb-* class renames (the beta.36 sweep): the map with surface: 'class'`,
@@ -2683,6 +2757,24 @@ function listChanges({
 		}
 	}
 
+	if (kind === 'added') {
+		const pairs = addedPairs(doc, { since, until, component });
+		const page = pageLines(pairs, cursor);
+		return {
+			version: doc.version,
+			since: since ?? null,
+			until: until ?? doc.version,
+			...(component ? { filteredBy: { component } } : {}),
+			count: pairs.length,
+			added: page.byRelease,
+			...page.more,
+			hint:
+				pairs.length === 0
+					? 'Nothing added in that range (fixes are not tracked).'
+					: 'One "area · what" line per feature, grouped by release, from its feat commit. Breaking changes: the same call without kind. Next page: cursor: nextCursor.',
+		};
+	}
+
 	const rows = detail === 'rows';
 	const filtered = (doc.breaking ?? []).filter(
 		(row) =>
@@ -2742,7 +2834,8 @@ function listChanges({
 						Object.fromEntries(Object.entries(bucket).filter(([, n]) => n > 0)),
 					])
 			),
-			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".',
+			added: addedPairs(doc, {}).length,
+			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". `added`: features, kind: "added".',
 		};
 	}
 
@@ -2799,10 +2892,11 @@ function listChanges({
 			count: inRange.length,
 			...changeLines(inRange, cursor, surface === 'class', component),
 			guide: doc.guide,
+			added: addedPairs(doc, { since, until, component }).length,
 			hint:
 				inRange.length === 0
-					? 'No breaking changes recorded in that range — features and fixes are deliberately not tracked here, so an empty result means nothing BREAKS, not that nothing changed.'
-					: 'One line per change, grouped by the release that shipped it (id, components, old → new, or the break in one sentence). Whole rows: detail: "rows". The `guide` page explains each. Next page: cursor: nextCursor.',
+					? `No breaking changes recorded in that range: nothing BREAKS. ${ADDED_HINT}`
+					: `One line per change, grouped by the release that shipped it (id, components, old → new, or the break in one sentence). Whole rows: detail: "rows". The \`guide\` page explains each. Next page: cursor: nextCursor. \`added\`: features, kind: "added".`,
 		};
 	}
 
@@ -2815,7 +2909,7 @@ function listChanges({
 		guide: doc.guide,
 		hint:
 			inRange.length === 0
-				? 'No breaking changes recorded in that range — features and fixes are deliberately not tracked here, so an empty result means nothing BREAKS, not that nothing changed.'
+				? `No breaking changes recorded in that range: nothing BREAKS. ${ADDED_HINT}`
 				: `Each entry names the component and the new spelling; \`guide\` is the migration page with the full explanation. ${ROW_FIELDS}`,
 	};
 }
@@ -3009,7 +3103,7 @@ function buildServer() {
 		'list_changes',
 		{
 			description:
-				'Breaking changes between bitboss-ui releases — what breaks if you bump. Call with since=<the version you are on>: one line per change, grouped by release. No arguments: counts per release. Narrow with component / surface / kind; detail: "rows" for the full records. Only BREAKING changes are tracked; features and fixes are not.',
+				'Breaking changes between bitboss-ui releases — what breaks if you bump. Call with since=<the version you are on>: one line per change, grouped by release. No arguments: counts per release. Narrow with component / surface / kind; detail: "rows" for the full records. kind: "added" lists what the range added (features); fixes are not tracked.',
 			inputSchema: {
 				since: z
 					.string()
@@ -3044,9 +3138,11 @@ function buildServer() {
 						'Only renames of this surface (`item` = a field of an `items` entry, e.g. a dropdown row `key` → `value`).'
 					),
 				kind: z
-					.enum(['rename', 'behaviour'])
+					.enum(['rename', 'behaviour', 'added'])
 					.optional()
-					.describe('Only renames, or only behaviour changes.'),
+					.describe(
+						"Only renames, or only behaviour changes; 'added': what the range added (features), one line each."
+					),
 				detail: z
 					.enum(['lines', 'rows'])
 					.optional()

package/bin/bitboss-ui.mjs

@@ -40,8 +40,8 @@
  *   add       Copy Inertia helpers into the app as files it owns
  *             (scripts/lib/helpers-add.mjs); `helpers list|diff|update`
  *             reports on them and refreshes the ones the app has not edited.
- *   changelog Breaking changes between two releases — `--since <version>`
- *             answers "what breaks if I bump", without MCP. Reads the
+ *   changelog Breaking changes between two releases, then what they added —
+ *             `--since <version>` answers "what breaks if I bump", without MCP. Reads the
  *             installed `dist/ai/changelog.json`.
  *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
  *             (search_docs, search_components, get_component, get_composable,
@@ -167,7 +167,7 @@ function coreRules(version) {
 1. **Start at the AI Router**: \`${ROUTER}\` — which file to open next (do not dump the full catalogue into context).
 2. **Obey the agent contract**: \`${CONTRACT}\`.
 3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` and the \`BbBase*Icon\` glyphs are consumer API; the \`Common*\` building blocks are not.)
-4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or its API file \`${KNOWLEDGE_BASE}/manifest/components/<ComponentName>.json\` (one member per line; the list is \`${KNOWLEDGE_BASE}/manifest/index.json\`). Never read \`components.json\` whole: it is the 1.2 MB file the tools use.
+4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or its API file \`${KNOWLEDGE_BASE}/manifest/components/<ComponentName>.json\` (one member per line; a row marked \`common: true\` is whole in \`${KNOWLEDGE_BASE}/manifest/common.json\`; the list is \`${KNOWLEDGE_BASE}/manifest/index.json\`). Never read \`components.json\` whole: it is the 1.2 MB file the tools use.
 5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
 6. **Item-driven components**: declarative \`items\` (an object row reads its own \`label\` and \`value\`; \`item-text\` / \`item-value\` only for other field names, never to restate those two), \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
 7. **Whole pages**: one recipe under \`${KNOWLEDGE_BASE}/recipes/{vue|nuxt|inertia}/\` (see the router table).
@@ -780,7 +780,7 @@ function printFindingLegend(findings) {
  */
 /**
  * `changelog [--since <v>] [--until <v>] [--json]` — what breaks between two
- * releases, for anyone not driving the MCP server (a human at a terminal, CI,
+ * releases, then what they added (Q74.4: one line per feature), for anyone not driving the MCP server (a human at a terminal, CI,
  * or an agent whose harness has no MCP). Same data and same range rules as the
  * `list_changes` tool; this is the transport-free path to it.
  */
@@ -823,6 +823,22 @@ function changelogCommand({ since, until, json: jsonMode }) {
 		if (until != null && compareReleaseVersions(at, until) > 0) return false;
 		return true;
 	});
+	// Q74.4: what the range ADDED (feat commits, one line each), oldest first.
+	const inRange = (at) => {
+		if (!ranged) return true;
+		if (at === 'unreleased') return until == null;
+		if (since != null && compareReleaseVersions(at, since) <= 0) return false;
+		if (until != null && compareReleaseVersions(at, until) > 0) return false;
+		return true;
+	};
+	const added = Object.entries(doc.added ?? {})
+		.filter(([at]) => inRange(at))
+		.flatMap(([at, entries]) =>
+			entries.map((entry) => ({
+				at,
+				line: typeof entry === 'string' ? entry : entry.text,
+			}))
+		);
 
 	if (jsonMode) {
 		console.log(
@@ -833,6 +849,7 @@ function changelogCommand({ since, until, json: jsonMode }) {
 					until: until ?? doc.version,
 					count: rows.length,
 					breaking: rows,
+					added: added.map(({ at, line }) => `[${at}] ${line}`),
 					guide: doc.guide,
 				},
 				null,
@@ -845,13 +862,26 @@ function changelogCommand({ since, until, json: jsonMode }) {
 	const range = ranged
 		? `${since ?? 'the start of v3'} → ${until ?? doc.version}`
 		: `the whole v2 → v3 upgrade`;
+	const printAdded = () => {
+		if (!added.length) return;
+		// Compact by default: the whole v3 line is hundreds of lines.
+		if (!ranged) {
+			console.log(
+				`\n${added.length} addition(s) over ${range}: list one hop with --since <your version>.`
+			);
+			return;
+		}
+		console.log(`\n${added.length} addition(s), ${range}:\n`);
+		for (const { at, line } of added) console.log(`  [${at}] ${line}`);
+	};
 	if (rows.length === 0) {
 		// "Nothing breaks" and "I could not tell you" must not look alike.
 		console.log(
 			`[bitboss-ui] changelog: no BREAKING changes in ${range}.\n` +
-				'            Features and fixes are deliberately not tracked here, so this\n' +
-				'            means nothing breaks — not that nothing changed.'
+				'            Fixes are not tracked here, so this means nothing\n' +
+				'            breaks — not that nothing changed.'
 		);
+		printAdded();
 		return;
 	}
 	console.log(
@@ -874,6 +904,7 @@ function changelogCommand({ since, until, json: jsonMode }) {
 		}
 		if (entry.guide) console.log(`           ${entry.guide}`);
 	}
+	printAdded();
 	console.log(`\nFull migration guide: ${doc.guide}`);
 }
 
@@ -1651,7 +1682,8 @@ Commands:
                       \`bitboss-ui/validated\`, retired: everything is in
                       \`bitboss-ui\`; \`--fix\` rewrites it in .vue files),
                       \`unregistered-rule\` (a string or object rule no
-                      \`defineRule\` in the project registers; a
+                      \`defineRule\` in the project registers (in a .md
+                      page, also one the page's own fences show); a
                       registration it cannot read is named, never skipped:
                       list such names under \`registeredRules\` in
                       bitboss-ui.check.json),
@@ -1711,13 +1743,20 @@ Commands:
                       \`<…Portal name>\` nothing opens: no call site and the
                       name in no string of the project), \`vue-tsc-major\`
                       (\`vue-tsc\` below 3 in package.json: the generic
-                      components' props go unchecked).
+                      components' props go unchecked), \`prefer-v-bb-dialog\`
+                      (a \`ref(false)\` only a BbDialog / BbOffCanvas
+                      \`v-model\` and \`@click="x = true"\` use: give the
+                      dialog an \`id\` and put \`v-bb-dialog\` on the
+                      trigger; ESLint's \`--fix\` rewrites it when nothing
+                      else uses the ref).
   changelog [--since <version>] [--until <version>] [--json]
                       Breaking changes between two releases — "what breaks if I
                       bump". \`--since\` is the version you are ON, and is
                       exclusive. With no range, every break in the v2 → v3
-                      upgrade. Only BREAKING changes are tracked, so an empty
-                      result means nothing breaks, not that nothing changed.
+                      upgrade. Then what the range added, one line per feature
+                      (with no range, only their count). Fixes are not tracked,
+                      so no breaking changes means nothing breaks, not that
+                      nothing changed.
                         npx bitboss-ui changelog --since 3.0.0-beta.20
                       Pair it with \`check --manifest\` to turn the list into the
                       files in YOUR app that break.

package/dist/ai/BbBreadcrumbs.md

@@ -750,7 +750,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 `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
       - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--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__content`, `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`
+      - `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__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--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__text`; 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`, `BbBaseButton`, `BbSpinner`
   - Also mounts `BbIcon`

package/dist/ai/BbCheckbox.md

@@ -709,7 +709,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `description`, `hint`, `icon`, `label`, `message`, `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbCheckboxProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
 | `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-label-spacing-y` for `--bb-label-spacing-y-compact`, so tune a compact field's label gap with the `-compact` token, not the base one. The same meaning as on the checkbox, radio and switch groups. |
 | `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`). |

package/dist/ai/BbCheckboxGroup.md

@@ -983,7 +983,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: `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`. In `<script>` a `pt` value is typed `BbCheckboxGroupProps<Row>['pt']` (`BbCheckboxGroupProps['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
 | `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. |

package/dist/ai/BbColorInput.md

@@ -687,7 +687,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. Shows an opacity slider and uses `#RRGGBBAA` hex8 format. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
 | `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. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
 | `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
 | `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-h-compact` (and `--bb-input-py-compact`) instead. |
 | `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`). |
@@ -811,7 +811,7 @@ Set these on the element, or on a class you put on it, to retune this component
   - `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`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `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`, `--fg-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); 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__content`, `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`
+    - `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__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--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

@@ -821,7 +821,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - 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 `manifest/components/BbColorPalette.tree.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__content`, `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`
+  - `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__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--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

@@ -821,7 +821,7 @@ 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__content`, `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__content`, `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`
+    - `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__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--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__text`; 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`
 

package/dist/ai/BbDatePicker.md

@@ -540,7 +540,7 @@ Set these on the element, or on a class you put on it, to retune this component
   - `BbCalendar` _(public — [contract](./BbCalendar.md))_ — its own pt parts (`BbCalendar`): `header` → `div.bb-calendar__header`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`; documented CSS variables: `--cell`, `--unit-row`; also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`
     - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
     - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — its own pt parts (`BbCalendar`): `header` → `div.bb-time-selector__header`, `cellColumnHeader` → `div.bb-time-selector__cell-column-header`, `item` → `BbBaseButton`; documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
-  - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `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`
+  - `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__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--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/BbDatePickerInput.md

@@ -883,7 +883,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
 | `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. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
 | `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
 | `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-h-compact` (and `--bb-input-py-compact`) instead. |
 | `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`). |
@@ -1033,7 +1033,7 @@ Set these on the element, or on a class you put on it, to retune this component
     - `BbCalendar` _(public — [contract](./BbCalendar.md))_ — its own pt parts (`BbCalendar`): `header` → `div.bb-calendar__header`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`; documented CSS variables: `--cell`, `--unit-row`; also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`
       - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
       - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — its own pt parts (`BbCalendar`): `header` → `div.bb-time-selector__header`, `cellColumnHeader` → `div.bb-time-selector__cell-column-header`, `item` → `BbBaseButton`; documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
-    - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `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`
+    - `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__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--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`
   - `CommonField` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'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`, `--fg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`