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

package/bin/bitboss-ui-mcp.mjs

@@ -2950,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');

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
 

package/dist/ai/BbDialog.md

@@ -1520,7 +1520,26 @@ const route = useRoute();
 ```
 
 Template dialogs only: a dialog opened on demand has no place in the page URL
-(`navigation` is ignored there, with a dev warning). On the phone the adaptive
+(`navigation` is ignored there, with a dev warning). A wrapper component that
+should live in the URL is rendered in the page and opened by id: reload opens
+it, Back closes it, closing strips the key. State it needs fresh on every
+opening (a form object made in setup) goes in its body, a small component
+inside the BbDialog whose setup runs per opening, or in the opening's `data`
+with `default-data`:
+
+```vue
+<!-- CreatePatientDialog.vue renders
+     <BbDialog id="create-patient" navigation query-key="create">
+       <PatientForm /> (its own setup: a fresh form per opening)
+     </BbDialog> -->
+<CreatePatientDialog />
+<BbButton v-bb-dialog="'create-patient'">New patient</BbButton>
+```
+
+On demand stays for openings with no page to live in (a command palette, a
+store action, stacked copies of one dialog), which want no URL anyway.
+
+On the phone the adaptive
 sheet is the same dialog: one key, and Back is refused by the sheet's own
 gates. Under Inertia, a Back that changes only dialog keys never reaches
 Inertia, so the page is not remounted; this needs `bitbossUiPlugin` installed
@@ -1757,7 +1776,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `close`, `content`, `description`, `footer`, `header`, `root`, `sheet`, `title`. States: `fullscreen`, `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbDialogProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, renders as a `BbOffCanvas` drawer instead of a centred dialog; the surface is chosen when the dialog opens and kept until it closes. Unset: the global `config.adaptive`. |
-| `defaultData` | `Record<string, any> \| undefined` |  |  | The `data` of an opening that passes none (a create), as an object: copied at once and exposed as `data`, so inputs bind `data.x` with no guard. An opening with data lays it over this (`{ ...defaultData, ...row }`, one level). `reset()` restores its keys, keeping an edit's `id`; a close restores it. |
+| `defaultData` | `Record<string, any> \| undefined` |  |  | What `data` is when an opening passes none (a create): an object, copied at once, so inputs bind `data.x` with no guard. An opening's data lays over it (`{ ...defaultData, ...row }`, one level). `reset()` restores its keys but keeps an edit's `id`; a close restores it. |
 | `description` | `string \| undefined` |  |  | One short line under the title, muted (the shadcn `DialogDescription` shape), and the only element `aria-describedby` points at. Keep it to a sentence; anything longer belongs in the body. |
 | `eager` | `boolean \| undefined` | `false` |  | Keep the body mounted while closed, from before the first opening. Without it the body mounts per opening and unmounts after `@hidden`. `data` still clears while closed, so an eager body guards its reads. |
 | `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
@@ -1765,16 +1784,16 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `hideClose` | `boolean \| undefined` | `false` |  | Hide the default close (×) button. The button is shown by default; set this to remove it (e.g. for a `persistent` dialog you don't want dismissible — the × otherwise still closes a persistent dialog). |
 | `id` | `string \| undefined` |  |  | Names the dialog for `v-bb-dialog="'edit'"` and `useBbDialogContext`, found nearest to the trigger, so two pages may reuse an id. Also the DOM `id`: one dialog per id, rows pass `data`. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the dialog. A dialog with no `v-model` starts closed. |
-| `navigation` | `boolean \| undefined` | `false` |  | Syncs the open state with the URL: opening writes `?<queryKey>=true`, closing removes it, a URL carrying the key opens the dialog on load, and Back closes it (refused like Escape when locked). Template dialogs only; a record id stays in your own query. |
+| `navigation` | `boolean \| undefined` | `false` |  | Syncs the open state with the URL: opening writes `?<queryKey>=true`, closing removes it, a URL with the key opens the dialog on load, and Back closes it (refused whenever Escape is). Template dialogs only; keep a record id in your own query. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on mobile), spread over its defaults. A `pt` inside it styles only the sheet (passthrough guide § Inside the sheet). |
-| `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks or Escape key. The header close (×) button STILL closes a persistent dialog — that is the documented escape hatch; combine with `hideClose` to remove it, or use `preventClose` to block every dismissal. Programmatic close is still allowed. |
-| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape and the ✕, and the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always. `false`: never, not even mid-save. Beside a form: `busy \|\| undefined`. |
+| `persistent` | `boolean \| undefined` | `false` |  | Blocks closing by outside click or Escape. The header close (×) STILL closes a persistent dialog, the documented escape hatch: add `hideClose` to remove it, or use `preventClose` to block every dismissal. Programmatic close still works. |
+| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape, the ✕, the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always; `false`: never, not even mid-save. Beside a form: `busy \|\| undefined`. |
 | `queryKey` | `string \| undefined` | `"dialog"` |  | The query key `navigation` writes. |
 | `replace` | `boolean \| undefined` | `false` |  | With `navigation`, replaces the history entry instead of pushing one, so Back leaves the page instead of closing the dialog. |
 | `size` | `Responsive<NonNullable<number \| CssSize \| keyof BbDialogSizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
 | `snap` | `BbSnapPoint \| undefined` |  |  | The phone sheet's snap stop (Q71.8), one of the `snapPoints` entries. The desktop dialog ignores it. |
-| `snapPoints` | `BbSnapPoint[] \| undefined` |  |  | Heights the phone sheet rests at, smallest first: a fraction of the screen (`0.5`; `1` = as tall as it gets) or a pixel height (`'240px'`). The first stop is the opening height; `v-model:snap` reads and sets the stop. Phone sheet only: the desktop dialog ignores it. |
-| `stack` | `string \| undefined` |  |  | Name of the stack this dialog belongs to. Dialogs sharing the same `stack` value replace one another: only the most recently opened stays visible while the others in the stack are hidden beneath it. Dialogs in different stacks — or with no `stack` — never affect each other and remain fully visible. |
+| `snapPoints` | `BbSnapPoint[] \| undefined` |  |  | Heights the phone sheet rests at, smallest first: a screen fraction (`0.5`; `1` = as tall as it gets) or pixels (`'240px'`). The first is the opening height; `v-model:snap` reads and sets the stop. Sheet only: the centred dialog ignores it. |
+| `stack` | `string \| undefined` |  |  | Name of this dialog's stack. Dialogs with the same `stack` replace one another: only the latest opened shows, the rest of the stack hide beneath it. Dialogs in different stacks, or with no `stack`, never affect each other and stay fully visible. |
 | `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered (unless a `header` slot is supplied) and accessibility must be handled manually. |
 | `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |
 

package/dist/ai/BbDropzone.md

@@ -1664,7 +1664,7 @@ button, grows with every file added, and changes mid-drag. So:
 | `accept` | `string[] \| undefined` |  |  | File filter: MIME types (`'image/png'`), wildcards (`'image/*'`), extensions (`'.png'`) or bare tokens (`'png'`, upgraded to the extension and its MIME type from the lazily imported `mime` database; files that arrive earlier wait for it). |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
 | `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. |
 | `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. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
@@ -1674,11 +1674,11 @@ button, grows with every file added, and changes mid-drag. So:
 | `modelValue` | `File \| File[] \| null \| undefined` |  |  | Used by v-model. |
 | `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `readonly` | `boolean \| undefined` | `false` |  | Shows the files without letting the user change them: drop, the file picker and the `open()` slot prop do nothing, while the input stays focusable and a `name`d zone still submits its files (unlike `disabled`). Your slot renders the list, so hide your remove buttons with the `readonly` slot prop. |
