bitboss-ui 3.0.0-beta.35 → 3.0.0-beta.36

package/README.md

@@ -78,7 +78,7 @@ Product-ready components with labels, hints, errors, and consistent styling:
 
 - **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`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanels`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`

package/bin/bitboss-ui-mcp.mjs

@@ -316,6 +316,8 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 			...(type.deprecated ? { deprecated: true } : {}),
 			...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
 			usedBy: type.usedBy ?? [],
+			// The short answer only; get_component(name) has the definition.
+			...(type.values ? { values: type.values } : {}),
 			import: `import type { ${type.replacedBy ?? type.name} } from 'bitboss-ui';`,
 		}));
 
@@ -425,9 +427,16 @@ function getComponent({ name, maxChars } = {}) {
 				...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
 				component: type.component,
 				usedBy: type.usedBy ?? [],
+				// What it is (Q50.2): the declaration, the accepted values when
+				// finite (open when `extensibleVia` names a registry), and the
+				// resolved fields when the declaration leans on a private type.
+				...(type.definition ? { definition: type.definition } : {}),
+				...(type.values ? { values: type.values } : {}),
+				...(type.extensibleVia ? { extensibleVia: type.extensibleVia } : {}),
+				...(type.fields ? { fields: type.fields } : {}),
 				import: `import type { ${type.replacedBy ?? name} } from 'bitboss-ui';`,
 				hint: use
-					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. Call get_component('${use.component}') for the contract that documents its fields.`
+					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. \`definition\` above is the type itself; call get_component('${use.component}') to see it in use.`
 					: 'A type, not a component — import it for the value you pass, never write it as a tag.',
 			};
 		}
@@ -467,6 +476,8 @@ function getComponent({ name, maxChars } = {}) {
 			name: type.name,
 			usage: type.usage,
 			usedBy: (type.usedBy ?? []).filter((use) => use.component === entry.name),
+			...(type.values ? { values: type.values } : {}),
+			...(type.extensibleVia ? { extensibleVia: type.extensibleVia } : {}),
 			import: `import type { ${type.name} } from 'bitboss-ui';`,
 		}));
 

package/dist/ai/BbAccordion.md

@@ -234,13 +234,13 @@ const endpoints = ref<Endpoint[]>([
      Non-scoped so variant classes on the child badge receive the accents. -->
 <style>
 .bb-badge.bb-badge--soft-blue {
-	--accent: #2563eb;
+	--accent: var(--bb-info);
 }
 .bb-badge.bb-badge--soft-green {
-	--accent: #16a34a;
+	--accent: var(--bb-success);
 }
 .bb-badge.bb-badge--soft-red {
-	--accent: #dc2626;
+	--accent: var(--bb-danger);
 }
 .bb-badge.bb-badge--soft-blue,
 .bb-badge.bb-badge--soft-green,
@@ -619,7 +619,7 @@ grammar, the merge rules and the global map are in the
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `header`, `panel`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
-| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `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` | `250` |  | How long the transition has to last in milliseconds |
 
@@ -641,7 +641,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Events
 
-- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+- `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots
 
@@ -664,4 +664,4 @@ States are listed in precedence order: when two are on at once and their entries
 ## See Also
 
 - [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.
-- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
+- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanels exports enable split layouts).

package/dist/ai/BbAlert.md

@@ -53,6 +53,11 @@ the user should attend to; `destructive` reports a failure or dangerous state.
 An alert reads far better with a matching leading `icon`, so treat variant and
 icon as a pair.
 
+There is no `success` or `info` alert, on purpose (the built-in ramps stay
+closed): a confirmation is usually a toast, and a neutral note is `outline`
+with an icon. When an app needs one anyway, register it with the plugin's
+`alertVariants` option and colour it from `--bb-success` / `--bb-info`.
+
 **Semantic variants, each with a fitting icon**
 
 ```vue
@@ -475,7 +480,7 @@ full grammar, the merge rules and the global map are in the
 
 ## Events
 
-- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+- `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots
 

package/dist/ai/BbAvatar.md

@@ -648,6 +648,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--bg` | `.bb-avatar` | `var(--bb-primary)` | fallback surface (an image covers it) |
 | `--fg` | `.bb-avatar` | `var(--bb-primary-fg)` | Initials; the built-in icon is an 80/20 mix of this toward --bg |
 | `--default-icon-size` | `.bb-avatar` | `clamp(14px, calc(var(--size) * 0.7), 48px)` | Built-in fallback icon: 70% of the avatar, floored at 14px and capped at 48px. `--size` is the avatar's own box, set inline from the `size` prop. |
+| `--fs` | `.bb-avatar` | `max(8px, calc(var(--size) * 0.4))` | Initials: 40% of the avatar, floored at 8px |
 | `--elev` | `.bb-avatar` | `var(--bb-elev-sm)` | The theme's resting lift on small chrome (Q44.15), declared here so an ancestor's `--elev` cannot reach in; `--elev: none` flattens one. |
 | `--size` | `.bb-avatar__default-icon` | `var(--default-icon-size)` |  |
 

package/dist/ai/BbBadge.md

@@ -161,19 +161,19 @@ const invoices: InvoiceRow[] = [
      Non-scoped so variant classes on the child badge receive the accents. -->
 <style>
 .bb-badge.bb-badge--soft-gray {
-	--accent: #64748b;
+	--accent: var(--bb-text-muted);
 }
 .bb-badge.bb-badge--soft-blue {
-	--accent: #2563eb;
+	--accent: var(--bb-info);
 }
 .bb-badge.bb-badge--soft-green {
-	--accent: #16a34a;
+	--accent: var(--bb-success);
 }
 .bb-badge.bb-badge--soft-amber {
-	--accent: #d97706;
+	--accent: var(--bb-warn);
 }
 .bb-badge.bb-badge--soft-red {
-	--accent: #dc2626;
+	--accent: var(--bb-danger);
 }
 
 .bb-badge.bb-badge--soft-gray,
@@ -650,12 +650,12 @@ and the clear control be independent controls:
 		<!-- <button>/<a> in button mode -->
 		<svg class="bb-badge__prepend-icon" />
 		<!-- or __icon / BbSpinner -->
-		<span class="bb-badge__content">label</span>
+		<span class="bb-badge__text">label</span>
 	</span>
 	<span class="bb-badge__trailing">
 		<!-- only when needed -->
 		<svg class="bb-badge__append-icon" />
-		<button class="bb-badge__clear-button">…</button>
+		<button class="bb-badge__clear">…</button>
 	</span>
 </span>
 ```
@@ -669,7 +669,7 @@ Focus is always ringed on the **whole pill** (never on the inner control), for
 the body and the clear button alike; the clear button additionally lights its
 glyph. The class hooks above are the supported styling surface —
 `.bb-badge__body` and `.bb-badge__trailing` are new, so avoid direct-child
-selectors like `.bb-badge > .bb-badge__content`, which no longer match.
+selectors like `.bb-badge > .bb-badge__text`, which no longer match.
 
 ### Restyling with passthrough
 
@@ -767,13 +767,13 @@ const endpoints: Endpoint[] = [
      Non-scoped so variant classes on the child badge receive the accents. -->
 <style>
 .bb-badge.bb-badge--soft-blue {
-	--accent: #2563eb;
+	--accent: var(--bb-info);
 }
 .bb-badge.bb-badge--soft-green {
-	--accent: #16a34a;
+	--accent: var(--bb-success);
 }
 .bb-badge.bb-badge--soft-red {
-	--accent: #dc2626;
+	--accent: var(--bb-danger);
 }
 .bb-badge.bb-badge--soft-blue,
 .bb-badge.bb-badge--soft-green,
@@ -874,7 +874,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Events
 
-- `click:clear` — `(event: "click:clear", event: MouseEvent): void`
+- `click:clear` — `(event: MouseEvent): void` — Emitted when the clear button is pressed (only rendered when `clearable`).
 
 ## Slots
 
@@ -892,11 +892,11 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-color` | `.bb-badge` | `transparent` |  |
 | `--ring-color` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring colour, per variant |
 | `--ring-size` | `.bb-badge` | `var(--bb-ring-size)` | focus ring width |
-| `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
+| `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 14px)` | 18px at the default |
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
+| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 2px)` | 12px at the default (Q49.25) |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
 | `--px` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
@@ -914,7 +914,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbBadge`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbBadge`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbBadge` _(this component)_ — its own template binds: `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`
+- `BbBadge` _(this component)_ — its own template binds: `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`
   - Also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
 
 ## See Also

package/dist/ai/BbBadgeButton.md

@@ -88,11 +88,11 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-color` | `.bb-badge` | `transparent` |  |
 | `--ring-color` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring colour, per variant |
 | `--ring-size` | `.bb-badge` | `var(--bb-ring-size)` | focus ring width |
-| `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
+| `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 14px)` | 18px at the default |
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
+| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 2px)` | 12px at the default (Q49.25) |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
 | `--px` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |

package/dist/ai/BbBreadcrumbs.md

@@ -157,6 +157,13 @@ visible. Hidden crumbs keep their full navigation target inside the menu, so
 nothing becomes unreachable. Just pass the full `items` array and let the
 component measure — narrow the frame below to watch it collapse.
 
+**The current page never folds.** When not even it fits beside the `…`, every
+other crumb goes into the menu and the current page stays, its label truncated
+with an ellipsis (the full text in a tooltip and to assistive tech). That is the
+floor: in a very narrow toolbar the trail reads `… / Quarterly rev…`. If that is
+too little, give the trail its own full-width row, or shorten the last label
+(`text` is yours).
+
 **Overflow folds into an ellipsis menu**
 
 ```vue
@@ -722,13 +729,13 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `BbBreadcrumbs` _(this component)_ — its own template binds: `item` → `li.bb-breadcrumbs__item`, `icon` → `BbIcon`, `text` → `span.bb-breadcrumbs__text`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
-  - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__items-container`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
+  - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
     - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbBaseButton`, `BbIcon`, `CommonPopover`, `BbDropdownList`
-      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
+      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
     - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
-      - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
+      - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
         - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
-      - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbBaseButton`, `BbSpinner`
+      - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbBaseButton`, `BbSpinner`
   - Also mounts `BbIcon`
 
 ## See Also

package/dist/ai/BbButton.md

@@ -56,8 +56,11 @@ Start with the built-in ladder: `primary`, `secondary`, `outline`, `ghost`,
 everything else is `secondary`, `outline` or `ghost`. Reserve `destructive` for
 irreversible actions (and gate them behind `useConfirm`). `link` is navigation
 disguised as text — pair it with `href`/`to`, not with heavy actions.
-`variant="none"` renders structure with no variant styling — an escape hatch,
-avoid it.
+`variant="none"` is a blank starting point: the button keeps its structure,
+behaviour and accessibility but takes no look, so your own classes don't have
+to fight a built-in one. You then own hover, focus and disabled. It is fine for
+a one-off; keep the inline styling short, and when the same look shows up
+again, register it as a real variant instead.
 
 **`link` changes color, not layout.** It keeps the button box: the size scale's
 height and horizontal padding still apply, so it occupies button space and never
@@ -994,7 +997,7 @@ Gotchas (real behavior, verified against source):
 
 - A `v-model` bound to an undefined value is not a toggle yet — the first click
   won't set it. Seed the model.
-- Every default-slot child lands inside one `.bb-button__content` span, so
+- Every default-slot child lands inside one `.bb-button__text` span, so
   sibling elements sit inline with no gap and the button's own flex layout
   cannot space them — `class="justify-between"` on the button reaches the
   content span, not its children, and `Label` + `142` renders as `Label142`.
@@ -1058,7 +1061,7 @@ Anti-patterns:
 | `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` |  |  |  |
+| `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
 | `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async click handlers (enabled by default). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component: native `disabled` (or `aria-disabled` on a link), muted paint. Beside `loading`, loading wins the look (spinner and variant colours) and this only adds the native blocking — redundant but harmless. |
 | `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… |
@@ -1067,32 +1070,32 @@ Anti-patterns:
 | `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` | `false` |  | Identifies the button as part of a button group. |
-| `headers` | `object \| undefined` |  |  |  |
+| `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `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` | `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. A loading button is soft-disabled on its own (`aria-disabled`, out of the tab order, clicks and navigation blocked) and keeps its variant colours; with `disabled` set too, loading still wins the look. |
-| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  |  |
-| `modelValue` | `any` |  |  |  |
-| `onBefore` | `(() => void) \| undefined` |  |  |  |
-| `onCancel` | `(() => void) \| undefined` |  |  |  |
-| `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  |  |
+| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
+| `modelValue` | `any` |  |  | Makes the button a toggle: clicking flips the model between `trueValue` and `falseValue`, and the button reports `aria-pressed`. Leave it unbound for a plain button. |
+| `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. |
+| `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
 | `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request… |
-| `onFinish` | `(() => void) \| undefined` |  |  |  |
-| `only` | `string[] \| undefined` |  |  |  |
+| `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
+| `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
 | `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
 | `onPrefetching` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link starts. |
-| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  |  |
-| `onStart` | `(() => void) \| undefined` |  |  |  |
-| `onSuccess` | `(() => void) \| undefined` |  |  |  |
+| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
+| `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
+| `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'`). |
 | `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` |  |  |  |
