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

package/dist/ai/BbCalendar.md

@@ -235,7 +235,9 @@ plus seconds with `seconds` and an AM/PM column with `ampm`; `step` sets the
 minute granularity. With `floating` the day stays plain and the time travels
 only through `v-model:time` (`HH:mm` / `HH:mm:ss`); otherwise the time lives
 inside `modelValue` and `time` mirrors it. In `range` + `datetime`
-`v-model:active-segment` says which end the rail edits.
+`v-model:active-segment` says which end the rail edits. A `min` / `max` with
+a time (`YYYY-MM-DDTHH:mm`) disables the days outside it and, on its own day,
+the times before `min` / after `max` on the rail.
 
 The calendar takes its natural width (grid plus rail, about 335px; wider with
 seconds or AM/PM) or the room it is given, whichever is less. When its own box
@@ -594,16 +596,16 @@ the page is `BbDatePicker`.
 | `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` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. With `datetime`, on its own day the time rail disables the times after it. |
-| `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. With `datetime`, the grid disables the days before it and, on its own day, the time rail disables the times before it. |
-| `modelValue` | `string \| string[] \| null` |  | yes | v-model value. `null` for empty, a single string for single selection, or a two-element `[start, end]` array when `range` is true (a sorted array under `multiple`). The string shape follows `type`: `YYYY-MM-DD` when `floating` (`YYYY-MM` for `month`, `YYYY` for `year`), otherwise a zoned ISO instant carrying the time inline with `type="datetime"`. |
-| `multiple` | `boolean \| undefined` | `false` |  | Enables multi-selection: every pick toggles a value in or out of a sorted array. Works in whatever `type` selects — days, months or years — and requires an array `modelValue` (use `[]` for empty, never `null`). Mutually exclusive with `range` (two different selection models) and with `type="datetime"` (the time rail edits one value; with several there is no one it could mean). Both combinations throw. |
+| `min` | `string \| undefined` |  |  | Minimum selectable value in this `type`'s shape (`YYYY-MM-DD`; `YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is floored to the unit, with a warning. With `datetime` the rail also disables the earlier times on its day. |
+| `modelValue` | `string \| string[] \| null` |  | yes | v-model: `null` when empty, a string, a `[start, end]` pair with `range`, or a sorted array with `multiple`. The string is `YYYY-MM-DD` when `floating` (`YYYY-MM` / `YYYY` for `month` / `year`), otherwise a zoned ISO instant (carrying the time under `datetime`). |
+| `multiple` | `boolean \| undefined` | `false` |  | Multi-selection: each pick toggles a value in a sorted array (days, months or years). Needs an array `modelValue` (`[]` when empty, never `null`). Throws with `range` or `type="datetime"`. |
 | `range` | `boolean \| undefined` | `false` |  | Enables range selection (`[start, end]`). |
 | `readonly` | `boolean \| undefined` | `false` |  | Shows the calendar and lets the user page through it, but no pick changes the value. |
 | `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds column (requires `type="datetime"`). |
 | `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked per candidate; return `false` to disable it. Receives the value in this `type`'s shape — `YYYY-MM` under `month`, `YYYY` under `year`. |
 | `step` | `number \| undefined` | `1` |  | Minute-column granularity and arrow stepping (requires `type="datetime"`). |
 | `time` | `string \| string[] \| null \| undefined` |  |  | Companion time model (`v-model:time`), 24-hour `HH:mm` / `HH:mm:ss`. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue`. Requires `type="datetime"`. |
-| `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the calendar selects, and therefore what it emits. - `date` (default) — a day. - `datetime` — a day plus a time rail beside the grid. Non-floating values carry the time inside `modelValue`; with `floating` the time travels only through `time`. - `month` — a month grid emitting `YYYY-MM`. - `year` — a year list emitting `YYYY`. `month`/`year` are calendar labels, not instants: they force `floating` and ignore `utc`, and the time props (`seconds`, `ampm`, `step`, `time`) are inert outside `datetime`. |
+| `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the calendar selects and emits: `date` (a day), `datetime` (a day plus a time rail), `month` (`YYYY-MM`) or `year` (`YYYY`). `month` / `year` force `floating`, ignore `utc`, and leave the time props inert. |
 | `utc` | `boolean \| undefined` | `false` |  | Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`, and therefore with `type="month"`/`type="year"`. |
 
 ## Passthrough parts and states

package/dist/ai/BbCheckbox.md

@@ -695,7 +695,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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`). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
-| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
+| `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. |
 | `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. |
@@ -720,8 +720,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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 checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's `aria-describedby`, after any errors and before the description/hint. |
+| `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. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbCheckboxGroup.md

