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

package/dist/ai/BbBaseSwitchGroup.md

@@ -17,34 +17,34 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes the entire checkbox group for assistive technologies. Forwarded to each generated input as `aria-describedby`. |
-| `autofocus` | `Booleanish \| undefined` |  |  | Automatically focuses the first checkbox on mount when true. Applied only to the first option. |
-| `dependencies` | `unknown[] \| undefined` |  |  | List of reactive values which, when changed, trigger items re-fetching. Useful to reload options based on external inputs. |
+| `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the first checkbox on mount when true. Applied only to the first option. |
+| `dependencies` | `unknown[] \| undefined` | `[]` |  | List of reactive values which, when changed, trigger items re-fetching. Useful to reload options based on external inputs. |
 | `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `dependencies` changes. |
 | `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the group layout. - `horizontal`: options flow in rows - `vertical`: options stack in a column |
-| `disabled` | `boolean \| undefined` |  |  | Disables interaction for the whole group. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence th… |
-| `hasErrors` | `boolean \| undefined` |  |  | Puts the component into an error state adds the error styling class. |
-| `hasWarning` | `boolean \| undefined` |  |  | Puts the component into a warning state. Errors take priority when both are set. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables interaction for the whole group. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components.bitboss.it/it/guides/coherence the doc… |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state adds the error styling class. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state. Errors take priority when both are set. |
+| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. |
 | `id` | `string \| undefined` |  |  | Identifier of the group. Used to derive per-option IDs for accessible labeling. |
 | `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Items provider. Can be: - An array of items - A sync/async function `(prefill, modelValue) => items` When a function is provided, it is invoked on prefill and when dependencies change to load options dynamically. |
-| `itemText` | `(T extends object ? string \| ((item: T) => string) : (item: T) => string) \| undefined` |  |  | Defines how to derive the display text from an item. Accepts a nested key path into the item or a function `(item) => string`. |
-| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` |  |  | Defines how to derive the value from an item. Accepts a nested key path into the item or a function `(item) => any`. |
-| `loadingText` | `string \| undefined` |  |  | Text displayed while items are loading. |
+| `itemText` | `(T extends object ? string \| ((item: T) => string) : (item: T) => string) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the display text from an item. Accepts a nested key path into the item or a function `(item) => string`. |
+| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the value from an item. Accepts a nested key path into the item or a function `(item) => any`. |
+| `loadingText` | `string \| undefined` | `'Loading...'` |  | Text displayed while items are loading. |
 | `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items. |
 | `modelValue` | `any` |  | yes | Selected values for the group. Used with `v-model`. Single value when `multiple` is false, array when `multiple` is true. |
 | `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `modelValue` changes. |
 | `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When `true`, `modelValue` must be an array and emitted updates are arrays. When `false`, `modelValue` must be a single value (or `null`) and emitted updates are single values. |
 | `name` | `string \| undefined` |  |  | Name attribute applied to each input for form submission. |
-| `noDataText` | `string \| undefined` |  |  | Text displayed when there are no items to show. |
-| `readonly` | `boolean \| undefined` |  |  | Makes all checkboxes read-only. Since checkboxes do not support native `readonly`, inputs are disabled while styled as read-only. |
+| `noDataText` | `string \| undefined` | `'No data to display'` |  | Text displayed when there are no items to show. |
+| `readonly` | `boolean \| undefined` | `false` |  | Makes all checkboxes read-only. Since checkboxes do not support native `readonly`, inputs are disabled while styled as read-only. |
 | `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. |
 
 ## Events
 
 - `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
@@ -162,13 +180,13 @@ ancestor — they inherit):
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `checked` | `boolean \| undefined` |  |  | Renders the checked state (fills the track and slides the thumb to the end). |
-| `disabled` | `boolean \| undefined` |  |  | Disables the glyph (muted track, not-allowed cursor). Purely visual. |
-| `focusVisible` | `boolean \| undefined` |  |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
-| `hasErrors` | `boolean \| undefined` |  |  | Puts the glyph into the error state (danger border and ring color). |
-| `hasWarning` | `boolean \| undefined` |  |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
-| `indeterminate` | `boolean \| undefined` |  |  | Renders the indeterminate state (filled track with the thumb parked at the midpoint of its travel). Takes visual precedence over `checked`. |
-| `readonly` | `boolean \| undefined` |  |  | Renders the read-only affordance. Reserved for parity with the other glyphs; currently has no distinct visual. |
+| `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the track and slides the thumb to the end). |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted track, not-allowed cursor). Purely visual. |
+| `focusVisible` | `boolean \| undefined` | `false` |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the glyph into the error state (danger border and ring color). |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
+| `indeterminate` | `boolean \| undefined` | `false` |  | Renders the indeterminate state (filled track with the thumb parked at the midpoint of its travel). Takes visual precedence over `checked`. |
+| `readonly` | `boolean \| undefined` | `false` |  | Renders the read-only affordance. Reserved for parity with the other glyphs; currently has no distinct visual. |
 
 ## Events
 