+| `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` |  |  |  |
+| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `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` | `'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… |
@@ -1101,7 +1104,7 @@ Anti-patterns:
 | `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. |
+| `variant` | `ButtonVariantType \| undefined` | `"primary"` |  | Visual variant of the button. Controls colors and surface style while keeping spacing and sizing unchanged. `'none'` is a blank starting point: the button keeps its structure and behaviour but takes no look, so your own classes don't fight … |
 | `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Passthrough parts and states
@@ -1124,7 +1127,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Events
 
-- `update:modelValue` — `(event: "update:modelValue", value: any): void`
+- `update:modelValue` — `(value: any): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots
 
@@ -1206,7 +1209,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbButton`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbButton`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbButton` _(this component)_ — its own template binds: `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`
+- `BbButton` _(this component)_ — its own template binds: `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - Also mounts `BbIcon`, `BbSpinner`
 

package/dist/ai/BbCalendar.md

@@ -17,6 +17,9 @@
 | `pt:arrow` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
 | `pt:month` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
 | `pt:year` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
+| `pt:header` | `div.bb-time-selector__header` | `CommonTimeSelector` _(internal)_ |
+| `pt:cellColumnHeader` | `div.bb-time-selector__cell-column-header` | `CommonTimeSelector` _(internal)_ |
+| `pt:item` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
 
 ## Usage & Guidelines
 
