bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/ai/BbOffCanvas.md

@@ -161,13 +161,68 @@ header and footer stay pinned.
 
 - Use the `title` slot to restyle just the title text — it stays wired to
   `aria-labelledby` and receives the `title` prop as `text`.
-- Unlike `BbDialog`, the **`header` slot is fully supported here** and replaces
-  the whole header section; it receives `titleId`, `title` and `close`, so you
-  can build a custom header and still keep the accessible name wired through
-  `titleId`.
+- **`description`** adds one muted line under the title — the panel's subtitle,
+  and the only thing `aria-describedby` points at. Keep it to a sentence; the
+  body is deliberately not described. The `description` slot takes markup and
+  receives the prop as `text`. A panel without one keeps its original
+  single-row header.
+- The **`header` slot** replaces the whole header section; it receives
+  `titleId`, `title` and `close`, so you can build a custom header and still
+  keep the accessible name wired through `titleId`. `BbDialog` supports the
+  same slot with the same payload, and forwards it to its adaptive sheet — the
+  two surfaces are symmetric here.
 - Omitting `title` (and the `header` slot) removes the header entirely — you
   then own the accessible name.
 
+**A described panel (via the #description slot)**
+
+```vue
+<template>
+	<BbButton
+		prepend:icon="lucide:user-plus"
+		variant="outline"
+		@click="open = true"
+	>
+		Invite teammate
+	</BbButton>
+	<BbOffCanvas v-model="open" side="right" title="Invite teammate">
+		<!-- The slot takes markup where the prop would only take a string. -->
+		<template #description>
+			They join the <strong>Northwind</strong> workspace as a viewer.
+		</template>
+		<div class="grid gap-3">
+			<BbTextInput
+				v-model="email"
+				compact
+				label="Email"
+				placeholder="ada@northwind.co"
+				type="email"
+			/>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton
+					:disabled="!email.trim()"
+					variant="primary"
+					@click="open = false"
+				>
+					Send invite
+				</BbButton>
+			</div>
+		</template>
+	</BbOffCanvas>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
+
+const open = ref(false);
+const email = ref('');
+</script>
+```
+
 ### A filters drawer
 
 The archetypal off-canvas: search + toggles in the `default` slot, Apply/Reset
@@ -566,15 +621,26 @@ Set `draggable` to let the user flick the panel toward its edge to dismiss; a
 grab handle appears on the inner edge as the affordance. A draggable,
 `auto`-sized bottom panel is the canonical mobile sheet.
 
-The gesture is physical, not just a tap target:
-
-- Dragging past **a quarter of the panel's extent**, or a fast **flick toward
-  the edge**, dismisses it; a shorter drag springs back to fully open.
-- On a vertical (top/bottom) sheet with a scrollable body, the drag **hands off
-  to native scrolling** first — you only start dragging the sheet once the body
-  is scrolled to its edge, so scrolling a long sheet never accidentally closes
-  it.
-- `persistent` / `disabled` still win: a drag that would dismiss instead plays
+The gesture is powered by VueUse `useSwipe` with a **fixed pixel threshold**
+(not a fraction of the panel height), so a tall filters sheet and a short menu
+dismiss with the same motion:
+
+- Swiping **about 50px toward the exit edge** dismisses it; a shorter swipe
+  springs back. Motion matches Vaul: the sheet exits on inline `transform`
+  (iOS easing, 500ms) while the backdrop fades on the same clock. Styles stay
+  frozen off-screen until the normal close wait finishes, so `dialog.close()`
+  does not flash the panel or jump the blur. Escape / backdrop / × still use
+  the open/close `translate` path.
+- Only travel on the dismiss axis counts — a mostly horizontal flick on a short
+  bottom sheet does not latch or close it.
+- On a vertical sheet with a scrollable body, the swipe **hands off to native
+  scrolling** first — you only drag the sheet once every scrollable ancestor
+  under the finger is at its dismiss edge (latched at touchstart, so a row
+  button and the empty panel chrome behave the same). A downward flick that
+  starts by scrolling _into_ the list stays a scroll for the rest of the
+  gesture; once the sheet is following the finger, reversing back to rest
+  does not start a scroll — lift to cancel.
+- `persistent` / `disabled` still win: a swipe that would dismiss instead plays
   the "deny" nudge and springs back.
 
 **A draggable bottom sheet**
@@ -912,6 +978,8 @@ The panel is a native `<dialog>` opened with `showModal()` — the same mechanic
 - The panel is a true modal (`showModal()`): focus is contained within it, the
   page behind is inert, and focus returns to the trigger when it closes.
   `focus-target` only chooses where focus **starts**.
+- `description` is what `aria-describedby` points at, so the panel announces
+  its purpose and not just its name.
 - The header close button carries a localized `aria-label` out of the box
   (`config.locale`).
 - Draggable dismissal is a convenience, not the only way out — the close button,
@@ -928,20 +996,21 @@ The panel is a native `<dialog>` opened with `showModal()` — the same mechanic
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `disabled` | `boolean \| undefined` |  |  | Disable EVERY user-initiated dismissal: backdrop click, Escape, drag-to-dismiss AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the drawer cannot be dismissed mi… |
-| `draggable` | `boolean \| undefined` | `false` |  | Enable drag-to-dismiss. The panel can be dragged from anywhere toward its edge to close, and a grab handle is shown on the inner edge as the affordance. When `false`, the panel is static (dismiss via the close button, backdrop, or Escape on… |
-| `eager` | `boolean \| undefined` |  |  | Render offcanvas content immediately instead of waiting for the first open. |
+| `description` | `string \| undefined` |  |  | One short line under the title, in the header — the shadcn `DialogDescription` shape: same block as the title, lower hierarchy, muted. It is also what `aria-describedby` points at. That wiring was dropped in v3 along with the old `descripti… |
+| `disabled` | `boolean \| undefined` | `false` |  | Disable EVERY user-initiated dismissal: backdrop click, Escape, drag-to-dismiss AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the drawer cannot be dismissed mi… |
+| `draggable` | `boolean \| undefined` | `false` |  | Enable drag-to-dismiss via VueUse `useSwipe` (fixed ~50px threshold toward the exit edge, including from the scrollable body once it is at its scroll edge). A grab handle on the inner edge is the visual cue. When `false`, the panel is stati… |
+| `eager` | `boolean \| undefined` | `false` |  | Render offcanvas content immediately instead of waiting for the first open. |
 | `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
 | `fullscreen` | `boolean \| "mobile" \| undefined` |  |  | Display the offcanvas fullscreen. Use `'mobile'` to restrict fullscreen to small devices. |
-| `hideClose` | `boolean \| undefined` |  |  | Hides the default close (×) button in the header (e.g. for a `persistent` drawer you don't want dismissible — the × otherwise still closes a persistent drawer). |
+| `hideClose` | `boolean \| undefined` | `false` |  | Hides the default close (×) button in the header (e.g. for a `persistent` drawer you don't want dismissible — the × otherwise still closes a persistent drawer). |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the panel. A panel with no `v-model` starts closed. |
-| `persistent` | `boolean \| undefined` |  |  | Prevent closing via outside clicks, Escape key or drag-to-dismiss. The header close (×) button STILL closes a persistent drawer — that is the documented escape hatch; combine with `hideClose` to remove it, or use `disabled` to block every d… |
+| `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks, Escape key or drag-to-dismiss. The header close (×) button STILL closes a persistent drawer — that is the documented escape hatch; combine with `hideClose` to remove it, or use `disabled` to block every d… |
 | `side` | `"left" \| "right" \| "top" \| "bottom" \| undefined` | `"left"` |  | Which viewport edge the offcanvas docks to (and slides in from). |
 | `size` | `Responsive<OffCanvasSize> \| undefined` | `"sm"` |  | Controls the maximum size of the offcanvas panel. Accepts named presets from `'xs'` to `'2xl'`, `'auto'`, a custom CSS size string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch responsive… |
 | `stack` | `string \| undefined` |  |  | Name of the stack this drawer belongs to. Drawers sharing the same `stack` value step back behind one another as later ones open; drawers in different stacks never affect each other. When omitted, the drawer stacks with nothing. |
 | `stackGap` | `number \| undefined` | `60` |  | Pixels each stacked parent drawer shifts inward when a child opens on top, leaving a peeking band of the parent visible. |
 | `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered and accessibility must be handled manually. |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | Controls the duration of the open and close animations. |
+| `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |
 
 ## Events
 
@@ -954,9 +1023,10 @@ The panel is a native `<dialog>` opened with `showModal()` — the same mechanic
 ## Slots
 
 - `default` — scope: `{ close: () => void; }` — Primary body content of the off-canvas panel, rendered in the scrollable body area.
+- `description` — scope: `BbOffCanvasDescriptionSlotProps` — Replaces the description text under the title. Renders the header even when `title` and `description` are unset — a slotted description is a description, the same rule `#title` follows.
 - `footer` — scope: `object` — Content rendered in the panel footer, below the body area. Typically used for action buttons.
 - `header` — scope: `BbOffCanvasHeaderSlotProps` — Replaces the entire off-canvas header section (title + close button). Maintains accessibility wiring via the provided props.
-- `title` — scope: `BbOffCanvasTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`.
+- `title` — scope: `BbOffCanvasTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.
 
 ## See Also
 

package/dist/ai/BbPagination.md

@@ -494,15 +494,15 @@ reach invalid pages.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `align` | `"left" \| "center" \| "right" \| undefined` | `"right"` |  | Alignment of the pagination control. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `ellipsis` | `string \| undefined` | `"..."` |  | String of text displayed in place of hidden pages. |
 | `label` | `string \| undefined` |  |  | Label of the pagination navigation landmark. When unset, falls back to the localized `pagination.label` (`'Pagination'` / `'Paginazione'`). |
 | `maxSize` | `string \| number \| undefined` | `6` |  | Maximum number of clickable pages displayed at all times. This has a tolerance of +/- 1 for odd / even numbering. It does not include ellipses. |
 | `modelValue` | `number \| undefined` | `1` |  | Used by v-model. The 1-based index of the current page — pagination starts on the first page, not page `0`. |
-| `navigation` | `boolean \| undefined` |  |  | Synchronizes the current page with the URL. Pair it with `replace` — see that prop. |
+| `navigation` | `boolean \| undefined` | `false` |  | Synchronizes the current page with the URL. Pair it with `replace` — see that prop. |
 | `perPage` | `string \| number \| undefined` |  |  | Number of items per page. Together with `totalItems` it derives the page count (`ceil(totalItems / perPage)`); when unset, one page holds everything. With a `tableId` it is also published to the shared table context, exactly like the table'… |
 | `queryKey` | `string \| undefined` | `"page"` |  | Defines the query key to reference for maintaining navigation. |
-| `replace` | `boolean \| undefined` |  |  | Replaces history rather than pushing it when changing page. Recommended default whenever `navigation` is on: the URL keeps the current page (deep-linkable, survives reload) while Back returns to the page the user came from, instead of stepp… |
+| `replace` | `boolean \| undefined` | `false` |  | Replaces history rather than pushing it when changing page. Recommended default whenever `navigation` is on: the URL keeps the current page (deep-linkable, survives reload) while Back returns to the page the user came from, instead of stepp… |
 | `tableId` | `string \| undefined` |  |  | Id of a `BbTable` to pair with through the shared table context (see `useBbTableContext`). The current page is kept two-way synced with the table's context state, and the context's page count drives the control, overriding the local props. … |
 | `totalItems` | `string \| number \| undefined` |  |  | Total number of items across all pages. When set, the page count is derived as `ceil(totalItems / perPage)` and wins over `totalPages`. With a `tableId` it is also published to the shared table context, exactly like the table's own `total-i… |
 | `totalPages` | `string \| number \| undefined` |  |  | Total number of pages. A shortcut for when the server reports a page count rather than a row count — a page count derived from `totalItems` (locally or through the shared table context) always wins over it. Falls back to `1` when nothing pr… |

package/dist/ai/BbPopover.md

@@ -27,9 +27,12 @@ Pick a sibling when the shape is more specific:
 - A focused, page-blocking task → `BbDialog`; supplementary side content →
   `BbOffCanvas`.
 
-`BbPopover` is a lightweight floating panel, **not** a blocking modal: it does
-not dim or lock the page, and an outside click dismisses it. If the surface must
-own the user's attention until resolved, that is `BbDialog`.
+`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`.
 
 ### Activator and content
 
@@ -235,10 +238,12 @@ import {
 	BbIcon,
 	BbPopover,
 } from 'bitboss-ui';
-import {
-	demoAvatarTimeout,
-	demoAvatarSrc,
-} from '@/components/BbAvatar/examples/demoAvatars';
+// Inlined rather than imported from BbAvatar's example folder: every example
+// must be copy-pasteable into a consumer project on its own, and a
+// cross-example import is the one thing that breaks that.
+const demoAvatarTimeout = 4000;
+const demoAvatarSrc = (photoId: string, size = 256) =>
+	`https://images.unsplash.com/${photoId}?w=${size}&h=${size}&fit=crop&crop=faces&auto=format`;
 
 const member = {
 	name: 'Maria Bianchi',
@@ -246,7 +251,7 @@ const member = {
 	role: 'Platform engineer · Infra',
 	email: 'maria.bianchi@acme.dev',
 	location: 'Milan, Italy (UTC+2)',
-	src: demoAvatarSrc('Maria Bianchi'),
+	src: demoAvatarSrc('photo-1573496359142-b8d87734a5a2'),
 };
 </script>
 ```
@@ -596,8 +601,18 @@ falls back to `config.adaptive`.
   `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 a floating panel, not a modal — it does not trap focus or lock
-  the page behind it. For a blocking task, use `BbDialog`.
+- **The popover is modal, despite looking like it isn't.** It renders as a
+  `<dialog>` opened with `showModal()` (`CommonPopover.vue:271`), 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.
 - Give an icon-only activator its own `aria-label`; the popover does not name it.
 
 ## v-model
@@ -609,19 +624,19 @@ falls back to `config.adaptive`.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and click events are attached programmatically to the referenced element. |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | 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 i… |
+| `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 i… |
 | `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` |  |  | Disables the component. |
-| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
 | `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 identifier of the component. |
 | `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` |  |  | Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`direction: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | 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`. |
 | `offset` | `number \| undefined` | `3` |  | Space the floating container will maintain from the activator. |
 | `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page. |
-| `placement` | `Placement \| "cursor" \| undefined` | `"bottom"` |  | Position of the popover relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow). |
+| `placement` | `Placement \| "cursor" \| undefined` | `"bottom"` |  | Position of the popover relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (BbPopover never draws an arrow — arrows are tooltip-only in v3.) |
 | `scrollable` | `boolean \| undefined` | `false` |  | Caps the popover height to the available viewport space and enables internal scrolling. Useful for tall content like filter panels. Not recommended for atomic popovers (calendars, color pickers). |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds. |
+| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds. |
 | `trigger` | `PopoverTrigger \| PopoverTrigger[] \| undefined` | `"click"` |  | Interaction(s) that open the popover. Accepts a single trigger or an array to combine them. - `'click'` — left-click / tap (default) - `'contextMenu'` — right-click on desktop, long-press on mobile |
 | `width` | `string \| number \| undefined` |  |  | Width of the popover. Accepts pixels or percentage (relative to activator width). |
 
@@ -644,4 +659,4 @@ falls back to `config.adaptive`.
 
 - [BbTooltip](./BbTooltip.md) — Displays contextual helper text on interaction.
 - [BbDialog](./BbDialog.md) — Presents modal dialogs for focused user interactions.
-- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

package/dist/ai/BbProgress.md

@@ -95,7 +95,8 @@ const nearLimit = usedGb / maxGb >= 0.8;
 `min` shifts the lower bound for ranges that don't start at zero (a sales floor,
 a level's XP band). Out-of-range values are clamped — below `min` renders empty,
 above `max` renders full — and a degenerate range (`max <= min`) safely renders
-an empty bar. Width changes animate over 250 ms on their own; don't add your own
+an empty bar. Value changes animate over 250 ms on their own — via `transform`,
+not `width`, so the bar composites instead of relaying out. Don't add your own
 transition.
 
 **A range that does not start at zero**
@@ -444,8 +445,10 @@ another `role="progressbar"`.
 
 What's still on you:
 
-- **An accessible name.** Pass `aria-label` (or `aria-labelledby`) — it falls
-  through to the progressbar element.
+- **An accessible name.** Prefer the **`label` prop** — it forwards to
+  `aria-label` on the progressbar and is the same naming prop `BbSpinner` and
+  `BbIcon` carry, so one spelling covers all three. A raw `aria-label` (or
+  `aria-labelledby`) still falls through if you need it.
 - **A visible textual value** beside the bar (`72%`, `220 / 500 GB`) so the
   number is legible, not just the geometry. Add `aria-valuetext` when raw
   numbers read poorly (units, steps).
@@ -471,7 +474,7 @@ What's still on you:
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `label` | `string \| 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… |
+| `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… |
 | `max` | `number \| undefined` | `100` |  | Maximum value. Upper cap. |
 | `min` | `number \| undefined` | `0` |  | Minimum value. Lower cap. |
 | `modelValue` | `number \| null` | `0` | yes | The current progress value — a number between `min` and `max`. This is a one-way input prop (BbProgress is a display component and never emits `update:modelValue`); `null` means no value and renders an empty bar. |

package/dist/ai/BbRadio.md

@@ -279,11 +279,12 @@ ring itself.
 - `input-position` / `label-position` (`'left' | 'center' | 'right'`) align the
   button and label text within their columns.
 - `hide-label` keeps the label for screen readers but hides it visually.
-- **`reverse` is inverted.** The prop is wired through an internal negation, so a
-  `BbRadio` is "reversed" by default and `:reverse="false"` is identical to
-  omitting it. Treat `reverse` as a swap-order switch you turn **on**, not a
-  boolean you can turn off. (Same quirk as standalone `BbCheckbox`; the _group_
-  components don't have it.)
+- **`reverse`** swaps the label in front of the button. It is an ordinary
+  opt-in boolean: unset and `:reverse="false"` both put the button first,
+  `reverse` puts the label first. (The source negates it internally to cancel
+  `BbBaseInputContainer`'s own polarity; that is invisible from outside.
+  Earlier revisions of this guide called it a consumer-facing quirk — it is
+  not, and the same correction applies to `BbCheckbox` and `BbSwitch`.)
 
 ### Events and focus
 
@@ -309,8 +310,8 @@ listen to them for side concerns only. `autofocus` focuses the input on mount.
   back to its own generated name.
 - Hand-composed groups have **no** fieldset semantics on their own — wrap them in
   a `role="radiogroup"` element with an accessible name (see Accessibility).
-- `reverse` is inverted (see Layout) — don't rely on `:reverse="false"` doing
-  anything.
+- `reverse` is an opt-in, not a toggle you turn off: unset already means
+  button-first. Setting `:reverse="false"` is legal but says nothing.
 - `checked` + `v-model` together fight; pick one.
 - `readonly` still submits and stays focusable; use `disabled` when the value
   must not post.
@@ -347,11 +348,11 @@ listen to them for side concerns only. `autofocus` focuses the input on mount.
 | `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
 | `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`). |
 | `direction` | `InputDirection \| undefined` | `"auto"` |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `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… |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
@@ -359,10 +360,10 @@ listen to them for side concerns only. `autofocus` focuses the input on mount.
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. Optional: an omitted name falls back to a generated one, unique to this button and stable for its lifetime, so a lone radio needs no name at all. Buttons that must form ONE exclusive group still have to share … |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
 | `value` | `any` |  | yes | Defines the value of the radio input. It can be any serializable value. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |
 

package/dist/ai/BbRadioGroup.md

@@ -98,9 +98,11 @@ option for it rather than expecting a cleared model.
 
 ### Layout and density
 
-`input-direction="horizontal"` lays options in a row for segmented-style
-choices (shipping speed, billing cycle); the default stacks them. `compact`
-tightens spacing. Because a radio group binds a single value, it drives cleanly
+Options flow in a **wrapping row by default** — `BbBaseRadioGroup` defaults its
+direction to `'horizontal'`, which suits segmented-style choices (shipping
+speed, billing cycle). Pass `input-direction="vertical"` to stack them one per
+line, which is what you want for long option text or a scannable list.
+`compact` tightens spacing. Because a radio group binds a single value, it drives cleanly
 from `v-model` inline.
 
 **Horizontal shipping speed**
@@ -313,9 +315,9 @@ const loadStrategies = (
 
 ### Slots
 
-`#label` replaces an option's text (`{ item, text }`); `#icon` replaces the
+`#label` replaces an option's text (`{ item, text, checked }` — `checked` is what tile layouts key off); `#icon` replaces the
 default radio-dot visual for each option (you then own its selected/focus
-styling). `#legend` replaces the fieldset legend (`{ text, hasErrors }`);
+styling). `#legend` replaces the fieldset legend (`{ text, hasErrors, hasWarning }`; the validated wrappers add `showAsterisk`);
 `#prepend` / `#append` inject content inside the options container.
 
 ### Selection tiles
@@ -416,7 +418,8 @@ Two width facts worth knowing before you reach for `width: 100%` anywhere:
 `update:modelValue` (the `v-model` channel) carries the single selected value —
 the only source of selection truth. Native `blur`, `change`, `click`, `focus`,
 `input`, `keydown`, `mousedown`, `mouseup` re-emit with raw payloads, plus
-`inactive` when focus leaves the group; use them for side effects, never to
+`active` when focus enters the group (it drives the hint internally) and
+`inactive` when focus leaves; use them for side effects, never to
 compute selection. `autofocus` focuses the first option on mount.
 
 ### Works well with
@@ -478,18 +481,18 @@ compute selection. `autofocus` focuses the first option on mount.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
 | `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
 | `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
 | `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`). |
 | `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
 | `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… |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
-| `hideLegend` | `boolean \| undefined` |  |  | Visually hides the legend of the fieldset while maintaining accessibility. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use `hideLegend` for that. |
+| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
@@ -505,10 +508,10 @@ compute selection. `autofocus` focuses the first option on mount.
 | `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
 | `name` | `string \| undefined` |  |  | Defines the name of the option inputs. Optional: the options live inside a single component instance, so an omitted name falls back to a generated one that groups them correctly on its own — unique per group, so two groups never clear each … |
 | `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `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. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |
 

package/dist/ai/BbRating.md

@@ -330,15 +330,15 @@ renders SSR-safe markup in Nuxt and Inertia apps.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `clearable` | `boolean \| undefined` |  |  | Allows clearing the selected rating by clicking the current value. |
-| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `clearable` | `boolean \| undefined` | `false` |  | Allows clearing the selected rating by clicking the current value. |
+| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
 | `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`). |
 | `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `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… |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLegend` | `boolean \| undefined` |  |  | Visually hides the legend of the fieldset while maintaining accessibility. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
@@ -347,11 +347,11 @@ renders SSR-safe markup in Nuxt and Inertia apps.
 | `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the legend. |
 | `modelValue` | `number \| null` |  | yes | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the star radio inputs. Optional: the stars live inside a single component instance, so an omitted name falls back to a generated one that groups them correctly on its own. Pass a name only when the value has to be submit… |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
-| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` |  |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `'md'` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
 | `stars` | `number \| undefined` |  |  | Maximum number of stars to render and maximum value of the component. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |