bitboss-ui 3.0.0-beta.12 → 3.0.0-beta.15

package/dist/ai/BbAccordion.md

@@ -532,7 +532,7 @@ is generated for you.
 | `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
-| `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
 
@@ -546,4 +546,4 @@ is generated for you.
 ## See Also
 
 - [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.
-- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; BbTabRoot enables split layouts).
+- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).

package/dist/ai/BbAlert.md

@@ -139,8 +139,12 @@ Bind `v-model` when the visibility matters to you:
 			</p>
 		</div>
 
+		<!--
+			`v-model` alone owns the dismissal, so the alert plays its own leave
+			transition. Pairing it with a `v-if` on the SAME element unmounts the
+			node the instant the model flips and the animation never runs.
+		-->
 		<BbAlert
-			v-if="showBanner"
 			v-model="showBanner"
 			close-label="Dismiss email verification reminder"
 			icon="lucide:mail"
@@ -149,7 +153,7 @@ Bind `v-model` when the visibility matters to you:
 			variant="primary"
 		/>
 		<BbButton
-			v-else
+			v-if="!showBanner"
 			prepend:icon="lucide:mail"
 			variant="ghost"
 			@click="showBanner = true"
@@ -399,7 +403,7 @@ const publish = () => {
 | `role` | `"alert" \| "status" \| undefined` |  |  | Accessibility role for the alert container. Defaults to `'alert'` for destructive/warning variants, otherwise `'status'`. |
 | `text` | `string \| undefined` |  |  | Text content of the alert body. |
 | `title` | `string \| undefined` |  |  | Text content of the alert title. |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | Transition duration in milliseconds for enter/leave. |
+| `transitionDuration` | `number \| undefined` | `250` |  | Transition duration in milliseconds for enter/leave. |
 | `variant` | `keyof AlertVariantRegistry \| undefined` | `"outline"` |  | Visual variant of the alert. |
 
 ## Events
@@ -414,4 +418,4 @@ const publish = () => {
 
 ## See Also
 
-- [BbToast](./BbToast.md) — Shows transient notification messages.
+- [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).

package/dist/ai/BbAsterisk.md

@@ -33,6 +33,23 @@ you compose a bespoke label outside those controls.
 Wrap it in an element with your own spacing if the default `margin-inline-start`
 doesn't suit the layout; the glyph inherits nothing else from its surroundings.
 
+### It is `aria-hidden` — the control carries the requirement
+
+The span renders `aria-hidden="true"`, so **screen readers never announce it**.
+That is deliberate: an asterisk read aloud as "star" is noise, and a marker
+placed in a label is not a reliable way to convey a requirement. What actually
+carries mandatoriness to assistive tech is the **`required` attribute on the
+control** — which the library sets from your `required` prop.
+
+The practical consequence: the marker is a _visual_ affordance only, and
+`required` is the real thing. Never ship a field that shows the asterisk
+without `required` (sighted users see a requirement that assistive tech cannot
+perceive), and never assume the asterisk is doing accessibility work.
+
+`showAsterisk` on the validated controls is also gated on the plugin option, so
+with `requiredAsterisk: false` there is no way to render the marker through
+them at all — placing `BbAsterisk` by hand is then the only route.
+
 ## Props
 
 - None.

package/dist/ai/BbAvatar.md

@@ -83,8 +83,17 @@ not hero examples.
 The fallback surface is **always painted with the primary design token** —
 `--bb-primary` behind, `--bb-primary-fg` for the initials/icon, the same
 pairing as a primary button — so initials stay legible in light and dark and
-every avatar matches your theme automatically. There is no per-avatar tinting
-API: theming happens through the tokens, not a prop.
+every avatar matches your theme automatically.
+
+There is no tinting **prop**, but there are three component locals on
+`.bb-avatar` for the cases the theme cannot cover — a per-tenant or
+per-user colour: `--bg-color` (fallback surface, defaults to `--bb-primary`),
+`--text-color` (initials, `--bb-primary-fg`) and `--default-icon-color` (the
+placeholder glyph). Set them on the avatar or on a class you put on it:
+
+```vue
+<BbAvatar text="Acme Studio" :style="{ '--bg-color': tenant.color }" />
+```
 
 **The size scale**
 
@@ -512,4 +521,4 @@ available in visible text or an adjacent label.
 
 ## See Also
 
-- [BbBadge](./BbBadge.md) — Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).

package/dist/ai/BbBadge.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Feedback**
-- Description: Displays compact status counters or labels, the floating mode acts as notification dot.
+- Description: Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbBadge.md](./source/BbBadge.md)
 