@@ -979,8 +979,8 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `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`). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `emptyText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
-| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. Checked after every applied, successful load (an empty one included); a failed load never prunes. |
-| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
+| `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. |
 | `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. |
@@ -993,10 +993,10 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
 | `itemInputAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of each option's control in its row; `'center'` is the middle of the label plus its description. Omitted, it sits on the label's first line. |
 | `itemLabelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of each option's label in its row. Omitted, it stays as it is. |
-| `itemLayout` | `FieldLayout \| undefined` | `'auto'` |  | How each row's input and label sit together — the keywords of `layout`: `'auto'`, `'vertical'` (the input above the label), `'horizontal'` (50/50), `'label-fill'` (the label takes the row's free space — pair it with `list-layout="vertical-stretch"` and `item-reverse` for a settings list), `'input-fill'`, or a two-word ratio pattern like `'xx xxxxx'`, read in on-screen order. |
-| `itemProps` | `BbOptionGroupItemProps<T> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Option groups accept one field: - `description` — a muted line under the option label, beside the control; it may wrap. Either an object with a path or getter per field (`{ description: 'email' }`) or a function returning the fields (`(item) => ({ description: item.email })`). Without it no field renders — an item's own `description` is never read implicitly — and an empty value renders nothing for that item. The description is announced as the option's description, never part of its name. To disable individual options use `selectable`. |
+| `itemLayout` | `FieldLayout \| undefined` | `'auto'` |  | How each row's input and label sit together, in the `layout` keywords: `'auto'`, `'vertical'`, `'horizontal'`, `'label-fill'`, `'input-fill'`, or a two-word ratio pattern like `'xx xxxxx'`. |
+| `itemProps` | `BbOptionGroupItemProps<T> \| undefined` |  |  | ADDITIONAL row fields, never the text or value: `description`, a muted line under the label (it may wrap; announced as the option's description). An object of paths or getters, or a function of the item; nothing is read implicitly. |
 | `itemReverse` | `boolean \| undefined` | `false` |  | Swaps each row's input and label from their natural order (input first), in every `item-layout`. `reverse` swaps the legend and the options instead. |
-| `items` | `T[] \| ((context: BbCheckboxGroupItemsContext) => T[] \| Promise<T[]>)` |  | yes | The options: an array, or a provider function called with ONE context object and returning the rows, sync or async. The context carries: - `reason` — why this call happened: `'initial'` (the first load, on mount), `'dependencies'` (a `dependencies` entry or the `items` function changed; a retry arrives this way) or `'model'` (the model changed from outside and the options cannot resolve it). The group has no search field, so it never passes `query`; - `modelValue` — the `v-model` as-is; - `signal` — an `AbortSignal`, aborted when a newer call starts or the group is disposed; pass it to every request. A provider signals a failure by THROWING, never by returning `[]`: the rows are cleared, nothing is pruned, and `#empty` receives the `error` (`failed-text` is shown). Zero-argument providers keep working. Annotate the parameter `BbCheckboxGroupItemsContext` (`BbSwitchGroupItemsContext` on a switch group, the same shape). |
+| `items` | `T[] \| ((context: BbCheckboxGroupItemsContext) => T[] \| Promise<T[]>)` |  | yes | The options: an array, or a provider called with a `BbCheckboxGroupItemsContext` (`BbSwitchGroupItemsContext` on a switch group) (`reason`, `modelValue`, `signal`), sync or async. A provider fails by THROWING, never by returning `[]`: the rows clear and `#empty` gets the `error`. |
 | `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. |
@@ -1004,7 +1004,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `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. |
-| `listLayout` | `'horizontal'` \| `'vertical'` \| `'vertical-stretch'` \| `'tiles'` | `'horizontal'` |  | How the rows sit inside the list: `'horizontal'` (on a line, wrapping, each row its own size), `'vertical'` (stacked, each row its own size), `'vertical-stretch'` (stacked, each row as wide as the list) or `'tiles'` (equal-size boxes, wrapping onto new lines as the field narrows; `--tile-min-width` on `pt:list` sets how narrow a tile gets). |
+| `listLayout` | `'horizontal'` \| `'vertical'` \| `'vertical-stretch'` \| `'tiles'` | `'horizontal'` |  | How the rows sit in the list: `'horizontal'` (on a line, wrapping), `'vertical'` (stacked), `'vertical-stretch'` (stacked, as wide as the list) or `'tiles'` (equal boxes; `--tile-min-width` on `pt:list` sets the narrowest). |
 | `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
 | `max` | `number \| undefined` |  |  | Maximum number of selected items. |
 | `modelValue` | `any` |  |  | Used by v-model. Can be an array of any serializable type. |
@@ -1017,8 +1017,8 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `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 checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's `aria-describedby`, after any errors and before the description/hint. |
+| `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. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbCollapsible.md

@@ -503,7 +503,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - **Don't skip the trigger ARIA** — the component only manages
   `aria-hidden`/`inert` on its content; `aria-expanded`/`aria-controls` on the
   trigger (and a `role="region"` if you want one) are yours — or use
-  `BbAccordion`, which wires all of it.
+  `BbAccordion`, which wires all of it. A trigger with
+  `@click="open = !open"` and no `aria-expanded` is reported by
+  `bitboss-ui/collapsible-trigger-aria` and `check`.
 - **Don't use it as a pure height animator** — if nothing is ever hidden,
   `BbSmoothHeight` is the right tool.
 - **Initialize the model** — an omitted or `undefined` binding silently
@@ -526,7 +528,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `content`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbCollapsibleProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the content at mount, while closed, instead of on the first open. Closed content is `inert` and `aria-hidden` either way. |
-| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. Optional, matching the runtime: `withDefaults` supplies `false`, so an omitted binding renders closed and Vue never warns. It was typed required while carrying that default, which made the manifest publish a row that was `required: true` AND `default: false` — a contradiction that read as a generator bug. |
+| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open or close the collapsible. Optional: omitted, it renders closed. |
 | `tag` | `'div'` \| `'span'` | `"span"` |  | Element rendered as the root, and mirrored by the inner animating element — so the pair is span-in-span or div-in-div, both valid. Keep the default inside phrasing content (a `<p>`); use `'div'` when the body is block content (paragraphs, lists, forms), which a `span` may not contain. |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
 

package/dist/ai/BbColorInput.md

@@ -462,7 +462,10 @@ The sheet is titled by your `label`, can be dragged down to dismiss, and has no
 never drag it — dragging there picks a colour. Tune the sheet through
 `offCanvasProps`, spread over those defaults:
 `:off-canvas-props="{ hideClose: false }"` brings the ✕ back, and an explicit
-`title` replaces the label.
+`title` replaces the label (`size`, `persistent` pass straight through). It is
+also the only way to style the sheet's header, title and ✕: none of the
+input's own parts reach inside the sheet, so put a `pt` in `offCanvasProps`
+(passthrough guide § Inside the sheet).
 
 ### Events
 
@@ -687,7 +690,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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`). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
-| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
+| `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. |
 | `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. |
