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

package/dist/ai/BbHoverCardPortal.md

@@ -20,7 +20,7 @@
 
 ## Slots
 
-- `default` — scope: `DirectivePortalSlotProps` `{ props: Record<string, unknown>; close: () => void }` — The card's body. `props` is the directive's `portalProps`; `close` closes the card.
+- `default` — scope: `BbHoverCardPortalSlotProps` `{ props: P; close: () => void }` — The card's body. `props` is the directive's `portalProps`; `close` closes the card.
 
 ## See Also
 

package/dist/ai/BbNumberInput.md

@@ -217,14 +217,41 @@ field goes through `2`). Leave the field below `min`, or press Enter in it, and
 it rises to `min` — Enter corrects it before a surrounding form submits, so
 `@submit` never receives a value below `min` (defaults are
 the safe-integer bounds, i.e. effectively unbounded). `maxPrecision` caps the number of decimal places (default `8`),
-which is how you pin a field to whole numbers (`0`) or currency (`2`). Commas are
-accepted as the decimal separator and normalised to a period, so European
-keyboards work without configuration. Grouping separators are read too: with
-both `.` and `,` in the value the last one is the decimal (a pasted `1.234,56`
-or `1,234.56` is 1234.56), and a separator that repeats groups (`1.234.567`).
-Typed key by key, only the European form survives — the field rewrites as you
-type, so a typed `1,234.56` has already turned its first comma into a decimal
-point.
+which is how you pin a field to whole numbers (`0`); for money set `currency`,
+which brings its own decimals. Extra decimals are refused as typed, never
+rounded: with `0`, a typed `,` or `.` stays until blur and the digits after it
+are refused (`12,5` is 12). `minPrecision` (default `0`) is
+its twin: with `2` the field always shows two decimals (`1` shows `1,00`),
+padding with zeros the user types over, while the model stays the number
+(`1.5`).
+
+### Locale display
+
+The field shows its number the way the app's locale writes numbers, while the
+user types: in Italian `10005,6` shows `10.005,6`, in English `10,005.6`.
+Grouping follows each locale (Italian shows `1000` and starts grouping at
+`10.000`). **Type the digits; the field groups them for you; `,` or `.` starts
+the decimals** — whichever key the user presses. An Italian who types the
+thousands dot out of habit (`1.234,56`) still gets 1234.56: the later comma
+turns the earlier dot into grouping. That needs every digit kept, so a field
+with fewer than 3 decimals (`maxPrecision` 0–2, a currency field) refuses a
+second `,` or `.` once a decimal exists: `1.234,50` in a euro field stays
+`1,23 €`. `-` typed anywhere flips the sign, and the caret stays on its digit. A pasted number written the locale's way
+is read that way (`1.000` pasted in Italian is 1000); anything else is read
+like typed text. The paste keeps only the number, the first one when the
+text holds several (`$1,234.56 - $2,000` is 1234.56): `15 m²` is 15,
+accounting brackets `(1,234.56)` are negative, and `1.2E+05` is 120000. With
+`minPrecision`, Backspace at the end walks back over the placeholder zeros
+and the mark first (`1,00|` → `1|,00`, the value kept); the next one deletes
+the digit. A field holds 20 characters; a key, a paste or an autofill past that is
+refused (the field keeps its number), never cut short. On blur the field rebuilds the text from the value, so
+`1,50` shows `1,5` and `007` shows `7` (keep the zeros with `minPrecision`).
+
+The model is always a plain number, and a form posts the raw value (`10005.6`)
+through a hidden input that carries `name`; the visible input has no `name`.
+`event.target.value` and a `pt:input` listener see the formatted text.
+`disable-formatting` shows the number as typed, with a period decimal and no
+grouping, as the field did before.
 
 **Clamped office setpoint, 16–28 °C**
 
