bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/ai/BbColorInput.md

@@ -496,35 +496,35 @@ const form = useForm({ brandColor: '#4f46e5' });
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | When `true`, the color palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbSelect`/`BbDatePickerInput`. When unset, falls back to … |
-| `alpha` | `boolean \| undefined` |  |  | Enable the alpha channel. Shows an opacity slider and uses `#RRGGBBAA` hex8 format. |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the color palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbSelect`/`BbDatePickerInput`. When unset, falls back to … |
+| `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. Shows an opacity slider and uses `#RRGGBBAA` hex8 format. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
 | `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
-| `compact` | `boolean \| undefined` |  |  | Displays the component in a compact version. |
+| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
+| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
 | `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`). |
 | `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `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… |
-| `eyeDropper` | `boolean \| undefined` |  |  | Show an eyedropper button to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `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. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelMode` | `"floating" \| "outside" \| "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. |
-| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
-| `modelValue` | `string \| null` |  | yes | Used by v-model. |
+| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `modelValue` | `string \| null` | `null` | yes | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `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 |
 | `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… |
 

package/dist/ai/BbColorPalette.md

@@ -53,6 +53,12 @@ prop), so always initialise it; `null` is the correct "no color yet" value.
 `null` renders an "empty" trigger (nothing painted) and is what you get when
 nothing is chosen yet.
 
+**The palette never emits `null`** — every selection is a concrete hex — so
+`null` is an _inbound_ value only. Once the user picks a colour there is no
+built-in way back to empty: clearing is the consumer's job (set the model to
+`null` yourself from a Clear button). Don't write an `update:modelValue`
+handler that branches on `null`; that branch is dead code.
+
 The label manager below embraces the emit frequency instead of fighting it: the
 chip repaints on every drag frame (cheap — it's one style binding), while the
 _persistence_ is debounced behind a short timer, so only the trailing edge of a
@@ -593,22 +599,22 @@ styling (a caret, a highlight). Two props gate interaction:
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click listeners are attached programmatically to the referenced element — mirroring the BbDropdown activator API. |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | When `true`, the palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbPopover`/`BbDropdown`/`BbDatePicker`. When unset, falls back … |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbPopover`/`BbDropdown`/`BbDatePicker`. When unset, falls back … |
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. The picker shows an opacity slider and emits `#RRGGBBAA` hex8 values. |
 | `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator element when omitted, allowing the popover to be anchored to a larger container (e.g. the full input row) while a smaller element (e.g. a color dot… |
 | `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
-| `disabled` | `boolean \| undefined` |  |  | Disable all interaction (activator and palette). |
-| `disableFlip` | `boolean \| undefined` |  |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
-| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disable all interaction (activator and palette). |
+| `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
 | `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 applied to the activator element via `aria-label`. 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. |
 | `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. |
-| `readonly` | `boolean \| undefined` |  |  | Prevent opening the palette while keeping the activator visible. |
+| `readonly` | `boolean \| undefined` | `false` |  | Prevent opening the palette while keeping the activator visible. |
 | `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 |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds |
+| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
 
 ## Events
 

package/dist/ai/BbConfirm.md

@@ -34,8 +34,12 @@ first — this is that gate.
 Mount `<BbConfirm />` **exactly once, at the app root** (`App.vue` under Vue,
 `app.vue` under Nuxt, the `createInertiaApp` render root under Inertia) — a
 single instance serves the whole app, and `confirm()` can then be called from
-anywhere, components and stores alike. Calls queue: if a dialog is open, the
-next message waits its turn. Mounting a second host renders every dialog twice
+anywhere, components and stores alike. **Calls do not queue — a new
+`confirm()` supersedes the open one**, and the superseded promise settles
+`false` (an implicit dismiss; no callback runs). So two `confirm()` calls in a
+row show only the second, and the first silently answers "no". If you need both
+questions asked, `await` the first before opening the second.
+Mounting a second host renders every dialog twice
 (nothing warns you). Mounting none is worse: `await confirm(...)` never settles
 and the caller hangs.
 
@@ -376,7 +380,7 @@ the peek closes. For app-lifetime confirms that survive any unmount, call
 `useConfirm()` outside a component scope (app setup, a store, module level).
 
 `useConfirm()` also returns `dismissAll()` — an imperative escape hatch that
-quietly dismisses the open dialog and any queued ones regardless of owner, for
+quietly dismisses the open dialog regardless of owner, for
 app-level events like logout or a global error boundary.
 
 The classic case for `persistent` is the unsaved-changes prompt: an accidental
@@ -638,8 +642,11 @@ standard footer and resolve from inside the slot with its `yes` / `no` helpers.
 
 ### Gotchas and anti-patterns
 
-- **Don't hand-build a yes/no dialog** out of `BbDialog` + buttons — queueing,
-  busy states, dismissal semantics and focus handling already live here.
+- **Don't hand-build a yes/no dialog** out of `BbDialog` + buttons — busy
+  states, dismissal semantics, ownership and focus handling already live here.
+- **Don't fire two `confirm()` calls without awaiting the first.** The second
+  supersedes the first, which settles `false` — so a "delete these two things"
+  flow written as two un-awaited confirms deletes nothing and asks once.
 - **Don't forget the `await`** — `confirm(...)` without it never gates
   anything.
 - **Don't call `close()` to "cancel"** a dialog whose buttons haven't run —

package/dist/ai/BbDatePicker.md

@@ -257,33 +257,33 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | --- | --- | --- | --- | --- |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click + ARIA are attached programmatically to the referenced element — mirroring the `BbColorPalette` activator API. |
 | `activeSegment` | `BbDatePickerSegment \| undefined` |  |  | Which end the time rail edits in range + `type="datetime"` (`v-model:active-segment`). Standalone use manages this internally; an embedding host (the date input) drives it from its focused field. Ignored outside range + datetime. |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
-| `ampm` | `boolean \| undefined` |  |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
+| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
 | `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator when omitted (anchor to a larger row while a smaller element stays the click target). |
 | `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the activator and the calendar. |
-| `disableFlip` | `boolean \| undefined` |  |  | Disable the automatic flip to the opposite side on overflow. |
-| `eager` | `boolean \| undefined` |  |  | Render popover content before it is first shown. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the calendar. |
+| `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
+| `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |
 | `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | First day of the week (0 = Sunday … 6 = Saturday). |
-| `floating` | `boolean \| undefined` |  |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
+| `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
 | `label` | `string \| undefined` |  |  | Accessible label applied to the activator via `aria-label`. |
 | `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`), oth… |
