bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.65

package/dist/ai/BbButton.md

@@ -396,6 +396,22 @@ a `local:` file in your `iconDir`, not a hand-made icon component wrapped in a
 </div>
 ```
 
+To change the glyph with the button's state (a filled star while a toggle is
+on, a solid icon on the current page's link), use the slot named after the
+prop: `#icon`, `#prepend:icon`, `#append:icon`. The slot replaces the prop and
+renders inside the `icon` part, so `pt:icon`, `--icon-size` and the loading
+spinner work as they do on the prop's glyph. Its scope is the button's states:
+`{ activeLink, exactActiveLink, pressed, loading, disabled }`. What you put in
+it is yours: a `BbIcon` takes the part's size, anything else you size.
+
+```vue
+<BbButton v-model="starred" text="Star">
+	<template #prepend:icon="{ pressed }">
+		<BbIcon :icon="pressed ? 'lucide:star' : 'lucide:star-off'" />
+	</template>
+</BbButton>
+```
+
 ### Toggle buttons
 
 Binding `v-model` turns the button into a toggle: each click flips the model
@@ -787,6 +803,84 @@ by `to`, by Inertia `href`, or by a plain `href`.
 </style>
 ```
 
+##### Styling the current page's entry
+
+The same match is a `pt` state and a slot prop, so a sidebar entry can change
+more than one class. `activeLink` is on whenever `active-class` is (the page
+or one below it), `exactActiveLink` whenever `exact-active-class` is; every
+part takes them (`pt:root:active-link`, `pt:icon:exact-active-link`, …), and
+the default slot and the icon slots get `{ activeLink, exactActiveLink }`.
+`#prepend:icon` picks what the classes cannot (a solid glyph on the current
+page) and the states style the rest:
+
+**Sidebar: solid icon and bold label on the current page**
+
+```vue
+<template>
+	<nav aria-label="Main" class="grid w-full max-w-xs gap-0.5">
+		<!-- `#prepend:icon` picks the glyph: solid on the current page's entry,
+		     still the button's icon (size, gap, spinner). The `active-link`
+		     states style the rest — no class of your own, no second matcher. -->
+		<BbButton
+			v-for="item in items"
+			:key="item.label"
+			block
+			class="justify-start"
+			:href="item.href"
+			pt:root:active-link="bg-(--bb-muted) text-(--bb-text)"
+			pt:text:active-link="font-semibold"
+			:text="item.label"
+			variant="ghost"
+		>
+			<template #prepend:icon="{ activeLink }">
+				<BbIcon :icon="activeLink ? item.current : item.icon" />
+			</template>
+		</BbButton>
+	</nav>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbIcon } from 'bitboss-ui';
+
+// This demo runs router-free, so each href is matched against
+// `window.location`: "Home" points at the page you are viewing. In your app
+// the entries are real paths, and a `to` link takes the router's own answer.
+// The hash hrefs keep the preview from navigating (never active).
+const here =
+	typeof window !== 'undefined' ? window.location.pathname : '/dashboard';
+
+const items = [
+	{
+		label: 'Home',
+		href: here,
+		icon: 'heroicons:home',
+		current: 'heroicons:home-solid',
+	},
+	{
+		label: 'Team',
+		href: '#team',
+		icon: 'heroicons:users',
+		current: 'heroicons:users-solid',
+	},
+	{
+		label: 'Settings',
+		href: '#settings',
+		icon: 'heroicons:cog-6-tooth',
+		current: 'heroicons:cog-6-tooth-solid',
+	},
+] as const;
+</script>
+```
+
+The classes, the states and the slot props are one answer: a `to` link takes
+vue-router's own (`useLink`, as `RouterLink` does — so `/users` lights up on
+`/users/5` when `/users/:id` is a child route of `/users`), an `href` link the
+path match above. They rank below the real states: a `pressed`, `disabled` or
+`loading` entry styles as that. `BbDropdownButton`'s main button, a `BbBadge`
+whose `BbBadgeButton` is a link (the whole chip), and `BbDropdown` link entries
+(`pt:item:active-link`, and the row slots' `activeLink` / `exactActiveLink`)
+get the same states.
+
 #### Inertia visits
 
 Under Inertia, `href` accepts the full visit surface as props, grouped by
@@ -860,11 +954,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`, `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).
+`loading`, `disabled`, `pressed` (a `v-model` toggle that is on), and on a
+link `activeLink` / `exactActiveLink` (it points at the current page: see
+Active state above). 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"`).
 
 **pt: a part, a part while loading, the object form**
 
