bitboss-ui 3.0.0-beta.57 → 3.0.0-beta.59

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 } },
 		});
@@ -2556,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 = {};
@@ -2576,25 +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);
-	// A page ends at CHANGES_PAGE lines or CHANGES_PAGE_CHARS of them, so its
-	// size holds however long the summaries grow; the rest is a cursor away.
-	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 {
-		changes: byRelease,
-		...(end < lines.length
-			? {
-					nextCursor: String(end),
-					remaining: lines.length - end,
-				}
-			: {}),
+		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'`,
@@ -2692,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) =>
@@ -2751,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".',
 		};
 	}
 
@@ -2808,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".`,
 		};
 	}
 
@@ -2824,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}`,
 	};
 }
@@ -2865,13 +2950,13 @@ const platformSchema = z.enum(RECIPE_PLATFORMS);
  * way to know which tool answers which question, and read whole guides.
  */
 const SERVER_INSTRUCTIONS = [
-	'bitboss-ui: a Vue 3 component library. Answer from these tools, never from memory — agents that guess invent props.',
+	'bitboss-ui: a Vue 3 component library. Answer from these tools, never from memory: agents that guess invent props.',
 	"- Tailwind v4 app: set cssLayers: TAILWIND_V4_LAYERS ('bitboss-ui/vite') at setup, or utilities lose.",
-	'- A topic or "how do I…" question (dark mode, cascade layers, SSR, a plugin option, a CLI command): search_docs, then open the section it points to.',
-	'- Which component: search_components (empty query = the whole catalog). One component: get_component({ name }), one line per member; members: [names] for whole rows, sections for prose.',
-	'- A type in a props table (BbTableColumn, ButtonVariantType): get_component({ name }) returns its definition and values.',
+	'- A topic or "how do I…" (dark mode, cascade layers, SSR, a plugin option, a CLI command): search_docs, then open the section it names.',
+	'- Which component: search_components (empty query = whole catalog). One component: get_component({ name }), one line per member; members: [names] for whole rows, sections for prose.',
+	'- A type in a props table (BbTableColumn, ButtonVariantType): get_component({ name }) gives its definition and values.',
 	'- After writing markup: validate. Before custom CSS: list_tokens.',
-	'- An old name (v2 or earlier-beta prop, slot, item field, pt key, class) that stopped working: search_docs(the old name). What a bump breaks: list_changes({ since: <your version> }), one line per change.',
+	'- An old name (v2 or earlier-beta prop, slot, item field, pt key, class) that stopped working: search_docs(old name). What a bump breaks: list_changes({ since: <your version> }), a line per change.',
 	"- pt in <script> (a const, a wrapper's prop): type it <Name>Props['pt']; Pt* types are not exported.",
 	'- Composables: get_composable. Whole pages: list_recipes, get_recipe (prose + files). Long docs answer with an outline: pass sections.',
 ].join('\n');
@@ -3018,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()
@@ -3053,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),
@@ -1721,8 +1753,10 @@ Commands:
                       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/BbBadgeButton.md

@@ -20,11 +20,11 @@
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
-| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"` and `tabindex="-1"`, and prevents navigation: the link stays announced as a link but leaves the tab order. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. A native button gets the `disabled` attribute; a link (anchor/Inertia) loses `href`, gets `aria-disabled="true"` and `tabindex="-1"`, and never navigates: still announced as a link, but out of the tab order. |
 | `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download: a plain `<a download>` with a native navigation (never an Inertia or router visit), so `blob:` and `data:` files work too. A string sets the suggested filename. |
 | `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
-| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target` and `download`. |
+| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception, as Nuxt's `NuxtLink` `external` does. For links outside the SPA; a native-anchor signal alongside `target` and `download`. |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
 | `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
@@ -48,7 +48,7 @@
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
 | `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
-| `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element for the plain (non-link) button: `'button'` (default), `'div'` / `'span'` (a clickable box inside another button or link) or `'label'` (a file-upload trigger). Ignored with `href` / `to`. Off `button`, native `type` / `disabled` drop (disabled stays a class). |
+| `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element of the plain (non-link) button: `'button'` (default), `'div'` / `'span'` (a clickable box inside a button or link) or `'label'` (a file-upload trigger). Ignored with `href` / `to`. Off `button`, native `type` / `disabled` drop (disabled stays a class). |
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
 | `type` | `"button" \| "submit" \| "reset" \| undefined` | `'button'` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |

package/dist/ai/BbBaseButton.md

@@ -547,11 +547,11 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
-| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"` and `tabindex="-1"`, and prevents navigation: the link stays announced as a link but leaves the tab order. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. A native button gets the `disabled` attribute; a link (anchor/Inertia) loses `href`, gets `aria-disabled="true"` and `tabindex="-1"`, and never navigates: still announced as a link, but out of the tab order. |
 | `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download: a plain `<a download>` with a native navigation (never an Inertia or router visit), so `blob:` and `data:` files work too. A string sets the suggested filename. |
 | `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
-| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target` and `download`. |
+| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception, as Nuxt's `NuxtLink` `external` does. For links outside the SPA; a native-anchor signal alongside `target` and `download`. |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
 | `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
@@ -575,7 +575,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
 | `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
-| `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element for the plain (non-link) button: `'button'` (default), `'div'` / `'span'` (a clickable box inside another button or link) or `'label'` (a file-upload trigger). Ignored with `href` / `to`. Off `button`, native `type` / `disabled` drop (disabled stays a class). |
+| `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element of the plain (non-link) button: `'button'` (default), `'div'` / `'span'` (a clickable box inside a button or link) or `'label'` (a file-upload trigger). Ignored with `href` / `to`. Off `button`, native `type` / `disabled` drop (disabled stays a class). |
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
 | `text` | `string \| undefined` |  |  | Fallback text content rendered when no default slot is provided. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |

package/dist/ai/BbCheckbox.md

@@ -712,9 +712,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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`). |
+| `description` | `string \| undefined` |  |  | Text between the label and the input. Unlike the hint it is always visible; it joins the input's `aria-describedby` after any `errors` / `warnings`, before the `hint`. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
-| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or string array. They render in an `aria-live="polite"` region and are referenced first from the control's `aria-describedby`, so they are re-read when it regains focus. |
+| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or array, in an `aria-live="polite"` region and first in the control's `aria-describedby`, so they are re-read when it regains focus. |
 | `falseValue` | `any` |  |  | Value of the input when unchecked. It handles any kind of serializable object. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
@@ -728,7 +728,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelAlign` | `FieldCrossAlign \| undefined` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
-| `layout` | `Responsive<FieldLayout> \| undefined` | `"auto"` |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map such as `{ default: 'vertical', md: 'xx xxxxx' }`. |
+| `layout` | `Responsive<FieldLayout> \| undefined` | `"auto"` |  | How label and input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`). |
 | `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. |
@@ -738,9 +738,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `rules` | `RuleExpression<any>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `submitWhenFalse` | `boolean \| undefined` | `false` |  | Will submit "falseValue" if the input is not checked. Otherwise "trueValue" will be submitted. |
 | `trueValue` | `any` |  |  | Value of the input when checked. It handles any kind of serializable object. |
-| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; the field's `name` never shows. Set it when the label is not a good noun for a sentence (an icon-only label, a question) or is hidden. Only inside a `BbForm`. |
-| `validationMode` | `ValidationMode \| undefined` |  |  | When this field validates as the user works: `aggressive` (every change), `balanced` (on leave, then live while it shows an error), `lazy` (on leave), `submit-only` or `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). Only in a `BbForm`. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or string array: amber, in their own `aria-live` region, and in the control's `aria-describedby` after the errors. A non-empty list implies the warning state; errors win when both are set. |
+| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; never the `name`. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). `BbForm` only. |
+| `validationMode` | `ValidationMode \| undefined` |  |  | When the field validates: `aggressive` (each change), `balanced` (on leave, then live while in error), `lazy` (on leave), `submit-only`, `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). `BbForm` only. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or array: amber, in their own `aria-live` region and in the control's `aria-describedby` after the errors. Non-empty turns on the warning state; errors win when both are set. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbCheckboxGroup.md

@@ -987,11 +987,11 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `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`). |
+| `description` | `string \| undefined` |  |  | Text between the label and the input. Unlike the hint it is always visible; it joins the input's `aria-describedby` after any `errors` / `warnings`, before the `hint`. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `emptyText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | After every applied, successful load (an empty one included), drops the model values the options no longer contain (a single value resets to `null`). A failed load never prunes. |
-| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or string array. They render in an `aria-live="polite"` region and are referenced first from the control's `aria-describedby`, so they are re-read when it regains focus. |
+| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or array, in an `aria-live="polite"` region and first in the control's `aria-describedby`, so they are re-read when it regains focus. |
 | `failedText` | `string \| undefined` | `the localized `common.failedText` ("Couldn't load items")` |  | String displayed in the empty state while the latest load FAILED (the `items` provider threw): the twin of `emptyText` for that case. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
