bitboss-ui 3.0.0-beta.47 → 3.0.0-beta.49

package/dist/ai/BbBreadcrumbs.md

@@ -36,9 +36,9 @@ use `BbPagination`. Show at most one breadcrumb trail per view.
 
 ### Build the trail from `items`
 
-Each item is `{ key, text }` plus a navigation target. `key` must be unique (it
-also becomes the crumb's named-slot name and the label fallback when `text` is
-missing). Navigation is always the item's job — give a crumb an `href` (or
+Each item is `{ label, value }` plus a navigation target. `label` is the
+crumb's text; `value` is optional and, when set, must be unique (it names the
+crumb's own slots). Navigation is always the item's job — give a crumb an `href` (or
 `to`, or an `onClick`) and it renders as a real link; **never** wrap a crumb in
 your own click-to-route handler. Leave the **last** item without a target: a
 last crumb with no target is the current page, and the component marks it
@@ -51,10 +51,10 @@ it) never marks the parent current.
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'dashboard', text: 'Dashboard', href: '#dashboard' },
-		{ key: 'billing', text: 'Billing', href: '#billing' },
-		{ key: 'invoices', text: 'Invoices', href: '#invoices' },
-		{ key: 'invoice', text: 'Invoice #1042' },
+		{ value: 'dashboard', label: 'Dashboard', href: '#dashboard' },
+		{ value: 'billing', label: 'Billing', href: '#billing' },
+		{ value: 'invoices', label: 'Invoices', href: '#invoices' },
+		{ value: 'invoice', label: 'Invoice #1042' },
 	]"
 />
 ```
@@ -124,20 +124,20 @@ import type { BbBreadcrumbsItem } from 'bitboss-ui';
 // crumb is a real link; the current page stays without a target.
 const trail: BbBreadcrumbsItem[] = [
 	{
-		key: 'settings',
-		text: 'Settings',
+		value: 'settings',
+		label: 'Settings',
 		href: '#settings',
 		'prepend:icon': 'lucide:settings',
 	},
 	{
-		key: 'team',
-		text: 'Team',
+		value: 'team',
+		label: 'Team',
 		href: '#team',
 		'prepend:icon': 'lucide:users',
 	},
 	{
-		key: 'members',
-		text: 'Members',
+		value: 'members',
+		label: 'Members',
 		'prepend:icon': 'lucide:user-round',
 	},
 ];
@@ -164,7 +164,7 @@ 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).
+(`label` is yours).
 
 **Overflow folds into an ellipsis menu**
 
@@ -172,12 +172,12 @@ too little, give the trail its own full-width row, or shorten the last label
 <div class="max-w-xs">
 	<BbBreadcrumbs
 		:items="[
-			{ key: 'workspace', text: 'Workspace', href: '#workspace' },
-			{ key: 'engineering', text: 'Engineering', href: '#engineering' },
-			{ key: 'frontend', text: 'Frontend', href: '#frontend' },
-			{ key: 'design-system', text: 'Design System', href: '#design-system' },
-			{ key: 'components', text: 'Components', href: '#components' },
-			{ key: 'breadcrumbs', text: 'Breadcrumbs' },
+			{ value: 'workspace', label: 'Workspace', href: '#workspace' },
+			{ value: 'engineering', label: 'Engineering', href: '#engineering' },
+			{ value: 'frontend', label: 'Frontend', href: '#frontend' },
+			{ value: 'design-system', label: 'Design System', href: '#design-system' },
+			{ value: 'components', label: 'Components', href: '#components' },
+			{ value: 'breadcrumbs', label: 'Breadcrumbs' },
 		]"
 	/>
 </div>
@@ -250,8 +250,8 @@ When slot (or icon) content adds width the estimator cannot see, set
 <BbBreadcrumbs
 	:offset-width="96"
 	:items="[
-		{ key: 'settings', text: 'Settings', href: '#settings' },
-		{ key: 'notifications', text: 'Notifications' },
+		{ value: 'settings', label: 'Settings', href: '#settings' },
+		{ value: 'notifications', label: 'Notifications' },
 	]"
 >
 	<template #prepend>
@@ -260,7 +260,7 @@ When slot (or icon) content adds width the estimator cannot see, set
 	<template #item:prepend="{ item }">
 		<BbIcon
 			class="mr-1"
-			:icon="item.key === 'settings' ? 'lucide:settings' : 'lucide:bell'"
+			:icon="item.value === 'settings' ? 'lucide:settings' : 'lucide:bell'"
 			size="14"
 		/>
 	</template>
@@ -310,10 +310,10 @@ import type { BbBreadcrumbsItem } from 'bitboss-ui';
 // File-view header: trail says where you are; compact `append` actions act on
 // the file. Declare their width with `offset-width` so overflow stays honest.
 const items: BbBreadcrumbsItem[] = [
-	{ key: 'repo', text: 'acme-ui', href: '#repo' },
-	{ key: 'src', text: 'src', href: '#src' },
-	{ key: 'components', text: 'components', href: '#components' },
-	{ key: 'button', text: 'Button.tsx' },
+	{ value: 'repo', label: 'acme-ui', href: '#repo' },
+	{ value: 'src', label: 'src', href: '#src' },
+	{ value: 'components', label: 'components', href: '#components' },
+	{ value: 'button', label: 'Button.tsx' },
 ];
 
 const copied = ref(false);
@@ -330,17 +330,17 @@ const onCopyPath = () => {
 
 ### Own one crumb's label with its named slot
 
-Every item also gets a slot named after its `key`, replacing that crumb's
-default text (same scope as `item:prepend`). Use it when a single crumb needs
-richer content — a status dot on the current record, a badge on one level —
-while the rest of the trail stays plain. A crumb's `key` is optional unless
-it has a slot of its own — a keyless crumb renders with the generic `item:*`
-slots and its text, and its slot name is never derived from the text (a label
-changes with translation; a slot name must not). The slot name is the key through
+Every item with a `value` also gets a slot named after it, replacing that
+crumb's default label (same scope as `item:prepend`). Use it when a single crumb
+needs richer content — a status dot on the current record, a badge on one level —
+while the rest of the trail stays plain. A crumb's `value` is optional unless
+it has a slot of its own — a crumb without one renders with the generic `item:*`
+slots and its label, and its slot name is never derived from the label (a label
+changes with translation; a slot name must not). The slot name is the value through
 `slotKey`, which is kebab-case — `'Order History'` → `#order-history`,
 `'orderHistory'` → `#order-history`, `'order_history'` → `#order-history`; for