@@ -1123,7 +1217,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`, `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>`. |
+| `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: `activeLink`, `destructive`, `disabled`, `exactActiveLink`, `ghost`, `link`, `loading`, `outline`, `pressed`, `primary`, `secondary`. 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. |
@@ -1193,9 +1287,17 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `activeLink` | Component-wide: a link to the current page or one of its ancestors (`/users` on `/users/5`) — exactly when `activeClass` is on. The weakest state: `pressed`, `disabled` and `loading` win a conflict. |
+| `exactActiveLink` | Component-wide: a link to the current page itself — exactly when `exactActiveClass` is on (`activeLink` is on too, so its entries apply first and these win). |
 | `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. |
+| `destructive` | Component-wide: `variant="destructive"`. Keeps the red under a base `pt`: `pt:root:destructive`. |
+| `ghost` | Component-wide: `variant="ghost"`. Below the real states, like every variant. |
+| `link` | Component-wide: `variant="link"`. Below the real states, like every variant. |
+| `outline` | Component-wide: `variant="outline"`. Below the real states, like every variant. |
+| `primary` | Component-wide: `variant="primary"`. Merged after the part's base entry and before its states, so `disabled` / `loading` still win. |
+| `secondary` | Component-wide: `variant="secondary"`. Below the real states, like every variant. |
 
 ## Events
 
@@ -1203,7 +1305,10 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `default` — scope: `object` — Primary content rendered inside the button. Falls back to the `text` prop when empty.
+- `append:icon` — scope: `BbButtonIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; pressed: boolean; loading: boolean; disabled: boolean }` — The trailing icon, replacing `append:icon`; inside the `icon` part.
+- `default` — scope: `BbLinkSlotProps` `{ activeLink: boolean; exactActiveLink: boolean }` — Primary content rendered inside the button. Falls back to the `text` prop when empty. A link's slot gets `{ activeLink, exactActiveLink }`: whether it points at the current page (both `false` on a button).
+- `icon` — scope: `BbButtonIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; pressed: boolean; loading: boolean; disabled: boolean }` — The icon of an icon-only button, replacing the `icon` prop. Renders inside the `icon` part: `pt:icon`, `--icon-size` and the loading spinner apply.
+- `prepend:icon` — scope: `BbButtonIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; pressed: boolean; loading: boolean; disabled: boolean }` — The leading icon, replacing `prepend:icon`; inside the `icon` part.
 
 ## Exposed (template ref)
 
@@ -1285,7 +1390,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 `manifest/components/BbButton.tree.json`.
 
-- `BbButton` _(this component)_ — its own template binds: `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`
+- `BbButton` _(this component)_ — its own template binds: `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `span.bb-button__icon`, `icon` → `BbIcon`, `icon` → `span.bb-button__prepend-icon`, `text` → `span.bb-button__text`, `icon` → `span.bb-button__append-icon`
   - `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/BbCheckbox.md

@@ -646,7 +646,7 @@ const onSave = async () => {
 </script>
 ```
 
-An attribute in `attrs` wins over ours. The visually hidden native input is
+An attribute in `attrs` wins over ours. The invisible native input under the glyph is
 not a part — plain attributes on the component land on the root. A listener in `attrs` runs after the control's own
 handler, never instead of it. The full grammar, the merge rules and the global
 map are in the [passthrough guide](./guides/passthrough.md).

package/dist/ai/BbCheckboxGroup.md

@@ -39,6 +39,27 @@
 | `--bg` | `pt:icon` | `BbBaseCheckboxIcon` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface's fill, which happens to match at the shipped default and would diverge the moment anyone writes `.my-table { --bg: … }`. Identical to the raw tokens it replaces at every theme. |
 | `--border-color` | `pt:icon` | `BbBaseCheckboxIcon` | Resting border colour of the glyph; re-pointed by error and warning states. |
 | `--ctrl-line` | `pt:label` | `CommonField` | Where the control's first line is centred, from the top of the control column (half the box height by default); the label's first line aligns to it in side-by-side layouts. |
+| `--list-bg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The strip behind the triggers |
+| `--list-border` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The strip's edge line, --bb-border-w thick, painted inside the strip: under the triggers (beside them when vertical). `pill` draws none; `line` sets it to --bb-border |
+| `--p` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | strip inner padding — the gutter the indicator sits in, and the scroll inset |
+| `--list-r` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | strip corners |
+| `--list-h` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | strip min height |
+| `--fs` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | trigger label size |
+| `--trigger-gap` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | space between triggers |
+| `--trigger-px` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | trigger side padding |
+| `--trigger-r` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Trigger corners, concentric inside --list-r |
+| `--trigger-min-h` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Trigger height inside the padded strip |
+| `--list-fg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | unchecked trigger label |
+| `--hover-fg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | hovered trigger label |
+| `--active-fg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | checked trigger label |
+| `--active-fw` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | checked trigger label weight (unchecked labels are 500) |
+| `--indicator-bg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | the indicator's fill |
+| `--indicator-border` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The indicator's edge |
+| `--indicator-r` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The indicator's corners — the pill's, concentric inside --list-r |
+| `--indicator-h` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The indicator's thickness: its height, its width on a vertical strip. `initial` fills the whole trigger box — the pill; a bar is `2px`, on the trigger's bottom edge (inline-end edge when vertical) |
+| `--indicator-inset` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Inset of the indicator from the trigger box — shrinks the pill; a bar keeps its thickness, shortens by it at both ends and floats it above the edge |
+| `--elev` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The theme's resting lift, composed UNDER the indicator's own shadow |
+| `--indicator-shadow` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Indicator lift, painted on top of --elev |
 
 ## Usage & Guidelines
 
@@ -487,7 +508,7 @@ checked day painted, the hint reading the choice back:
 			name="reminder-days"
 			persistent-hint
 			pt:icon="hidden"
-			pt:item="justify-items-center gap-0 rounded-(--bb-radius) border py-2 hover:bg-(--bb-muted)"
+			pt:item="justify-items-center rounded-(--bb-radius) border py-2 hover:bg-(--bb-muted)"
 			pt:item:checked="border-(--bb-primary) bg-(--bb-primary) hover:bg-(--bb-primary-hover)"
 			pt:item:focus-visible="ring-2 ring-(--bb-primary-ring)"
 			pt:label="text-sm font-medium"
@@ -626,6 +647,60 @@ const total = computed(() =>
 </script>
 ```
 
+#### Pick values with the tabs look
+
+`variant="pill"` or `variant="line"` gives the group a tab strip's look, for a
+multi-pick that reads as a strip (opening days, channels, filters). `pill`
+draws one pill per run of adjacent picks, so Mon–Wed reads as one block, and
+each pill then lives on: ticking a neighbour stretches it, unticking an end
+option shortens it, unticking a middle option splits it (the hole opens in
+place), a lone pick pops a new pill in, and a pill whose options are all
+unticked shrinks to its centre and fades. Two pills that come to touch stay
+two pills, drawn as one shape. `line` draws a bar under each pick across a baseline that spans the field;
+adjacent bars join. The strip and its triggers measure exactly as BbTabs'.
+It is still a checkbox group (native checkboxes, `max`, forms, validation);
+the box is hidden (an `icon` slot shows before the label) and the strip
+never wraps (it scrolls); `list-layout="vertical"` stacks it into a column
+(runs stack on the Y axis), `"vertical-stretch"` spans the field, and the
+other layouts and `item-layout` do not apply. `pt:indicator` reaches every
+pill or bar, and `pt:<part>:pill` / `pt:<part>:line` style a part in one look
+only. The strip's tokens are its own, named and valued as a tab strip's; a
+registered `checkboxVariants: ['brand']` sets them on
+`.bb-checkbox-group__list--brand` and draws pills per run, as `pill` does.
+
+**Pick values with the tabs look**
+
+```vue
+<template>
+	<div class="flex flex-col gap-4">
+		<BbCheckboxGroup
+			v-model="days"
+			:items="weekdays"
+			legend="Open on"
+			variant="pill"
+		/>
+		<BbCheckboxGroup
+			v-model="channels"
+			:items="['Email', 'SMS', 'Push']"
+			legend="Notify by"
+			variant="line"
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbCheckboxGroup } from 'bitboss-ui';
+
+// BbTabs' looks on a multi-pick. `pill`: one pill per run of adjacent picks,
+// so Mon–Wed reads as one block; tick Thu and the pill grows, untick Tue and
+// it splits. `line`: a bar under each pick, adjacent bars join.
+const weekdays = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+const days = ref(['Mon', 'Tue', 'Wed', 'Fri']);
+const channels = ref(['Email', 'Push']);
+</script>
+```
+
 ### Legend, description and validation
 
 The `legend` is the group's accessible name — always set it. `description` is
@@ -868,6 +943,15 @@ list already spans the field, so the tiles do too.
 slot does not remove it: the default box is the slot's fallback and renders
 whenever the slot is empty.
 
+A side hidden with the library's or Tailwind's hiding classes takes its gap
+with it: a box hidden with `pt:icon="hidden"` (or `sr-only`), or a label
+hidden with `hide-label` or `pt:label="sr-only"`, leaves the other side
+centred, no `gap-0` needed. In `list-layout="tiles"` the whole tile is the
+click and hover target, padding included (a tooltip whose activator is the
+row's input shows anywhere on it); a link or a button inside a tile keeps its
+own click. List rows keep the box as the target, beside a label that selects
+too.
+
 **pt:item — cadence tiles, the selected ones accented**
 
 ```vue
@@ -918,7 +1002,7 @@ ours, an attribute in `attrs` wins over ours. The full grammar, the merge rules
 and the global map are in the [passthrough guide](./guides/passthrough.md).
 
 A `pt` value written in `<script>` (a constant, a preset, a wrapper's
-`pt` prop) is typed as `BbCheckboxGroupProps<Row>['pt']`, or `BbCheckboxGroupProps['pt']`
+`pt` prop) is typed as `BbCheckboxGroupProps<Row>['pt']`, or `BbCheckboxGroupProps<object>['pt']`
 for a preset that fits any row type (never `<any>`), not an imported
 `PtValue`: see
 [passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
@@ -982,7 +1066,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 
 | 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: `description`, `hint`, `icon`, `item`, `itemDescription`, `label`, `legend`, `list`, `message`, `root`. States: `disabled`, `errors`, `hasValue`, `loading`, `readonly`, `warnings`, `checked`, `focused`, `focusVisible`. 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 `BbCheckboxGroupProps<Row>['pt']` (`BbCheckboxGroupProps['pt']` for a preset that fits any row type, never `<any>`) (`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: `description`, `hint`, `icon`, `indicator`, `item`, `itemDescription`, `label`, `legend`, `list`, `message`, `root`. States: `disabled`, `errors`, `hasValue`, `line`, `loading`, `pill`, `readonly`, `warnings`, `checked`, `focused`, `focusVisible`. 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 `BbCheckboxGroupProps<Row>['pt']` (`BbCheckboxGroupProps<object>['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
 | `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-label-spacing-y` for `--bb-label-spacing-y-compact`, so tune a compact group's label gap with the `-compact` token, not the base one. |
 | `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
@@ -1029,6 +1113,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `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. |
 | `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; never the `name`. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). `BbForm` only. |
 | `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When the field validates: `aggressive` (each change), `balanced` (on leave, then live while in error), `lazy` (on leave), `submit-only`, `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). `BbForm` only. |
+| `variant` | `'pill'` \| `'line'` |  |  | A tab-strip look (Q76.11 d): `'pill'` (a pill per run of adjacent picks) or `'line'` (a bar under each pick). `list-layout="vertical"` stacks it. Register more with `checkboxVariants`. Unset: the group's own rows. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or array: amber, in their own `aria-live` region and in the control's `aria-describedby` after the errors. Non-empty turns on the warning state; errors win when both are set. |
 
 ## Passthrough parts and states