@@ -1011,7 +1011,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `itemText` | `ItemAccessor<T, string> \| undefined` | `own `label`, else `text`, else `JSON.stringify(item)`` |  | Defines a path that returns a property of the object to use as text or a function that returns a string. Unset: own `label`, else `text` (`{ label, value }` needs no accessor). |
 | `itemValue` | `ItemAccessor<T> \| undefined` | `own `value`, else the whole item` |  | Defines a path that returns a property of the object to use as value or a function that returns any value. Unset: own `value`, even `null`. |
 | `labelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
-| `layout` | `Responsive<FieldLayout> \| undefined` |  |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map such as `{ default: 'vertical', md: 'xx xxxxx' }`. |
+| `layout` | `Responsive<FieldLayout> \| undefined` |  |  | How label and input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`). |
 | `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 no single field for the legend to float against. |
 | `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
@@ -1027,9 +1027,9 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `rules` | `RuleExpression<any>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
-| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; the field's `name` never shows. Set it when the label is not a good noun for a sentence (an icon-only label, a question) or is hidden. Only inside a `BbForm`. |
-| `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When this field validates as the user works: `aggressive` (every change), `balanced` (on leave, then live while it shows an error), `lazy` (on leave), `submit-only` or `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). Only in a `BbForm`. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or string array: amber, in their own `aria-live` region, and in the control's `aria-describedby` after the errors. A non-empty list implies the warning state; errors win when both are set. |
+| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; never the `name`. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). `BbForm` only. |
+| `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When the field validates: `aggressive` (each change), `balanced` (on leave, then live while in error), `lazy` (on leave), `submit-only`, `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). `BbForm` only. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or array: amber, in their own `aria-live` region and in the control's `aria-describedby` after the errors. Non-empty turns on the warning state; errors win when both are set. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbColorInput.md

@@ -689,10 +689,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `autocomplete` | `string \| undefined` | `"off"` |  | Guides the browser as to the type of information expected in the field. |
 | `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`). |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density: the field uses the `-compact` twins of `--bb-input-h`, `--bb-input-py` and `--bb-label-spacing-y`, so a `--bb-input-h` set on the component is ignored while it is on. Size a compact field with `--bb-input-h-compact` (and `--bb-input-py-compact`). |
+| `description` | `string \| undefined` |  |  | Text between the label and the input. Unlike the hint it is always visible; it joins the input's `aria-describedby` after any `errors` / `warnings`, before the `hint`. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
-| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or string array. They render in an `aria-live="polite"` region and are referenced first from the control's `aria-describedby`, so they are re-read when it regains focus. |
+| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or array, in an `aria-live="polite"` region and first in the control's `aria-describedby`, so they are re-read when it regains focus. |
 | `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
@@ -705,7 +705,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `labelAlign` | `FieldCrossAlign \| undefined` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `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` | `Responsive<FieldLayout> \| undefined` |  |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map such as `{ default: 'vertical', md: 'xx xxxxx' }`. |
+| `layout` | `Responsive<FieldLayout> \| undefined` |  |  | How label and input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`). |
 | `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
 | `modelValue` | `string \| null \| undefined` | `null` |  | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