-a key with accents or other scripts write `#[slotKey('Qualità')]` (`import {
-slotKey } from 'bitboss-ui'`). Because keys become slot names, a key spelled
+a value with accents or other scripts write `#[slotKey('Qualità')]` (`import {
+slotKey } from 'bitboss-ui'`). Because values become slot names, a value spelled
 like a reserved slot (`prepend`, `append`, `divider`, `ellipsis`, `item`) is an
 error: `bitboss-ui check` flags it when `items` is in the same file.
 
@@ -349,16 +349,16 @@ error: `bitboss-ui check` flags it when `items` is in the same file.
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'deployments', text: 'Deployments', href: '#deployments' },
-		{ key: 'release', text: 'v2.4.0' },
+		{ value: 'deployments', label: 'Deployments', href: '#deployments' },
+		{ value: 'release', label: 'v2.4.0' },
 	]"
 >
-	<template #release="{ text }">
+	<template #release="{ label }">
 		<span class="inline-flex items-center gap-1.5">
 			<span
 				class="size-2 rounded-full bg-(--bb-primary)"
 			></span>
-			{{ text }}
+			{{ label }}
 		</span>
 	</template>
 </BbBreadcrumbs>
@@ -380,10 +380,10 @@ wider than `…`, pair it with `ellipsis-width`.
 	<BbBreadcrumbs
 		:ellipsis-width="40"
 		:items="[
-			{ key: 'library', text: 'Library', href: '#library' },
-			{ key: 'photos', text: 'Photos', href: '#photos' },
-			{ key: 'albums', text: 'Albums', href: '#albums' },
-			{ key: 'summer', text: 'Summer 2026' },
+			{ value: 'library', label: 'Library', href: '#library' },
+			{ value: 'photos', label: 'Photos', href: '#photos' },
+			{ value: 'albums', label: 'Albums', href: '#albums' },
+			{ value: 'summer', label: 'Summer 2026' },
 		]"
 	>
 		<template #divider>