@@ -336,11 +363,30 @@ const formattedSubtotal = computed(() =>
 
 ### Currency & unit fields
 
-Combine `maxPrecision="2"`, `min="0"` and the `prefix` / `suffix` slots for money
-and measurement inputs. The affixes are inert decoration inside the field; the
-model stays a clean number.
-
-**Invoice unit price with currency affixes**
+`currency="EUR"` (an ISO 4217 code) shows the amount the locale's way, symbol
+included, inside the text: `1.234,56 €` in Italian, `$1,234.56` in English,
+`CHF-1’234.56` in Swiss German. The decimals follow the currency (2 for EUR,
+0 for JPY, 3 for KWD); `minPrecision` / `maxPrecision` win when you set them.
+`unit="kilogram"` does the same for a measure (`20 kg`, any unit
+`Intl.NumberFormat` knows); `unit="percent"` holds the number you see, so `15%`
+is `15`, not `0.15`. Set one or the other; with both, `currency` wins. The
+model is always the plain number, and `#prefix` / `#suffix` stay free for icons.
+
+The caret stays on the number: a click, Home / End or an arrow on the symbol
+lands at the nearest digit (Home / End move the caret, never the value),
+Backspace after a prefix does nothing, and `-` typed anywhere flips the sign.
+A selection may cover the symbol (select-all copies it), but deleting the
+symbol alone does nothing. Clearing the last digit leaves the field empty (no
+lone `$`), so the placeholder and `required` keep working. A pasted amount,
+symbol and all (`$1,234.56`, `1.234,56 €`, `1,234 kg`), is read as the number;
+another currency's symbol is dropped and the amount kept, with no conversion.
+The unit follows the number's plural (`1 hr`, `2 hrs`), and at rest a screen
+reader hears the amount spelled out (`1,234.50 US dollars`, `20 kilograms`).
+Percent is written the locale's way: `15%` in English and Italian, `15 %` in
+German and French, `%15` in Turkish. `unit` is typed: `kilowatt` and
+`square-meter` are not `Intl` units, so they are type errors.
+
+**Invoice unit price in dollars, discount in percent**
 
 ```vue
 <template>
@@ -348,21 +394,27 @@ model stays a clean number.
 		<div>
 			<p class="text-sm font-medium">Line item · INV-2048</p>
 			<p class="text-xs text-(--bb-text-muted)">
-				Currency stays in the chrome; the model is a clean number.
+				The symbol sits in the text; the model is a clean number.
 			</p>
 		</div>
 		<BbNumberInput
 			v-model="price"
 			compact
+			currency="USD"
 			label="Unit price"
-			:max-precision="2"
 			:min="0"
 			name="unit-price"
 			:step="0.5"
-		>
-			<template #prefix>$</template>
-			<template #suffix>USD</template>
-		</BbNumberInput>
+		/>
+		<BbNumberInput
+			v-model="discount"
+			compact
+			label="Discount"
+			:max="100"
+			:min="0"
+			name="discount"
+			unit="percent"
+		/>
 	</div>
 </template>
 <script setup lang="ts">
@@ -370,6 +422,8 @@ import { ref } from 'vue';
 import { BbNumberInput } from 'bitboss-ui';
 
 const price = ref<number | null>(49.99);
+// `unit="percent"` holds the number you see: 15 shows `15%`.
+const discount = ref<number | null>(15);
 </script>
 ```
 
@@ -762,6 +816,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - Don't rebuild parsing/clamping in a watcher; the component already sanitises,
   clamps and limits precision.
 - Icon-only stepper buttons **require** an `aria-label`.
+- Don't put a currency symbol in `#prefix` / `#suffix` text: use `currency`,
+  which places it the locale's way and sets the decimals. With `currency` or
+  `unit`, `maxlength`, `pattern`, `event.target.value` and a `pt:input`
+  listener see the symbol too; `disable-formatting` drops both.
 - `layout` is ignored under `labelMode="floating"`/`"inside"` — those modes
   embed the label in the field and force the vertical layout; it works with the
   default `'outside'` mode.
@@ -771,6 +829,11 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - The field carries `role="spinbutton"` and mirrors `min` / `max` / current
   value into `aria-valuemin` / `aria-valuemax` / `aria-valuenow`, so keep `min`
   and `max` set when the range is known.
+- At rest the field sets `aria-valuetext` to the formatted text (`12.345,5`);
+  while it has focus it sets none, so the value is not announced again on
+  every keystroke. With `currency` / `unit` it is the spoken amount
+  (`1,234.50 US dollars`, `20 kilograms`); `aria-valuenow` stays the number.
+- Grouped text is wider: check a narrow fixed-width field at 200% zoom.
 - ArrowUp / ArrowDown step the value natively — don't rebuild that with custom
   key handlers.
 - `hasErrors` / non-empty `errors` set `aria-invalid`; `disabled` / `readonly`
@@ -792,8 +855,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
 | `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-input-h`, `--bb-input-py` and `--bb-label-spacing-y` for their `-compact` twins on the field, so a `--bb-input-h` you set on the component is ignored while `compact` is on: size a compact field with `--bb-input-h-compact` (and `--bb-input-py-compact`) instead. |
+| `currency` | `string \| undefined` |  |  | An ISO 4217 code (`'EUR'`, `'USD'`, `'JPY'`): the field shows the amount the locale's way, symbol included (`1.234,56 €` in Italian, `$1,234.56` in English), inside the text, so `#prefix` / `#suffix` stay free. The model is the number (`1234.56`). The decimals default to the currency's own; `minPrecision` / `maxPrecision` win when set. One or the other with `unit`. |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `disableFormatting` | `boolean \| undefined` | `false` |  | Shows the number as typed, with a period decimal and no grouping — the field before Q60.25: no locale display, `name` on the visible input. Without it the field shows the number the locale's way while the user types (`10.005,6` in Italian), groups it for them, and posts the raw value (`10005.6`) through a hidden input carrying `name`. |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
@@ -809,8 +874,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper'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'`. |
 | `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
 | `max` | `number \| undefined` | `Number.MAX_SAFE_INTEGER` |  | Maximum value cap. |
-| `maxPrecision` | `number \| undefined` | `8` |  | Maximum precision of the number. |
+| `maxPrecision` | `number \| undefined` | `8` |  | Maximum precision of the number: fraction digits past it are refused as typed (never rounded). With `currency`, the currency's own digits (`2` for EUR, `0` for JPY, `3` for KWD), or `minPrecision` when that is larger. |
 | `min` | `number \| undefined` | `Number.MIN_SAFE_INTEGER` |  | Minimum value cap. Applied on blur and on Enter (before a surrounding form submits), not while typing, so a value above a `min` greater than 1 can be typed digit by digit. |
+| `minPrecision` | `number \| undefined` | `0` |  | Fraction digits always shown (`2`: `1` shows `1,00`, `1,5` shows `1,50`), also while typing, where the padding zeros are placeholders the user types over. The model stays the number (`1.5`). A `minPrecision` above `maxPrecision` gives way to it. Applies with `disableFormatting` too (the padding only, period decimal). With `currency`, the currency's own digits (`2` for EUR, `0` for JPY). |
 | `modelValue` | `string \| number \| null \| undefined` | `null` |  | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
@@ -821,6 +887,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `rules` | `RuleExpression<string \| number \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `step` | `number \| undefined` | `1` |  | Incremental unit used by ArrowUp / ArrowDown and by the `increase` and `decrease` functions the slots receive. It is NOT applied to manual input as a step of 5 would prevent the user from inserting a value like `115` because of rounding down. |
+| `unit` | `BbNumberUnit \| undefined` |  |  | A unit `Intl.NumberFormat` knows (`'kilogram'`, `'kilometer-per-hour'`, `'celsius'`, `'percent'`; a typo is a type error): the field shows it the locale's way inside the text (`20 kg`, `15 %`). The model is the number you see: `unit="percent"` showing `15 %` holds `15`, not `0.15`. One or the other with `currency` (set both and `currency` wins). |
 | `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; the field's `name` never shows. Set it when the label is not a good noun for a sentence (an icon-only label, a question) or is hidden. Only inside a `BbForm`. |
 | `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When this field checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
 | `variant` | `'outline'` \| `'secondary'` \| `'none'` \| `'ghost'` | `'outline'` |  | Visual variant of the field box — the same names and tokens as the `BbButton` variants. Colours only: height, padding and border width are identical across variants, so a form never reflows when one changes. `'ghost'` has no border in any state (errors and warnings show through the icon and the messages); every variant keeps the focus ring. Register extra names with the plugin's `inputVariants` option. `'none'` is a blank starting point: the field keeps its structure and behaviour but takes no look, so your own classes don't fight a built-in one. You then own hover, focus, disabled and the error / warning states. Fine for a one-off; keep inline styling short, and register a real variant (`inputVariants`) when the look recurs. |
@@ -902,7 +969,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 `BbNumberInput`'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 `BbNumberInput`'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/BbNumberInput.tree.json`.
 
-- `BbNumberInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-number-input__input`, `input` → `input.bb-number-input__input`
+- `BbNumberInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-number-input__input`, `input` → `input.bb-number-input__input`, `controlAttrs` → `input`
   - `CommonField` _(internal — not importable, reach it through `BbNumberInput`)_ — `BbNumberInput`'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`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbNumberInput`)_ — `BbNumberInput`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--fg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
 

package/dist/ai/BbPopover.md

@@ -42,12 +42,12 @@ Pick a sibling when the shape is more specific:
 - A focused, page-blocking task → `BbDialog`; supplementary side content →
   `BbOffCanvas`.
 
-`BbPopover` looks lightweight — it does not dim the page, and an outside click
-dismisses it — but it **is** modal underneath: a `<dialog>` opened with
-`showModal()`, so focus is trapped and the page behind is inert while it is
-open (see Accessibility). Plan for that: the user cannot interact with the page
-until they dismiss it. If the surface should also _look_ like it owns the
-user's attention until resolved, that is `BbDialog`.
+`BbPopover` is lightweight, and it behaves that way: it does not dim the page,
+the page behind stays live while it is open, and a click outside closes it and
+still reaches what was clicked (see Accessibility). Set `modal` when the panel
+must hold the user until they dismiss it: the page goes inert and Tab stays
+inside. If the surface should also _look_ like it owns the user's attention
+until resolved, that is `BbDialog`.
 
 ### Activator and content
 
@@ -360,8 +360,9 @@ A directive has no slot, so the body is a **portal**, as in `BbConfirm`:
   it). The portal's slot gets `{ props, close }`: `props` is your
   `portalProps`, `close` closes the popover.
 - **A component:** `v-bb-popover="RenameForm"` renders `RenameForm` in the