+| `readonly` | `boolean \| undefined` | `false` |  | Shows the files; the user cannot change them: drop, the file picker and the `open()` slot prop do nothing, yet the input stays focusable and a `name`d zone still submits its files (unlike `disabled`). Your slot renders the list: hide your remove buttons with the slot's `readonly`. |
 | `rules` | `RuleExpression<File \| File[] \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `tag` | `'div'` \| `'span'` | `"div"` |  | Element rendered as the component's wrapper. |
-| `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`. |
+| `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 dropzone, 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. |
 
 ## Passthrough parts and states
@@ -1704,7 +1704,7 @@ States are listed in precedence order: when two are on at once and their entries
 ## Events
 
 - `blur` — `(event: FocusEvent): void` — Emitted when the file input loses focus. Forwards the original DOM `FocusEvent`.
-- `error` — `(errors: DropZoneError[]): void` — Emitted once per drop or pick that rejected at least one file, AFTER that gesture's `update:modelValue`: every rejection of the gesture (size, type, uniqueness, max count), in file order. A clean drop emits none, so clear your messages on `update:modelValue` and set them here.
+- `error` — `(errors: DropZoneError[]): void` — Emitted once per drop or pick that rejected any file, AFTER that gesture's `update:modelValue` (if any): all its rejections (size, type, uniqueness, max count), in file order. A clean drop emits none: clear your messages on `update:modelValue`, set them here.
 - `focus` — `(event: FocusEvent): void` — Emitted when the file input receives focus. Forwards the original DOM `FocusEvent`.
 - `update:modelValue` — `(value: File \| File[] \| null): void` — Emitted when the selected files change. Payload is the new file or file array.
 

package/dist/ai/BbForm.md

@@ -1761,12 +1761,12 @@ marker stays consistent with the rules.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `disableSubmitLock` | `boolean \| undefined` | `false` |  | Keeps the fields editable while a `@submit` promise is pending (by default every joined field is read-only until it settles; a `@submit` that returns nothing never locks). Submit buttons spin either way. |
-| `fieldErrors` | `Record<string, unknown> \| null \| undefined` |  |  | A server's validation errors by field path (Inertia's `form.errors`, a Laravel 422 body), shown on their fields for as long as they are in the object. They never block a submit; a key no field has is in `unmatchedErrors`. A one-off message: `setErrors`. |
+| `fieldErrors` | `Record<string, unknown> \| null \| undefined` |  |  | Server validation errors by field path (Inertia's `form.errors`, a Laravel 422 body), shown on their fields while they are in the object. They never block a submit; a key no field has is in `unmatchedErrors`. A one-off message: `setErrors`. |
 | `id` | `string \| undefined` |  |  | Lets anything outside the form read and drive it through `useBbFormContext(id)` (a dialog footer, a toolbar, a leave guard). It is also the `<form>`'s id, so `<button form="id" type="submit">` outside it submits it. |
 | `keepValuesOnUnmount` | `boolean \| Ref<boolean, boolean> \| undefined` |  |  | Keep a field's value (and its place in `@submit`) when it unmounts — the `v-if` wizard step you left, a collapsed section. Off, an unmounted field drops out of the values. |
-| `model` | `Record<string, any> \| undefined` |  |  | The object the fields edit (`reactive()`, a `ref`, Pinia state, Inertia `useForm()`), written in place: bind it one way, `:model`, never `v-model`. A field without its own `v-model` reads and writes the value at its `name` path. Nothing is written on mount. |
-| `schema` | `MaybeRef<S \| undefined>` |  |  | One Standard Schema for the whole form (Zod, Valibot, ArkType, Yup, Joi, Effect), passed as is. Errors land on the field whose `name` is the issue path; `@submit` gets the typed output. Set it at mount (a `computed` may change it); per-field `rules` are then ignored. |
-| `validationMode` | `ValidationMode \| undefined` |  |  | When the fields inside check themselves while the user works: `aggressive`, `balanced`, `lazy`, `submit-only` or `submit-live` (see `ValidationMode`). A field's own `validation-mode` wins. Unset, the app's `formControls.validationMode` applies (`'balanced'` by default). |
+| `model` | `Record<string, any> \| undefined` |  |  | The object the fields edit in place (`reactive()`, a `ref`, Pinia state, Inertia `useForm()`): bind it one way, `:model`, never `v-model`. A field without its own `v-model` reads and writes the value at its `name` path. Nothing is written on mount. |
+| `schema` | `MaybeRef<S \| undefined>` |  |  | One Standard Schema for the form (Zod, Valibot, ArkType, Yup, Joi, Effect), passed as is. An issue lands on the field whose `name` is its path; `@submit` gets the typed output. Set it at mount (a `computed` may change it); per-field `rules` are then ignored. |
+| `validationMode` | `ValidationMode \| undefined` |  |  | When the fields inside validate as the user works: `aggressive`, `balanced`, `lazy`, `submit-only` or `submit-live` (see `ValidationMode`). A field's own `validation-mode` wins. Unset: the app's `formControls.validationMode` (default `'balanced'`). |
 
 ## Events
 

package/dist/ai/BbNumberInput.md

@@ -863,12 +863,12 @@ 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. |
+| `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`). |
 | `currency` | `string \| undefined` |  |  | An ISO 4217 code (`'EUR'`): the amount shows the locale's way, symbol inside the text (`1.234,56 €`), leaving `#prefix` / `#suffix` free; the model is the number. Decimals default to the currency's; `minPrecision` / `maxPrecision` win. Not with `unit`. |