@@ -482,8 +482,8 @@ const items = computed<BbBreadcrumbsItem[]>(() =>
 	path.value.map((name, index) => {
 		const isCurrent = index === path.value.length - 1;
 		return {
-			key: `${index}-${name}`,
-			text: name,
+			value: `${index}-${name}`,
+			label: name,
 			'prepend:icon': 'lucide:folder',
 			...(isCurrent
 				? {}
@@ -507,9 +507,9 @@ active-class props are wired for you:
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'home', text: 'Home', to: { name: 'index' } },
-		{ key: 'team', text: 'Team', to: '/team' },
-		{ key: 'member', text: 'Ada Lovelace' },
+		{ value: 'home', label: 'Home', to: { name: 'index' } },
+		{ value: 'team', label: 'Team', to: '/team' },
+		{ value: 'member', label: 'Ada Lovelace' },
 	]"
 />
 ```
@@ -521,9 +521,9 @@ visit:
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
-		{ key: 'orders', text: 'Orders', href: '/orders', preserveScroll: true },
-		{ key: 'order', text: 'Order #8842' },
+		{ value: 'dashboard', label: 'Dashboard', href: '/dashboard' },
+		{ value: 'orders', label: 'Orders', href: '/orders', preserveScroll: true },
+		{ value: 'order', label: 'Order #8842' },
 	]"
 />
 ```
@@ -597,20 +597,20 @@ import type { BbBreadcrumbsItem } from 'bitboss-ui';
 
 const trail: BbBreadcrumbsItem[] = [
 	{
-		key: 'settings',
-		text: 'Settings',
+		value: 'settings',
+		label: 'Settings',
 		href: '#settings',
 		'prepend:icon': 'lucide:settings',
 	},
 	{
-		key: 'team',
-		text: 'Team',
+		value: 'team',
+		label: 'Team',
 		href: '#team',
 		'prepend:icon': 'lucide:users',
 	},
 	{
-		key: 'members',
-		text: 'Members',
+		value: 'members',
+		label: 'Members',
 		'prepend:icon': 'lucide:user-round',
 	},
 ];
@@ -682,7 +682,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   when its URL is the page you are on. Do not link the page the user is
   already on.
 - The overflow button is a real `button` with a localized, count-aware label
-  ("Show N hidden breadcrumbs"); its menu is a `BbDropdown` with full keyboard
+  ("Show hidden breadcrumbs (N)"); its menu is a `BbDropdown` with full keyboard
   support — nothing to add on your side.
 - The dividers are decorative (`aria-hidden`); never encode meaning in them.
 - `disabled` on the component (or an item) removes `href` and exposes
@@ -728,12 +728,12 @@ States are listed in precedence order: when two are on at once and their entries
 - `append` — scope: `BbBreadcrumbsEdgeSlotProps` `{ disabled?: boolean }` — Content rendered after the breadcrumb list, in a dedicated append region.
 - `divider` — scope: `Record<string, never>` — Replaces the default separator rendered between breadcrumb items.
 - `ellipsis` — scope: `BbBreadcrumbsEllipsisSlotProps` `{ props: { ref: (reference: unknown) => void; }; disabled?: boolean; overflowCount: number; ellipsisWidth: number }` — Replaces the default `…` overflow button shown when items overflow.
-- `item:append` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; text?: string }` — Content rendered after **every** breadcrumb item's link/button. Generic fallback below a per-item `<key>:append` slot and above the item's `append:icon`.
-- `item:prepend` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; text?: string }` — Content rendered before **every** breadcrumb item's link/button, in the leading edge region. Generic fallback: a per-item `<key>:prepend` slot takes precedence, and the item's `prepend:icon` is used when neither slot is present.
+- `item:append` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; label?: string }` — Content rendered after **every** breadcrumb item's link/button. Generic fallback below a per-item `<value>:append` slot and above the item's `append:icon`.
+- `item:prepend` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; label?: string }` — Content rendered before **every** breadcrumb item's link/button, in the leading edge region. Generic fallback: a per-item `<value>:prepend` slot takes precedence, and the item's `prepend:icon` is used when neither slot is present.
 - `prepend` — scope: `BbBreadcrumbsEdgeSlotProps` `{ disabled?: boolean }` — Content rendered before the breadcrumb list, in a dedicated prepend region.
-- `#<key>` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — One crumb's label, by its `key` through `slotKey`; falls back to `item.text`. A crumb folded into the overflow menu follows BbDropdown's slot rules instead. Reserved keys (their slot is one of this component's own, so a key spelled like them is an error): `append`, `divider`, `ellipsis`, `item`, `prepend`.
-- `#<key>:prepend` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph before one crumb's label; beats `item:prepend`, which beats its `prepend:icon`.
-- `#<key>:append` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph after one crumb's label; beats `item:append`, which beats its `append:icon`.
+- `#<value>` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — One crumb's label, by its `value` through `slotKey`; falls back to `item.label`. A crumb folded into the overflow menu follows BbDropdown's slot rules instead (the same `#<value>` names). Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `append`, `divider`, `ellipsis`, `item`, `prepend`.
+- `#<value>:prepend` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph before one crumb's label; beats `item:prepend`, which beats its `prepend:icon`.
+- `#<value>:append` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph after one crumb's label; beats `item:append`, which beats its `append:icon`.
 
 ## Component tree
 
@@ -747,7 +747,7 @@ 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__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`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
+    - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
       - `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`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--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__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`

package/dist/ai/BbButton.md

@@ -410,9 +410,15 @@ live example below uses this shape). The mistake above only becomes possible
 once that loop is unrolled into separate elements with their own literal
 strings.
 
-Add `group` to fuse adjacent buttons into one visual segment control. It is
-purely visual (shared borders/radius between siblings) — each button keeps its
-own semantics, and there is no arrow-key roving between them.
+Add `group` to fuse adjacent buttons into one visual segment control (shared
+borders and radius between siblings). Each button keeps its own semantics: a
+toggle still announces as a toggle button with its pressed state. Adjacent
+`group` **toggles** are also one Tab stop: Tab lands on the pressed button (or
+the one last focused, or the first), ArrowLeft / ArrowRight move between the
+buttons (mirrored under `dir="rtl"`, wrapping at the ends), Home / End jump to
+the first / last, and Space / Enter toggle. Disabled and loading buttons are
+skipped. Any other element between two buttons splits them into two sets, and
+`group` buttons without a `v-model` keep one Tab stop each.
 
 **Exclusive toggle groups**
 
@@ -494,6 +500,11 @@ const activeView = ref<IssueView>('list');
 </script>
 ```
 
+A toggle that is on carries `aria-pressed="true"` and the class
+`bb-button--pressed`. Restyle that state with `pt:root:pressed` (or
+`pt:icon:pressed`, `pt:text:pressed`), not with a selector of your own: it is
+the state's contract.
+
 Listen to `update:modelValue` only if you need side effects; state itself is
 handled. For form-ish multi-selection prefer `BbCheckboxGroup` /
 `BbRadioGroup`; toggle buttons are for immediate, tool-bar-like state.
@@ -835,8 +846,11 @@ label span). Typography inherits from `root`, so reach for `text` only when a
 class must apply to the label ALONE — `truncate` on a long label that must not
 clip the icons beside it. That span also carries the margin the label slides by
 while the spinner is in, so a margin of your own fights the slide. States:
-`loading`, `disabled`. A name outside that list is a type error and an ESLint
-error.
+`loading`, `disabled`, `pressed` (a `v-model` toggle that is on). A name
+outside that list is a type error and an ESLint error. There is no `active`
+state: a pointer press is Tailwind's `active:` variant (`pt:root="active:scale-95"`).
+There is no `current` state either: a link to the current route is
+`active-class` / `exact-active-class` (see Active state above).
 
 **pt: a part, a part while loading, the object form**
 
@@ -1043,7 +1057,10 @@ Gotchas (real behavior, verified against source):
   attribute and drops yours. A hand-rolled toggle (`:aria-pressed` plus a
   `variant` swap) therefore looks right and is invisible to assistive tech.
   Use `v-model` — see [Toggle buttons](#toggle-buttons). Dev builds warn.
-- `group` fuses looks only; it adds no radio semantics or arrow-key navigation.
+- `group` adds no radio semantics: an exclusive set is still toggle buttons
+  with `aria-pressed`. Adjacent `group` toggles share one Tab stop and move
+  with the arrow keys (see [Toggle buttons](#toggle-buttons)); keep a set's
+  buttons side by side in one parent, since anything between them splits it.
 - Responsive `size` maps change height/font/gap per breakpoint; padding, icon
   size and radius follow the `default` entry.
 - Auto-loading tracks the promise **returned** from `@click`; a handler that
@@ -1072,6 +1089,8 @@ Anti-patterns:
   report one as an error.
 - Toggles expose `aria-pressed` (`true`/`false`) automatically — never add your
   own.
+- A set of adjacent `group` toggles is one Tab stop (roving `tabindex`), with
+  ArrowLeft / ArrowRight / Home / End inside it — the APG toolbar pattern.
 - While loading: `aria-disabled="true"`, `tabindex="-1"`, and a localized
   visually-hidden loading announcement.
 - Disabled links render with `role="link"`, `aria-disabled="true"`, no `href`,
@@ -1090,7 +1109,7 @@ Anti-patterns:
 
 | 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: `icon`, `root`, `spinner`, `text`. States: `disabled`, `loading`. 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`. In `<script>` a `pt` value is typed `BbButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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: `icon`, `root`, `spinner`, `text`. States: `disabled`, `loading`, `pressed`. 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`. In `<script>` a `pt` value is typed `BbButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
 | `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
@@ -1107,7 +1126,7 @@ Anti-patterns:
 | `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` | `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. |
+| `group` | `boolean \| undefined` | `false` |  | Identifies the button as part of a button group: adjacent `group` buttons fuse into one segment (shared borders and radius). Adjacent `group` toggles (each with a `v-model`) are also one Tab stop, with ArrowLeft / ArrowRight / Home / End moving between them. |
 | `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. |
@@ -1160,6 +1179,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `pressed` | Component-wide: a toggle button (`v-model`) is on — `aria-pressed="true"`, `--pressed` on the root. |
 | `disabled` | Component-wide: the button is `disabled`. |
 | `loading` | Component-wide: `loading` is on — the spinner shows and the button ignores the pointer. |
 

package/dist/ai/BbCheckbox.md

@@ -447,8 +447,6 @@ for the children.
 				v-model="granted"
 				class="pl-5"
 				hide-legend
-				item-text="label"
-				item-value="value"
 				:items="scopes"
 				legend="Scopes"
 				name="scope-list"

package/dist/ai/BbCheckboxGroup.md

@@ -58,18 +58,14 @@ Reach elsewhere when the shape differs:
 
 ### Items are your domain objects
 
-**Object items need `item-text`.** Without it each label is
-`JSON.stringify(item)`, and without `item-value` the whole object is the value.
-`{ label, value }` items take both:
+**`{ label, value }` and `{ text, value }` items work as they are; any other
+shape needs `item-text` / `item-value`.** With neither prop an option reads its
+own `label` (else its own `text`) and its own `value`, whatever it holds (`null`
+included). An object with none of those fields falls back to
+`JSON.stringify(item)` as text and the whole object as value.
 
 ```vue
-<BbCheckboxGroup
-	v-model="plans"
-	legend="Plans"
-	:items="options"
-	item-text="label"
-	item-value="value"
-/>
+<BbCheckboxGroup v-model="plans" legend="Plans" :items="options" />
 ```
 
 Pass backend rows straight to `items` and select the display text and stored
@@ -92,7 +88,6 @@ mapped (here, channel ids), which is what you send back to the server.
 			v-model="selected"
 			compact
 			hint="Choose one or more channels."
-			item-text="label"
 			item-value="id"
 			:items="channels"
 			legend="Channels"
@@ -141,7 +136,8 @@ Two items that resolve to the **same** `item-value` collapse to one option
 
 #### Additional row fields: `item-props`
 
-`item-text` and `item-value` are the option's label and identity. Anything
+The option's text and value (from `item-text` / `item-value`, or the item's own
+`label` and `value`) are its label and identity. Anything
 **additional** about a row comes from `item-props` — for option groups that is
 one field, `description`: a muted line **under** the option's label, beside the
 control.