-  popover; `portalProps` arrive as its real props, and `emit('close')` closes
-  the popover.
+  popover; `portalProps` arrive as its real props. It has no way to close the
+  popover: content that needs `close` is a named portal (its slot has it), or
+  the `BbPopover` component.
 - **The object form** takes either one as `portal`, `portalProps`, and any
   `BbPopover` prop (`width`, `scrollable`, `trigger`, …):
   `{ portal: 'rename-report', portalProps: { report }, width: 260 }`. The
@@ -376,6 +377,15 @@ a field in a named portal declared inside the form. A `<BbPtScope>` around the
 trigger styles the popover too. A component portal remounts on every open, so keep anything that must
 survive between openings outside it.
 
+**Names are checked.** A name is a string on one side and a `<BbPopoverPortal
+name>` on the other, so `bitboss-ui check` and the ESLint rules (in
+`recommended`) read both across the project: `bitboss-ui/portal-names`
+fails on a name no file declares, with a did-you-mean (`'renam'` → `rename`),
+and on a hover-card portal opened by `v-bb-popover` (it names the family the portal belongs to); `bitboss-ui/unused-portal` warns on a
+`<BbPopoverPortal>` nothing opens. Only literal names are judged: a `:name`
+binding or a name held in a variable is never reported. The slot's `props`
+is `any` per key, so `props.report.title` needs no cast.
+
 **Rename on every row, from the directive**
 
 ```vue
@@ -404,26 +414,17 @@ survive between openings outside it.
 
 	<!-- Declared once; renders only in the popover that opens. -->
 	<BbPopoverPortal v-slot="{ props, close }" name="rename-report">
-		<form
-			class="grid gap-2"
-			@submit.prevent="rename(props.report as Report, close)"
-		>
+		<form class="grid gap-2" @submit.prevent="rename(props.report, close)">
 			<BbTextInput
 				label="Title"
-				:model-value="draftOf(props.report as Report)"
-				@update:model-value="drafts[(props.report as Report).id] = $event ?? ''"
+				:model-value="draftOf(props.report)"
+				@update:model-value="drafts[props.report.id] = $event ?? ''"
 			/>
 			<div class="flex justify-end gap-2">
-				<BbButton
-					variant="ghost"
-					@click="discard(props.report as Report, close)"
-				>
+				<BbButton variant="ghost" @click="discard(props.report, close)">
 					Cancel
 				</BbButton>
-				<BbButton
-					:disabled="!draftOf(props.report as Report).trim()"
-					type="submit"
-				>
+				<BbButton :disabled="!draftOf(props.report).trim()" type="submit">
 					Save
 				</BbButton>
 			</div>
@@ -667,12 +668,13 @@ height; without it a tall panel grows freely.
 - `transition-duration` (ms) times the open/close animation.
 - For imperative open/close, use `v-model`: write `true` to open and `false` to
   close, and the popover writes it back on every dismiss (outside click, Escape,
-  backdrop) — the self-correcting two-way model `BbDialog`/`BbOffCanvas` use.
+  Tab out) — the self-correcting two-way model `BbDialog`/`BbOffCanvas` use.
   There is no template-ref `show()`/`close()` API; the boolean model is it.
 
 ### Top layer: escaping overflow and z-index
 
-The floating panel opens in the browser **top layer** (a native `<dialog>`), so
+The floating panel opens in the browser **top layer** (a native popover, or a
+`<dialog>` with `modal`), so
 it paints above every `z-index`, sticky header, `overflow: hidden` clip, or
 transformed ancestor — there is nothing to z-index-manage, and a popover inside
 a scrolling card or table cell is not clipped by it. A popover, select, or
@@ -820,8 +822,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 - **Don't forget to spread `props`** onto the activator (or pass an `activator`
   ref) — without it there is no anchor, no ARIA, and no open handler.
-- **Don't put a blocking task in a popover** — it doesn't lock the page and
-  dismisses on outside click; use `BbDialog`.
+- **Don't put a blocking task in a popover** — it doesn't dim the page and
+  dismisses on outside click, even with `modal`; use `BbDialog`.
 - **Don't reach for a popover when you mean a menu** — a plain list of actions is
   `BbDropdown`.
 - **Don't set `width` and expect it on mobile** — the adaptive sheet ignores it;
@@ -839,19 +841,23 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   `activator`); that is what publishes `aria-expanded` / `aria-controls` /
   `aria-haspopup` and makes the trigger operable by keyboard.
 - Focus moves into the panel on open and returns to the activator on close;
-  `focus-target` overrides where it lands first.
-- **The popover is modal, despite looking like it isn't.** It renders as a
-  `<dialog>` opened with `showModal()` (in `CommonPopover.vue`), so while it is
-  open Tab is trapped inside it and the rest of the document is inert —
-  `dialog.matches(':modal')` is `true`. What makes it _read_ as non-modal is
-  that the `::backdrop` is merely `background-color: transparent`: the page
-  behind stays fully visible and un-dimmed. That transparent backdrop is also
-  what makes click-outside-to-close work — the outside click lands on it, and
-  `@click.self` closes the panel.
-  Consequence for design: do **not** plan a flow where the user keeps working
-  behind an open popover. They cannot. If the surrounding page must stay live,
-  use a non-modal surface instead. For a blocking task that should _look_
-  blocking, use `BbDialog`, which dims its backdrop.
+  `focus-target` overrides where it lands first. A click outside is the
+  exception: the popover closes and focus stays where the user clicked.
+- **The popover is a non-modal dialog.** The panel is `role="dialog"` without
+  `aria-modal`: the page behind stays clickable, focusable and scrollable while
+  it is open. A click outside closes it _and_ reaches what was clicked, so one
+  click both dismisses the popover and presses the button behind it. Tab past
+  the last control (or Shift+Tab before the first) leaves the panel and closes
+  it; Escape closes it and returns focus to the activator.
+- **`modal` makes it a modal dialog.** The panel becomes a `<dialog>` opened
+  with `showModal()`: Tab stays inside, the rest of the document is inert and
+  the page cannot scroll, and an outside click only closes the panel (it lands
+  on the transparent backdrop, not on the page). Reach for it when the user
+  must finish or dismiss the panel before touching the page, and for a
+  blocking task that should _look_ blocking, use `BbDialog`, which dims its
+  backdrop.
+- **The phone sheet is always modal**, whatever `modal` says: it is a
+  `BbOffCanvas` that covers the bottom of the screen.
 - Give an icon-only activator its own `aria-label`; the popover does not name it.
 
 ## v-model
@@ -867,9 +873,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile viewports (below `config.mobileMaxWidth`), render the popover as a bottom-anchored, auto-sized off-canvas sheet instead of a floating panel. The `header`, `default` and `footer` slots are forwarded to the sheet. The `width` prop is intentionally ignored in this mode (it means a different thing for a sheet); pass `offCanvasProps` to size or otherwise customise the sheet. When unset, falls back to the global `config.adaptive`. |
 | `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. When provided, the popover will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the panel's content at mount instead of on the first open (the phone sheet's too). |
 | `focusTarget` | `string \| undefined` |  |  | Selector for the element that receives focus after opening. Defaults to the first focusable element inside the popover. |
 | `id` | `string \| undefined` |  |  | The activator's id (the panel is `bbp_<id>` and is labelled by it). Generated when omitted. |
