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

package/dist/ai/BbTooltip.md

@@ -34,7 +34,9 @@ Do **not** put interactive content in a tooltip (links, buttons, form fields):
 - A menu of actions → `BbDropdown`.
 
 A tooltip is a supplement, never the only source of information — critical text
-must live in the page, not hide behind a hover.
+must live in the page, not hide behind a hover. Host it on something keyboard
+focus reaches (a button or link); an info icon is an icon-only ghost
+`BbButton` (see [The `v-bb-tooltip` directive](#the-v-bb-tooltip-directive)).
 
 ### Text via `text` or the default slot
 
@@ -90,6 +92,22 @@ bubble (`top` by default; the `top` / `right` / `bottom` / `left` families with
 </p>
 ```
 
+### A trigger you don't render
+
+When the trigger isn't yours to wrap (an element another component renders,
+like the native input of a selection tile), pass it as `activator` instead of
+using the slot: an element, a component ref, or a CSS selector string, looked
+up in the document once the tooltip mounts. The tooltip then wires its
+listeners and its description onto that element. The `v-bb-tooltip` directive
+always uses the element it sits on.
+
+```vue
+<BbTooltip
+	activator="#export-format-csv"
+	text="Comma-separated, opens in any spreadsheet"
+/>
+```
+
 ### Variant
 
 `variant` tints the bubble. Two variants ship styles out of the box:
@@ -249,7 +267,8 @@ is concerned — the whole label (shortcut included) is flattened into the
 ### Placement, timing, width and disabling
 
 - `placement` — as above; the `top`/`right`/`bottom`/`left` families with
-  `-start`/`-end` variants, auto-flipping near an edge.
+  `-start`/`-end` variants, auto-flipping near an edge. Read at open: a change
+  while open applies at the next open.
 - `delay` (ms, default `100`) holds the tooltip back until the pointer settles,
   so a cursor passing over a row of buttons doesn't flash a bubble at each one;
   raise it on dense toolbars. It delays only the **open**, and only for a
@@ -333,7 +352,13 @@ The value grammar has three forms, plus a directive argument for placement:
 
 ```vue
 <!-- string (or number) shorthand: the value is the tooltip text -->
-<span v-bb-tooltip="'North Atlantic Treaty Organization'">NATO</span>
+<BbButton
+	variant="ghost"
+	icon="lucide:info"
+	v-bb-tooltip="'Prices include VAT'"
+>
+	About prices
+</BbButton>
 
 <!-- the directive argument sets placement -->
 <BbButton
@@ -344,21 +369,36 @@ The value grammar has three forms, plus a directive argument for placement:
 
 <!-- object form: a required `text` plus any BbTooltip prop
      (placement, delay, variant, width, disabled, …) -->
-<span
+<BbButton
 	v-bb-tooltip="{
 		text: 'Opens after 300ms, anchored right',
 		placement: 'right',
 		delay: 300,
 		variant: 'destructive',
 	}"
+	variant="ghost"
+	icon="lucide:trash-2"
 >
-	Hover me
-</span>
+	Delete draft
+</BbButton>
 
 <!-- an empty value attaches nothing — safe to bind conditionally -->
 <span v-bb-tooltip="isTruncated ? label : ''">{{ label }}</span>
 ```
 
+**Put it on something keyboard focus reaches.** The tooltip opens on hover and
+on keyboard focus, so its host decides who can read it. On a button or a link
+everyone can. On a non-interactive element (a bare `BbIcon`, a `<span>`, an
+`<svg>`) it is a pointer-only hint: it works, but keyboard and touch never open
+it, so use that only when the tip repeats text already on the page (the
+truncated cell above). An info icon is an icon-only ghost `BbButton`, its slot
+text the name and the tip the description:
+`<BbButton variant="ghost" icon="lucide:info" v-bb-tooltip="'Prices include VAT'">About prices</BbButton>`.
+Text that must be readable on touch belongs in a `BbPopover` toggletip
+(see the BbPopover guide, "Inline field help"). Never add a `tabindex` to an
+icon to make it reachable: a focusable icon is a tab stop with no role, and it
+takes the opening focus of a dialog or popover it sits in.
+
 These grammar fences are intentionally **static** (not runnable): the guide's
 live-example compiler mounts a bare template and cannot register a directive.
 In a real SFC the directive just works — either globally (plugin) or by
@@ -456,7 +496,8 @@ const files: SharedFile[] = [
 `pt` reaches a named part of the tooltip with a class list — or, in the
 object form, a style and attributes — optionally only while a state is on.
 Parts: `root` (the floating element, arrow included) and `panel` (the
-bubble). State: `open`.
+bubble). State: `open`. A `class`, `style` or attribute on `<BbTooltip>`
+itself lands on `root` too.
 
 The document-toolbar hints, restyled through those parts: a muted wash on
 `pt:panel` (the bubble — default is the inverted primary), a drop shadow
@@ -564,6 +605,13 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - **Keep the activator's `aria-label`.** The tooltip describes the control, it
   does not name it — dropping the label because "the tooltip already says it"
   breaks assistive tech (see Accessibility).
+- **A `class` on `<BbTooltip>` styles the floating element, not the trigger
+  or the bubble's paint.** Attributes land on `root`, which wraps the bubble
+  and the arrow, and exists only from the first open. To style the trigger,
+  put the class on your element in `#activator`; to recolour the bubble and
+  its arrow, set `--bg` and `--border-color` (and `--fg`) on the tag
+  (`:style="{ '--bg': '#334155', '--border-color': '#334155' }"`); for the bubble's
+  spacing or type, use `pt:panel`.
 - **Custom variant strings ship no CSS.** Anything beyond `'default'` and
   `'destructive'` is a bare `bb-tooltip--<name>` class hook — if you haven't
   written that CSS, the bubble silently renders with default paint.
@@ -584,8 +632,20 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   thing you just clicked.
 - Because the bubble is not focusable and holds no interactive content, never
   place a link or button inside it — use `BbPopover` for that.
+- The visible bubble is `aria-hidden`: its text reaches assistive tech only as
+  the activator's description, so a tooltip rendered inside a `<label>` never
+  joins the control's name. Tests assert the activator's description, not a
+  `tooltip` role.
 - The tooltip supplements an accessible name; it does not provide one. Icon-only
   triggers still need their own `aria-label`.
+- A tip whose text repeats the control's accessible name (the icon-only button
+  above) adds nothing for screen readers, which hear the name and then the same
+  words as the description: make the tip add information (a shortcut, a
+  consequence), or accept the repeat.
+- Keyboard and touch reach the tip only through a focusable host: on a bare
+  icon or `<span>` it is pointer-only (see
+  [The `v-bb-tooltip` directive](#the-v-bb-tooltip-directive) for the info-tip
+  button).
 
 ## v-model
 
@@ -595,8 +655,8 @@ 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: `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`. In `<script>` a `pt` value is typed `BbTooltipProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
+| `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: `panel`, `root`. 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 `BbTooltipProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `activator` | `ElementOrComponentRefOrSelector \| undefined` |  |  | External activator: an HTMLElement, a Vue component ref, or a CSS selector string (looked up in the document once the tooltip mounts). When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
 | `arrowPadding` | `number \| undefined` | `10` |  | Space the arrow will maintain to the edge of the tooltip bubble. Useful when the floating element has border radius so it won't appear broken |
 | `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the tooltip within a bounding element: it stays inside it alongside its trigger (sideways for a tooltip above or below); away from the trigger it may pass the edge, and it flips at the viewport only. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `delay` | `number \| undefined` | `100` |  | Milliseconds a pointer rests on the activator before the tooltip shows (`0`: at once). Keyboard focus shows it at once, and so does a pointer arriving while another tooltip shows or within 300 ms of one closing. |
@@ -626,6 +686,8 @@ States are listed in precedence order: when two are on at once and their entries
 | State | When it is on |
 | --- | --- |
 | `open` | Component-wide: the tooltip is showing. |
+| `default` | Component-wide: `variant: 'default'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `destructive` | Component-wide: `variant: 'destructive'`. Below the real states, like every variant. |
 
 ## Events
 

package/dist/ai/ChipsBox.md

@@ -79,4 +79,4 @@
 - Listed nodes are the ones `ChipsBox`'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/ChipsBox.tree.json`.
 
 - `ChipsBox` _(this component)_ — its own template binds: `badge` → `BbBadge`
-  - `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`
+  - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `span.bb-badge__append-icon`, `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`

package/dist/ai/CommonField.md

@@ -35,7 +35,7 @@
 | `loading` | `boolean \| undefined` | `false` |  | Whether the inner control is in a loading state. |
 | `mobile` | `boolean \| undefined` | `false` |  | Whether the inner control is in mobile viewport mode. |
 | `name` | `string \| undefined` |  |  | Explicit name attribute forwarded to the input. When omitted, a slug derived from `label` is used. |
-| `passthrough` | `(Partial<Record<FieldPtPart, Record<string, unknown>>> & { part?: ((part: FieldPtPart, states: Partial<Record<string, boolean>>, item?: unknown) => Record<strin…` |  |  | Passthrough bindings resolved by the public control, one `v-bind` object per part (`root`, `label`, `description`, `message`: the errors OR the warnings), bound last. Internal: the public `pt:*` props are the surface. |
+| `passthrough` | `(Partial<Record<FieldPtPart, Record<string, unknown>>> & { part?: ((part: FieldPtPart, states: Partial<Record<string, boolean>>, item?: unknown, variant?: strin…` |  |  | Passthrough bindings resolved by the public control, one `v-bind` object per part (`root`, `label`, `description`, `message`: the errors OR the warnings), bound last. Internal: the public `pt:*` props are the surface. |
 | `readonly` | `boolean \| undefined` | `false` |  | Whether the inner control is readonly. |
 | `reverse` | `boolean \| undefined` | `false` |  | Swap the label and input columns. |
 | `showAsterisk` | `boolean \| undefined` | `false` |  | Render the required marker (`BbAsterisk`) after the label text. The control decides (useFormBinding); a `#label` slot gets it as `showAsterisk` and renders its own. |

package/dist/ai/OptionsContainer.md

@@ -19,6 +19,7 @@
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Attaches a `--warnings` CSS class; suppressed when `hasErrors` is true. |
 | `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
+| `indicatorReady` | `boolean \| undefined` | `false` |  | With a `variant`: the indicators have been measured and painted, so they may transition. Until then the list is `--no-transition`. |
 | `itemInputAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of each option's control in its row; `'center'` is the middle of the label plus its description. Omitted, it sits on the label's first line. |
 | `itemLabelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of each option's label in its row. Omitted, it stays as it is. |
 | `itemLayout` | `FieldLayout \| undefined` | `'auto'` |  | How one row's input and label sit together: the keywords of a field's `layout`. Placed by the `-item--<keyword>` modifier. |
@@ -28,6 +29,7 @@
 | `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
 | `options` | `Option<T>[]` |  | yes | List of options to render. |
 | `passthrough` | `PtBindings<"icon" \| "label" \| "item" \| "list" \| "itemDescription", RowPtState> \| undefined` |  |  | Passthrough resolver from the public owner: `list` (bound whole, group-wide states), `item` and `label` (per row, with its own on-state and `disabled`). The on-state goes under both `selected` and `checked`; a resolver ignores a state its component lacks. Internal. |
+| `variant` | `string \| undefined` |  |  | A tab-strip look on the list (Q76.11 d): `--strip` plus the variant's class hook (`--pill`, `--line`, a registered name), the strip and its triggers (choice-strip.css). The owning group renders the indicators. |
 
 ## Events
 
@@ -41,3 +43,43 @@
 - `label` — scope: `OptionsContainerLabelSlotProps<T>` `{ checked: boolean; item: T; text: string; description: string }` — Replaces the default label text for each option.
 - `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
 - `prepend` — scope: `object` — Content rendered before the first option, inside the options container.
+
+## CSS custom properties
+
+Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+
+| Property | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--list-bg` | `.bb-radio-group__list--strip` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The strip behind the triggers |
+| `--list-border` | `.bb-radio-group__list--strip` | `transparent` | 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` | `.bb-radio-group__list--strip` | `3px` | strip inner padding — the gutter the indicator sits in, and the scroll inset |
+| `--list-r` | `.bb-radio-group__list--strip` | `var(--bb-radius)` | strip corners |
+| `--list-h` | `.bb-radio-group__list--strip` | `var(--bb-control-h)` | strip min height |
+| `--fs` | `.bb-radio-group__list--strip` | `var(--bb-fs)` | trigger label size |
+| `--trigger-gap` | `.bb-radio-group__list--strip` | `0px` | space between triggers |
+| `--trigger-px` | `.bb-radio-group__list--strip` | `10px` | trigger side padding |
+| `--trigger-r` | `.bb-radio-group__list--strip` | `calc(var(--list-r) - var(--p))` | Trigger corners, concentric inside --list-r |
+| `--trigger-min-h` | `.bb-radio-group__list--strip` | `calc(var(--list-h) - var(--p) * 2)` | Trigger height inside the padded strip |
+| `--list-fg` | `.bb-radio-group__list--strip` | `var(--bb-text-muted)` | unchecked trigger label |
+| `--hover-fg` | `.bb-radio-group__list--strip` | `var(--bb-text)` | hovered trigger label |
+| `--active-fg` | `.bb-radio-group__list--strip` | `var(--bb-text)` | checked trigger label |
+| `--active-fw` | `.bb-radio-group__list--strip` | `500` | checked trigger label weight (unchecked labels are 500) |
+| `--indicator-bg` | `.bb-radio-group__list--strip` | `var(--bb-panel)` | the indicator's fill |
+| `--indicator-border` | `.bb-radio-group__list--strip` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The indicator's edge |
+| `--indicator-r` | `.bb-radio-group__list--strip` | `var(--trigger-r)` | The indicator's corners — the pill's, concentric inside --list-r |
+| `--indicator-h` | `.bb-radio-group__list--strip` | `initial` | 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` | `.bb-radio-group__list--strip` | `0px` | 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` | `.bb-radio-group__list--strip` | `var(--bb-elev)` | The theme's resting lift, composed UNDER the indicator's own shadow |
+| `--indicator-shadow` | `.bb-radio-group__list--strip` | `var(--bb-shadow-sm)` | Indicator lift, painted on top of --elev |
+| `--list-bg` | `.bb-radio-group__list--line` | `transparent` |  |
+| `--list-border` | `.bb-radio-group__list--line` | `var(--bb-border)` |  |
+| `--p` | `.bb-radio-group__list--line` | `0px` |  |
+| `--list-r` | `.bb-radio-group__list--line` | `0px` |  |
+| `--trigger-r` | `.bb-radio-group__list--line` | `var(--bb-radius-sm)` |  |
+| `--active-fw` | `.bb-radio-group__list--line` | `600` |  |
+| `--indicator-bg` | `.bb-radio-group__list--line` | `var(--bb-primary)` |  |
+| `--indicator-border` | `.bb-radio-group__list--line` | `transparent` |  |
+| `--indicator-r` | `.bb-radio-group__list--line` | `0` |  |
+| `--indicator-h` | `.bb-radio-group__list--line` | `2px` |  |
+| `--indicator-shadow` | `.bb-radio-group__list--line` | `none` |  |
+| `--elev` | `.bb-radio-group__list--line` | `none` |  |