bitboss-ui 3.0.0-beta.24 → 3.0.0-beta.25

package/dist/ai/BbBaseCheckbox.md

@@ -17,6 +17,7 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes this checkbox for assistive technologies. Forwarded to the input as `aria-describedby`. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the checkbox when the page/component loads. Use sparingly to avoid usability issues. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Forces the checkbox checked state (controlled prop). When omitted, the checked state is derived from `modelValue === trueValue`. Deliberately `undefined` rather than `false`, so "unset" stays distinguishable from an explicit `:checked="fals… |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. Also applied when `readonly` is set, since native checkboxes do not support `readonly`. |

package/dist/ai/BbBaseCheckboxGroup.md

@@ -27,9 +27,10 @@
 | `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state. Errors take priority when both are set. |
 | `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. |
 | `id` | `string \| undefined` |  |  | Identifier of the group. Used to derive per-option IDs for accessible labeling. |
+| `itemProps` | `ItemProps<T, OptionGroupItemFields> \| 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… |
 | `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Items provider. Can be: - An array of items - A sync/async function `(prefill, modelValue) => items` When a function is provided, it is invoked on prefill and when dependencies change to load options dynamically. |
 | `itemText` | `(T extends object ? string \| ((item: T) => string) : (item: T) => string) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the display text from an item. Accepts a nested key path into the item or a function `(item) => string`. |
-| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the value from an item. Accepts a nested key path into the item or a function `(item) => any`. |
+| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` |  |  |  |
 | `loadingText` | `string \| undefined` | `'Loading...'` |  | Text displayed while items are loading. |
 | `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items. |
 | `modelValue` | `any` |  | yes | Selected values for the group. Used with `v-model`. Single value when `multiple` is false, array when `multiple` is true. |

package/dist/ai/BbBaseColorInput.md

@@ -20,6 +20,7 @@
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. When true the picker shows an opacity slider and emits / accepts `#RRGGBBAA` hex8 values. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of element(s) describing this input for assistive tech (space-separated). Typically includes the container hint id if used within a BaseInputContainer. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Autocomplete hint for the browser. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the input on mount. |
 | `clearable` | `boolean \| undefined` | `false` |  | Show a clear button when the input has a value. |

package/dist/ai/BbBaseInputContainer.md

@@ -44,5 +44,6 @@
 
 ## Slots
 
+- `description` — scope: `BaseInputContainerLabelSlotProps` — Replaces the description text. Rendering the slot alone (no `description` prop) shows the description region and wires it into `aria-describedby`. Stacks below the label, never beside it.
 - `input` — scope: `BaseInputContainerInputSlotProps` — The form control to render, positioned in the input column. Receives pre-computed wiring attributes so the inner input can be correctly associated with the label and hint.
 - `label` — scope: `BaseInputContainerLabelSlotProps` — Replaces the default label text. The outer label element and its `for` association are always rendered.

package/dist/ai/BbBaseNumberInput.md

@@ -18,6 +18,7 @@
 | --- | --- | --- | --- | --- |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of descriptive elements announced by screen readers. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically after mount. |
 | `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever a value is present and the control is interactive. |

package/dist/ai/BbBaseRadio.md

@@ -17,6 +17,7 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of descriptive elements associated with the radio. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the control automatically after mount. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Force the radio into a checked state regardless of `modelValue`. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disable the radio. When combined with `readonly`, the control is also disabled to mimic native behaviour. |

package/dist/ai/BbBaseRadioGroup.md

@@ -28,6 +28,7 @@
 | `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling to the group. Errors take priority when both are set. |
 | `hideLabel` | `boolean \| undefined` | `false` |  | Hide the visual label while keeping it accessible. |
 | `id` | `string \| undefined` |  |  | Explicit id for the fieldset. Used to generate ids for individual radios. |
+| `itemProps` | `ItemProps<T, OptionGroupItemFields> \| 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… |
 | `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Array of items or function to load them asynchronously. |
 | `itemText` | `(T extends object ? NestedKeyOf<T> \| ((item: T) => string) : ((item: T) => string) \| undefined) \| undefined` |  |  | Path to item property for display text or function to extract it. |
 | `itemValue` | `(T extends object ? NestedKeyOf<T> \| ((item: T) => string) : ((item: T) => any) \| undefined) \| undefined` |  |  | Path to item property for value or function to extract it. |

package/dist/ai/BbBaseSelect.md

