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

package/README.md

@@ -6,7 +6,7 @@ Vue 3 component library used across BitBoss products. It ships typed building bl
 
 ## What’s in the package
 
-Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components-docs.vercel.app/).
+Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components.bitboss.it/).
 
 ### Styles
 
@@ -36,46 +36,53 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 ### Composables
 
-| Composable                    | Role                                                       |
-| ----------------------------- | ---------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
-| `useConfirm`                  | Programmatic confirm / modal flows.                        |
-| `useCountdown`                | Countdown timer state.                                     |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
-| `useQueue`                    | Simple async task queue.                                   |
-| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
-| `useToast`                    | Toast notifications API.                                   |
+| Composable             | Role                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `useBbConfig`          | Global options for the kit (locale, defaults, etc.).                  |
+| `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
+| `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
+| `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
+| `useConfirm`           | Programmatic confirm / modal flows.                                   |
+| `useCountdown`         | Countdown timer state.                                                |
+| `useId`                | SSR-safe unique ids.                                                  |
+| `useMobile`            | Mobile / viewport-oriented behaviour.                                 |
+| `useSafeArea`          | Claim a screen edge for a docked panel so toasts avoid it.            |
+| `useToast`             | Toast notifications API.                                              |
 
-### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
+### Utilities
 
-Headless or low-level pieces used inside **Bb\*** wrappers or your own compositions:
+- **`slotKey`** — the normalizer behind every dynamic per-item named slot (`BbDropdown`, `BbTable`, `BbTabs`, `BbTree`, `BbBreadcrumbs`). Import it when building slot names programmatically instead of restating the rule.
 
-- **Actions:** `BbBaseButton`
-- **Text & numbers:** `BaseTextInput`, `BaseTextarea`, `BaseNumberInput`, `BaseTag`
-- **Choice:** `BaseCheckbox`, `BaseCheckboxGroup`, `BaseRadio`, `BaseRadioGroup`, `BaseSwitch`, `BaseSwitchGroup`, `BaseSlider`, `BaseRating`
-- **Choice glyphs (presentational SVGs):** `BbBaseCheckboxIcon`, `BbBaseRadioIcon`, `BbBaseSwitchIcon`
-- **Rich inputs:** `BaseSelect`, `BaseColorInput`, `BaseDatePicker`, `BaseDatePickerInput`
-- **Layout / chrome:** `BaseInputContainer`, `BaseDialog`
+### Directives
+
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
+over the component for simple no-slot cases.
+
+### Base\* primitives
+
+The styled `Base*` input controls and the input chrome (`BbBaseInputContainer`,
+`CommonInputWrapper` — label, prepend/append, prefix/suffix, clear button,
+spacing) are **internal composition layers and are not exported**. Use the full
+public inputs (`BbTextInput`, `BbSelect`, …); pass `hideLabel` for a
+bare/inline control. The exported primitives are **`BbBaseButton`** and the
+presentational glyphs **`BbBaseCheckboxIcon`**, **`BbBaseRadioIcon`**,
+**`BbBaseSwitchIcon`**.
 
 ### Bb\* components (composed)
 
 Product-ready components with labels, hints, errors, and consistent styling:
 
-- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbBadge`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownButton`
-- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`,`BbSmoothHeight`
+- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
+- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanes`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 
-### Shared input shells _(internal layout primitives - not for direct consumer use)_
-
-- **`CommonInputWrapper`** — the internal input-chrome primitive (label, prepend/append, prefix/suffix, clear button, spacing) that every `Bb*` input composes. Not exported; use the full public inputs (`BbTextInput`, `BbSelect`, …).
-
 ### Exported component types
 
-For most **Base\*** and **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BaseSelectEvents`). Use them for typed wrappers and design-system layers; the docs list the full set per component.
+For the public **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BbTableEvents`), plus supporting shapes like `BbDropdownItem` and `DropdownGroupItemsGetter`. Use them for typed wrappers and design-system layers; the docs list the full set per component.
 
 ---
 
@@ -83,7 +90,7 @@ For most **Base\*** and **Bb\*** components, the package exports matching **prop
 
 **Primary docs (components, props, guides):**
 
-- [BitBoss UI documentation](https://ui-components-docs.vercel.app/) — site with guides and API reference.
+- [BitBoss UI documentation](https://ui-components.bitboss.it/) — site with guides and API reference.
 
 **For AI coding agents:**
 
@@ -93,10 +100,10 @@ v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.5`) for stable
 links. Sizes grow with the catalogue — treat them as the current order of
 magnitude, not a contract.
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
-- [Index](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt) (~19 KB) — link index into every document.
-- [components.json](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (~19 KB) — link index into every document.
+- [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -321,6 +328,38 @@ migrations — a value that must move to a slot, directive, or CSS — are repor
 with a migration-guide link but left for you. Run `eslint --fix`, then the
 remaining reports are exactly the by-hand cases.
 
+#### The one v2 break a codemod cannot own: `reverse`
+
+`reverse` on `BbCheckbox` / `BbRadio` / `BbSwitch` kept its **name** and
+inverted its **meaning** in v3. Both versions render the same default layout,
+so only explicit values moved:
+
+| v2                            | v3        |
+| ----------------------------- | --------- |
+| `:reverse="false"`            | `reverse` |
+| `reverse` / `:reverse="true"` | delete it |
+
+That is invisible to every other check — `:reverse="false"` is a declared prop,
+correctly typed, holding its own default value — and it cannot go in the
+rename table above, because the table is keyed by prop _name_: an entry for
+`reverse` would rewrite the legitimate v3 spellings too.
+
+So it has its own rule, `bitboss-ui/no-reverse-false` (in `recommended`). It
+flags only a **literal** `:reverse="false"` and offers both corrections as
+editor suggestions — a dynamic `:reverse="isRtl"` that merely evaluates false
+is left alone. For a bulk sweep of a v2 codebase, opt into the fix:
+
+```js
+{
+	rules: {
+		'bitboss-ui/no-reverse-false': ['error', { assumeV2: true }],
+	},
+}
+```
+
+`assumeV2` is off by default because the two readings produce opposite
+layouts — turn it on only for files you know came from v2, then turn it off.
+
 Every real HTML attribute (plus `aria-*` / `data-*`) falls through untouched, so
 attribute inheritance is never flagged. Escape hatches when you do need one:
 
@@ -399,7 +438,7 @@ MIT — see [`LICENSE`](LICENSE).
 
 ## Support
 
-- **Usage and APIs:** see the [documentation](https://ui-components-docs.vercel.app/).
+- **Usage and APIs:** see the [documentation](https://ui-components.bitboss.it/).
 - **Company / licensing / commercial:** [BitBoss](https://www.bitboss.it/).
 
 ### Reporting a bug

package/dist/ai/BbAccordion.md

@@ -529,10 +529,10 @@ is generated for you.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | 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"
@@ -392,14 +396,14 @@ const publish = () => {
 | --- | --- | --- | --- | --- |
 | `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Defaults to `'assertive'` for destructive/warning variants, otherwise `'polite'`. |
 | `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
-| `hideClose` | `boolean \| undefined` |  |  | Defines whether to hide the close button. |
+| `hideClose` | `boolean \| undefined` | `false` |  | Defines whether to hide the close button. |
 | `icon` | `string \| undefined` |  |  | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
 | `iconSize` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"16"` |  | Size of the icon to use. |
 | `modelValue` | `any` | `true` |  | Used by v-model, set type to any to avoid Vue casting it as false. Alerts are visible on mount; the model dismisses them. |
 | `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)
 
@@ -309,9 +309,12 @@ state in the handler. Prefer `secondary` / `outline` for filter chips; reserve
 ```
 
 The clear button inherits the variant's foreground, so it reads on every surface
-— light on a filled `primary`, dark on a `secondary`/`outline`. Set
-`clearable-label` for the button's accessible name (defaults to the localized
-`badge.clearLabel`).
+— light on a filled `primary`, dark on a `secondary`/`outline`. By default its
+accessible name composes the localized verb with the badge's own text — a chip
+reading "Italy" announces "Remove Italy", with no per-chip wiring. Set
+`clearable-label` only when that composition is wrong for the context (it
+replaces the whole name). With a `BbBadgeButton` body the composition is
+skipped and the button falls back to the bare localized `badge.clearLabel`.
 
 Icons combine with `clearable`: a **`prepend:icon`** stays (it leads the label);
 an **`append:icon`** shares the trailing slot with the clear button — the icon
@@ -695,8 +698,10 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 - An icon-only badge (`icon`) has no visible text; the default slot is rendered
   as a screen-reader-only label — never leave it empty. In button mode that
   label is also the **button's accessible name**, so it is doubly required.
-- The `clearable` button has an accessible name from `clearable-label` (or the
-  localized `badge.clearLabel`).
+- The `clearable` button's accessible name is composed by default: the
+  localized `badge.clearLabel` verb plus the badge body's text ("Remove
+  Italy"). `clearable-label` replaces the whole name; with a `BbBadgeButton`
+  body the composition is skipped (bare verb only).
 - A clickable **and** clearable badge is two tab stops (body, then clear). That
   is intended: two actions, two controls.
 - Keyboard focus on either control rings the whole pill, so the focused target
@@ -709,10 +714,10 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `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. |
+| `clearable` | `boolean \| undefined` | `false` |  | 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. 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… |
+| `loading` | `boolean \| undefined` | `false` |  | 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. |
 | `size` | `keyof Sizes \| undefined` | `"md"` |  | Preset size of the badge. |
 | `variant` | `keyof BadgeVariantRegistry \| undefined` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--color`). |
@@ -727,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

@@ -12,21 +12,21 @@
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `activeClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
-| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
-| `async` | `boolean \| undefined` |  |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
+| `activeClass` | `string \| undefined` | `'router-link-active'` |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
+| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `async` | `boolean \| undefined` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
 | `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` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
-| `disabled` | `boolean \| undefined` |  |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
 | `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 (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
-| `exactActiveClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
+| `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
-| `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
+| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
-| `instant` | `boolean \| undefined` |  |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
+| `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
@@ -41,17 +41,17 @@
 | `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
 | `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
 | `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
-| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
-| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
+| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` | `false` |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` | `false` |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
+| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
-| `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
-| `tag` | `ButtonTag \| undefined` |  |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
+| `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
+| `tag` | `ButtonTag \| undefined` | `'button'` |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
-| `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
-| `viewTransition` | `boolean \| undefined` |  |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
+| `type` | `"button" \| "submit" \| "reset" \| undefined` | `'button'` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
+| `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Events
 
@@ -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

@@ -455,22 +455,22 @@ const sent = ref(false);
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `activeClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
-| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
-| `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` |  |  | Makes the component take the full available width (block-level layout). Adds the `bb-base-button--block` modifier class. |
+| `activeClass` | `string \| undefined` | `'router-link-active'` |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
+| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `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` |  | Makes the component take the full available width (block-level layout). Adds the `bb-base-button--block` modifier class. |
 | `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` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
-| `disabled` | `boolean \| undefined` |  |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
 | `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 (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
-| `exactActiveClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
+| `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
-| `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
+| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
-| `instant` | `boolean \| undefined` |  |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
+| `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
@@ -485,18 +485,18 @@ const sent = ref(false);
 | `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
 | `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
 | `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
-| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
-| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
+| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` | `false` |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` | `false` |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
+| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
-| `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
-| `tag` | `ButtonTag \| undefined` |  |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
+| `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
+| `tag` | `ButtonTag \| undefined` | `'button'` |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
 | `text` | `string \| undefined` |  |  | Fallback text content rendered when no default slot is provided. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
 | `type` | `"button" \| "submit" \| "reset" \| undefined` | `"button"` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
-| `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
 
@@ -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/BbBaseCheckbox.md

@@ -17,19 +17,19 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes this checkbox for assistive technologies. Forwarded to the input as `aria-describedby`. |
-| `autofocus` | `Booleanish \| undefined` |  |  | Automatically focuses the checkbox when the page/component loads. Use sparingly to avoid usability issues. |
+| `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the checkbox when the page/component loads. Use sparingly to avoid usability issues. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Forces the checkbox checked state (controlled prop). When omitted, the checked state is derived from `modelValue === trueValue`. Deliberately `undefined` rather than `false`, so "unset" stays distinguishable from an explicit `:checked="fals… |
-| `disabled` | `boolean \| undefined` |  |  | Disables user interaction. Also applied when `readonly` is set, since native checkboxes do not support `readonly`. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. Also applied when `readonly` is set, since native checkboxes do not support `readonly`. |
 | `falseValue` | `any` | `false` |  | Value submitted/emitted when the checkbox is unchecked. Accepts any serializable value. Serialized to a string for form submission. |
-| `hasErrors` | `boolean \| undefined` |  |  | Puts the component into an error state (adds error styling class `bb-base-checkbox--errors`). |
-| `hasWarning` | `boolean \| undefined` |  |  | Puts the component into a warning state (adds `bb-base-checkbox--warnings`). Errors take priority when both are set. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state (adds error styling class `bb-base-checkbox--errors`). |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state (adds `bb-base-checkbox--warnings`). Errors take priority when both are set. |
 | `id` | `string \| undefined` |  |  | Identifier forwarded to the input. |
-| `indeterminate` | `boolean \| undefined` |  |  | Renders the checkbox in the indeterminate state (neither checked nor unchecked). Note: the native `indeterminate` state resets on user click; this component re-applies it to keep UI and prop aligned. |
+| `indeterminate` | `boolean \| undefined` | `false` |  | Renders the checkbox in the indeterminate state (neither checked nor unchecked). Note: the native `indeterminate` state resets on user click; this component re-applies it to keep UI and prop aligned. |
 | `modelValue` | `any` |  |  | Bound value for `v-model`. When it equals `trueValue` the checkbox is considered checked, otherwise unchecked. |
 | `name` | `string \| undefined` |  |  | Name attribute of the input, used during form submission. |
-| `readonly` | `boolean \| undefined` |  |  | Puts the input in a read-only state. Since checkboxes do not support native `readonly`, the input is disabled while styled as read-only. |
-| `required` | `boolean \| undefined` |  |  | Marks the input as required for form validation. |
-| `submitWhenFalse` | `boolean \| undefined` |  |  | When unchecked, submits a hidden input with `falseValue` so that a value is still posted with the form. When checked, the visible input submits `trueValue` as usual. |
+| `readonly` | `boolean \| undefined` | `false` |  | Puts the input in a read-only state. Since checkboxes do not support native `readonly`, the input is disabled while styled as read-only. |
+| `required` | `boolean \| undefined` | `false` |  | Marks the input as required for form validation. |
+| `submitWhenFalse` | `boolean \| undefined` | `false` |  | When unchecked, submits a hidden input with `falseValue` so that a value is still posted with the form. When checked, the visible input submits `trueValue` as usual. |
 | `trueValue` | `any` | `true` |  | Value submitted/emitted when the checkbox is checked. Accepts any serializable value. Serialized to a string for form submission. |
 
 ## Events

package/dist/ai/BbBaseCheckboxGroup.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.