@@ -1042,7 +1127,8 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `description` | The muted line under the legend (the `description` prop). |
 | `message` | The errors / warnings line. A node of its own: it can show at the same time as `hint`. |
 | `hint` | The helper line (the `hint` prop), shown on focus, or always with `persistent-hint`. |
-| `list` | The node that lays the rows out (flex + wrap, gaps on `--gap` / `--row-gap`): `pt:list="grid grid-cols-3"` re-lays them, `pt:list="[--gap:8px]"` tightens them. Takes the group-wide states only. |
+| `list` | The node that lays the rows out (flex + wrap, gaps on `--gap` / `--row-gap`): `pt:list="grid grid-cols-3"` re-lays them, `pt:list="[--gap:8px]"` tightens them. With a `variant`, the tab strip. Takes the group-wide states only. |
+| `indicator` | With a `variant`: the shape under the checked option, BbTabs' indicator — the sliding pill or bar of a radio group, a checkbox group's pill per run of adjacent picks (or bar per pick). Takes the group-wide states only. |
 | `item` | One option row — a broadcast, resolved per option with its own `checked` / `disabled` / focus. Takes a per-item function. |
 | `icon` | One row's drawn glyph — the default one: a consumer `icon` slot replaces it. Takes a per-item function. |
 | `label` | One option's label text (the `label` slot's default). Takes a per-item function. |
@@ -1061,6 +1147,8 @@ States are listed in precedence order: when two are on at once and their entries
 | `focused` | Per row, on the row parts: that option's input has focus — any focus, mouse included. |
 | `focusVisible` | Per row, on the row parts: that option's focus is keyboard-visible — where a focus ring belongs. |
 | `loading` | Component-wide: the items are being fetched. |
+| `line` | On every part: `variant: 'line'`. Below the real states, like every variant. |
+| `pill` | On every part: `variant: 'pill'`. Merged after the part's base entry and before its states, so the real states still win. |
 
 ## Events
 
@@ -1106,9 +1194,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 `BbCheckboxGroup`'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 `BbCheckboxGroup`'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 `manifest/components/BbCheckboxGroup.tree.json`.
 
-- `BbCheckboxGroup` _(this component)_ — its own template binds: `icon` → `BbBaseCheckboxIcon`
+- `BbCheckboxGroup` _(this component)_ — its own template binds: `indicator` → `span.bb-checkbox-group__indicator`, `icon` → `BbBaseCheckboxIcon`
   - `CommonField` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
-  - `OptionsContainer` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `list` → `span`, `item` → `label`, `label` → `span`, `itemDescription` → `span`
+  - `OptionsContainer` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `list` → `span`, `item` → `label`, `label` → `span`, `itemDescription` → `span`; documented CSS variables: `--list-bg`, `--list-border`, `--p`, `--list-r`, `--list-h`, `--fs`, `--trigger-gap`, `--trigger-px`, `--trigger-r`, `--trigger-min-h`, `--list-fg`, `--hover-fg`, `--active-fg`, `--active-fw`, `--indicator-bg`, `--indicator-border`, `--indicator-r`, `--indicator-h`, `--indicator-inset`, `--elev`, `--indicator-shadow`
   - Also mounts `BbBaseCheckboxIcon`
 
 ## See Also

package/dist/ai/BbColorInput.md

@@ -682,7 +682,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: `box`, `clear`, `description`, `hint`, `icon`, `indicator`, `input`, `label`, `message`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `swatch`. States: `disabled`, `errors`, `hasValue`, `loading`, `readonly`, `warnings`, `selected`. 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 `BbColorInputProps['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: `box`, `clear`, `description`, `hint`, `icon`, `indicator`, `input`, `label`, `message`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `swatch`. States: `disabled`, `errors`, `ghost`, `hasValue`, `loading`, `outline`, `readonly`, `secondary`, `warnings`, `selected`. 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 `BbColorInputProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the color palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbSelect`/`BbDatePickerInput`. When unset, falls back to the global `config.adaptive`. |
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. Shows an opacity slider and uses `#RRGGBBAA` hex8 format. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
@@ -757,6 +757,9 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the control is in its warning state (`warnings` / `has-warnings`) and not in an error state — errors win, so the two are never on together. |
 | `errors` | Component-wide: the control is in its error state (`errors` / `has-errors`, or its validation) — the message line and the box turn red. |
 | `loading` | Component-wide: `loading` is on; the box shows its `spinner`. |