@@ -333,7 +329,6 @@ on the row, feed that field to the predicate.
 			v-model="selected"
 			compact
 			hint="SMS unlocks once a sender number is configured."
-			item-text="label"
 			item-value="id"
 			:items="channels"
 			legend="Channels"
@@ -665,7 +660,6 @@ border) — floating mode is not supported for checkbox groups.
 					? 'Select at least one contact method.'
 					: undefined
 			"
-			item-text="label"
 			item-value="id"
 			:items="options"
 			legend="Contact permissions"
@@ -731,7 +725,6 @@ Read-only, with no cleanup code.
 		<BbRadioGroup
 			v-model="role"
 			compact
-			item-text="label"
 			item-value="id"
 			:items="roles"
 			legend="Token role"
@@ -745,7 +738,6 @@ Read-only, with no cleanup code.
 			:deps-debounce-time="150"
 			enforce-coherence
 			hint="Scopes outside the selected role are removed automatically."
-			item-text="label"
 			item-value="id"
 			:items="loadScopes"
 			legend="Scopes"
@@ -947,8 +939,9 @@ for a preset that fits any row type (never `<any>`), not an imported
   `disabled`.
 - `readonly` still submits its values and stays focusable; use `disabled` only
   for choices that genuinely don't apply.
-- Don't pre-map `items` into `{ label, value }` — pass raw rows and resolve with
-  `item-text` / `item-value`.
+- Don't pre-map domain rows into `{ label, value }` copies — pass raw rows and
+  resolve with `item-text` / `item-value` (a list that already is
+  `{ label, value }` needs neither).
 - A native (non-JS) form post needs `name`: the group generates none, unlike
   `BbRadioGroup`, where the name is what ties the options together. Independent
   boxes need no tie, so with `v-model` alone leave it off.