+| `modal` | `boolean \| undefined` | `false` |  | Makes the floating panel modal: the page behind it goes inert and cannot scroll, and Tab stays inside the panel until it closes. Off by default, the panel is a non-modal dialog: the page stays usable, a click outside closes it and still reaches what was clicked, and Tab past its last control (or Shift+Tab before its first) leaves it and closes it. The phone sheet is modal either way. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the popover. A popover with no `v-model` starts closed and is driven by its `trigger`. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`side: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. |
 | `offset` | `number \| undefined` | `4` |  | Space the floating container will maintain from the activator. |

package/dist/ai/BbPopoverPortal.md

@@ -20,7 +20,7 @@
 
 ## Slots
 
-- `default` — scope: `DirectivePortalSlotProps` `{ props: Record<string, unknown>; close: () => void }` — The popover body. `props` is the directive's `portalProps`; `close` closes the popover.
+- `default` — scope: `BbPopoverPortalSlotProps` `{ props: P; close: () => void }` — The popover body. `props` is the directive's `portalProps`; `close` closes the popover.
 
 ## See Also
 

package/dist/ai/BbProgress.md

@@ -12,11 +12,12 @@
 
 ### When to use
 
-`BbProgress` is for **determinate** progress — a task whose completion you can
-measure: an upload, a multi-step setup, a storage quota. Bind the current value
-with `:model-value` and the bar fills from `min` to `max`. If the wait has no
-measurable end, use [`BbSpinner`](./BbSpinner.md) instead — passing `null` here
-renders an _empty_ bar, not an animated indeterminate state.
+`BbProgress` is for progress you can show as a bar: an upload, a multi-step
+setup, a storage quota. Bind the current value with `:model-value` and the bar
+fills from `min` to `max`. While the wait has no measurable end yet, set
+`indeterminate`: the bar slides and reports no value. Passing `null` alone
+renders an _empty_ bar, not the indeterminate one. For a wait with no bar at all
+(a button, a small inline busy mark), use [`BbSpinner`](./BbSpinner.md).
 
 The component is purely presentational: it emits no events and never changes the
 value on its own. `v-model` compiles but has nothing to write back — prefer the
@@ -197,14 +198,29 @@ toast({
 });
 ```
 