-| `multiple` | `boolean \| undefined` |  |  | 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 emp… |
+| `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 emp… |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when adaptive on mobile. |
 | `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` | `Placement \| undefined` |  |  | Position of the popover relative to the activator/anchor. |
-| `range` | `boolean \| undefined` |  |  | Enables range selection (`[start, end]`). |
-| `readonly` | `boolean \| undefined` |  |  | Prevents opening while keeping the activator visible. |
-| `seconds` | `boolean \| undefined` |  |  | Adds the seconds column (requires `type="datetime"`). |
+| `range` | `boolean \| undefined` | `false` |  | Enables range selection (`[start, end]`). |
+| `readonly` | `boolean \| undefined` | `false` |  | Prevents opening while keeping the activator visible. |
+| `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` |  |  | Minute-column granularity and arrow stepping (requires `type="datetime"`). |
+| `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` | `transitions.medium` |  | Popover/sheet transition duration in milliseconds. |
+| `transitionDuration` | `number \| undefined` | `250` |  | Popover/sheet transition duration in milliseconds. |
 | `type` | `DatePickerType \| undefined` | `"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 throu… |
-| `utc` | `boolean \| undefined` |  |  | Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`, and therefore with `type="month"`/`type="year"`. |
+| `utc` | `boolean \| undefined` | `false` |  | Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`, and therefore with `type="month"`/`type="year"`. |
 
 ## Events
 

package/dist/ai/BbDatePickerInput.md

@@ -702,49 +702,49 @@ label>')` matches nothing; query each segment by its own label instead. See
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelect`. When unset, falls back to the global `config.adaptive`. |
-| `ampm` | `boolean \| undefined` |  |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelect`. When unset, falls back to the global `config.adaptive`. |
+| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
 | `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
-| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
+| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
 | `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`). |
 | `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
 | `disableCalendar` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | 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 … |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
-| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Disables typing into the input. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. |
+| `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… |
 | `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
-| `floating` | `boolean \| undefined` |  |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `floating` | `boolean \| undefined` | `false` |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `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. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
-| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `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. |
 | `modelValue` | `string \| string[] \| null` |  | yes | 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` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
-| `range` | `boolean \| undefined` |  |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
-| `seconds` | `boolean \| undefined` |  |  | 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. |
+| `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. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `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` |  |  | 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, a… |
+| `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, a… |
 | `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 i… |
 | `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
-| `type` | `DatePickerType \| undefined` |  |  | 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`, emittin… |
-| `utc` | `boolean \| undefined` |  |  | 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. F… |
+| `type` | `DatePickerType \| undefined` | `'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`, emittin… |
+| `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. F… |
 | `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… |
 
 ## Events

package/dist/ai/BbDialog.md

@@ -186,6 +186,65 @@ Use the `title` slot to restyle just the title text — it stays wired to
 removes the whole header (the close button then floats over the body corner
 unless `hide-close`), and you own the accessible name.
 