+| `ghost` | On the field's parts: `variant: 'ghost'`. Below the real states, like every variant. |
+| `outline` | On the field's parts: `variant: 'outline'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `secondary` | On the field's parts: `variant: 'secondary'`. Below the real states, like every variant. |
 
 ## Events
 

package/dist/ai/BbColorPalette.md

@@ -444,7 +444,8 @@ The float itself is tuned with the popover props:
 
 - `placement` (`'bottom'`, `'bottom-start'`, `'top-end'`, …) — the preferred
   side; the popover **auto-flips** to the opposite side when it would overflow,
-  unless you set `disable-flip`.
+  unless you set `disable-flip`. Read at open: a change while open applies at
+  the next open.
 - `offset` (default 4) — gap between anchor and popover; `padding` (default 6) —
   minimum space kept from the viewport edge.
 - `boundary` — keep the popover inside an element (ref or CSS selector)

package/dist/ai/BbConfirm.md

@@ -216,7 +216,9 @@ promise runs, the opposite button is disabled, the X is hidden and dismissal
 is blocked until it settles. Add `returning: true` to resolve with the
 callback's own return value rather than a plain boolean. One sharp edge:
 `confirm()` **rejects** when a button's `onClick` throws — wrap the await in
-`try/catch` when the work can fail.
+`try/catch` when the work can fail. An Inertia visit returns no promise: wrap
+it, as in `ai/composables/useConfirm.md` § async work, rather than calling
+`close()` from its callbacks.
 
 **Async publish with a spinner**
 
@@ -801,7 +803,7 @@ The map is typed where you write it by `definePt`, never with an imported
 
 | 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: `action`, `close`, `content`, `footer`, `header`, `root`, `sheet`, `text`, `title`. 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 `BbConfirmProps['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: `action`, `close`, `content`, `footer`, `header`, `root`, `sheet`, `text`, `title`. States: `default`, `destructive`, `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 `BbConfirmProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 
 ## Passthrough parts and states
 
@@ -824,6 +826,8 @@ States are listed in precedence order: when two are on at once and their entries
 | State | When it is on |
 | --- | --- |
 | `open` | Component-wide: a confirm is showing. |
+| `default` | Component-wide, from the message: `variant: 'default'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `destructive` | Component-wide, from the message: `variant: 'destructive'`. Below the real states, like every variant. |
 
 ## Events
 
@@ -846,7 +850,7 @@ States are listed in precedence order: when two are on at once and their entries
   - `BbDialog` _(public — [contract](./BbDialog.md))_ — its own pt parts (`BbDialog`): `header` → `div.bb-dialog__header`, `title` → `span.bb-dialog__title`, `description` → `p.bb-dialog__description`, `close` → `CloseButton`, `content` → `div.bb-dialog__content`, `footer` → `div.bb-dialog__footer`; hands `BbOffCanvas` the pt map `{ root: 'root', header: 'header', title: 'title', description: 'description', content: 'content', footer: 'footer', close: 'close', sheet: 'root', }` (ours → theirs); documented CSS variables: `--px`, `--close-size`
     - `CloseButton` _(internal — not importable, reach it through `BbDialog`)_ — documented CSS variables: `--size`, `--p`
     - `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`, `--snap-y`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`; also mounts `CloseButton`
-  - `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`, `BbSpinner`
+  - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `span.bb-button__icon`, `icon` → `BbIcon`, `icon` → `span.bb-button__prepend-icon`, `text` → `span.bb-button__text`, `icon` → `span.bb-button__append-icon`; 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`, `BbSpinner`
     - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
 
 ## See Also

package/dist/ai/BbDatePicker.md

@@ -251,7 +251,8 @@ On mobile the calendar opens in a bottom off-canvas sheet instead of a floating
 popover (`adaptive`, on by default via `config.adaptive`; forward extra sheet
 props with `offCanvasProps`). Position the desktop popover with `placement`,
 `offset`, `padding`, `boundary`, and `disableFlip` — the same knobs as the other