@@ -1004,8 +997,8 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `itemProps` | `BbOptionGroupItemProps<T> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Option groups accept one field: - `description` — a muted line under the option label, beside the control; it may wrap. Either an object with a path or getter per field (`{ description: 'email' }`) or a function returning the fields (`(item) => ({ description: item.email })`). Without it no field renders — an item's own `description` is never read implicitly — and an empty value renders nothing for that item. The description is announced as the option's description, never part of its name. To disable individual options use `selectable`. |
 | `itemReverse` | `boolean \| undefined` | `false` |  | Swaps each row's input and label from their natural order (input first), in every `item-layout`. `reverse` swaps the legend and the options instead. |
 | `items` | `T[] \| ((context: BbCheckboxGroupItemsContext) => T[] \| Promise<T[]>)` |  | yes | The options: an array, or a provider function called with ONE context object and returning the rows, sync or async. The context carries: - `reason` — why this call happened: `'initial'` (the first load, on mount), `'dependencies'` (a `dependencies` entry or the `items` function changed; a retry arrives this way) or `'model'` (the model changed from outside and the options cannot resolve it). The group has no search field, so it never passes `query`; - `modelValue` — the `v-model` as-is; - `signal` — an `AbortSignal`, aborted when a newer call starts or the group is disposed; pass it to every request. A provider signals a failure by THROWING, never by returning `[]`: the rows are cleared, nothing is pruned, and `#empty` receives the `error` (`failed-text` is shown). Zero-argument providers keep working. Annotate the parameter `BbCheckboxGroupItemsContext` (`BbSwitchGroupItemsContext` on a switch group, the same shape). |