@@ -704,9 +707,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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. |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `size`, `persistent`). Spread over the defaults: the sheet's `title` is the field `label`, it is `draggable` (the colour square and sliders never drag it) and it hides its ✕; pass `{ hideClose: false }` to bring the ✕ back. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. For this component it is the only way to style the sheet's header, title and ✕: none of its own parts reach inside the sheet. |
+| `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). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
-| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
+| `placeholder` | `string \| undefined` |  |  | Text shown while the field is empty. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
 | `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
 | `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
@@ -714,9 +717,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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 checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
-| `variant` | `InputVariantType \| undefined` | `'outline'` |  | Visual variant of the field box — the same names and tokens as the `BbButton` variants. Colours only: height, padding and border width are identical across variants, so a form never reflows when one changes. `'ghost'` has no border in any state (errors and warnings show through the icon and the messages); every variant keeps the focus ring. Register extra names with the plugin's `inputVariants` option. `'none'` is a blank starting point: the field keeps its structure and behaviour but takes no look, so your own classes don't fight a built-in one. You then own hover, focus, disabled and the error / warning states. Fine for a one-off; keep inline styling short, and register a real variant (`inputVariants`) when the look recurs. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's `aria-describedby`, after any errors and before the description/hint. |
+| `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. |
 
 ## Passthrough parts and states
 
@@ -775,14 +778,14 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `append` — scope: `Record<string, never>` — Content rendered after the color picker indicator button, at the end of the inner container. Mutually exclusive with `suffix`: the `suffix` slot renders inside this slot's default content, so providing `append` replaces the suffix rendering entirely and any `suffix` content is silently dropped. This slot receives no scoped props.
+- `append` — scope: `Record<string, never>` — Content after the colour indicator button, at the end of the inner container. It replaces the `suffix` wrapper, so with `append` any `suffix` content is dropped. No scoped props.
 - `append:outer` — scope: `Record<string, never>` — Content rendered after the entire input control, outside the input chrome. This slot receives no scoped props.
 - `description` — scope: `BbColorInputDescriptionSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `label` — scope: `BbColorInputLabelSlotProps` `{ hasErrors: boolean; hasWarnings: boolean; text: string }` — Replaces the default label text rendered above the color input.
 - `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the input field area, before the typed text. This slot receives no scoped props.
 - `prepend` — scope: `Record<string, never>` — Content rendered before the text input, at the start of the inner container. This slot receives no scoped props.
 - `prepend:outer` — scope: `Record<string, never>` — Content rendered before the entire input control, outside the input chrome. This slot receives no scoped props.