-overlays. Escape and backdrop clicks close it; focus returns to the activator.
+overlays (`placement` is read at open: a change while open applies at the next
+open). Escape and backdrop clicks close it; focus returns to the activator.
 
 The sheet can be **dragged down to dismiss** and shows **no ✕** — picking,
 drag, backdrop tap and Escape close it. The time wheels and the year list are

package/dist/ai/BbDatePickerInput.md

@@ -878,7 +878,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 
 | 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: `activator`, `arrow`, `box`, `cellColumnHeader`, `clear`, `day`, `dayButton`, `description`, `header`, `hint`, `icon`, `input`, `item`, `label`, `message`, `month`, `monthItem`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `year`, `yearItem`. States: `active`, `disabled`, `errors`, `hasValue`, `highlighted`, `inRange`, `loading`, `open`, `outside`, `rangeEnd`, `rangeStart`, `readonly`, `selected`, `today`, `warnings`. 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 `BbDatePickerInputProps['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: `activator`, `arrow`, `box`, `cellColumnHeader`, `clear`, `day`, `dayButton`, `description`, `header`, `hint`, `icon`, `input`, `item`, `label`, `message`, `month`, `monthItem`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`, `year`, `yearItem`. States: `active`, `disabled`, `errors`, `ghost`, `hasValue`, `highlighted`, `inRange`, `loading`, `open`, `outline`, `outside`, `rangeEnd`, `rangeStart`, `readonly`, `secondary`, `selected`, `today`, `warnings`. 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 `BbDatePickerInputProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelect`. When unset, falls back to the global `config.adaptive`. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
@@ -982,6 +982,9 @@ States are listed in precedence order: when two are on at once and their entries
 | `open` | Component-wide: the calendar is showing — `pt:activator:open` styles the trigger while it is. |
 | `highlighted` | Per node, on the cells: the keyboard cursor. |
 | `loading` | Component-wide: `loading` is on; the box shows its `spinner`. |
+| `ghost` | On the field's parts: `variant: 'ghost'`. Below the real states, like every variant. |
+| `outline` | On the field's parts: `variant: 'outline'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `secondary` | On the field's parts: `variant: 'secondary'`. Below the real states, like every variant. |
 
 ## Events
 

package/dist/ai/BbDialog.md

@@ -1360,17 +1360,18 @@ const save = async (draft: Project): Promise<Project> => {
 Dialogs sharing a `stack` name **replace** one another: only the most recently
 opened member is visible, the ones beneath are hidden until it closes — the
 stack reads as a single surface whose content swaps as you drill in. When a
-member closes, the one beneath crossfades in as it fades out. Each stacked
-member dims what lies beneath it (via `--bb-overlay-stacked`, the same
-dim as `--bb-overlay` by default); only the bottom member blurs, and its backdrop is
-never handed off while members swap above it, so the page behind never
-re-blurs between them. Set `--bb-overlay-stacked: transparent` for a single
-dim under the whole stack. The backdrop split follows the **open order of
-every dialog**, whatever its `stack` name or none, exactly as for
-off-canvases: the bottom-most open dialog blurs and dims, each one opened
-above it adds the stacked dim. The `stack` name only decides
-cover/replace. Dialogs with different names (or none) therefore pile up
-visibly, each dimming the one beneath. Use a stack for a two-step flow that
+member closes, the one beneath crossfades in as it fades out. A member adds
+no dim of its own: the one it covers keeps painting its backdrop, so the page
+behind is exactly as dark as under the first member. The backdrop otherwise
+follows the **open order of every dialog**, whatever its `stack` name or
+none, exactly as for off-canvases: the bottom-most open dialog blurs and
+dims, and each one opened above a dialog that stays VISIBLE (another stack
+name, or none) adds its own dim (`--bb-overlay-above`, the same dim as
+`--bb-overlay` by default; `transparent` for a single dim under the whole
+pile). Only the bottom dialog blurs, and its backdrop is never handed off
+while dialogs swap above it, so the page behind never re-blurs between them.
+Dialogs with different names (or none) therefore pile up visibly, each
+dimming the one beneath. Use a stack for a two-step flow that
 should not read as two boxes piling up.
 
 **Drill into advanced options**