@@ -718,10 +718,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `rules` | `RuleExpression<string \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display in the picker: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |
-| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; the field's `name` never shows. Set it when the label is not a good noun for a sentence (an icon-only label, a question) or is hidden. Only inside a `BbForm`. |
-| `validationMode` | `ValidationMode \| undefined` |  |  | When this field validates as the user works: `aggressive` (every change), `balanced` (on leave, then live while it shows an error), `lazy` (on leave), `submit-only` or `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). Only in a `BbForm`. |
-| `variant` | `InputVariantType \| undefined` | `'outline'` |  | Visual variant of the field box, with the `BbButton` names and tokens. Colours only, so a form never reflows; `'ghost'` has no border in any state, and `'none'` takes no look at all (you own hover, focus and the states). Register more with the plugin's `inputVariants`. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or string array: amber, in their own `aria-live` region, and in the control's `aria-describedby` after the errors. A non-empty list implies the warning state; errors win when both are set. |
+| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; never the `name`. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). `BbForm` only. |
+| `validationMode` | `ValidationMode \| undefined` |  |  | When the field validates: `aggressive` (each change), `balanced` (on leave, then live while in error), `lazy` (on leave), `submit-only`, `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). `BbForm` only. |
+| `variant` | `InputVariantType \| undefined` | `'outline'` |  | The field box's look, with `BbButton`'s names and tokens. Colours only, so a form never reflows; `'ghost'` has no border in any state, `'none'` no look at all (you own hover, focus and the states). Register more with the plugin's `inputVariants`. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or array: amber, in their own `aria-live` region and in the control's `aria-describedby` after the errors. Non-empty turns on the warning state; errors win when both are set. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbDatePickerInput.md

@@ -885,12 +885,12 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `autocomplete` | `string \| undefined` | `"off"` |  | Guides the browser as to the type of information expected in the field. |
 | `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`). |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density: the field uses the `-compact` twins of `--bb-input-h`, `--bb-input-py` and `--bb-label-spacing-y`, so a `--bb-input-h` set on the component is ignored while it is on. Size a compact field with `--bb-input-h-compact` (and `--bb-input-py-compact`). |
+| `description` | `string \| undefined` |  |  | Text between the label and the input. Unlike the hint it is always visible; it joins the input's `aria-describedby` after any `errors` / `warnings`, before the `hint`. |
 | `disableCalendar` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables the calendar: hides the trigger button and prevents the popover from opening. Use `'desktop'` to disable it on desktop only (keeping the calendar for mobile, complementing `disableWriting: 'mobile'`) or `'mobile'` to disable it on mobile only. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables typing into the input. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. |
-| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or string array. They render in an `aria-live="polite"` region and are referenced first from the control's `aria-describedby`, so they are re-read when it regains focus. |
+| `errors` | `string \| string[] \| undefined` |  |  | Error messages under the field, a string or array, in an `aria-live="polite"` region and first in the control's `aria-describedby`, so they are re-read when it regains focus. |
 | `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `the locale's week start` |  | First day of the week (0 = Sunday … 6 = Saturday). Omitted, the active locale's week start: Monday for `it`, `de`, `fr`, `en-gb`…, Sunday for bare `en` (US) and `pt` (Brazil). |
 | `floating` | `boolean \| undefined` | `false` |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
@@ -904,7 +904,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `labelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `labelMode` | `"outside" \| "floating" \| "inside" \| undefined` |  |  | Label rendering mode. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
-| `layout` | `Responsive<FieldLayout> \| undefined` |  |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map such as `{ default: 'vertical', md: 'xx xxxxx' }`. |
+| `layout` | `Responsive<FieldLayout> \| undefined` |  |  | How label and input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`). |
 | `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
 | `max` | `string \| undefined` |  |  | Maximum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
 | `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
@@ -926,10 +926,10 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
 | `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the field edits, and so its segments and emitted shape: `date` (`DD/MM/YYYY`), `datetime` (adds the time segments and rail), `month` (`MM/YYYY`, emits `YYYY-MM`) or `year` (`YYYY`). `month` / `year` force `floating`, ignore `utc`, and leave the time props inert. |
 | `utc` | `boolean \| undefined` | `false` |  | Emits UTC ISO strings (`…Z`) instead of the local offset (`…+01:00`). Emission only: incoming values parse the same either way, and the field always displays local time. Ignored with `floating`. |
-| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; the field's `name` never shows. Set it when the label is not a good noun for a sentence (an icon-only label, a question) or is hidden. Only inside a `BbForm`. |
-| `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When this field validates as the user works: `aggressive` (every change), `balanced` (on leave, then live while it shows an error), `lazy` (on leave), `submit-only` or `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). Only in a `BbForm`. |
-| `variant` | `'outline'` \| `'secondary'` \| `'none'` \| `'ghost'` | `'outline'` |  | Visual variant of the field box, with the `BbButton` names and tokens. Colours only, so a form never reflows; `'ghost'` has no border in any state, and `'none'` takes no look at all (you own hover, focus and the states). Register more with the plugin's `inputVariants`. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or string array: amber, in their own `aria-live` region, and in the control's `aria-describedby` after the errors. A non-empty list implies the warning state; errors win when both are set. |
+| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; never the `name`. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). `BbForm` only. |
+| `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When the field validates: `aggressive` (each change), `balanced` (on leave, then live while in error), `lazy` (on leave), `submit-only`, `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). `BbForm` only. |
+| `variant` | `'outline'` \| `'secondary'` \| `'none'` \| `'ghost'` | `'outline'` |  | The field box's look, with `BbButton`'s names and tokens. Colours only, so a form never reflows; `'ghost'` has no border in any state, `'none'` no look at all (you own hover, focus and the states). Register more with the plugin's `inputVariants`. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or array: amber, in their own `aria-live` region and in the control's `aria-describedby` after the errors. Non-empty turns on the warning state; errors win when both are set. |
 
 ## Passthrough parts and states