@@ -715,7 +715,7 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 | --- | --- | --- | --- | --- |
 | `append:icon` | `string \| undefined` |  |  | Icon rendered after the label. On a `clearable` badge it shares the trailing slot with the clear button: the icon shows at rest and the clear button reveals over it on hover/focus. |
 | `clearable` | `boolean \| undefined` |  |  | Renders a trailing clear button and emits `click:clear` when pressed — turns the badge into a dismissible token (the pattern formerly served by `BbChip`). |
-| `clearableLabel` | `string \| undefined` |  |  | Accessible label for the clear button. Falls back to the localized `badge.clearLabel` key. |
+| `clearableLabel` | `string \| undefined` |  |  | Accessible label for the clear button. Rarely needed: unset, the name is **composed** from the localized `badge.clearLabel` verb and the badge's own text — "Remove Italy", not a bare "Remove" — which is already the right name in almost ever… |
 | `icon` | `string \| undefined` |  |  | Renders an icon-only badge. When set, `prepend:icon` / `append:icon` are ignored and the default slot becomes the badge's visually hidden accessible label — always provide it. |
 | `loading` | `boolean \| undefined` |  |  | Shows a spinner in place of the leftmost icon, mirroring `BbButton`: it replaces the `icon` glyph or the `prepend:icon` when one is set; when the `append:icon` is the sole icon it replaces that instead (e.g. a select-activator chevron while… |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
@@ -732,6 +732,6 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 
 ## See Also
 
-- [BbIndicator](./BbIndicator.md) — Anchors a notification bubble (count/short text) or a dot over a wrapped element, with floating and corner-placement options.
+- [BbIndicator](./BbIndicator.md) — Anchors a notification bubble (count/short text) or a dot over a wrapped element.
 - [BbAvatar](./BbAvatar.md) — Displays an avatar and has a fallback content slot.
 - [BbBadgeButton](./BbBadgeButton.md) — Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.

package/dist/ai/BbBadgeButton.md

@@ -63,5 +63,5 @@
 
 ## See Also
 
-- [BbBadge](./BbBadge.md) — Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.

package/dist/ai/BbBaseButton.md

@@ -510,4 +510,4 @@ const sent = ref(false);
 
 - [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
 - [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
-- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

package/dist/ai/BbBaseCheckboxGroup.md

@@ -44,7 +44,7 @@
 
 - `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
 - `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
-- `change` — `(e: "change", event: Event): void` — Emitted when a checkbox option is toggled. Forwards the original DOM `Event` from the checkbox input.
+- `change` — `(e: "change", event: Event): void` — Emitted when an option is toggled. Forwards the original DOM `Event` from the checkbox input.
 - `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
 - `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
 - `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.

package/dist/ai/BbBaseCheckboxIcon.md

@@ -110,8 +110,8 @@ const selected = ref<string[]>(['email']);
 
 ### Styling
 
-The glyph owns its own tokens, so restyle it by overriding CSS custom properties
-on the element (or an ancestor — they inherit):
+The glyph owns its own tokens, so restyle it by overriding CSS custom
+properties on it:
 
 - `--size` — box edge length (default `16px`)
 - `--r` — corner radius (default `4px`)
@@ -119,6 +119,23 @@ on the element (or an ancestor — they inherit):
 - `--check-color` — checkmark stroke (default `--bb-primary-fg`)
 - `--ring-color` — focus ring color
 
+**On the element itself, not an ancestor.** Each of these is declared on the
+glyph's own class, and a declaration on the element always beats one inherited
+from an ancestor — so `--size` set on a wrapper `div` is simply ignored
+(verified: the glyph stays 16px). Target the glyph class, or pass a `style` /
+`class` that lands on it:
+
+```css
+/* works */
+.bb-base-checkbox-icon {
+	--size: 20px;
+}
+/* does nothing */
+.my-form {
+	--size: 20px;
+}
+```
+
 **Bigger, rounder, recolored**
 
 ```vue

package/dist/ai/BbBaseRadioIcon.md

@@ -130,14 +130,30 @@ const selected = ref('team');
 
 ### Styling
 
-Restyle by overriding the glyph's CSS custom properties on the element (or an
-ancestor — they inherit):
+Restyle by overriding the glyph's CSS custom properties on it:
 
 - `--size` — ring diameter (default `16px`)
-- `--space` — gap between ring and dot when checked (default `6px`)
+- `--space` — gap between ring and dot when checked (default `2px`)
 - `--color` — dot color (default `--bb-primary`)
 - `--ring-color` — focus ring color
 
+**On the element itself, not an ancestor.** Each of these is declared on the
+glyph's own class, and a declaration on the element always beats one inherited
+from an ancestor — so `--size` set on a wrapper `div` is simply ignored
+(verified: the glyph stays at its 16px default). Target the glyph class, or pass a `style` /
+`class` that lands on it:
+
+```css
+/* works */
+.bb-base-radio-icon {
+	--size: 20px;
+}
+/* does nothing */
+.my-form {
+	--size: 20px;
+}
+```
+
 **Bigger and recolored**
 
 ```vue

package/dist/ai/BbBaseSwitchGroup.md

@@ -44,7 +44,7 @@
 
 - `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
 - `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
-- `change` — `(e: "change", event: Event): void` — Emitted when a checkbox option is toggled. Forwards the original DOM `Event` from the checkbox input.
+- `change` — `(e: "change", event: Event): void` — Emitted when an option is toggled. Forwards the original DOM `Event` from the checkbox input.
 - `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
 - `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
 - `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.

package/dist/ai/BbBaseSwitchIcon.md

@@ -120,15 +120,33 @@ const state = reactive<Record<string, boolean>>({
 
 ### Styling
 
-Restyle by overriding the glyph's CSS custom properties on the element (or an
-ancestor — they inherit):
+Restyle by overriding the glyph's CSS custom properties on it:
 
 - `--w` / `--h` — track width / height (default `32px` / `18px`)
 - `--thumb` — thumb diameter (default `16px`)
 - `--color` — track fill when checked (default `--bb-primary`)
-- `--bg-color` — track fill when off (default `--bb-muted`)
+- `--bg-color` — track fill when off (default `--bb-track`)
 - `--radius` — track/thumb rounding (default `999px`)
 
+**On the element itself, not an ancestor.** Each of these is declared on the
+glyph's own class, and a declaration on the element always beats one inherited
+from an ancestor — so `--w` set on a wrapper `div` is simply ignored
+(verified: the glyph keeps its shipped size). Target the glyph class, or pass a `style` /
+`class` that lands on it:
+
+```css
+/* works */
+.bb-base-switch-icon {
+	--w: 40px;
+	--h: 22px;
+	--thumb: 18px;
+}
+/* does nothing */
+.my-form {
+	--w: 40px;
+}
+```
+
 **Larger and recolored**
 
 ```vue

package/dist/ai/BbBreadcrumbs.md

@@ -582,4 +582,4 @@ overflow calculation runs after hydration once real widths exist.
 ## See Also
 
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.
-- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

package/dist/ai/BbButton.md

@@ -945,5 +945,5 @@ Anti-patterns:
 
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.
 - [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
-- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
 - [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).

package/dist/ai/BbCheckbox.md

@@ -476,11 +476,12 @@ const toggleAll = (checked: boolean) => {
   two-token pattern like `"x xxxxxxx"` splits proportionally by token length —
   the first token sizes the **visually first** element, the second the other.
 - The box renders **before** the label by default — the conventional checkbox
-  arrangement. Setting `reverse` swaps the label in front of the box. Known
-  quirk: the prop is wired through an internal negation, so the layout is
-  "reversed" by default and `:reverse="false"` is identical to omitting the
-  prop — treat `reverse` as a swap-order switch, not a boolean you can turn
-  off.
+  arrangement. Setting `reverse` swaps the label in front of the box. It is an
+  ordinary opt-in boolean: unset and `:reverse="false"` both give box-first,
+  `reverse` gives label-first. (There _is_ an internal negation in the source,
+  but it exists to cancel `BbBaseInputContainer`'s own polarity, so it is
+  invisible from outside. Earlier revisions of this guide described that
+  negation as a consumer-facing quirk — it is not.)
 - `input-position` / `label-position` (`'left' | 'center' | 'right'`) align box
   and label text inside their columns — useful with percentage directions.
 - `hide-label` keeps the label for screen readers but hides it visually — only
@@ -522,8 +523,8 @@ input on mount — use sparingly.
   use `disabled` (see the readonly-vs-disabled section).
 - Unchecked boxes post nothing in classic forms; use `submit-when-false` when
   the backend expects an explicit "no".
-- `reverse` semantics are inverted internally (see Layout) — don't rely on
-  `:reverse="false"` doing anything.
+- `reverse` is an opt-in, not a toggle you turn off: unset already means
+  box-first. Setting `:reverse="false"` is legal but says nothing.
 - `checked` + `v-model` together fight each other; pick one source of truth.
 
 ### Accessibility

package/dist/ai/BbCheckboxGroup.md

@@ -449,7 +449,7 @@ enforcement can empty the array but never throws.
 Per-option, `#label` replaces an option's text (receives `{ item, text, checked }`)
 and `#icon` replaces the **entire box visual** for that option (you then own its
 checked/focus/error styling). `#legend` replaces the fieldset legend
-(`{ text, hasErrors }`). `#prepend` / `#append` inject content inside the options
+(`{ text, hasErrors, hasWarning }`; the validated wrapper adds `showAsterisk`). `#prepend` / `#append` inject content inside the options
 container, before the first / after the last box.
 
 ### Events and focus
@@ -457,7 +457,8 @@ container, before the first / after the last box.
 `update:modelValue` (the `v-model` channel) carries the full array — it is the
 only source of selection truth. The native `blur`, `change`, `click`, `focus`,
 `input`, `keydown`, `mousedown`, `mouseup` events are re-emitted with their raw
-payloads, plus an `inactive` event when focus leaves the group; listen to those
+payloads, plus the pair `active` (focus enters the group — it is what drives
+the hint's show/hide internally) and `inactive` (focus leaves); listen to those
 for analytics or side effects, never to compute selection yourself. `autofocus`
 focuses the first option on mount — use sparingly.
 
@@ -537,7 +538,7 @@ focuses the first option on mount — use sparingly.
 | `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
 | `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
 | `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 checkbox groups. |
+| `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 … |
 | `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
 | `max` | `number \| undefined` |  |  | Maximum number of selected items. |
@@ -556,7 +557,7 @@ focuses the first option on mount — use sparingly.
 
 - `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
 - `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
-- `change` — `(e: "change", event: Event): void` — Emitted when a checkbox option is toggled. Forwards the original DOM `Event` from the checkbox input.
+- `change` — `(e: "change", event: Event): void` — Emitted when an option is toggled. Forwards the original DOM `Event` from the checkbox input.
 - `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
 - `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
 - `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.

package/dist/ai/BbCollapsible.md

@@ -27,7 +27,7 @@ Pick the neighbour that fits instead when you can:
   async panels, wizard steps) → **`BbSmoothHeight`** (`./BbSmoothHeight.md`) —
   it has no hidden state, it only animates height.
 
-The whole API: `modelValue` (required boolean), `eager`, `transition-duration`,
+The whole API: `modelValue` (boolean, defaults `false`), `eager`, `transition-duration`,
 and one default slot. There are no events — see "You own the state" below.
 
 ### Advanced options in a form
@@ -124,13 +124,14 @@ const includeDrafts = ref(false);
 
 ### You own the state (one-way model)
 
-`modelValue` is a **required** prop and the component never writes it back:
+`modelValue` is a **one-way** prop and the component never writes it back:
 `BbCollapsible` emits no events and has nothing to emit — it cannot close or
 open itself. `v-model` works purely as a prop binding; every change comes from
 your trigger. Two consequences:
 
-- Initialize the boolean explicitly (`const open = ref(false)`) — `modelValue`
-  is required, so leaving it `undefined` is a real omission and Vue warns.
+- Initialize the boolean explicitly (`const open = ref(false)`). Omitting the
+  binding is legal — it defaults to `false`, i.e. closed, and **nothing warns**
+  — so a forgotten `v-model` looks like a collapsible that will not open.
 - Don't listen for `update:modelValue` on it; put side effects on the trigger
   that flips the state.
 
@@ -405,8 +406,9 @@ const active = ref<DetailTab | null>('specs');
   `BbAccordion`, which wires all of it.
 - **Don't use it as a pure height animator** — if nothing is ever hidden,
   `BbSmoothHeight` is the right tool.
-- **Initialize the model** — `modelValue` is required with no default; an
-  `undefined` binding warns in dev (it behaves as closed).
+- **Initialize the model** — an omitted or `undefined` binding silently
+  behaves as closed and does **not** warn, so a missing `v-model` presents as
+  "the collapsible is broken" rather than as a mistake.
 
 ### Accessibility
 
@@ -423,8 +425,8 @@ const active = ref<DetailTab | null>('specs');
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
-| `modelValue` | `boolean` | `false` | yes | Used by v-model to trigger opening / closing the collapsible. |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds |
+| `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, whic… |
+| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
 
 ## Events
 

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
@@ -608,7 +614,7 @@ styling (a caret, a highlight). Two props gate interaction:
 | `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. |
 | `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

@@ -281,7 +281,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `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"`). |
 | `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"`. |
 

package/dist/ai/BbDialog.md

@@ -355,10 +355,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
@@ -779,12 +782,12 @@ default falls back to `config.adaptive`.
 | `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). |
 | `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… |
+| `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` |  |  | 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