package/dist/ai/BbBaseTag.md

@@ -20,23 +20,23 @@
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this tag input for assistive technologies. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically on mount. |
-| `caseSensitive` | `boolean \| undefined` |  |  | Compare tags case-sensitively when rejecting duplicates, so `Vue` and `vue` can both exist. By default matching folds case, because two chips differing only in case read as duplicates to a user. Either way the tag is stored with the casing … |
-| `clearable` | `boolean \| undefined` |  |  | Show a clear button whenever tags are present and the control is interactive. |
-| `comma` | `boolean \| undefined` |  |  | Display selected tags as a comma-separated string instead of individual chips. When enabled, tags cannot be deselected by clicking individual chips. |
-| `compact` | `boolean \| undefined` |  |  | Apply the compact density variant. |
-| `disabled` | `boolean \| undefined` |  |  | Disable all interactions with the tag input. |
+| `caseSensitive` | `boolean \| undefined` | `false` |  | Compare tags case-sensitively when rejecting duplicates, so `Vue` and `vue` can both exist. By default matching folds case, because two chips differing only in case read as duplicates to a user. Either way the tag is stored with the casing … |
+| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever tags are present and the control is interactive. |
+| `comma` | `boolean \| undefined` | `false` |  | Display selected tags as a comma-separated string instead of individual chips. When enabled, tags cannot be deselected by clicking individual chips. |
+| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the tag input. |
 | `divider` | `string \| string[] \| undefined` | `"Enter"` |  | Keyboard key that triggers tag creation from current input value. Accepts a single key or an array of keys (e.g. `['Enter', ',']`) — any of them commits the current text. |
-| `hasErrors` | `boolean \| undefined` |  |  | Apply error styling to the tag input. |
-| `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the tag input. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
 | `id` | `string \| undefined` |  |  | Explicit id for the input element. |
-| `loading` | `boolean \| undefined` |  |  | Display the loading state styles. |
+| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
 | `max` | `number \| undefined` |  |  | Maximum number of tags that can be created. |
 | `modelValue` | `string[]` |  | yes | v-model value for selected tags. |
 | `name` | `string \| undefined` |  |  | Name attribute forwarded to the input element. |
 | `placeholder` | `string \| undefined` |  |  | Placeholder text when no tags are present. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the input. |
-| `readonly` | `boolean \| undefined` |  |  | Make the input read-only while keeping tags visible. |
-| `required` | `boolean \| undefined` |  |  | Mark the input as required for form validation. |
+| `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only while keeping tags visible. |
+| `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |
 
 ## Events
 

package/dist/ai/BbBaseTextInput.md

@@ -20,16 +20,16 @@
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this input for assistive technologies. |
 | `autocomplete` | `string \| undefined` |  |  | Browser autocomplete hint for the input field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically on mount. |
-| `clearable` | `boolean \| undefined` |  |  | Show a clear button whenever a value is present and the control is interactive. |
-| `compact` | `boolean \| undefined` |  |  | Apply the compact density variant. |
-| `disabled` | `boolean \| undefined` |  |  | Disable all interactions with the input. |
-| `emitMasked` | `boolean \| undefined` |  |  | When using a mask, emit the formatted (masked) value instead of the raw input. |
-| `hasErrors` | `boolean \| undefined` |  |  | Apply error styling to the input and set `aria-invalid`. |
-| `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
+| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever a value is present and the control is interactive. |
+| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the input. |
+| `emitMasked` | `boolean \| undefined` | `false` |  | When using a mask, emit the formatted (masked) value instead of the raw input. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the input and set `aria-invalid`. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
 | `id` | `string \| undefined` |  |  | Explicit id for the input element. |
 | `inputMode` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "none" \| "numeric" \| "decimal" \| undefined` |  |  | Input mode hint for mobile keyboards. |
 | `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode, forwarded by wrapper components. |