@@ -470,7 +473,7 @@ and attributes — optionally only while a state is on. Parts: `root` (the
 calendar's box, where a consumer `class` lands too; it carries the sizing
 tokens, so `pt:root="[--px:2px]"` tightens the padding and the grid width
 follows), `header` (the navigation bar), `arrow` (the previous / next
-buttons), `month` and `year` (the heading buttons), `columnHeader` (each
+buttons), `month` and `year` (the heading buttons), `cellColumnHeader` (each
 weekday letter), `day` (one whole day cell) and `dayButton` (the button
 inside it), `monthItem` and `yearItem` (one button of the month / year
 panel).
@@ -485,7 +488,11 @@ open. The cells resolve per node — on `day` and `dayButton`: `selected`,
 
 `day` is the whole cell and `dayButton` the rounded mark inside it: a
 background on `pt:day` paints the full cell square, so restyle the mark on
-`pt:day-button`. The time rail is not a part.
+`pt:day-button`. With `type="datetime"` the time rail takes the same words
+as `BbTimePicker`: `item` is one entry (`selected`, and `disabled` outside the
+bound's time on the day `min` / `max` falls on), and `header` /
+`cellColumnHeader` land on its readout and column letters too — one
+`pt:header` styles the navigation bar and the readout together.
 
 ```vue
 <BbCalendar
@@ -522,14 +529,14 @@ the page is `BbDatePicker`.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `arrow`, `columnHeader`, `day`, `dayButton`, `header`, `month`, `monthItem`, `root`, `year`, `yearItem`. States: `active`, `disabled`, `highlighted`, `inRange`, `outside`, `rangeEnd`, `rangeStart`, `selected`, `today`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `arrow`, `cellColumnHeader`, `day`, `dayButton`, `header`, `item`, `month`, `monthItem`, `root`, `year`, `yearItem`. States: `active`, `disabled`, `highlighted`, `inRange`, `outside`, `rangeEnd`, `rangeStart`, `selected`, `today`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `activeSegment` | `BbCalendarSegment \| undefined` |  |  | Which end the time rail edits in range + `type="datetime"` (`v-model:active-segment`). Standalone use manages this internally; an embedding host (the date input) drives it from its focused field. Ignored outside range + datetime. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables every cell, the navigation and the time rail. |
 | `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | First day of the week (0 = Sunday … 6 = Saturday). |
 | `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
-| `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. |
-| `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. |
+| `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. With `datetime`, on its own day the time rail disables the times after it. |
+| `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. With `datetime`, the grid d… |
 | `modelValue` | `string \| string[] \| null` |  | yes | v-model value. `null` for empty, a single string for single selection, or a two-element `[start, end]` array when `range` is true (a sorted array under `multiple`). The string shape follows `type`: `YYYY-MM-DD` when `floating` (`YYYY-MM` fo… |
 | `multiple` | `boolean \| undefined` | `false` |  | Enables multi-selection: every pick toggles a value in or out of a sorted array. Works in whatever `type` selects — days, months or years — and requires an array `modelValue` (use `[]` for empty, never `null`). Mutually exclusive with `rang… |
 | `range` | `boolean \| undefined` | `false` |  | Enables range selection (`[start, end]`). |
@@ -552,11 +559,12 @@ the page is `BbDatePicker`.
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
 | `year` | The year heading button; it opens the year panel. |
-| `columnHeader` | Each weekday letter above the grid — a broadcast. |
+| `cellColumnHeader` | Each weekday letter above the grid — a broadcast. |
 | `day` | One whole day cell — a broadcast resolved per day. A background here paints the full cell square; restyle the round mark on `dayButton`. |
 | `dayButton` | The button inside a day cell — the mark that shows selection. A broadcast resolved per day. |
 | `monthItem` | One month button of the month panel (the home grid of `type="month"`) — a broadcast resolved per month. |
 | `yearItem` | One year button of the year list — a broadcast resolved per year. |
+| `item` | One entry of the time rail's columns (hour, minute, second, AM / PM) with `type="datetime"` — a broadcast resolved per entry, as on `BbTimePicker`. With the rail, `header` also lands on its readout and `cellColumnHeader` on its column letters (`HH`, `MM`). |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
 
@@ -565,20 +573,20 @@ States are listed in precedence order: when two are on at once and their entries
 | `outside` | Per node, on `day` / `dayButton`: a day of the previous or next month, shown to fill the grid. |
 | `today` | Per node, on `day` / `dayButton`: today. |
 | `inRange` | Per node, on the cells (`day`, `dayButton`, `monthItem`, `yearItem`): inside a committed range, between its ends. |
-| `selected` | Per node, on the cells: a chosen day, month or year. |
+| `selected` | Per node, on the cells: a chosen day, month or year; on `item`, the picked time's entry in each column. |
 | `rangeStart` | Per node, on the cells: a committed range's first day, month or year. |
 | `rangeEnd` | Per node, on the cells: a committed range's last day, month or year. |
-| `disabled` | Component-wide while the calendar is `disabled`. Also per node: on the cells, one outside `min` / `max` or refused by `selectable`; on `arrow`, at a bound or while the month / year panel is open. |
+| `disabled` | Component-wide while the calendar is `disabled`. Also per node: on the cells, one outside `min` / `max` or refused by `selectable`; on `arrow`, at a bound or while the month / year panel is open; on `item`, a time entry outside the bound's time on the day `min` / `max` falls on. |
 | `active` | Per node, on `month` / `year`: its panel is open. |
 | `highlighted` | Per node, on the cells: the keyboard cursor. |
 
 ## Events
 
-- `grid-pick` — `(event: "grid-pick", value: string \| string[] \| null): void`
-- `time-pick` — `(event: "time-pick", payload: { unit: TimeUnit; value: string; }): void`
-- `update:activeSegment` — `(event: "update:activeSegment", value: BbCalendarSegment): void`
-- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
-- `update:time` — `(event: "update:time", value: string \| string[] \| null): void`
+- `grid-pick` — `(value: string \| string[] \| null): void` — Relay of the raw grid pick, before this component combines it with the time. An embedding host binds this to run its own value engine (the date picker closes on it once the selection is complete); clean consumers ignore it and use `update:m…
+- `time-pick` — `(payload: { unit: TimeUnit; value: string; }): void` — Relay of the raw time-rail pick. An embedding host binds this to run its own value engine; clean consumers ignore it and use `update:time`.
+- `update:activeSegment` — `(value: BbCalendarSegment): void` — The active range end changed (range + `type="datetime"` only).
+- `update:modelValue` — `(value: string \| string[] \| null): void` — Emitted when the selected value changes (single / range / multiple / null).
+- `update:time` — `(value: string \| string[] \| null): void` — Companion time model, alongside every change while `type="datetime"`.
 
 ## Slots
 
@@ -611,9 +619,9 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbCalendar`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbCalendar`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbCalendar` _(this component)_ — its own template binds: `header` → `div.bb-calendar__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__date`, `dayButton` → `button.bb-calendar__date-button`
+- `BbCalendar` _(this component)_ — its own template binds: `header` → `div.bb-calendar__header`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
-  - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
+  - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — `BbCalendar`'s pt parts land here: `header` → `div.bb-time-selector__header`, `cellColumnHeader` → `div.bb-time-selector__cell-column-header`, `item` → `BbBaseButton`; documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
   - Also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`
 
 ## See Also

package/dist/ai/BbCheckbox.md

@@ -18,9 +18,8 @@
 | `pt:root` | `div.bb-field` | `CommonField` _(internal)_ |
 | `pt:label` | `component` | `CommonField` _(internal)_ |
 | `pt:description` | `span.bb-field__description` | `CommonField` _(internal)_ |
-| `pt:hint` | `span.bb-field__hint-text` | `CommonField` _(internal)_ |
-| `pt:message` | `div.bb-field__errors` | `CommonField` _(internal)_ |
-| `pt:message` | `div.bb-field__warnings` | `CommonField` _(internal)_ |
+| `pt:hint` | `span.bb-field__hint` | `CommonField` _(internal)_ |
+| `pt:message` | `div.bb-field__message` | `CommonField` _(internal)_ |
 
 **CSS variables you can set through those parts** — declared deeper in the tree, so set one on the part that reads it (`pt:<part>="[--name:value]"`), never on `BbCheckbox`'s root:
 
@@ -684,7 +683,7 @@ map are in the [passthrough guide](./guides/passthrough.md).
 | `hasWarnings` | `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. |
+| `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
 | `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. |
@@ -728,15 +727,15 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Events
 
-- `blur` — `(event: "blur", event: FocusEvent): void`
-- `change` — `(event: "change", event: Event): void`
-- `click` — `(event: "click", event: MouseEvent): void`
-- `focus` — `(event: "focus", event: FocusEvent): void`
-- `input` — `(event: "input", event: Event): void`
-- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
-- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
-- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
-- `update:modelValue` — `(event: "update:modelValue", value: any): void`
+- `blur` — `(event: FocusEvent): void` — Emitted when the native input loses focus. Forwards the original DOM `FocusEvent`.
+- `change` — `(event: Event): void` — Emitted when the checkbox checked state changes. Forwards the original DOM `Event` from the input.
+- `click` — `(event: MouseEvent): void` — Emitted when the input receives a click interaction. Forwards the original DOM `MouseEvent`.
+- `focus` — `(event: FocusEvent): void` — Emitted when the native input gains focus. Forwards the original DOM `FocusEvent`.
+- `input` — `(event: Event): void` — Emitted on native input events from the checkbox input. Forwards the original DOM `Event`.
+- `keydown` — `(event: KeyboardEvent): void` — Emitted for keyboard interaction on the input. Forwards the original DOM `KeyboardEvent`.
+- `mousedown` — `(event: MouseEvent): void` — Emitted when a pointing device button is pressed over the input. Forwards the original DOM `MouseEvent`.
+- `mouseup` — `(event: MouseEvent): void` — Emitted when a pointing device button is released over the input. Forwards the original DOM `MouseEvent`.
+- `update:modelValue` — `(value: any): void` — Emitted on checked-state changes with the effective model value: - `trueValue` when checked - `falseValue` when unchecked
 
 ## Slots
 
@@ -764,7 +763,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 - Listed nodes are the ones `BbCheckbox`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
 - `BbCheckbox` _(this component)_ — its own template binds: `icon` → `BbBaseCheckboxIcon`
-  - `CommonField` _(internal — not importable, reach it through `BbCheckbox`)_ — `BbCheckbox`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint-text`, `message` → `div.bb-field__errors`, `message` → `div.bb-field__warnings`
+  - `CommonField` _(internal — not importable, reach it through `BbCheckbox`)_ — `BbCheckbox`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`
   - Also mounts `BbBaseCheckboxIcon`
 
 ## See Also