-- `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the input field area, after the typed text. Renders inside the default `append` area's suffix wrapper — mutually exclusive with `append`: if an `append` slot is provided it replaces this wrapper and the `suffix` content is not rendered. This slot receives no scoped props.
+- `suffix` — scope: `Record<string, never>` — Inline content at the end of the field, after the typed text, inside the default `append` area: an `append` slot replaces it. No scoped props.
 
 ## CSS custom properties
 

package/dist/ai/BbColorPalette.md

@@ -764,7 +764,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button inside the palette to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
 | `label` | `string \| undefined` |  |  | Accessible label. The activator is named by it followed by the activator's own text, through `aria-labelledby`. Defaults to the locale string for "Open color picker" when omitted. |
 | `modelValue` | `string \| null` |  | yes | v-model: the current color as a `#RRGGBB` hex string (or `#RRGGBBAA` when `alpha` is enabled), or `null` when empty. |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). Spread over the defaults: the sheet is `draggable` (the colour square and sliders never drag it) and hides its ✕ (backdrop, Escape and drag close it); pass `{ hideClose: false }` to bring the ✕ back. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. For this component it is the only way to style the sheet's header, title and ✕: none of its own parts reach inside the sheet. |
+| `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). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `offset` | `number \| undefined` | `4` |  | Space the floating container will maintain from the activator. |
 | `padding` | `number \| undefined` | `6` |  | Minimum empty space to keep from the edge of the page |
 | `placement` | `Placement \| undefined` |  |  | Position of the overlay in respect to the related activator. |

package/dist/ai/BbDatePicker.md

@@ -425,9 +425,9 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `label` | `string \| undefined` |  |  | Accessible label. The activator is named by it followed by the activator's own text ("Due date 12 Sep"), through `aria-labelledby`. |
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. |
 | `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. |
-| `modelValue` | `string \| string[] \| null` |  | yes | v-model value. `null` for empty, a single string for single selection, or a two-element `[start, end]` array when `range` is true. The string shape follows `type`: `YYYY-MM-DD` when `floating` (`YYYY-MM` for `month`, `YYYY` for `year`), otherwise a zoned ISO instant carrying the time inline with `type="datetime"`. |
-| `multiple` | `boolean \| undefined` | `false` |  | Enables multi-selection: every pick toggles a value in or out of a sorted array, and the panel stays open until it is dismissed. Works in whatever `type` selects — days, months or years — and requires an array `modelValue` (use `[]` for empty, never `null`). Mutually exclusive with `range` (two different selection models) and with `type="datetime"` (the time rail edits one value; with several there is no one it could mean). Both combinations throw. |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). Spread over the defaults: the sheet is `draggable` (the time wheels and the year list never drag it) and hides its ✕ (picking, backdrop, Escape and drag close it); pass `{ hideClose: false }` to bring the ✕ back. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. For this component it is the only way to style the sheet's header, title and ✕: its own `pt:header` is the calendar's navigation bar. |
+| `modelValue` | `string \| string[] \| null` |  | yes | v-model: `null` when empty, a string, a `[start, end]` pair with `range`, or a sorted array with `multiple`. The string is `YYYY-MM-DD` when `floating` (`YYYY-MM` / `YYYY` for `month` / `year`), otherwise a zoned ISO instant (carrying the time under `datetime`). |
+| `multiple` | `boolean \| undefined` | `false` |  | Multi-selection: each pick toggles a value in a sorted array (days, months or years), and the panel stays open until dismissed. Needs an array `modelValue` (`[]` when empty, never `null`). Throws with `range` or `type="datetime"`. |
+| `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). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `offset` | `number \| undefined` | `4` |  | Space the popover keeps from the activator. |
 | `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page. |
 | `placement` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'top-start'` \| `'top-end'` \| `'right-start'` \| `'right-end'` \| `'bottom-start'` \| `'bottom-end'` \| `'left-start'` \| `'left-end'` |  |  | Position of the popover relative to the activator/anchor. |
@@ -438,7 +438,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `step` | `number \| undefined` | `1` |  | Minute-column granularity and arrow stepping (requires `type="datetime"`). |
 | `time` | `string \| string[] \| null \| undefined` |  |  | Companion time model (`v-model:time`), 24-hour `HH:mm` / `HH:mm:ss`. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue`. Requires `type="datetime"`. |
 | `transitionDuration` | `number \| undefined` | `250` |  | Popover/sheet transition duration in milliseconds. |