-| `loading` | `boolean \| undefined` |  |  | Display the loading state styles. |
+| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
 | `mask` | `MaskInputOptions \| undefined` |  |  | Input mask configuration. When provided, enables formatted input with validation. |
 | `max` | `string \| undefined` |  |  | Maximum value for numeric and date inputs. |
 | `maxlength` | `number \| undefined` |  |  | Maximum number of characters the input will accept. |
@@ -38,8 +38,8 @@
 | `name` | `string \| undefined` |  |  | Name attribute forwarded to the input element. |
 | `placeholder` | `string \| undefined` |  |  | Placeholder text when no value is present. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the input. |
-| `readonly` | `boolean \| undefined` |  |  | Make the input read-only while keeping it visible. |
-| `required` | `boolean \| undefined` |  |  | Mark the input as required for form validation. |
+| `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only while keeping it visible. |
+| `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |
 | `step` | `string \| undefined` |  |  | Stepping interval for numeric and date inputs. |
 | `type` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "password" \| undefined` | `"text"` |  | HTML input type attribute. Restricted to the textual input types this component supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates. |
 

package/dist/ai/BbBaseTextarea.md

@@ -20,20 +20,20 @@
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this textarea for assistive technologies. |
 | `autocomplete` | `string \| undefined` |  |  | Browser autocomplete hint for the textarea. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the textarea automatically on mount. |
-| `autoGrow` | `boolean \| undefined` |  |  | Automatically expand the textarea height to fit its content. Composes with `rows`: when both are set, `rows` acts as the minimum-height floor the field grows past but never shrinks below. |
-| `clearable` | `boolean \| undefined` |  |  | Show a clear button whenever text is present and the control is interactive. |
-| `compact` | `boolean \| undefined` |  |  | Apply the compact density variant. |
-| `disabled` | `boolean \| undefined` |  |  | Disable all interactions with the textarea. |
-| `hasErrors` | `boolean \| undefined` |  |  | Apply error styling to the textarea. |
-| `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
+| `autoGrow` | `boolean \| undefined` | `false` |  | Automatically expand the textarea height to fit its content. Composes with `rows`: when both are set, `rows` acts as the minimum-height floor the field grows past but never shrinks below. |
+| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever text is present and the control is interactive. |
+| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the textarea. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the textarea. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
 | `id` | `string \| undefined` |  |  | Explicit id for the textarea element. |
-| `loading` | `boolean \| undefined` |  |  | Display the loading state styles. |
+| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
 | `modelValue` | `string \| null` |  | yes | v-model value: the text content, or `null` when empty. |
 | `name` | `string \| undefined` |  |  | Name attribute forwarded to the textarea element. |
 | `placeholder` | `string \| undefined` |  |  | Placeholder text when no value is present. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the textarea. |
-| `readonly` | `boolean \| undefined` |  |  | Make the textarea read-only while keeping it visible. |
-| `required` | `boolean \| undefined` |  |  | Mark the textarea as required for form validation. |
+| `readonly` | `boolean \| undefined` | `false` |  | Make the textarea read-only while keeping it visible. |
+| `required` | `boolean \| undefined` | `false` |  | Mark the textarea as required for form validation. |
 | `rows` | `string \| number \| undefined` |  |  | Number of visible rows. Without `autoGrow` this is the fixed height; with `autoGrow` it becomes the minimum-height floor the field grows past but never shrinks below. |
 
 ## Events

package/dist/ai/BbBaseTimePickerInput.md

@@ -16,20 +16,20 @@
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile the time columns open inside 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 segment. Purely a field-composition concern: the model stays 24-hour. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the time columns open inside 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 segment. Purely a field-composition concern: the model stays 24-hour. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Additional description id(s) announced by assistive technologies. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the first text field automatically when the component mounts. |
-| `clearable` | `boolean \| undefined` |  |  | Displays a clear button whenever a value is present and the control is interactive. |
-| `compact` | `boolean \| undefined` |  |  | Applies the compact density styles to the control. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the input, clock trigger, and popover. |
+| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button whenever a value is present and the control is interactive. |
+| `compact` | `boolean \| undefined` | `false` |  | Applies the compact density styles to the control. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the input, clock trigger, and popover. |
 | `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether manual typing is disabled inside the text fields. Use `'mobile'` / `'desktop'` to disable typing on one platform only. |
-| `hasErrors` | `boolean \| undefined` |  |  | Marks the control as invalid, applying error styles and `aria-invalid`. |
-| `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Marks the control as invalid, applying error styles and `aria-invalid`. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
 | `id` | `string \| undefined` |  |  | Explicit id for the input element. Falls back to an auto-generated value. |