-| `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. |
 | `disableFormatting` | `boolean \| undefined` | `false` |  | Shows the number as typed (period decimal, no grouping), with `name` on the visible input. Without it the field formats the locale's way while typing (`10.005,6`) and posts the raw value (`10005.6`) through a hidden input carrying `name`. |
-| `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. |
 | `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. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
@@ -880,7 +880,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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` | `number \| undefined` | `Number.MAX_SAFE_INTEGER` |  | Maximum value cap. |
 | `maxPrecision` | `number \| undefined` | `8` |  | Maximum precision of the number: fraction digits past it are refused as typed (never rounded). With `currency`, the currency's own digits (`2` for EUR, `0` for JPY, `3` for KWD), or `minPrecision` when that is larger. |
@@ -897,10 +897,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `rules` | `RuleExpression<string \| number \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `step` | `number \| undefined` | `1` |  | Incremental unit used by ArrowUp / ArrowDown and by the `increase` and `decrease` functions the slots receive. It is NOT applied to manual input as a step of 5 would prevent the user from inserting a value like `115` because of rounding down. |
 | `unit` | `BbNumberUnit \| undefined` |  |  | A unit `Intl.NumberFormat` knows (`'kilogram'`, `'celsius'`, `'percent'`), shown the locale's way inside the text (`20 kg`). The model is the number you see: `percent` showing `15 %` holds `15`. Not with `currency` (which wins). |
-| `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
 

package/dist/ai/BbOffCanvas.md