+Add `description` for one muted line under the title — the dialog's subtitle,
+and the only thing `aria-describedby` points at:
+
+**A described dialog**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="m-0 text-sm font-medium">INV-2044</p>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+				Northwind Traders · €1,280.00 · paid
+			</p>
+		</div>
+		<div>
+			<BbButton
+				prepend:icon="lucide:trash-2"
+				variant="outline"
+				@click="open = true"
+			>
+				Delete invoice
+			</BbButton>
+		</div>
+	</div>
+	<BbDialog
+		v-model="open"
+		description="This permanently removes the invoice and its payment history."
+		title="Delete invoice INV-2044"
+	>
+		<p class="m-0">
+			Anything that does not fit in one line belongs here, in the body — which
+			is deliberately not what <code>aria-describedby</code> points at.
+		</p>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton variant="destructive" @click="open = false">Delete</BbButton>
+			</div>
+		</template>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog } from 'bitboss-ui';
+
+const open = ref(false);
+</script>
+```
+
+Keep it to a sentence; the detail belongs in the body, which is deliberately
+**not** described (pointing `aria-describedby` at arbitrary markup makes a
+screen reader read a whole form as the dialog's description). Use the
+`description` slot when the line needs markup — it receives the prop as `text`.
+A dialog with no `description` keeps its original single-row header, so nothing
+shifts unless you opt in.
+
 Prefer `title` (or the `title` slot) for the standard header. The `header` slot
 replaces the entire header on both surfaces — you own the close control and must
 wire `titleId` for `aria-labelledby`. Give your root element `flex-1` so it fills
@@ -355,10 +414,13 @@ Every dismissal path is governed by two props:
 - `disabled` — same guard, different intent: the surface is busy (a save in
   flight). Combine with disabling your footer actions.
 
-Constraint: the header **close button bypasses both** — it always closes,
-regardless of `persistent`/`disabled`. When a dialog truly must be resolved from
-the footer, pair `persistent` with `hide-close`, and keep a visible Cancel so
-users are never trapped.
+The header **close button bypasses `persistent`, but respects `disabled`**
+(`BbDialog.vue:471-477`): while `disabled` is set the × plays the same deny
+nudge as the backdrop and does not close. So for the common case — a dialog
+that must stay put while a save is in flight — `disabled` alone is enough and
+you keep the ×. Reach for `hide-close` only when the dialog must be resolved
+from the footer _permanently_; pair it with `persistent` and keep a visible
+Cancel so users are never trapped.
 
 Backdrop clicks are drag-protected: a text selection that starts inside the
 dialog and releases over the backdrop does not close it — only a genuine click
@@ -759,6 +821,8 @@ default falls back to `config.adaptive`.
 - The dialog is a true modal (`showModal()`): the browser contains focus within
   it, the page behind is inert, and focus returns to the trigger when it
   closes. `focus-target` only chooses where focus **starts**.
+- `description` is what `aria-describedby` points at, so the dialog announces
+  its purpose and not just its name. Nothing else is described — see above.
 - The header close button carries a localized `aria-label` out of the box
   (`config.locale`).
 - Don't lean on `persistent` to trap users. Keep a visible way out (a Cancel or
@@ -772,19 +836,20 @@ default falls back to `config.adaptive`.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | 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 nev… |
-| `disabled` | `boolean \| undefined` |  |  | 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 `… |
-| `eager` | `boolean \| undefined` |  |  | Render dialog content immediately instead of waiting for the first open. |
+| `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 nev… |
+| `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 `descripti… |
+| `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 `… |
+| `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` |  |  | 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). |
+| `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` |  |  | Overrides merged over the offcanvas (mobile) surface's props. The drawer defaults to a bottom, draggable, content-sized sheet (`direction: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to override those, set other drawer-only opti… |
-| `persistent` | `boolean \| undefined` |  |  | 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. Program… |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | 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 (… |
+| `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. Program… |
 | `size` | `Responsive<NonNullable<number \| ({ size?: any; } & string) \| keyof Sizes \| 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 … |
 | `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` | `transitions.medium` |  | Controls the duration of the open and close animations. |
+| `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |
 
 ## Events
 
@@ -797,9 +862,10 @@ default falls back to `config.adaptive`.
 ## Slots
 
 - `default` — scope: `BbDialogDefaultSlotProps` — Primary body content of the dialog, rendered in the scrollable body area.
+- `description` — scope: `BbDialogDescriptionSlotProps` — 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: `object` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
 - `header` — scope: `BbDialogHeaderSlotProps` — 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 `cl…
-- `title` — scope: `BbDialogTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`.
+- `title` — scope: `BbDialogTitleSlotProps` — 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.
 
 ## See Also