-| `loading` | `boolean \| undefined` |  |  | Shows loading visuals on the input. |
+| `loading` | `boolean \| undefined` | `false` |  | Shows loading visuals on the input. |
 | `max` | `string \| undefined` |  |  | Maximum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
 | `min` | `string \| undefined` |  |  | Minimum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
 | `modelValue` | `string \| string[] \| null` |  | yes | v-model value: `null` for empty, a 24-hour `HH:mm` (or `HH:mm:ss` with `seconds`) string, or a two-element array when `range` is true. |
@@ -37,11 +37,11 @@
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
 | `placeholder` | `string \| undefined` |  |  | Placeholder shown when empty; defaults to the localized format hint. |
 | `prepend:icon` | `string \| undefined` |  |  | Icon name rendered before the input field. |
-| `range` | `boolean \| undefined` |  |  | Range selection: v-model expects a two-element array `[start, end]`. An inverted pair swaps on finalize with an `end_before_start` error. |
-| `readonly` | `boolean \| undefined` |  |  | Makes the text fields read-only and prevents opening the popover. |
-| `required` | `boolean \| undefined` |  |  | Marks the inputs as required to the browser. |
-| `seconds` | `boolean \| undefined` |  |  | Adds the seconds segment. Without it an incoming value carrying seconds displays truncated and zeroes out on the next user commit. |
-| `step` | `number \| undefined` |  |  | Minute granularity for the minute column and its arrow stepping. Constrains what the columns produce, never what typing accepts. |
+| `range` | `boolean \| undefined` | `false` |  | Range selection: v-model expects a two-element array `[start, end]`. An inverted pair swaps on finalize with an `end_before_start` error. |
+| `readonly` | `boolean \| undefined` | `false` |  | Makes the text fields read-only and prevents opening the popover. |
+| `required` | `boolean \| undefined` | `false` |  | Marks the inputs as required to the browser. |
+| `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds segment. Without it an incoming value carrying seconds displays truncated and zeroes out on the next user commit. |
+| `step` | `number \| undefined` | `1` |  | Minute granularity for the minute column and its arrow stepping. Constrains what the columns produce, never what typing accepts. |
 | `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
 
 ## Events

package/dist/ai/BbBreadcrumbs.md

@@ -558,7 +558,7 @@ overflow calculation runs after hydration once real widths exist.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `dividerWidth` | `number \| undefined` | `16` |  | Width of the divider in pixels. |
 | `ellipsisWidth` | `number \| undefined` |  |  | Explicit width used by the estimator for the ellipsis activator. |
 | `estimationBias` | `number \| undefined` | `1.12` |  | Multiplier applied to each estimated item width. A higher value will result in more over-estimation. |
@@ -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

@@ -881,27 +881,27 @@ Anti-patterns:
 | --- | --- | --- | --- | --- |
 | `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
-| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value passed to the attribute `aria-current` when the link is exact active. |
-| `async` | `boolean \| undefined` |  |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
-| `block` | `boolean \| undefined` |  |  | Displays the component as full width. |
+| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
+| `async` | `boolean \| undefined` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
+| `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
 | `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be in… |
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  |  |
-| `disableAutoLoading` | `boolean \| undefined` |  |  | Disables the automatic loading state that tracks async click handlers (enabled by default). |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async click handlers (enabled by default). |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download: renders a plain `<a download>` doing a native navigation (never an Inertia/router visit), so file downloads work. Pass a string for the suggested filename. A native-anchor signal alongside `target` and `e… |
 | `exactActiveClass` | `string \| undefined` |  |  | Class to apply when the link is exact active. |
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
-| `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — same intent as Nuxt's `external`. A native-anchor signal alongside `target` and `download`. |
+| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — same intent as Nuxt's `external`. A native-anchor signal alongside `target` and `download`. |
 | `falseValue` | `any` | `false` |  | Value emitted when the toggle is deactivated. |
-| `group` | `boolean \| undefined` |  |  | Identifies the button as part of a button group. |
+| `group` | `boolean \| undefined` | `false` |  | Identifies the button as part of a button group. |
 | `headers` | `object \| undefined` |  |  |  |
 | `href` | `string \| undefined` |  |  | Returns the hyperlink's URL. Can be set, to change the URL. |
 | `icon` | `string \| undefined` |  |  | Used when only an icon with no text should be displayed. |
-| `instant` | `boolean \| undefined` |  |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
-| `interactiveWhileLoading` | `boolean \| undefined` |  |  | Keeps the button clickable while it is loading. Buttons are disabled while loading by default; this escape hatch exists for toggles that must stay interactive (e.g. the dropdown-button caret). |
-| `loading` | `boolean \| undefined` |  |  | Triggers a loading indicator. |
+| `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
+| `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the button clickable while it is loading. Buttons are disabled while loading by default; this escape hatch exists for toggles that must stay interactive (e.g. the dropdown-button caret). |
+| `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  |  |
 | `modelValue` | `any` |  |  |  |
 | `onBefore` | `(() => void) \| undefined` |  |  |  |