@@ -36,6 +36,7 @@
 | `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). |
 | `id` | `string \| undefined` |  |  | Explicit id for the control element. Also used to generate listbox and search input ids. |
 | `itemHeight` | `number \| undefined` |  |  | Height of options in the listbox (px). |
+| `itemProps` | `ItemProps<Item, SelectItemFields> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Accepted fields: - `description` — a muted line under the option label. Setting it gives every row a fixed two-line height (th… |
 | `items` | `Item[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<Item[]>) \| ((query: string, prefill: boolean, modelValue: any) => Item[])` |  | yes | Array of items or async loader function. Loader functions receive `(query, prefill, modelValue)`; `modelValue` is the raw v-model: an array in `multiple` mode, the raw model value (possibly `null`) in single mode. |
 | `itemText` | `string \| ((item: Item) => string) \| undefined` |  |  | Path or function to extract display text from an item. |
 | `itemValue` | `string \| ((item: Item) => string) \| undefined` |  |  | Path or function to extract a value from an item. |

package/dist/ai/BbBaseSwitch.md

@@ -17,6 +17,7 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes this checkbox for assistive technologies. Forwarded to the input as `aria-describedby`. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the checkbox when the page/component loads. Use sparingly to avoid usability issues. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Forces the checkbox checked state (controlled prop). When omitted, the checked state is derived from `modelValue === trueValue`. Deliberately `undefined` rather than `false`, so "unset" stays distinguishable from an explicit `:checked="fals… |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. Also applied when `readonly` is set, since native checkboxes do not support `readonly`. |

package/dist/ai/BbBaseSwitchGroup.md

@@ -27,9 +27,10 @@
 | `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state. Errors take priority when both are set. |
 | `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. |
 | `id` | `string \| undefined` |  |  | Identifier of the group. Used to derive per-option IDs for accessible labeling. |
+| `itemProps` | `ItemProps<T, OptionGroupItemFields> \| 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… |
 | `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Items provider. Can be: - An array of items - A sync/async function `(prefill, modelValue) => items` When a function is provided, it is invoked on prefill and when dependencies change to load options dynamically. |
 | `itemText` | `(T extends object ? string \| ((item: T) => string) : (item: T) => string) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the display text from an item. Accepts a nested key path into the item or a function `(item) => string`. |
-| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the value from an item. Accepts a nested key path into the item or a function `(item) => any`. |
+| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` |  |  |  |
 | `loadingText` | `string \| undefined` | `'Loading...'` |  | Text displayed while items are loading. |
 | `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items. |
 | `modelValue` | `any` |  | yes | Selected values for the group. Used with `v-model`. Single value when `multiple` is false, array when `multiple` is true. |

package/dist/ai/BbBaseTag.md

@@ -18,6 +18,7 @@
 | --- | --- | --- | --- | --- |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this tag input for assistive technologies. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically on mount. |
 | `caseSensitive` | `boolean \| undefined` | `false` |  | Compare tags case-sensitively when rejecting duplicates, so `Vue` and `vue` can both exist. By default matching folds case, because two chips differing only in case read as duplicates to a user. Either way the tag is stored with the casing … |

package/dist/ai/BbBaseTextInput.md

@@ -18,6 +18,7 @@
 | --- | --- | --- | --- | --- |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this input for assistive technologies. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autocomplete` | `string \| undefined` |  |  | Browser autocomplete hint for the input field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically on mount. |
 | `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever a value is present and the control is interactive. |

package/dist/ai/BbBaseTextarea.md

@@ -18,6 +18,7 @@
 | --- | --- | --- | --- | --- |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the textarea. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this textarea for assistive technologies. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) naming this control, forwarded as `aria-labelledby`. |
 | `autocomplete` | `string \| undefined` |  |  | Browser autocomplete hint for the textarea. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the textarea automatically on mount. |
 | `autoGrow` | `boolean \| undefined` | `false` |  | Automatically expand the textarea height to fit its content. Composes with `rows`: when both are set, `rows` acts as the minimum-height floor the field grows past but never shrinks below. |

package/dist/ai/BbCheckbox.md

@@ -576,6 +576,7 @@ input on mount — use sparingly.
 
 ## Slots
 
+- `description` — scope: `BbCheckboxDescriptionSlotProps` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `icon` — scope: `BbCheckboxIconSlotProps` — Replaces the default checkmark SVG inside the checkbox box. Receives `BaseCheckbox` slot attributes plus the label text.
 - `label` — scope: `BbCheckboxLabelSlotProps` — Replaces the default label text rendered next to the checkbox.
 