+### A wait with no measurable end: `indeterminate`
+
+`indeterminate` slides a short bar across the track (a slow pulse in place
+under `prefers-reduced-motion`) and the progressbar reports no value, which is
+how assistive tech hears "busy, amount unknown". The `model-value` is kept:
+turn `indeterminate` off and the bar shows it again.
+
+**Preparing an export**
+
+```vue
+<div class="flex max-w-sm flex-col gap-2">
+	<span class="text-sm">Preparing your export…</span>
+	<BbProgress indeterminate label="Export" :model-value="0" />
+</div>
+```
+
 ### Handing off to an unmeasurable phase
 
 Uploads often finish before the work does: the server still parses rows,
-transcodes, indexes — with no measurable progress. Swap the bar for
-[`BbSpinner`](./BbSpinner.md) at that boundary instead of faking a bar that
-creeps toward 99%. The determinate phase gets `BbProgress`, the indeterminate
-one gets a spinner, and completion is derived from your own state — the bar
-emits nothing.
+transcodes, indexes — with no measurable progress. Don't fake a bar that
+creeps toward 99%: switch the same bar to `indeterminate` at that boundary, or
+swap it for [`BbSpinner`](./BbSpinner.md) as the example below does. Completion
+is derived from your own state — the bar emits nothing.
 
 **CSV import: upload, then processing**
 