@@ -167,6 +167,8 @@ It works exactly like `v-bb-dialog` (see the BbDialog guide):
 - On Android, the system back button closes the top panel like Escape (it is the browser's close request), so `prevent-close` and a saving form refuse it the same way; iOS swipe-back and the desktop back button are page navigation.
 - The button gets `aria-haspopup="dialog"`, `aria-expanded` and
   `aria-controls`, and focus returns to it on close.
+- A native `<button commandfor="…" command="show-modal">` (or `"close"`) is
+  safe: it takes the same open and user-close paths. Prefer `v-bb-off-canvas`.
 
 An adaptive `BbDialog` that shows as a sheet on a phone is still a dialog:
 open it with `v-bb-dialog`.
@@ -1130,7 +1132,9 @@ import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
 `?offcanvas=true` (`query-key` renames it), closing removes it, a link or
 reload carrying the key opens the panel, and Back closes it with
 `reason: 'escape'`, refused like Escape by `persistent`, `prevent-close` or a
-saving form. `replace` skips the history entry. Same rules as
+saving form. `replace` skips the history entry. Template panels only: a
+wrapper that should live in the URL is rendered in the page and opened by id
+(`v-bb-off-canvas`), with per-opening state in its body. Same rules as
 [BbDialog § In the URL](./BbDialog.md#in-the-url-navigation).
 
 ```vue
@@ -1370,7 +1374,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: `close`, `content`, `description`, `footer`, `header`, `root`, `title`. States: `fullscreen`, `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbOffCanvasProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `defaultData` | `Record<string, any> \| undefined` |  |  | The `data` of an opening that passes none (a create), as an object: copied at once and exposed as `data`, so inputs bind `data.x` with no guard. An opening with data lays it over this (`{ ...defaultData, ...row }`, one level). `reset()` restores its keys, keeping an edit's `id`; a close restores it. |
+| `defaultData` | `Record<string, any> \| undefined` |  |  | What `data` is when an opening passes none (a create): an object, copied at once, so inputs bind `data.x` with no guard. An opening's data lays over it (`{ ...defaultData, ...row }`, one level). `reset()` restores its keys but keeps an edit's `id`; a close restores it. |
 | `description` | `string \| undefined` |  |  | One short line under the title, muted (the shadcn `DialogDescription` shape), and the only element `aria-describedby` points at. Keep it to a sentence; anything longer belongs in the body. |
 | `draggable` | `boolean \| undefined` | `false` |  | Drag-to-dismiss: a ~50px swipe toward the exit edge (also from the body once it is scrolled to its edge), with a grab handle as the cue. A gesture that starts inside `data-bb-no-drag` never drags the panel. |
 | `eager` | `boolean \| undefined` | `false` |  | Keep the body mounted while closed, from before the first opening. Without it the body mounts per opening and unmounts after `@hidden`. `data` still clears while closed, so an eager body guards its reads. |
@@ -1379,13 +1383,13 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `hideClose` | `boolean \| undefined` | `false` |  | Hides the default close (×) button in the header (e.g. for a `persistent` drawer you don't want dismissible — the × otherwise still closes a persistent drawer). |
 | `id` | `string \| undefined` |  |  | Names the panel for `v-bb-off-canvas="'filters'"` and `useBbOffCanvasContext`, found nearest to the trigger, so two pages may reuse an id. Also the DOM `id`: one panel per id. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the panel. A panel with no `v-model` starts closed. |
-| `navigation` | `boolean \| undefined` | `false` |  | Syncs the open state with the URL: opening writes `?<queryKey>=true`, closing removes it, a URL carrying the key opens the panel on load, and Back closes it (refused like Escape when locked). Template panels only; a record id stays in your own query. |
-| `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks, Escape key or drag-to-dismiss. The header close (×) button STILL closes a persistent drawer — that is the documented escape hatch; combine with `hideClose` to remove it, or use `preventClose` to block every dismissal. Programmatic close is still allowed. |
-| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape, drag and the ✕, and the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always. `false`: never, not even mid-save. Beside a form: `busy \|\| undefined`. |
+| `navigation` | `boolean \| undefined` | `false` |  | Syncs the open state with the URL: opening writes `?<queryKey>=true`, closing removes it, a URL with the key opens the panel on load, and Back closes it (refused whenever Escape is). Template panels only; keep a record id in your own query. |
+| `persistent` | `boolean \| undefined` | `false` |  | Blocks closing by an outside click, Escape or drag-to-dismiss. The header close (×) STILL closes a persistent drawer, the documented escape hatch: add `hideClose` to remove it, or use `preventClose` to block every dismissal. Programmatic close still works. |
+| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape, drag, the ✕, the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always; `false`: never, not even mid-save. Beside a form: `busy \|\| undefined`. |
 | `queryKey` | `string \| undefined` | `"offcanvas"` |  | The query key `navigation` writes. |
 | `replace` | `boolean \| undefined` | `false` |  | With `navigation`, replaces the history entry instead of pushing one, so Back leaves the page instead of closing the panel. |
 | `side` | `"left" \| "top" \| "bottom" \| "right" \| undefined` | `"left"` |  | Which viewport edge the offcanvas docks to (and slides in from). |
-| `size` | `Responsive<OffCanvasSize> \| undefined` | `"sm"` |  | The panel's extent along its axis: the width of a left/right panel (shrinking with a narrower viewport) or the height of a top/bottom one (capped at the viewport). A preset `'xs'`–`'2xl'`, `'auto'`, a CSS size, a pixel number, or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`). |
+| `size` | `Responsive<OffCanvasSize> \| undefined` | `"sm"` |  | The panel's extent along its axis: a left/right panel's width (shrinks with a narrower viewport) or a top/bottom one's height (capped at the viewport). A preset `'xs'`–`'2xl'`, `'auto'`, a CSS size, a pixel number, or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`). |
 | `snap` | `BbSnapPoint \| undefined` |  |  | The snap stop the sheet rests at, written as one of the `snapPoints` entries (Q71.8). Updated once the sheet settles on another stop; setting it moves the sheet there. Unbound, every opening starts at the first stop. |
 | `snapPoints` | `BbSnapPoint[] \| undefined` |  |  | Heights a draggable bottom sheet rests at, smallest first: a fraction of the screen (`0.5`, `1` = full) or `'240px'`. The first is the opening height; `v-model:snap` holds the stop. Ignored on other sides and `fullscreen` (guide § Snap points). |
 | `stack` | `string \| undefined` |  |  | Name of the stack this drawer belongs to. Drawers sharing the same `stack` value step back behind one another as later ones open; drawers in different stacks never affect each other. When omitted, the drawer stacks with nothing. |

package/dist/ai/BbRadio.md

@@ -505,9 +505,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. |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
 | `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
@@ -518,7 +518,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` | `'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. |
 | `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` |  |  | Name of the input. Optional: a generated one is unique to this radio, so radios that form ONE exclusive group must share an explicit `name`. Pass one too for a native (non-JS) form post under a known key. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
@@ -526,7 +526,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
 | `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
 | `value` | `any` |  | yes | Defines the value of the radio input. It can be any serializable value. |
-| `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. |
+| `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