package/dist/ai/BbCheckboxGroup.md

@@ -97,6 +97,94 @@ prefer stable primitive ids: they survive refetches and are cheap to submit.
 Two items that resolve to the **same** `item-value` collapse to one option
 (first wins), so keep values unique.
 
+#### Additional row fields: `item-props`
+
+`item-text` and `item-value` are the option's 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.
+
+```vue
+<BbCheckboxGroup
+	legend="Plan"
+	:items="plans"
+	item-text="name"
+	item-value="id"
+	:item-props="{ description: 'summary' }"
+/>
+```
+
+**Add-ons with item descriptions and a description slot**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-3">
+		<BbCheckboxGroup
+			v-model="addons"
+			input-direction="vertical"
+			:item-props="{ description: 'summary' }"
+			item-text="name"
+			item-value="id"
+			:items="catalog"
+			legend="Add-ons"
+			name="addons"
+		>
+			<!-- The group's OWN description, under the legend. A slot, so it can
+			hold a link; `description="…"` is the plain-text form. -->
+			<template #description>
+				Billed monthly with your plan.
+				<a class="underline" href="#pricing">See pricing</a>
+			</template>
+		</BbCheckboxGroup>
+		<p class="addon-summary text-xs text-(--bb-text-muted)">
+			{{ addons.length }} add-on{{ addons.length === 1 ? '' : 's' }} selected
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbCheckboxGroup } from 'bitboss-ui';
+
+type Addon = { id: string; name: string; summary: string };
+
+// `item-props` holds the ADDITIONAL row fields — never the text or value, which
+// stay on `item-text` / `item-value`. Option groups take one field,
+// `description`: a muted line under each option's label, beside the box.
+// "Priority support" has an empty summary, so it renders no line at all.
+const catalog: Addon[] = [
+	{
+		id: 'backups',
+		name: 'Daily backups',
+		summary: 'Kept for 30 days, restorable from the dashboard.',
+	},
+	{
+		id: 'sso',
+		name: 'Single sign-on',
+		summary: 'SAML and OIDC for up to 500 seats.',
+	},
+	{ id: 'support', name: 'Priority support', summary: '' },
+];
+
+const addons = ref<string[]>(['backups']);
+</script>
+```
+
+Each field takes a dot-path or a getter; or pass one function that returns the
+fields: `:item-props="(plan) => ({ description: plan.summary })"`.
+
+- **Only additional fields.** Text and value never go in `item-props`.
+- **Nothing is read implicitly.** Without `item-props` no description renders,
+  even if your items carry a `description` field. An empty value renders no
+  line for that item.
+- **The line may wrap**, is announced as the option's description (never part of
+  its name), and reaches the `#label` slot as `description`.
+- **No icons here.** An option group has no place for an icon other than the
+  control itself, which the `#icon` slot already replaces.
+- **Disabling individual options is `selectable`'s job** —
+  `:selectable="(plan) => plan.available"` — not a field in `item-props`.
+- The group's own `description` prop is a different thing: it sits under the
+  legend.
+
 ### The array model is mandatory
 
 `multiple` defaults to **`true`**, so `modelValue` **must be an array** — seed
@@ -534,6 +622,7 @@ focuses the first option on mount — use sparingly.
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
 | `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. |
+| `itemProps` | `ItemProps<T, OptionGroupItemFields> \| 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… |
 | `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
 | `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | 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` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
@@ -570,6 +659,7 @@ focuses the first option on mount — use sparingly.
 ## Slots
 
 - `append` — scope: `object` — Content rendered after the last option, inside the options container.
+- `description` — scope: `BbCheckboxGroupDescriptionSlotProps` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `icon` — scope: `BaseCheckboxGroupIconSlotProps<T>` — Replaces the default checkmark icon for each checkbox option.
 - `label` — scope: `BaseCheckboxGroupLabelSlotProps<T>` — Replaces the default label text for each option.
 - `legend` — scope: `BbCheckboxGroupLegendSlotProps` — Replaces the default fieldset legend text for the group.

package/dist/ai/BbColorInput.md

@@ -552,6 +552,7 @@ the `BbTextInput` guide.
 
 - `append` — scope: `Record<string, never>` — Content rendered after the color picker indicator button, at the end of the inner container. Mutually exclusive with `suffix`: the `suffix` slot renders inside this slot's default content, so providing `append` replaces the suffix rendering…
 - `append-outer` — scope: `Record<string, never>` — Content rendered after the entire input control, outside the input chrome. This slot receives no scoped props.
+- `description` — scope: `BbColorInputDescriptionSlotProps` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `label` — scope: `BbColorInputLabelSlotProps` — Replaces the default label text rendered above the color input.
 - `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the input field area, before the typed text. This slot receives no scoped props.
 - `prepend` — scope: `Record<string, never>` — Content rendered before the text input, at the start of the inner container. This slot receives no scoped props.