-| `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the picker selects, and therefore what it emits. - `date` (default) — a day. - `datetime` — a day plus a time rail beside the calendar. Non-floating values carry the time inside `modelValue`; with `floating` the time travels only through `time`. - `month` — a month grid emitting `YYYY-MM`. - `year` — a year list emitting `YYYY`. `month`/`year` are calendar labels, not instants: they force `floating` and ignore `utc`, and the time props (`seconds`, `ampm`, `step`, `time`) are inert outside `datetime`. |
+| `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the picker selects and emits: `date` (a day), `datetime` (a day plus a time rail), `month` (`YYYY-MM`) or `year` (`YYYY`). `month` / `year` force `floating`, ignore `utc`, and leave the time props inert. |
 | `utc` | `boolean \| undefined` | `false` |  | Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`, and therefore with `type="month"`/`type="year"`. |
 
 ## Passthrough parts and states

package/dist/ai/BbDatePickerInput.md

@@ -180,8 +180,12 @@ The value is edited as three separate inputs — day, month, year — not one fr
 string. Their **order and separator follow `config.locale`**, read from the
 locale's own format hint: `en` renders `MM/DD/YYYY`, `it` `DD/MM/YYYY`, `de`
 `TT.MM.JJJJ`, `ja` `YYYY/MM/DD`. A region writes its own order with its
-language's letters: `en-GB` `DD/MM/YYYY`, `fr-CA` `AAAA-MM-JJ`. Typing is
-forgiving:
+language's letters: `en-GB` `DD/MM/YYYY`, `fr-CA` `AAAA-MM-JJ`. So an
+English app that wants DD/MM/YYYY sets `locale: 'en-GB'`. If that is a type
+error (`Type '"en-GB"' is not assignable to type 'keyof LocaleRegistry'`), the
+locale ships but is not enabled in this build: add it to `enabledLocales`
+([Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
+`enabledLocales`). Typing is forgiving:
 
 - digits **auto-advance** to the next segment when a segment fills (or can't
   take another digit — e.g. `4` in a day segment becomes `04` and moves on);
@@ -549,7 +553,9 @@ The picker adapts to touch vs pointer, and you can steer that explicitly:
   swaps a live popover into a sheet. The sheet drags down to dismiss and shows
   no ✕ (the time wheels and the year list never drag it). Forward sheet options
   via `offCanvasProps`, spread over those defaults (e.g. `title`, `size`,
-  `persistent`, `{ hideClose: false }` to bring the ✕ back). Set `:adaptive="false"` to
+  `persistent`, `{ hideClose: false }` to bring the ✕ back); a `pt` inside it is
+  the only way to style the sheet's header, title and ✕ (the input's own
+  `pt:header` is the calendar's navigation bar). Set `:adaptive="false"` to
   force the floating popover on every viewport (deterministic in tests).
 - **`disableWriting`**: block typing so the calendar is the only way in. Use
   `'mobile'` / `'desktop'` to disable typing on just one platform. Where
@@ -875,7 +881,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `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` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
+| `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. |
 | `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). |
@@ -895,9 +901,9 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `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. |
 | `modelValue` | `string \| string[] \| null \| undefined` |  |  | Used by v-model. Can be null, a single string, or an array of strings based on whether a range or single date is needed. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). Spread over the defaults: the sheet is `draggable` (the time wheels and the year list never drag it) and hides its ✕ (picking, backdrop, Escape and drag close it); pass `{ hideClose: false }` to bring the ✕ back. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. For this component it is the only way to style the sheet's header, title and ✕: its own `pt:header` is the calendar's navigation bar. |
+| `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). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
-| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
+| `placeholder` | `string \| undefined` |  |  | Text shown while the field is empty. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
 | `range` | `boolean \| undefined` | `false` |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
 | `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