-| `itemText` | `ItemAccessor<T, string> \| undefined` | `JSON.stringify(item)` |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
-| `itemValue` | `ItemAccessor<T> \| undefined` | `the whole item` |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
+| `itemText` | `ItemAccessor<T, string> \| undefined` | `own `label`, else `text`, else `JSON.stringify(item)`` |  | Defines a path that returns a property of the object to use as text or a function that returns a string. Unset: own `label`, else `text` (`{ label, value }` needs no accessor). |
+| `itemValue` | `ItemAccessor<T> \| undefined` | `own `value`, else the whole item` |  | Defines a path that returns a property of the object to use as value or a function that returns any value. Unset: own `value`, even `null`. |
 | `labelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `layout` | `FieldLayout \| undefined` |  |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'` (the label takes the free space, the input keeps its size), `'input-fill'` (the other way round), or a two-word ratio pattern like `'xx xxxxx'`. |
 | `legend` | `string` |  | yes | Text content of the legend. |

package/dist/ai/BbCollapsible.md

@@ -525,7 +525,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | 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: `content`, `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`. In `<script>` a `pt` value is typed `BbCollapsibleProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the content at mount, while closed, instead of on the first open. Closed content is `inert` and `aria-hidden` either way. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. Optional, matching the runtime: `withDefaults` supplies `false`, so an omitted binding renders closed and Vue never warns. It was typed required while carrying that default, which made the manifest publish a row that was `required: true` AND `default: false` — a contradiction that read as a generator bug. |
 | `tag` | `'div'` \| `'span'` | `"span"` |  | Element rendered as the root, and mirrored by the inner animating element — so the pair is span-in-span or div-in-div, both valid. Keep the default inside phrasing content (a `<p>`); use `'div'` when the body is block content (paragraphs, lists, forms), which a `span` may not contain. |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

package/dist/ai/BbColorPalette.md

@@ -760,7 +760,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disable all interaction (activator and palette). |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the palette panel at mount instead of on the first open (the phone sheet's too). |
 | `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button inside the palette to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
 | `label` | `string \| undefined` |  |  | Accessible label. The activator is named by it followed by the activator's own text, through `aria-labelledby`. Defaults to the locale string for "Open color picker" when omitted. |
 | `modelValue` | `string \| null` |  | yes | v-model: the current color as a `#RRGGBB` hex string (or `#RRGGBBAA` when `alpha` is enabled), or `null` when empty. |