package/dist/ai/BbDatePickerInput.md

@@ -770,6 +770,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 - `append-outer` — scope: `object` — Content rendered after the entire date picker control, outside the input chrome.
 - `append:day` — scope: `{ first: boolean; highlighted: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; selected: boolean; }` — Appends content below each calendar day.
 - `day` — scope: `{ first: boolean; highlighted: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; selected: boolean; }` — Replaces the day button label inside each calendar day.
+- `description` — scope: `BbDatePickerInputDescriptionSlotProps` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `label` — scope: `BbDatePickerInputLabelSlotProps` — Replaces the default label text rendered above the date picker.
 - `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the date fields.
 - `prepend` — scope: `object` — Content rendered before the date fields, at the start of the inner container.

package/dist/ai/BbDropdown.md

@@ -343,6 +343,34 @@ Behavior you can rely on:
   **value** (its `item-value` for pipeline groups, else its `key`) whenever any
   selectable group changes — the same value shape `BbTable` emits.
 
+**Gating individual rows.** `selectable` also takes a function
+`(item) => boolean`, the same contract as `BbSelect` and the option groups:
+
+```ts
+const statusGroup = {
+	key: 'status',
+	multiple: true,
+	selectable: (row: { archived?: boolean }) => !row.archived,
+	items: statuses,
+};
+```
+
+- The group is still a selectable group (a function counts as `true`): checks,
+  `menuitemcheckbox` / `menuitemradio` roles, the menu stays open while
+  toggling.
+- A row the function rejects renders **disabled**: clicks do nothing and
+  keyboard navigation skips it.
+- The lock holds on a row that is **already selected** — it cannot be
+  unselected by a click.
+- `max` stays a soft cap on top: at the limit, unselected rows disable but
+  selected ones stay live so the user can swap.
+- The function receives the **row object** in a hand-written group and the
+  **raw fetched item** in a fetched group.
+- `useBbDropdownContext(id).groups[key].selectable` stays a plain `true`.
+
+This is also how a fetched row gets disabled — see
+[why fetched rows have no `disabled`](#additional-row-fields-itemprops).
+
 Selection state lives on the dropdown; a companion `<BbDropdownGroup>` in the
 default slot binds to it. The companion is intentionally minimal — it takes
 only the group's `id` (which must match the group's `key` in `items`) and a
@@ -436,9 +464,10 @@ The full grammar:
   same provider drops into both.
 - `itemText` / `itemValue` — a path string or getter producing each raw item's
   label and value. `v-model` on the companion surfaces the selected value(s);
-  internally the selection key is a hash of the value. BbBaseButton props on the
-  raw items (`href`, `disabled`, icons, `variant`, `onClick`, …) pass through
-  to the rendered rows.
+  internally the selection key is a hash of the value.
+- `itemProps` — every **additional** field of a row (see
+  [Additional row fields](#additional-row-fields-itemprops) below). Nothing
+  else is read off the raw item.
 - `max` — caps a multiple selection; once reached, unselected rows render
   disabled.
 - `loadingText` / `noDataText` — placeholder row text per group; the
@@ -636,6 +665,233 @@ const assigneeNames = computed(() =>
 </script>
 ```
 