@@ -411,8 +427,9 @@ scattered per-usage.
 `pt` reaches a named part with a class list — or, in the object form, a
 style and attributes. Parts: `root` (the track; the bar follows it through
 `--track`, `--track-color`, `--accent` and `--r`) and `bar` (the fill
-itself, `.bb-progress__bar`). No states — nothing it
-paints is a state.
+itself, `.bb-progress__bar`). One state, `indeterminate`, on while the
+bar slides: `pt:bar:indeterminate="bg-(--bb-info)"` tints only the sliding
+bar.
 
 `pt:root` is plain `class` with extra letters: on the track, write `class` /
 `style` on the tag. Reach for `pt:bar` when the fill needs more than a
@@ -449,9 +466,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 ### Works well with
 
 - `BbDropzone` — captures the files; you upload and drive the bar (see above).
-- [`BbSpinner`](./BbSpinner.md) — for the phases you _can't_ measure (e.g.
-  server-side processing after the upload hits 100%). Swap components, don't
-  fake a creeping bar — see the CSV import example above.
+- [`BbSpinner`](./BbSpinner.md) — for a busy mark with no bar at all (a
+  button, an inline status). Inside a bar, an unmeasurable phase is
+  `indeterminate`, not a creeping fake — see the CSV import example above.
 - `useToast` — announce completion once the task finishes; the bar alone is a
   silent visual.
 - `BbTable` — for table data loads use its built-in `loading` skeleton, not a