package/dist/ai/BbConfirm.md

@@ -654,6 +654,14 @@ const removeMember = async () => {
 When the portal owns its own action buttons, pass `actions: false` to hide the
 standard footer and resolve from inside the slot with its `yes` / `no` helpers.
 
+**Names are checked.** `bitboss-ui check` and the ESLint rule
+`bitboss-ui/portal-names` (in `recommended`) read every literal
+`confirm({ portal: 'name' })` in your scripts against the
+`<BbConfirmPortal name>`s in your templates: a name no file declares fails,
+with a did-you-mean, and `bitboss-ui/unused-portal` warns on a portal nothing
+opens. A `portal` held in a variable, or `confirm(options)`, is never judged.
+The slot's `props` is `any` per key, so `props.member.name` needs no cast.
+
 ### Size, fullscreen and focus
 
 - `size` picks a maximum-width preset (`'xs'` … `'2xl'`, resolvable through

package/dist/ai/BbConfirmPortal.md

@@ -20,7 +20,7 @@
 
 ## Slots
 
-- `default` — scope: `{ yes: () => void; no: () => void; props: Record<string, unknown>; }`
+- `default` — scope: `BbConfirmPortalSlotProps` `{ props: P; yes: () => void; no: () => void }`
 
 ## See Also
 

package/dist/ai/BbDatePickerInput.md

@@ -179,7 +179,9 @@ entirely, reach for `disableWriting` (below), not `range`.
 The value is edited as three separate inputs — day, month, year — not one free
 string. Their **order and separator follow `config.locale`**, read from the
 locale's own format hint: `en` renders `MM/DD/YYYY`, `it` `DD/MM/YYYY`, `de`
-`TT.MM.JJJJ`, `ja` `YYYY/MM/DD`. Typing is forgiving:
+`TT.MM.JJJJ`, `ja` `YYYY/MM/DD`. A region writes its own order with its
+language's letters: `en-GB` `DD/MM/YYYY`, `fr-CA` `AAAA-MM-JJ`. Typing is
+forgiving:
 
 - digits **auto-advance** to the next segment when a segment fills (or can't
   take another digit — e.g. `4` in a day segment becomes `04` and moves on);
@@ -214,7 +216,7 @@ to catch config mistakes early — always pass the `YYYY-MM-DD` shape.
 For non-contiguous rules (no weekends, no holidays, only in-stock slots), pass a
 `selectable` predicate: it receives each date string and returns `false` to
 disable that day. The grid's week starts on the locale's day (Monday for
-`it` or `de`, Sunday for bare `en` and `pt`); `firstDayOfWeek` pins it
+`it`, `de` or `en-GB`, Sunday for bare `en`, `pt` and `en-CA`); `firstDayOfWeek` pins it
 (`0` = Sunday … `6` = Saturday) when the app's week differs from its
 language's.
 

package/dist/ai/BbDialog.md

@@ -402,14 +402,7 @@ dismissed invite doesn't resurface half-typed:
 				placeholder="teammate@company.com"
 				type="email"
 			/>
-			<BbSelect
-				v-model="role"
-				compact
-				item-text="label"
-				item-value="value"
-				:items="roles"
-				label="Role"
-			/>
+			<BbSelect v-model="role" compact :items="roles" label="Role" />
 			<p class="m-0 text-xs text-(--bb-text-muted)">
 				They'll get an email with a link that expires in 7 days.
 			</p>