@@ -907,14 +913,14 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds segment (requires `type="datetime"`). Without it, an incoming value carrying seconds displays truncated and is left untouched until the user commits an edit, at which point seconds zero out. |
 | `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a `string` object and returns a boolean. `false` meaning the date cannot be selected. |
 | `step` | `number \| undefined` | `1` |  | Minute granularity for the calendar's minute column and arrow stepping (requires `type="datetime"`). Constrains what the component produces, never what it accepts: a typed off-grid value (e.g. `10:07` with `step: 15`) is emitted verbatim, and no column row highlights for it. |
-| `time` | `string \| string[] \| null \| undefined` |  |  | Companion model for the time part (`v-model:time`), always 24-hour `HH:mm` / `HH:mm:ss` regardless of display. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue` (same digits) and writing it rewrites the model's time part. Requires `type="datetime"`. |
+| `time` | `string \| string[] \| null \| undefined` |  |  | `v-model:time`: the time part, always 24-hour `HH:mm` / `HH:mm:ss`. With `floating` it is the only carrier of the time; otherwise it mirrors `modelValue`'s, and writing it rewrites that. Requires `type="datetime"`. |
 | `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
-| `type` | `'date'` \| `'month'` \| `'year'` \| `'datetime'` | `"date"` |  | What the field edits, and therefore its segments and emitted shape. - `date` (default) — `DD/MM/YYYY`. - `datetime` — adds the time segments and the calendar's time rail. - `month` — `MM/YYYY`, emitting `YYYY-MM`. - `year` — `YYYY`, emitting `YYYY`. `month`/`year` are calendar labels: they force `floating`, ignore `utc`, and make the time props (`seconds`, `ampm`, `step`, `v-model:time`) inert. |
-| `utc` | `boolean \| undefined` | `false` |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. Fields always display local time — UTC is a backend concern. Ignored when `floating` is set (a plain date has no zone). |
+| `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 checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
-| `variant` | `'outline'` \| `'secondary'` \| `'none'` \| `'ghost'` | `'outline'` |  | Visual variant of the field box — the same names and tokens as the `BbButton` variants. Colours only: height, padding and border width are identical across variants, so a form never reflows when one changes. `'ghost'` has no border in any state (errors and warnings show through the icon and the messages); every variant keeps the focus ring. Register extra names with the plugin's `inputVariants` option. `'none'` is a blank starting point: the field keeps its structure and behaviour but takes no look, so your own classes don't fight a built-in one. You then own hover, focus, disabled and the error / warning states. Fine for a one-off; keep inline styling short, and register a real variant (`inputVariants`) when the look recurs. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's `aria-describedby`, after any errors and before the description/hint. |
+| `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. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbDialog.md

@@ -916,7 +916,9 @@ so a mid-flow resize never swaps modal ↔ sheet.
   `fullscreen`, `stack` and `transition-duration` carry over; the four
   lifecycle events fire the same either way.
 - `off-canvas-props` merges last over the sheet's props — use it to change
-  the `side`, the size, `stack-gap`, or disable dragging on the mobile surface only.
+  the `side`, the size, `stack-gap`, or disable dragging on the mobile surface only,
+  or to override a shared prop whose meaning differs on the drawer (`stack`).
+  It is ignored on the desktop dialog.
   A `pt` inside it is **sheet-only styling**:
   `:off-canvas-props="{ 'pt:header': 'pt-10' }"` next to
   `pt:header="bg-(--bb-muted) pt-1"` keeps `pt-1` on the desktop dialog and
@@ -1123,15 +1125,15 @@ 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`, `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`)` |  | Adapt the surface to the viewport: render as a `BbOffCanvas` drawer on mobile instead of a centered dialog. The surface is resolved when the dialog opens and stays fixed for that session: resizing across the mobile breakpoint while open never swaps it. When unset, falls back to the global `config.adaptive`. |
-| `description` | `string \| undefined` |  |  | One short line under the title, in the header — the shadcn `DialogDescription` shape: same block as the title, lower hierarchy, muted. It is also what `aria-describedby` points at. That wiring was dropped in v3 along with the old `description` prop, on the reasoning that pointing it at arbitrary body content would read whole forms aloud — true, and the reason it aims at THIS element only. Keep it to a sentence; anything longer belongs in the body. |
-| `disabled` | `boolean \| undefined` | `false` |  | Disable EVERY user-initiated dismissal: backdrop click, Escape AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the dialog cannot be dismissed mid-work. Compare `persistent`, which blocks backdrop/Escape but leaves the × working. Programmatic close (v-model) is still allowed. |
+| `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`. |
+| `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. |
+| `disabled` | `boolean \| undefined` | `false` |  | Blocks EVERY user dismissal (backdrop, Escape and the ✕; a denied attempt plays the deny nudge), e.g. while a save runs. `persistent` blocks only the backdrop and Escape. Closing through `v-model` still works. |
 | `eager` | `boolean \| undefined` | `false` |  | Render dialog content immediately instead of waiting for the first open. |
 | `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
 | `fullscreen` | `boolean \| "mobile" \| undefined` |  |  | Display the dialog fullscreen. Use `'mobile'` to restrict fullscreen to small devices. |
 | `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). |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the dialog. A dialog with no `v-model` starts closed. |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Overrides merged over the offcanvas (mobile) surface's props. The drawer defaults to a bottom, draggable, content-sized sheet (`side: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to override those, set other drawer-only options (`stackGap`), or override shared props whose meaning differs on the drawer (`stack`). Ignored on the desktop dialog surface. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. |
+| `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 `disabled` to block every dismissal. Programmatic close is still allowed. |
 | `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. |
 | `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. |
@@ -1173,7 +1175,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `default` — scope: `BbDialogDefaultSlotProps` `{ close: () => void }` — Primary body content of the dialog, rendered in the scrollable body area.
 - `description` — scope: `BbDialogDescriptionSlotProps` `{ text: string }` — Replaces the description text under the title. Renders the header even when `title` and `description` are unset — a slotted description is a description, the same rule `#title` follows.
 - `footer` — scope: `BbDialogFooterSlotProps` `{ close: () => void }` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
-- `header` — scope: `BbDialogHeaderSlotProps` `{ titleId: string; close: () => void; title: string }` — Replaces the entire dialog header section (title + close button) on both surfaces — the desktop `<dialog>` and the mobile off-canvas. Because it replaces the default close (✕), the slot owns closing: render your own control wired to the `close` prop, and wire `titleId` onto your title element to keep `aria-labelledby` intact. Providing this slot renders a header even when `title` is unset. Layout: the header container is a flex row (`justify-content: space-between`), so your root element is a flex item and shrinks to its content by default — give it `flex: auto` (Tailwind `flex-1`) to fill the width, or it renders squeezed against the left edge.
+- `header` — scope: `BbDialogHeaderSlotProps` `{ titleId: string; close: () => void; title: string }` — Replaces the whole header (title and ✕) on both surfaces, so it owns closing: wire your control to `close`, and `titleId` onto your title. It renders even without `title`. Its root is a flex item: give it `flex-1` to fill the width.
 - `title` — scope: `BbDialogTitleSlotProps` `{ text: string }` — Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.
 
 ## CSS custom properties

package/dist/ai/BbDropdown.md