+### Additional row fields: `itemProps`
+
+A fetched row's **text** and **value** come from `itemText` and `itemValue`.
+Everything **else** about the row comes from `itemProps` — and only from there.
+The raw item is data: a `href`, `disabled` or `prepend:icon` field sitting on it
+does nothing on its own.
+
+```ts
+const assigneeGroup = {
+	key: 'assignee',
+	selectable: true,
+	items: () => api.users(),
+	itemText: 'name',
+	itemValue: 'id',
+	itemProps: { description: 'email', 'prepend:icon': 'avatarIcon' },
+};
+```
+
+**Fetched assignees: description, icon, selectable gate, context**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-wrap items-center gap-2 rounded-(--bb-radius) border p-2"
+	>
+		<div class="min-w-0 flex-1">
+			<p class="truncate text-sm font-medium">INV-2048 · Northwind</p>
+			<p class="assignee-emails truncate text-xs text-(--bb-text-muted)">
+				{{ emails || 'No assignees' }}
+			</p>
+		</div>
+		<BbDropdown
+			id="invoice-assignees"
+			:items="items"
+			loading-text="Loading team…"
+			:width="260"
+		>
+			<template #activator="{ props, loading }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					:loading="loading"
+					size="xs"
+					variant="outline"
+				>
+					Assign
+				</BbButton>
+			</template>
+			<BbDropdownGroup id="assignees" v-model="assignees" />
+		</BbDropdown>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import {
+	BbButton,
+	BbDropdown,
+	BbDropdownGroup,
+	useBbDropdownContext,
+} from 'bitboss-ui';
+import type { BbDropdownItem } from 'bitboss-ui';
+
+type Member = { id: string; name: string; email: string; active: boolean };
+
+const team: Member[] = [
+	{
+		id: 'u1',
+		name: 'Sofia Esposito',
+		email: 'sofia@example.com',
+		active: true,
+	},
+	{
+		id: 'u2',
+		name: 'Marco Bianchi',
+		email: 'marco@example.com',
+		active: false,
+	},
+	{ id: 'u3', name: 'Aisha Khan', email: 'aisha@example.com', active: true },
+];
+
+const items: BbDropdownItem[] = [
+	{
+		key: 'assignees',
+		label: 'Assign to',
+		multiple: true,
+		// Fetched rows take their text and value from `itemText` / `itemValue`,
+		// and EVERY other field only from `itemProps` — a raw `disabled` or
+		// `prepend:icon` sitting on the item would do nothing.
+		itemText: 'name',
+		itemValue: 'id',
+		itemProps: { description: 'email', 'prepend:icon': () => 'lucide:user' },
+		// Fetched groups are for selection, so a row is disabled by the group's
+		// `selectable` predicate (it receives the RAW member), not by a field.
+		selectable: (member: Member) => member.active,
+		items: async () => {
+			await new Promise((resolve) => setTimeout(resolve, 300));
+			return team;
+		},
+	},
+];
+
+const assignees = ref<string[]>(['u1']);
+
+// The resolved description is on the context's `selectedOptions` too — no
+// second fetch to show the picked emails outside the menu.
+const context = useBbDropdownContext('invoice-assignees');
+const emails = computed(() =>
+	(context.groups.value.assignees?.selectedOptions ?? [])
+		.map((option) => option.description)
+		.filter(Boolean)
+		.join(', ')
+);
+</script>
+```
+
+**Fetched links: function form with href and a handler**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center gap-2 rounded-(--bb-radius) border p-2"
+	>
+		<span class="flex-1 text-sm">Workspace</span>
+		<BbDropdown :items="items" :width="260">
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="xs"
+					variant="outline"
+				>
+					Projects
+				</BbButton>
+			</template>
+		</BbDropdown>
+		<p class="last-opened text-xs text-(--bb-text-muted)">
+			{{ lastOpened ?? '' }}
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDropdown } from 'bitboss-ui';
+import type { BbDropdownItem } from 'bitboss-ui';
+
+type Project = { id: string; name: string; client: string; path: string };
+
+const recent: Project[] = [
+	{ id: 'p1', name: 'Apollo redesign', client: 'Northwind', path: '#apollo' },
+	{ id: 'p2', name: 'Gemini billing', client: 'Contoso', path: '#gemini' },
+];
+
+const lastOpened = ref<string | null>(null);
+
+const items: BbDropdownItem[] = [
+	{ key: 'new', text: 'New project', 'prepend:icon': 'lucide:plus' },
+	{
+		// A fetched group of LINKS (not selectable). Its rows get `href`, an icon,
+		// a description and a click handler from `itemProps`, using the function
+		// form. In the object form a function is a GETTER, so a handler would be
+		// written `onClick: (project) => () => …`; here the function form returns
+		// the handler directly.
+		key: 'recent',
+		label: 'Recent',
+		itemText: 'name',
+		itemValue: 'id',
+		itemProps: (project: Project) => ({
+			description: project.client,
+			href: project.path,
+			'prepend:icon': 'lucide:folder',
+			onClick: () => {
+				lastOpened.value = project.name;
+			},
+		}),
+		items: async () => recent,
+	},
+];
+</script>
+```
+
+**Two forms.**
+
+- **Object** — one dot-path or getter per field:
+  `{ description: 'email', href: (user) => '/users/' + user.id }`. Each field
+  resolves on its own.
+- **Function** — one function returning the fields:
+  `(user) => ({ description: user.email, href: user.url })`. Called once per
+  item and cached.
+
+In the object form **a function is always a getter**, so a handler field
+returns the handler: `onClick: (user) => () => openProfile(user)`. (The types
+reject the common slip `onClick: () => openProfile()`, because it doesn't return
+a function.)
+
+**Which fields.** Everything a hand-written row accepts, except its identity and
+structure — `key`, `text`, `items`, `group` — and `disabled`:
+
+- `description` — a muted second line under the text, announced as the row's
+  description (never part of its name), searched with the text, and exposed as
+  `description` on `useBbDropdownContext(id).groups[key].selectedOptions`.
+- `prepend:icon`, `append:icon`, `variant`.
+- `onClick`, `href`, `to`, `target`, `rel`, `download`, `external`, and the
+  Inertia visit options.
+
+An empty value (`null`, `undefined`, `''`) means the field is absent — no empty
+line, no blank icon, no `href=""`.
+
+**Why there is no `disabled`: fetched groups are for selection.** This is the
+subtle part, so here it is step by step.
+
+1. A greyed-out row can mean two different things: _"this can't be picked"_ (a
+   choice) or _"this can't be used"_ (an action or a link).
+2. A group holds one kind of rows. Its `items` is either hand-written rows or a
+   fetched source (a getter, or a raw array read through `itemText` /
+   `itemValue`) — never a mix. Mixing happens only **across** groups: a
+   hand-written "Actions" group next to a fetched "Assignees" group.
+3. A fetched group is meant to be **selectable** — assignees, labels, filters.
+   There, "can't be picked" is the only question, and the group's `selectable`
+   answers it: pass `(item) => boolean` and a rejected row renders disabled,
+   exactly as in `BbSelect` and the option groups.
+4. So a fetched row has no `disabled` field. The one case that loses out is a
+   fetched group of **actions or links** that needs to disable a single row —
+   no such menu exists in the library or its fixtures. If one ever does,
+   `disabled` can be added to `itemProps` later without breaking anything.
+5. Hand-written rows keep their `disabled` field as always — that is where
+   action menus live.
+
 ### Searchable groups
 
 A group can render **its own search field**, scoped to itself alone — the