@@ -459,8 +476,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 ### Gotchas & anti-patterns
 
-- **`modelValue: null` renders an empty bar.** There is no indeterminate
-  animation; for unknown waits use `BbSpinner`.
+- **`modelValue: null` renders an empty bar**, not an indeterminate one: set
+  `indeterminate` for a wait with no measurable end.
 - **Don't restate the built-in ARIA.** The bar already exposes
   `role="progressbar"` with `aria-valuemin/max/now` — wrapping it in another
   `role="progressbar"` double-announces (see Accessibility). Add a label, not
@@ -478,10 +495,12 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 The bar carries its own ARIA: `role="progressbar"` with `aria-valuemin`,
 `aria-valuemax`, and `aria-valuenow` kept in sync with `min`/`max`/the model
 value (out-of-range values are clamped, matching the visual fill). A `null`
-value reports `aria-valuenow` = `min`, matching the empty bar it renders —
-the component never signals "indeterminate" to assistive tech, because it has
-no indeterminate mode (that's `BbSpinner`). Do **not** wrap the component in
-another `role="progressbar"`.
+value reports `aria-valuenow` = `min`, matching the empty bar it renders. With
+`indeterminate` the bar omits `aria-valuenow` (and holds back an
+`aria-valuetext` you passed), which is how a progressbar says "indeterminate";
+both come back when it turns off. If the bar describes a region that is
+loading, mark that region `aria-busy="true"` meanwhile. Do **not** wrap the
+component in another `role="progressbar"`.
 
 What's still on you:
 
@@ -516,7 +535,8 @@ What's still on you:
 
 | 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: `bar`, `root`. States: —. 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 `BbProgressProps['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: `bar`, `root`. States: `indeterminate`. 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 `BbProgressProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `indeterminate` | `boolean \| undefined` | `false` |  | A wait you cannot measure yet: the bar slides back and forth (a calm pulse under `prefers-reduced-motion`) and the progressbar reports no value (`aria-valuenow` is omitted, as the ARIA pattern asks). The `modelValue` is kept and shows again when this turns off. A `null` `modelValue` alone is still an empty bar, not this. |
 | `label` | `string \| undefined` | `undefined` |  | Accessible name for the progress bar, forwarded to `aria-label`. A `progressbar` with no name is announced only as a bare percentage, so give it one whenever the surrounding text doesn't already name it (e.g. `"Upload"`). Matches the `label` naming prop on BbSpinner / BbIcon. |
 | `max` | `number \| undefined` | `100` |  | Maximum value. Upper cap. |
 | `min` | `number \| undefined` | `0` |  | Minimum value. Lower cap. |
@@ -531,6 +551,12 @@ What's still on you:
 | `root` | The track (the `progressbar` element); the bar follows it through its locals (`--track`, `--track-color`, `--accent`, `--r`, the same words as BbSlider's rail and bar). |
 | `bar` | The fill itself. Its inline `transform` IS the value (it slides from -100% to 0), so style its look here — colour, gradient, radius — never its position. |
 
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `indeterminate` | Component-wide: `indeterminate` is on; the bar slides (pulses under reduced motion) instead of showing a value. |
+
 ## Events
 
 - None.

package/dist/ai/BbRadioGroup.md

@@ -54,18 +54,14 @@ Choose by shape:
 
 ### Items and value mapping
 
-**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
-<BbRadioGroup
-	v-model="plan"
-	legend="Plan"
-	:items="plans"
-	item-text="label"
-	item-value="value"
-/>
+<BbRadioGroup v-model="plan" legend="Plan" :items="plans" />
 ```
 
 Pass domain objects to `items` and resolve the display text and stored value
@@ -121,7 +117,8 @@ const plan = ref<string>('pro');
 
 #### 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.
@@ -461,7 +458,6 @@ valid yet" and gate the submit on it.
 		<BbRadioGroup
 			v-model="branch"
 			compact
-			item-text="label"
 			item-value="id"
 			:items="branches"
 			legend="Target branch"
@@ -475,7 +471,6 @@ valid yet" and gate the submit on it.
 			:deps-debounce-time="150"
 			enforce-coherence
 			hint="Protected branches require a linear history."
-			item-text="label"
 			item-value="id"
 			:items="loadStrategies"
 			legend="Merge strategy"
@@ -561,7 +556,6 @@ whenever the slot is empty.
 			v-model="theme"
 			class="theme-tiles"
 			item-layout="vertical"
-			item-text="label"
 			item-value="id"
 			:items="themes"
 			legend="Appearance"
@@ -752,7 +746,6 @@ const plan = ref<string>('pro');
 		<BbRadioGroup
 			v-model="theme"
 			item-layout="vertical"
-			item-text="label"
 			item-value="id"
 			:items="themes"
 			legend="Appearance"
@@ -829,8 +822,9 @@ for a preset that fits any row type (never `<any>`), not an imported
   nothing.
 - `readonly` still submits its value and stays focusable; use `disabled` only
   when the whole choice doesn'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).
 
 ### Accessibility
 
@@ -889,8 +883,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: BbRadioGroupItemsContext) => 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 `BbRadioGroupItemsContext`. |
-| `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. |