@@ -2084,6 +2084,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   land on the floating menu, like every floating component: its box on desktop,
   the sheet on a phone (`class` rides `pt:root`, which has no node on a sheet).
   To hide or style the trigger, put the class on your element in `#activator`.
+- **The trigger never goes in the default slot.** That slot holds
+  `<BbDropdownGroup>` companions; a button there opens nothing. Use
+  `<template #activator="{ props }">` + `v-bind="props"`, or `v-bb-dropdown`
+  (`bitboss-ui/dropdown-default-slot` and `check` report it).
 - **There is no open flag to bind.** The menu keeps its open state internal
   (no `v-model:open`, by design): the activator opens it, a pick or an outside
   press closes it, and `@show` / `@hide` tell you when. Don't reopen it from a
@@ -2163,20 +2167,20 @@ 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: `footer`, `header`, `input`, `item`, `itemDescription`, `itemIcon`, `itemText`, `list`, `panel`, `root`, `sheet`. States: `disabled`, `open`, `selected`. 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 `BbDropdownProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. ARIA (`aria-haspopup`/`aria-expanded`/`aria-controls`) is attached programmatically too — don't add your own, or you get a double-set conflict. |
-| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile viewports (below `config.mobileMaxWidth`), render the dropdown as a bottom-anchored, auto-sized off-canvas sheet that **navigates** through nested submenus (drilling one level at a time with a back control) instead of showing hover flyouts. Slots and selection behave exactly as on desktop. When unset, falls back to the global `config.adaptive`. |
-| `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `the activator element` |  | Element the panel positions itself against, when it should differ from the activator — e.g. a wrapper that the activator is only a part of, so the menu aligns to the whole control while a single button opens it. Accepts an HTMLElement or a Vue component ref. Also drives a percentage `width`. Ignored when `placement` is `'cursor'`. |
+| `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | An external activator element or component ref: the activator slot is not rendered, and the listeners and ARIA (`aria-haspopup` / `aria-expanded` / `aria-controls`) are attached to it; don't add your own. |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom sheet that drills into submenus one level at a time instead of hover flyouts; slots and selection are unchanged. Unset: the global `config.adaptive`. |
+| `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `the activator element` |  | The element the panel positions against when it should differ from the activator (a wrapper the activator is part of); an HTMLElement or component ref. It also drives a percentage `width`. Ignored with `placement="cursor"`. |
 | `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the dropdown within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
-| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant — the same ladder `BbSelect` uses, on both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The label size does not change; density here is height, as it is for a select. A menu row is a touch target in a way a select option is not quite — a mis-tap fires the neighbouring COMMAND rather than picking the wrong value — so the compact sheet stops at 36px and never follows the flyout down to 24px. That is the same floor the select's sheet holds. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet rows 44px → 36px (a sheet row stays a touch target). The label size does not change. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too), and keeps its rows after a close. Without it the rows mount on each open and go once the menu has closed. |
 | `emptyText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group resolves to no items. A group's own `emptyText` overrides this; both fall back to the localized `common.emptyText` (`'No data to display'`). |
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
 | `failedText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group's latest load FAILED (its `items` getter threw). A group's own `failedText` overrides this; both fall back to the localized `common.failedText` (`"Couldn't load items"`). |
 | `id` | `string \| undefined` |  |  | Names this dropdown: the activator's id (unless it already has one), the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a companion `BbDropdownGroup` pair by. Generated when omitted. |
-| `items` | `BbDropdownItem[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated groups, or pass {@link InternalGroup} objects for titled / selectable sections. An item may carry its own `items` to open a submenu. The shapes can be mixed. |
+| `items` | `BbDropdownItem[]` | `[]` | yes | The menu rows, each a `BbBaseButton` (`button`, `a` or `router-link`): a flat array for one group, nested arrays for divider-separated groups, or `InternalGroup` objects for titled / selectable sections. A row's own `items` opens a submenu. |
 | `loadingText` | `string \| undefined` |  |  | Default placeholder text shown while a pipeline group's async items load. A group's own `loadingText` overrides this; both fall back to the localized `common.loadingText` (`'Loading...'`). |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`side: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. |
+| `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). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `offset` | `number \| undefined` | `4` |  | Space the floating container will maintain from the activator. |
 | `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page |
 | `placement` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'top-start'` \| `'top-end'` \| `'right-start'` \| `'right-end'` \| `'bottom-start'` \| `'bottom-end'` \| `'left-start'` \| `'left-end'` \| `'cursor'` | `"bottom"` |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (No arrow is drawn either way — arrows are tooltip-only in v3.) |

package/dist/ai/BbDropdownButton.md

@@ -631,17 +631,17 @@ 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: `footer`, `header`, `icon`, `input`, `item`, `itemDescription`, `itemIcon`, `itemText`, `main`, `panel`, `root`, `sheet`, `spinner`, `text`, `toggle`. States: `disabled`, `loading`, `open`, `selected`. 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 `BbDropdownButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile viewports (below `config.mobileMaxWidth`), render the dropdown as a bottom-anchored, auto-sized off-canvas sheet that **navigates** through nested submenus (drilling one level at a time with a back control) instead of showing hover flyouts. Slots and selection behave exactly as on desktop. When unset, falls back to the global `config.adaptive`. |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom sheet that drills into submenus one level at a time instead of hover flyouts; slots and selection are unchanged. Unset: the global `config.adaptive`. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
 | `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
-| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant — the same ladder `BbSelect` uses, on both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The label size does not change; density here is height, as it is for a select. A menu row is a touch target in a way a select option is not quite — a mis-tap fires the neighbouring COMMAND rather than picking the wrong value — so the compact sheet stops at 36px and never follows the flyout down to 24px. That is the same floor the select's sheet holds. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet rows 44px → 36px (a sheet row stays a touch target). The label size does not change. |
 | `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async actions (enabled by default). Only affects the main action button: the split toggle half still mirrors the dropdown's internal async-action loading state. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too), and keeps its rows after a close. Without it the rows mount on each open and go once the menu has closed. |
 | `id` | `string \| undefined` |  |  | Names this dropdown: the activator's id (unless it already has one), the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a companion `BbDropdownGroup` pair by. Generated when omitted. |
-| `items` | `BbDropdownItem[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated groups, or pass {@link InternalGroup} objects for titled / selectable sections. An item may carry its own `items` to open a submenu. The shapes can be mixed. |
+| `items` | `BbDropdownItem[]` | `[]` | yes | The menu rows, each a `BbBaseButton` (`button`, `a` or `router-link`): a flat array for one group, nested arrays for divider-separated groups, or `InternalGroup` objects for titled / selectable sections. A row's own `items` opens a submenu. |
 | `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. |
-| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`side: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. |
+| `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). The sheet hides its ✕; `{ hideClose: false }` brings it back. |
 | `offset` | `number \| undefined` | `4` |  | Space the floating container will maintain from the activator. |
 | `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page |
 | `placement` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'top-start'` \| `'top-end'` \| `'right-start'` \| `'right-end'` \| `'bottom-start'` \| `'bottom-end'` \| `'left-start'` \| `'left-end'` \| `'cursor'` | `'bottom'` |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (No arrow is drawn either way — arrows are tooltip-only in v3.) |
@@ -649,7 +649,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `size` | `Responsive<Sizes> \| undefined` | `"md"` |  | Sets the size of the button. When the value is a string, it will be applied to all screen sizes. Otherwise, it will be applied to the screen size specified by the object. |
 | `toggle:icon` | `string \| undefined` |  |  | Replaces the chevron shown inside the dropdown toggle button. A constrained alternative to a slot: only the toggle's icon changes, so the button keeps its semantics. Named after the part it sits in (the `toggle`), the way `prepend:icon` / `append:icon` name theirs. |
 | `transitionDuration` | `number \| undefined` | `150` |  | How long the transition has to last in milliseconds. Menus use the fast transition (150) rather than the medium one (250) the other popovers default to: a menu is opened to pick one command and is gone again, so it answers faster than a panel the user reads or edits in. |
-| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` \| `'ghost'` \| `'link'` | `"primary"` |  | Visual variant shared by both buttons of the split control. `'none'` is a blank starting point: the button keeps its structure and behaviour but takes no look, so your own classes don't fight a built-in one. You then own hover, focus and disabled. Fine for a one-off; keep inline styling short, and register a real variant when the look recurs: the plugin's `buttonVariants` option types the name, and you style `.bb-button--<name>` (the library ships no CSS for it). |
+| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` \| `'ghost'` \| `'link'` | `"primary"` |  | Visual variant shared by both buttons of the split control. `'none'` takes no look (you own hover, focus and disabled); register a real one with the plugin's `buttonVariants` and style `.bb-button--<name>`. |
 | `width` | `string \| number \| undefined` | `'auto'` |  | Width of the dropdown in pixels, percentage, or 'auto' to fit content. |
 
 ## Passthrough parts and states

package/dist/ai/BbDropzone.md

@@ -1617,10 +1617,10 @@ button, grows with every file added, and changes mid-drag. So:
 | 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: `content`, `message`, `root`. States: `active`, `disabled`, `errors`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbDropzoneProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `accept` | `string[] \| undefined` |  |  | Array of MIME types (`'image/png'`), wildcards (`'image/*'`), extensions (`'.png'`) or bare tokens (`'png'`) to filter selectable files. A bare token upgrades to its extension instantly and is enriched with its MIME type from the lazily-imported `mime` database; validation of files that arrive before the database resolves is queued until the rules are complete. |
+| `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` |  |  | Sets autofocus on page load. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
-| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
+| `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. |
 | `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. |
@@ -1634,8 +1634,8 @@ button, grows with every file added, and changes mid-drag. So:
 | `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 checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the dropzone, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's `aria-describedby`, after any errors and before the description/hint. |
+| `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 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