@@ -658,6 +914,7 @@ group owns an independent query.
 			items: (query, prefill, modelValue) => api.users({ q: query }),
 			itemText: 'name',
 			itemValue: 'id',
+			itemProps: { description: 'email' },
 		},
 	]"
 />
@@ -671,7 +928,8 @@ What each knob does:
   **leading** argument: `(query, prefill, modelValue)`, the same shape
   `BbSelect` uses, so one provider serves both.
 - **`filterBy`** picks which raw fields the local substring match reads. Empty
-  (the default) matches the resolved display text.
+  (the default) matches the resolved display text, plus the resolved
+  description when the group's `itemProps` gives one.
 - **`searchPlaceholder`** overrides the field's placeholder; it defaults to the
   localized label.
 - **`prefill: false`** means _search-first_ — nothing loads until the user

package/dist/ai/BbNumberInput.md

@@ -725,6 +725,7 @@ the `BbTextInput` guide.
 
 - `append` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the number input, at the end of the inner container. Typically used to place increment/decrement buttons next to the input.
 - `append-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the entire input control, outside the input chrome.
+- `description` — scope: `BbNumberInputDescriptionSlotProps` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `label` — scope: `BbNumberInputLabelSlotProps` — Replaces the default label text rendered above the number input.
 - `prefix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the start of the input field area, before the typed number.
 - `prepend` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the number input, at the start of the inner container.

package/dist/ai/BbRadio.md

@@ -381,6 +381,7 @@ listen to them for side concerns only. `autofocus` focuses the input on mount.
 
 ## Slots
 
+- `description` — scope: `BbRadioDescriptionSlotProps` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `icon` — scope: `BbRadioIconSlotProps` — Replaces the default radio dot visual inside the radio container. Receives `BaseRadio` slot attributes plus the label text.
 - `label` — scope: `BbRadioLabelSlotProps` — Replaces the default label text rendered next to the radio button.