@@ -920,18 +920,18 @@ Anti-patterns:
 | `prepend:icon` | `string \| undefined` |  |  | Icon to be added on the left of the text. |
 | `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  |  |
 | `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  |  |
-| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
+| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  |  |
-| `replace` | `boolean \| undefined` |  |  | Calls `router.replace` instead of `router.push`. |
+| `replace` | `boolean \| undefined` | `false` |  | Calls `router.replace` instead of `router.push`. |
 | `size` | `Responsive<Sizes> \| undefined` | `"md"` |  | Sets the size of the button. A single value applies at every breakpoint; a per-breakpoint map (e.g. `{ default: 'sm', lg: 'md' }`) switches responsively. Purely CSS-driven — no runtime breakpoint watching. |
-| `tag` | `ButtonTag \| undefined` |  |  | Element to render for the plain (non-link, non-router) button: `'button'` (default), `'div'`/`'span'` when nesting inside another button or link, or `'label'` for a file-upload trigger. Ignored when `href`/`to` make the button render as a l… |
+| `tag` | `ButtonTag \| undefined` | `'button'` |  | Element to render for the plain (non-link, non-router) button: `'button'` (default), `'div'`/`'span'` when nesting inside another button or link, or `'label'` for a file-upload trigger. Ignored when `href`/`to` make the button render as a l… |
 | `target` | `string \| undefined` |  |  | Sets or retrieves the window or frame at which to target content. |
 | `text` | `string \| undefined` |  |  | Text content of the component. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route Location the link should navigate to when clicked on. |
 | `trueValue` | `any` | `true` |  | Value emitted when the toggle is activated. |
 | `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Gets the classification and default behavior of the button. |
 | `variant` | `ButtonVariantType \| undefined` | `"primary"` |  | Visual variant of the button. Controls colors and surface style while keeping spacing and sizing unchanged. |
-| `viewTransition` | `boolean \| undefined` |  |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
+| `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Events
 
@@ -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
@@ -555,25 +556,25 @@ input on mount — use sparingly.
 | `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
 | `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` | `"auto"` |  | 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… |
 | `falseValue` | `any` |  |  | Value of the input when unchecked. It handles any kind of serializable object. |
-| `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. |
+| `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. |
-| `indeterminate` | `boolean \| undefined` |  |  | Sets the input in an indeterminate state. |
+| `indeterminate` | `boolean \| undefined` | `false` |  | Sets the input in an indeterminate state. |
 | `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. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
-| `submitWhenFalse` | `boolean \| undefined` |  |  | Will submit "falseValue" if the input is not checked. Otherwise "trueValue" will be submitted. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
+| `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: in every direction the order of the label and the input is swapped from the standard arrangement. |
+| `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. |
 | `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/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.
 
@@ -517,18 +518,18 @@ focuses the first option on mount — use sparingly.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `compact` | `boolean \| undefined` |  |  | Displays the component in a compact version. |
+| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
 | `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
 | `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
 | `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. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | 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. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `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. |
 | `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… |
-| `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 each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use `hideLegend` for that. |
-| `hideLegend` | `boolean \| undefined` |  |  | Visually hides the legend of the fieldset while maintaining accessibility. |
+| `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 each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use `hideLegend` for that. |
+| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset 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. |
 | `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
@@ -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. |
@@ -546,9 +547,9 @@ focuses the first option on mount — use sparingly.
 | `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When true, `modelValue` must be an array. When false, `modelValue` should be a single value. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `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. |
 | `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… |
 
@@ -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
 
@@ -422,9 +424,9 @@ 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 |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `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