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

package/dist/ai/BbDropdown.md

@@ -48,31 +48,33 @@ handling in markup — hand `BbDropdown` an `items` array.
 
 An `items` entry is one of three shapes, and you can mix them freely:
 
-- a **menu item** — an object with a `key` and a `text`;
+- a **menu item** — an object with a `value` and a `label`;
 - a **separator section** — a nested `[ … ]` array, rendered as its own
   divider-separated anonymous group;
-- a **group object** — `{ key, label?, items, selectable?, … }`, a titled and/or
-  selectable section (next sections). A group's heading is `label` (not `text`);
+- a **group object** — `{ id, label?, items, selectable?, … }`, a titled and/or
+  selectable section (next sections). A group's heading is its `label` too;
   add `hideLabel` to keep the `label` for the adaptive sheet title / chips /
   `useBbDropdownContext` while rendering no heading in the menu.
 
 Each item extends `BbBaseButton`'s prop surface, so an item is an action, a
 link, or a submenu opener depending on which fields it carries:
 
-- `key` — stable identity. **Required** wherever something outside the menu
-  reads it: a row in a `selectable` group (the v-model holds it), a row or
-  group with a slot of its own (`#<key>` is named by it), and a group that is
-  selectable or bound by a `<BbDropdownGroup id>`. **Optional** on a plain
-  action row (one with an `onClick`, `href` or submenu) and on a layout-only
-  group: the dropdown then keys the row internally from its text, and nothing
-  outside ever sees that identity. Why the split: an identifier something
-  outside reads must be one you wrote — derived from the label it would change
-  with every translation and copy edit. So a keyless row in a selectable group
-  renders but can't be selected, and two keyless rows with the same text in one
-  group need keys (the same text across groups is fine); `bitboss-ui check`
-  flags both when the items are in the same file.
-- `text` — the label; `description` adds a muted second line (the row grows,
-  icons stay aligned with the title line).
+- `value` — a row's stable identity (a group's is its `id`). **Required**
+  wherever something outside the menu reads it: a row in a `selectable` group
+  (the v-model holds it), a row with a slot of its own (`#<value>` is named by
+  it), and a group that has a slot, is selectable or is bound by a
+  `<BbDropdownGroup id>` (its `id`). **Optional** on a plain action row (one
+  with an `onClick`, `href` or submenu) and on a layout-only group: the
+  dropdown then keys the row internally from its label, and nothing outside
+  ever sees that identity. Why the split: an identifier something outside
+  reads must be one you wrote — derived from the label it would change with
+  every translation and copy edit. So a row without a `value` in a selectable
+  group renders but can't be selected, and two such rows with the same label in
+  one group need values (the same label across groups is fine); `bitboss-ui
+check` flags both (`missing-value`, `duplicate-row-label`) when the items are
+  in the same file.
+- `label` — the row's text; `description` adds a muted second line (the row
+  grows, icons stay aligned with the title line).
 - `onClick` — makes it an **action**. Never navigate from here.
 - `href` (anchor / Inertia visit, with `method`/`data`) or `to` (vue-router) —
   makes it a **navigation link**; the dropdown renders an `<a>` / router link,
@@ -141,22 +143,22 @@ const { confirm } = useConfirm();
 const items: BbDropdownItem[] = [
 	// Plain leaf actions carry an `onClick`.
 	{
-		key: 'rename',
-		text: 'Rename',
+		value: 'rename',
+		label: 'Rename',
 		'prepend:icon': 'lucide:pencil',
 		onClick: () => (last.value = 'Renamed'),
 	},
 	{
-		key: 'duplicate',
-		text: 'Duplicate',
+		value: 'duplicate',
+		label: 'Duplicate',
 		'prepend:icon': 'lucide:copy',
 		onClick: () => (last.value = 'Duplicated'),
 	},
 	// A navigation item: the dropdown renders an <a>. Never wire navigation
 	// through onClick — pass href (or `to` in a router app) instead.
 	{
-		key: 'preview',
-		text: 'Open preview',
+		value: 'preview',
+		label: 'Open preview',
 		'prepend:icon': 'lucide:external-link',
 		href: '#preview',
 		target: '_blank',
@@ -166,8 +168,8 @@ const items: BbDropdownItem[] = [
 	// proceeds on a yes.
 	[
 		{
-			key: 'delete',
-			text: 'Delete file',
+			value: 'delete',
+			label: 'Delete file',
 			description: 'This cannot be undone',
 			'prepend:icon': 'lucide:trash-2',
 			variant: 'destructive',
@@ -196,9 +198,9 @@ import type { BbDropdownItem } from 'bitboss-ui';
 
 const items: BbDropdownItem[] = [
 	// Nuxt / vue-router route
-	{ key: 'settings', text: 'Settings', to: { name: 'settings' } },
+	{ value: 'settings', label: 'Settings', to: { name: 'settings' } },
 	// Inertia visit
-	{ key: 'logout', text: 'Log out', href: '/logout', method: 'post' },
+	{ value: 'logout', label: 'Log out', href: '/logout', method: 'post' },
 ];
 </script>
 ```
@@ -258,8 +260,8 @@ const status = ref('Idle');
 // activator can stay busy while the work runs in the background.
 const items: BbDropdownItem[] = [
 	{
-		key: 'sync',
-		text: 'Sync now',
+		value: 'sync',
+		label: 'Sync now',
 		'prepend:icon': 'lucide:refresh-cw',
 		onClick: async () => {
 			status.value = 'Syncing…';
@@ -268,8 +270,8 @@ const items: BbDropdownItem[] = [
 		},
 	},
 	{
-		key: 'history',
-		text: 'View sync history',
+		value: 'history',
+		label: 'View sync history',
 		'prepend:icon': 'lucide:history',
 		href: '#history',
 	},
@@ -320,32 +322,32 @@ import type { BbDropdownItem } from 'bitboss-ui';
 // a chevron replaces the item's own `append:icon`.
 const items: BbDropdownItem[] = [
 	{
-		key: 'account',
-		text: 'Account',
+		value: 'account',
+		label: 'Account',
 		'prepend:icon': 'lucide:user',
 		items: [
-			{ key: 'profile', text: 'View profile', href: '#profile' },
-			{ key: 'billing', text: 'Billing & plans', href: '#billing' },
+			{ value: 'profile', label: 'View profile', href: '#profile' },
+			{ value: 'billing', label: 'Billing & plans', href: '#billing' },
 			{
-				key: 'security',
-				text: 'Security',
+				value: 'security',
+				label: 'Security',
 				items: [
-					{ key: '2fa', text: 'Two-factor auth', href: '#2fa' },
-					{ key: 'sessions', text: 'Active sessions', href: '#sessions' },
+					{ value: '2fa', label: 'Two-factor auth', href: '#2fa' },
+					{ value: 'sessions', label: 'Active sessions', href: '#sessions' },
 				],
 			},
 		],
 	},
 	{
-		key: 'help',
-		text: 'Help & support',
+		value: 'help',
+		label: 'Help & support',
 		'prepend:icon': 'lucide:life-buoy',
 		href: '#help',
 	},
 	[
 		{
-			key: 'signout',
-			text: 'Sign out',
+			value: 'signout',
+			label: 'Sign out',
 			'prepend:icon': 'lucide:log-out',
 			href: '#signout',
 		},
@@ -360,24 +362,24 @@ Turn a group into a chooser by marking it `selectable` (single choice, radio
 semantics) or `selectable` + `multiple` (many choices, checkbox semantics).
 Selected rows render a check on the right (replacing any `append:icon`).
 **Bind the selection with a `<BbDropdownGroup>` companion** whose `id` is the
-group's `key` (details below):
+group's `id` (details below):
 
 ```vue
 <BbDropdown
 	:items="[
 		{
-			key: 'status',
+			id: 'status',
 			label: 'Status',
 			selectable: true,
 			multiple: true,
 			items: [
-				{ key: 'open', text: 'Open' },
-				{ key: 'paid', text: 'Paid' },
+				{ value: 'open', label: 'Open' },
+				{ value: 'paid', label: 'Paid' },
 			],
 		},
 	]"
 >
-	<!-- selectedStatuses = ref<string[]>([]) — the checked rows' keys -->
+	<!-- selectedStatuses = ref<string[]>([]) — the checked rows' values -->
 	<BbDropdownGroup id="status" v-model="selectedStatuses" />
 </BbDropdown>
 ```
@@ -391,7 +393,7 @@ Behavior you can rely on:
   (the same one included) also closes the menu;
 - a **multiple** group keeps the menu open while you toggle;
 - the dropdown emits `item:selected` / `item:unselected` with the item's
-  **value** (its `item-value` for pipeline groups, else its `key`) when the user
+  **value** (its `itemValue` for pipeline groups, else its own `value`) when the user
   picks or unpicks a row, never for your own changes to a group's value — the
   same value shape and meaning as `BbTable`'s (and the companion's pair).
 
@@ -400,7 +402,7 @@ Behavior you can rely on:
 
 ```ts
 const statusGroup = {
-	key: 'status',
+	id: 'status',
 	multiple: true,
 	selectable: (row: { archived?: boolean }) => !row.archived,
 	items: statuses,
@@ -418,19 +420,19 @@ const statusGroup = {
   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`.
+- `useBbDropdownContext(id).groups[groupId].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
+only the group's `id` (which must match the group's `id` in `items`) and a
 `v-model`; the options themselves stay declared in the host's `items`. Its
 `v-model` seeds the initial selection before the menu ever opens, and it emits
 the same `item:selected` / `item:unselected` pair. Two hard rules, enforced
 with thrown errors: a `multiple` group's model must be an array, and the `id`
-must point at a _group_ (not a plain item, not a missing key).
+must point at a _group_ (not a plain item, not a missing id).
 
 A companion you listen to (`v-model`, or `@update:model-value`) is
 **controlled**, like a `BbCheckbox`: the menu shows your value and nothing
@@ -491,24 +493,24 @@ import type { BbDropdownItem } from 'bitboss-ui';
 // `multiple` → many choices (checkbox semantics, stays open while toggling).
 const items: BbDropdownItem[] = [
 	{
-		key: 'sort',
+		id: 'sort',
 		label: 'Sort by',
 		selectable: true,
 		items: [
-			{ key: 'recent', text: 'Most recent' },
-			{ key: 'name', text: 'Name (A–Z)' },
-			{ key: 'amount', text: 'Amount (high → low)' },
+			{ value: 'recent', label: 'Most recent' },
+			{ value: 'name', label: 'Name (A–Z)' },
+			{ value: 'amount', label: 'Amount (high → low)' },
 		],
 	},
 	{
-		key: 'tags',
+		id: 'tags',
 		label: 'Tags',
 		selectable: true,
 		multiple: true,
 		items: [
-			{ key: 'overdue', text: 'Overdue' },
-			{ key: 'vip', text: 'VIP' },
-			{ key: 'review', text: 'Needs review' },
+			{ value: 'overdue', label: 'Overdue' },
+			{ value: 'vip', label: 'VIP' },
+			{ value: 'review', label: 'Needs review' },
 		],
 	},
 ];
@@ -520,14 +522,14 @@ const tags = ref<string[]>(['overdue']);
 
 #### The same choices in two places
 
-Item keys are scoped to their **group** for selection. Two groups can both
+Row values are scoped to their **group** for selection. Two groups can both
 list `doctors` and `rooms` (say a day layout at the top level and a week
 layout inside a `Week ›` submenu) and each keeps its own pick, with its own
 companion and `v-model`.
 
 To show a submenu's current pick on its parent row, compute the row from the
 same state. `items` is reactive config, so the parent's `description` (or its
-`#<key>:append` slot) follows the submenu group's `v-model`:
+`#<value>:append` slot) follows the submenu group's `v-model`:
 
 **A submenu's pick on its parent row**
 
@@ -545,7 +547,7 @@ same state. `items` is reactive config, so the parent's `description` (or its
 					Layout
 				</BbButton>
 			</template>
-			<!-- Both groups list the same keys; each keeps its own selection. -->
+			<!-- Both groups list the same values; each keeps its own selection. -->
 			<BbDropdownGroup id="day" v-model="day" />
 			<BbDropdownGroup id="week" v-model="week" />
 		</BbDropdown>
@@ -561,11 +563,11 @@ import { BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
 import type { BbDropdownItem } from 'bitboss-ui';
 
 const choices = [
-	{ key: 'doctors', text: 'Doctors' },
-	{ key: 'rooms', text: 'Rooms' },
+	{ value: 'doctors', label: 'Doctors' },
+	{ value: 'rooms', label: 'Rooms' },
 ];
-const label = (key: string) =>
-	choices.find((choice) => choice.key === key)?.text ?? key;
+const label = (value: string) =>
+	choices.find((choice) => choice.value === value)?.label ?? value;
 
 const day = ref('doctors');
 const week = ref('rooms');
@@ -574,32 +576,33 @@ const week = ref('rooms');
 // from the same state its group writes, so the parent row always shows the
 // current pick ("Week · Rooms") without opening the submenu.
 const items = computed<BbDropdownItem[]>(() => [
-	{ key: 'day', label: 'Day', selectable: true, items: choices },
+	{ id: 'day', label: 'Day', selectable: true, items: choices },
 	{
-		key: 'week-menu',
-		text: 'Week',
+		value: 'week-menu',
+		label: 'Week',
 		description: label(week.value),
-		items: [{ key: 'week', selectable: true, items: choices }],
+		items: [{ id: 'week', selectable: true, items: choices }],
 	},
 ]);
 </script>
 ```
 
-Three things still go by the bare key across the whole menu, so give those
-rows distinct keys when it matters:
+Three things still go by the bare value across the whole menu, so give those
+rows distinct values when it matters:
 
-- **`#<key>` row slots.** `#doctors` fills every row keyed `doctors`, in every
-  group. Use `#<groupKey>:item` (with the `item` payload) to target one
+- **`#<value>` row slots.** `#doctors` fills every row whose value is `doctors`,
+  in every group. Use `#<groupId>:item` (with the `item` payload) to target one
   group's rows.
 - **The async loading flag.** While a row's async `onClick` runs, every row
-  with that key shows as loading.
-- **Submenu parents.** A row that opens a submenu needs a key unique in the
+  with that value shows as loading.
+- **Submenu parents.** A row that opens a submenu needs a value unique in the
   whole menu; the flyout is addressed by it.
 
 ### Loading options on demand
 
 For options that come from an API, make the group a **pipeline group**: pass an
-(async) getter as `items` and an `item-text` / `item-value` pair. This mirrors
+(async) getter as `items`, and an `itemText` / `itemValue` pair unless the raw
+rows already carry `label` and `value`. This mirrors
 `BbSelect`'s fetch model, so the same data source drops into either component.
 The full grammar:
 
@@ -619,7 +622,8 @@ The full grammar:
   A getter **throws** to fail: the group shows `failedText` (or the `#empty`
   slot with its `error` prop) instead of "no data".
 - `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);
+  label and value; without them a row reads its own `label` (else `text`) and
+  `value`. `v-model` on the companion surfaces the selected value(s);
   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
@@ -629,7 +633,7 @@ The full grammar:
 - `loadingText` / `emptyText` / `failedText` — placeholder row text per
   group; the dropdown-level `loading-text` / `empty-text` / `failed-text` props
   set the default for all groups, and the `#loading` / `#empty` slots (payload:
-  `{ text, groupKey }`, `#empty` also `error`) replace the placeholder rows
+  `{ text, groupId }`, `#empty` also `error`) replace the placeholder rows
   entirely.
 - `dependencies: [...]` + `depsDebounceTime` — re-run the getter (debounced)
   when any dependency changes, e.g. a search field feeding the fetch.
@@ -689,7 +693,7 @@ const team: Member[] = [
 // (prefill is always `true` here — menus have no search field).
 const items: BbDropdownItem[] = [
 	{
-		key: 'assignees',
+		id: 'assignees',
 		label: 'Assign to',
 		selectable: true,
 		multiple: true,
@@ -795,16 +799,16 @@ const loadMembers = (): Promise<Member[]> =>
 // refetch. `enforceCoherence` then drops picks missing from the fresh items.
 const menu = computed<BbDropdownItem[]>(() => [
 	{
-		key: 'board',
+		id: 'board',
 		label: 'Board',
 		selectable: true,
 		items: [
-			{ key: 'website', text: 'Website' },
-			{ key: 'mobile-app', text: 'Mobile app' },
+			{ value: 'website', label: 'Website' },
+			{ value: 'mobile-app', label: 'Mobile app' },
 		],
 	},
 	{
-		key: 'assignees',
+		id: 'assignees',
 		label: 'Assignee',
 		selectable: true,
 		multiple: true,
@@ -828,14 +832,15 @@ const assigneeNames = computed(() =>
 
 ### Additional row fields: `itemProps`
 
-A fetched row's **text** and **value** come from `itemText` and `itemValue`.
+A fetched row's **label** and **value** come from `itemText` and `itemValue` (by
+default the raw item's own `label` and `value`).
 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',
+	id: 'assignee',
 	selectable: true,
 	items: () => api.users(),
 	itemText: 'name',
@@ -908,10 +913,11 @@ const team: Member[] = [
 
 const items: BbDropdownItem[] = [
 	{
-		key: 'assignees',
+		id: 'assignees',
 		label: 'Assign to',
 		multiple: true,
-		// Fetched rows take their text and value from `itemText` / `itemValue`,
+		// Fetched rows take their text and value from `itemText` / `itemValue`
+		// (without them, the row's own `label` and `value`),
 		// and EVERY other field only from `itemProps` — a raw `disabled` or
 		// `prepend:icon` sitting on the item would do nothing.
 		itemText: 'name',
@@ -981,14 +987,14 @@ const recent: Project[] = [
 const lastOpened = ref<string | null>(null);
 
 const items: BbDropdownItem[] = [
-	{ key: 'new', text: 'New project', 'prepend:icon': 'lucide:plus' },
+	{ value: 'new', label: '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',
+		id: 'recent',
 		label: 'Recent',
 		itemText: 'name',
 		itemValue: 'id',
@@ -1021,11 +1027,11 @@ 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`:
+structure — `value`, `label`, `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`.
+  `description` on `useBbDropdownContext(id).groups[groupId].selectedOptions`.
 - `prepend:icon`, `append:icon`, `variant`.
 - `onClick`, `href`, `to`, `target`, `rel`, `download`, `external`, and the
   Inertia visit options.
@@ -1066,7 +1072,7 @@ group owns an independent query.
 <BbDropdown
 	:items="[
 		{
-			key: 'assignee',
+			id: 'assignee',
 			label: 'Assignee',
 			searchable: true,
 			searchPlaceholder: 'Find a teammate…',
@@ -1136,17 +1142,17 @@ const { isReady, open, groups } = useBbDropdownContext('invoice-filters');
 
 - `isReady` — a dropdown with that id is mounted.
 - `open` — the panel/sheet is open.
-- `groups` — one entry per **selectable** group, keyed by group key.
+- `groups` — one entry per **selectable** group, keyed by the group's `id`.
 
 Each entry is **the group exactly as you declared it, with live state on top**,
 so a chip can be driven entirely from the group config:
 
-| From your config                                                             | Added live                                                                      |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `key`, `label`, `hideLabel`, `max`, `filterBy`, `prepend:icon`, `variant`, … | `value` (the `v-model`), `selectedOptions`, `multiple`, `selectable`, `loading` |
+| From your config                                                            | Added live                                                                      |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `id`, `label`, `hideLabel`, `max`, `filterBy`, `prepend:icon`, `variant`, … | `value` (the `v-model`), `selectedOptions`, `multiple`, `selectable`, `loading` |
 
-`selectedOptions` is `{ value, text?, original? }[]`. `value` is always there;
-`text`/`original` fill in once the owning group has the item — so use
+`selectedOptions` is `{ value, label?, original? }[]`. `value` is always there;
+`label`/`original` fill in once the owning group has the item — so use
 `hideLabel` when a group's name is already shown by its parent category but you
 still want a chip prefix.
 
@@ -1165,55 +1171,55 @@ its resolved counterpart.
 ### Per-item and per-group slots
 
 Every row (and every titled group header) can be customized without leaving
-the config-driven model. Slot names come from keys through `slotKey`, which is
-kebab-case (words split at separators, camelCase humps and digits, lowercased,
-joined by `-`): key `"Delete file"`, `"delete_file"` and `"deleteFile"` all →
-`#delete-file`. For a key with accents, non-Latin letters or punctuation, or
+the config-driven model. Slot names come from a row's `value` (a group's `id`)
+through `slotKey`, which is kebab-case (words split at separators, camelCase
+humps and digits, lowercased, joined by `-`): `"Delete file"`, `"delete_file"`
+and `"deleteFile"` all → `#delete-file`. For a value with accents, non-Latin letters or punctuation, or
 when unsure, write `#[slotKey('Qualità')]` (`import { slotKey } from
 'bitboss-ui'`) instead of spelling it by hand.
 
-| Slot                                                            | Renders for                                               |
-| --------------------------------------------------------------- | --------------------------------------------------------- |
-| `#<key>`, `#<key>:prepend`, `#<key>:append`                     | one row — its content, leading or trailing region         |
-| `#<groupKey>:item`, `#<groupKey>:item:prepend`, `…:item:append` | **every row of that group**, and nothing else             |
-| `#<groupKey>`, `#<groupKey>:prepend`, `#<groupKey>:append`      | that group's title line                                   |
-| `item:prepend`, `item:append`                                   | every row **and** every group title line, across the menu |
+| Slot                                                          | Renders for                                               |
+| ------------------------------------------------------------- | --------------------------------------------------------- |
+| `#<value>`, `#<value>:prepend`, `#<value>:append`             | one row — its content, leading or trailing region         |
+| `#<groupId>:item`, `#<groupId>:item:prepend`, `…:item:append` | **every row of that group**, and nothing else             |
+| `#<groupId>`, `#<groupId>:prepend`, `#<groupId>:append`       | that group's title line                                   |
+| `item:prepend`, `item:append`                                 | every row **and** every group title line, across the menu |
 
 Each edge of a row has **one occupant** — nothing renders side by side. From
 strongest to weakest:
 
-| Leading edge               | Trailing edge                                            |
-| -------------------------- | -------------------------------------------------------- |
-| —                          | the check, on the **selected** row of a selectable group |
-| `#<key>:prepend`           | `#<key>:append`                                          |
-| —                          | the submenu chevron                                      |
-| `#<groupKey>:item:prepend` | `#<groupKey>:item:append`                                |
-| `item:prepend`             | `item:append`                                            |
-| `prepend:icon`             | `append:icon`                                            |
+| Leading edge              | Trailing edge                                            |
+| ------------------------- | -------------------------------------------------------- |
+| —                         | the check, on the **selected** row of a selectable group |
+| `#<value>:prepend`        | `#<value>:append`                                        |
+| —                         | the submenu chevron                                      |
+| `#<groupId>:item:prepend` | `#<groupId>:item:append`                                 |
+| `item:prepend`            | `item:append`                                            |
+| `prepend:icon`            | `append:icon`                                            |
 
 So a slot always replaces the row's icon and the most specific slot wins. A
-row's own `#<key>:append` is written for that one row, so it may replace its
+row's own `#<value>:append` is written for that one row, so it may replace its
 submenu chevron; the group-wide and shared append slots never do, so a submenu
 row keeps its chevron unless you name it. The check beats everything — as in
 `BbSelect`, it takes the append content's place on the selected row only, so unselected rows of a selectable group still show their
 `append:icon` or append slot. Group title lines follow the same order with
-their own `#<groupKey>:prepend` / `:append`. In fetched groups a row's `#<key>`
+their own `#<groupId>:prepend` / `:append`. In fetched groups a row's `#<value>`
 derives from its resolved `itemValue`.
 
 The payload is one-way — no callbacks; clicks and selection stay wired by the
 dropdown, so keep slot content presentational:
 
-- `item`, `text`, `description`, `index`, `selected`, `disabled`, `loading`,
+- `item`, `label`, `description`, `index`, `selected`, `disabled`, `loading`,
   `open`, `placement`
-- `group` — `{ key, label, meta, selectable, multiple }` of the group the row
-  sits in (`key` is `undefined` for loose rows and plain arrays)
+- `group` — `{ id, label, meta, selectable, multiple }` of the group the row
+  sits in (`id` is `undefined` for loose rows and plain arrays)
 - `level` — `0` in the root menu, `1` in a submenu, and so on, on the flyout
   and the phone sheet alike
 - `groupTitle` — `true` when the shared `item:prepend` / `item:append` is
   drawing a group's title line (with the group as `item`), `false` on a row
 
 There is **no** bare `#item` slot: restyle every row with the shared edge
-slots, one group's rows with `#<groupKey>:item…`, one row with its key.
+slots, one group's rows with `#<groupId>:item…`, one row with its value.
 
 **Status dots and a per-row badge**
 
@@ -1248,11 +1254,11 @@ slots, one group's rows with `#<groupKey>:item…`, one row with its key.
 				/>
 			</template>
 
-			<!-- Per-key slot: replaces just this row's label region. The name is
-			the item's `key` in kebab-case (`slotKey`: `billingInfo` → `#billing-info`). -->
-			<template #billing="{ text }">
+			<!-- Per-row slot: replaces just this row's label region. The name is
+			the row's `value` in kebab-case (`slotKey`: `billingInfo` → `#billing-info`). -->
+			<template #billing="{ label }">
 				<span class="flex flex-1 items-center justify-between gap-2 text-left">
-					{{ text }}
+					{{ label }}
 					<BbBadge variant="soft-amber">3 due</BbBadge>
 				</span>
 			</template>
@@ -1264,13 +1270,13 @@ import { BbBadge, BbButton, BbDropdown, BbIcon } from 'bitboss-ui';
 import type { BbDropdownItem, IconType } from 'bitboss-ui';
 
 const items: BbDropdownItem[] = [
-	{ key: 'production', text: 'Production', href: '#production' },
-	{ key: 'staging', text: 'Staging', href: '#staging' },
-	[{ key: 'billing', text: 'Billing', href: '#billing' }],
+	{ value: 'production', label: 'Production', href: '#production' },
+	{ value: 'staging', label: 'Staging', href: '#staging' },
+	[{ value: 'billing', label: 'Billing', href: '#billing' }],
 ];
 
 /** Status glyph per workspace row — color inherits via currentColor. */
-// `key` is optional on a row (Q53.17), so a slot reading it may see none.
+// `value` is optional on a row (Q53.17), so a slot reading it may see none.
 const envIcon = (key?: string): IconType => {
 	if (key === 'production') return 'lucide:circle-check';
 	if (key === 'staging') return 'lucide:circle-dashed';
@@ -1307,7 +1313,7 @@ pieces, and nothing else:
    announces the current one with the built-in check; `searchable` plus a
    fetched `items` getter scales to hundreds; bind its `<BbDropdownGroup
 v-model>` to the current id and switch when it changes.
-3. **`meta` + `#<groupKey>:item:prepend`** — every entry takes a `meta`: your
+3. **`meta` + `#<groupId>:item:prepend`** — every entry takes a `meta`: your
    own data, carried untouched to its slots as `item.meta` (and to per-item
    `pt` functions), never read by the dropdown, never put on the DOM. A
    hand-written row sets it directly (`meta: workspace`); a fetched row sets it
@@ -1388,7 +1394,7 @@ const initials = (workspace: Workspace) =>
 // A constant, so the fetched group is declared once while the row above it
 // follows the current workspace.
 const switcher: BbDropdownItem = {
-	key: 'workspaces',
+	id: 'workspaces',
 	label: 'Switch workspace',
 	// The row that opens this submenu already names it.
 	hideLabel: true,
@@ -1399,7 +1405,7 @@ const switcher: BbDropdownItem = {
 	itemText: 'name',
 	itemValue: 'id',
 	// `meta` hands each row its workspace, so the slot draws from the record
-	// instead of looking it up by key.
+	// instead of looking it up by value.
 	itemProps: (workspace: Workspace) => ({
 		description: workspace.plan,
 		meta: workspace,
@@ -1417,30 +1423,30 @@ const switcher: BbDropdownItem = {
 
 const items = computed<BbDropdownItem[]>(() => [
 	{
-		key: 'current-workspace',
-		text: current.value?.name ?? 'Choose a workspace',
+		value: 'current-workspace',
+		label: current.value?.name ?? 'Choose a workspace',
 		description: current.value?.plan,
 		meta: current.value,
 		items: [switcher],
 	},
 	[
 		{
-			key: 'profile',
-			text: 'Profile',
+			value: 'profile',
+			label: 'Profile',
 			'prepend:icon': 'lucide:user',
 			href: '#profile',
 		},
 		{
-			key: 'settings',
-			text: 'Settings',
+			value: 'settings',
+			label: 'Settings',
 			'prepend:icon': 'lucide:settings',
 			href: '#settings',
 		},
 	],
 	[
 		{
-			key: 'sign-out',
-			text: 'Sign out',
+			value: 'sign-out',
+			label: 'Sign out',
 			'prepend:icon': 'lucide:log-out',
 			href: '#sign-out',
 		},
@@ -1451,8 +1457,8 @@ const items = computed<BbDropdownItem[]>(() => [
 
 Two things this replaces, both seen in real apps:
 
-- **Matching keys in the shared slots** (`v-if="item.key === 'current'"`,
-  `v-else-if="clinicsById.get(item.key)"`) to tell a record row from an action
+- **Matching values in the shared slots** (`v-if="item.value === 'current'"`,
+  `v-else-if="clinicsById.get(item.value)"`) to tell a record row from an action
   row, and a lookup map rebuilt from the fetch to get the record back. The
   group row slot is the "which rows" answer; `item.meta` is the record.
 - **Re-drawing the other rows' icons**, because a shared `item:prepend`
@@ -1471,9 +1477,9 @@ the sheet's pinned header and footer.
 ```vue
 <BbDropdown
 	:items="[
-		{ key: 'jan', text: 'January', href: '#jan' },
-		{ key: 'feb', text: 'February', href: '#feb' },
-		{ key: 'mar', text: 'March', href: '#mar' },
+		{ value: 'jan', label: 'January', href: '#jan' },
+		{ value: 'feb', label: 'February', href: '#feb' },
+		{ value: 'mar', label: 'March', href: '#mar' },
 	]"
 	:width="240"
 >
@@ -1553,14 +1559,14 @@ const last = ref('Right-click the row');
 
 const items: BbDropdownItem[] = [
 	{
-		key: 'download',
-		text: 'Download PDF',
+		value: 'download',
+		label: 'Download PDF',
 		'prepend:icon': 'lucide:download',
 		onClick: () => (last.value = 'Downloading'),
 	},
 	{
-		key: 'share',
-		text: 'Share link',
+		value: 'share',
+		label: 'Share link',
 		'prepend:icon': 'lucide:link',
 		href: '#share',
 	},
@@ -1568,8 +1574,8 @@ const items: BbDropdownItem[] = [
 	// awaits useConfirm — see the mixed action menu example.
 	[
 		{
-			key: 'trash',
-			text: 'Move to trash',
+			value: 'trash',
+			label: 'Move to trash',
 			'prepend:icon': 'lucide:trash-2',
 			onClick: () => (last.value = 'Moved to trash'),
 		},
@@ -1608,15 +1614,20 @@ const items: BbDropdownItem[] = [
 	width="100%"
 	:items="[
 		{
-			key: 'starter',
-			text: 'Starter',
+			value: 'starter',
+			label: 'Starter',
 			description: 'For side projects',
 			href: '#starter',
 		},
-		{ key: 'pro', text: 'Pro', description: 'For growing teams', href: '#pro' },
 		{
-			key: 'enterprise',
-			text: 'Enterprise',
+			value: 'pro',
+			label: 'Pro',
+			description: 'For growing teams',
+			href: '#pro',
+		},
+		{
+			value: 'enterprise',
+			label: 'Enterprise',
 			description: 'Custom contracts',
 			href: '#enterprise',
 		},
@@ -1678,16 +1689,16 @@ long lists.
 ```vue
 <BbButton
 	v-bb-dropdown="[
-		{ key: 'profile', text: 'View profile', href: '#profile' },
+		{ value: 'profile', label: 'View profile', href: '#profile' },
 		{
-			key: 'settings',
-			text: 'Settings',
+			value: 'settings',
+			label: 'Settings',
 			'prepend:icon': 'lucide:settings',
 			href: '#settings',
 		},
 		{
-			key: 'signout',
-			text: 'Sign out',
+			value: 'signout',
+			label: 'Sign out',
 			variant: 'destructive',
 			href: '#signout',
 		},
@@ -1727,8 +1738,8 @@ the same floor the select's own sheet holds.
 		v-bb-dropdown="{
 			compact: true,
 			items: [
-				{ key: 'rename', text: 'Rename' },
-				{ key: 'duplicate', text: 'Duplicate' },
+				{ value: 'rename', label: 'Rename' },
+				{ value: 'duplicate', label: 'Duplicate' },
 			],
 		}"
 		size="sm"
@@ -1772,8 +1783,8 @@ broadcast, on the flyout and the phone sheet alike; its magnifier is chrome),
 — a flex column with a 1px gap; a submenu's list is not reached), `item` — every entry, submenus included, a broadcast
 resolved per entry — and `itemText` / `itemIcon` / `itemDescription`, that
 entry's label, its prepend / append icons and its muted second line (the item's
-`text` / `prepend:icon` · `append:icon` / `description`), resolved with the entry's
-states (a per-entry `#<key>` slot replaces the label and description). States: `open`, and `selected` / `disabled` per entry.
+`label` / `prepend:icon` · `append:icon` / `description`), resolved with the entry's
+states (a per-entry `#<value>` slot replaces the label and description). States: `open`, and `selected` / `disabled` per entry.
 Groups, headings and dividers are not parts.
 
 The invoice View menu, restyled through those parts: a muted wash on
@@ -1836,30 +1847,30 @@ import type { BbDropdownItem } from 'bitboss-ui';
 // container instead).
 const items: BbDropdownItem[] = [
 	{
-		key: 'sort',
+		id: 'sort',
 		label: 'Sort by',
 		selectable: true,
 		items: [
-			{ key: 'recent', text: 'Most recent' },
-			{ key: 'name', text: 'Name (A–Z)' },
-			{ key: 'amount', text: 'Amount (high → low)' },
+			{ value: 'recent', label: 'Most recent' },
+			{ value: 'name', label: 'Name (A–Z)' },
+			{ value: 'amount', label: 'Amount (high → low)' },
 		],
 	},
 	{
-		key: 'tags',
+		id: 'tags',
 		label: 'Tags',
 		selectable: true,
 		multiple: true,
 		items: [
-			{ key: 'overdue', text: 'Overdue' },
-			{ key: 'vip', text: 'VIP' },
-			{ key: 'review', text: 'Needs review' },
+			{ value: 'overdue', label: 'Overdue' },
+			{ value: 'vip', label: 'VIP' },
+			{ value: 'review', label: 'Needs review' },
 		],
 	},
 	[
 		{
-			key: 'export',
-			text: 'Export CSV',
+			value: 'export',
+			label: 'Export CSV',
 			disabled: true,
 		},
 	],
@@ -1929,23 +1940,23 @@ const run = (name: string) => () => {
 };
 
 const items: Action[] = [
-	{ key: 'rename', text: 'Rename', onClick: run('rename') },
-	{ key: 'duplicate', text: 'Duplicate', onClick: run('duplicate') },
+	{ value: 'rename', label: 'Rename', onClick: run('rename') },
+	{ value: 'duplicate', label: 'Duplicate', onClick: run('duplicate') },
 	{
-		key: 'archive',
-		text: 'Archive',
+		value: 'archive',
+		label: 'Archive',
 		description: 'Hidden from the board, kept for 30 days',
 		onClick: run('archive'),
 	},
 	{
-		key: 'delete',
-		text: 'Delete project',
+		value: 'delete',
+		label: 'Delete project',
 		danger: true,
 		onClick: run('delete'),
 	},
 	{
-		key: 'purge',
-		text: 'Purge history',
+		value: 'purge',
+		label: 'Purge history',
 		danger: true,
 		disabled: true,
 	},
@@ -1964,7 +1975,7 @@ const dangerText = ({ item }: { item: Action }) => item.danger && 'font-medium';
 ```
 
 The function can also map a VALUE to its own classes. Here every status in a
-single-choice group gets its own tone: `pt:item-icon` looks the entry's `key`
+single-choice group gets its own tone: `pt:item-icon` looks the entry's `value`
 up in a map for the dot's color, and `pt:item` adds a wash of the same tone
 while that entry is the `selected` one. Adding a status is one row in the map.
 
@@ -2005,7 +2016,7 @@ import { ref } from 'vue';
 import { BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
 import type { BbDropdownItem } from 'bitboss-ui';
 
-// One look per VALUE: the per-item function reads the entry's `key` and looks
+// One look per VALUE: the per-item function reads the entry's `value` and looks
 // its classes up in a map, so every status gets its own tone — the dot on
 // `:pt:item-icon`, a wash of the same tone on `item` while it is the `selected`
 // one. A new status is one row in `tones`.
@@ -2027,12 +2038,12 @@ const labels: Record<Status, string> = {
 
 const items: BbDropdownItem[] = [
 	{
-		key: 'status',
+		id: 'status',
 		label: 'Set status',
 		selectable: true,
 		items: (Object.keys(labels) as Status[]).map((key) => ({
-			key,
-			text: labels[key],
+			value: key,
+			label: labels[key],
 			'prepend:icon': 'lucide:circle',
 		})),
 	},
@@ -2040,10 +2051,10 @@ const items: BbDropdownItem[] = [
 
 const status = ref<Status>('overdue');
 
-// A group has no `key` in `tones`, so only the status entries match.
-// (`BbDropdownItem` also covers a nested list, which has no `key`.)
+// A group has no `value`, so only the status rows match.
+// (`BbDropdownItem` also covers a nested list, which has no `value`.)
 const toneOf = (item: BbDropdownItem) =>
-	'key' in item ? tones[item.key as Status] : undefined;
+	'value' in item ? tones[item.value as Status] : undefined;
 </script>
 ```
 
@@ -2083,12 +2094,12 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - **Don't rebuild selection** with `onClick` + your own state — mark the group
   `selectable` and bind a `<BbDropdownGroup v-model>`.
 - **There is no bare `#item` slot** — a template slot named `item` renders
-  nothing. Use `item:prepend`/`item:append`, a group's `#<groupKey>:item…`, or
-  a per-key slot.
-- **Don't sort rows by key inside the shared slots.** When only one group's
-  rows need a custom look, use `#<groupKey>:item:prepend`; when a slot needs the
+  nothing. Use `item:prepend`/`item:append`, a group's `#<groupId>:item…`, or
+  a per-row `#<value>` slot.
+- **Don't sort rows by value inside the shared slots.** When only one group's
+  rows need a custom look, use `#<groupId>:item:prepend`; when a slot needs the
   record behind a row, put it in `meta` (through `itemProps` on a fetched group)
-  instead of looking it up by `item.key`.
+  instead of looking it up by `item.value`.
 - **Don't hand-roll the "current" mark in a switcher** (a custom `variant` plus
   a check in `item:append`). Make the group `selectable` and bind its
   `v-model` to the current id — the check, `aria-checked` and the radio role
@@ -2098,7 +2109,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - Item `variant`s other than `destructive` render only a class hook — register
   names via the `dropdownItemVariants` plugin option and ship their CSS.
 - `<BbDropdownGroup>` must sit in a `BbDropdown` (or `BbDropdownButton`)
-  default slot, its `id` must match a group `key`, and a `multiple` group's
+  default slot, its `id` must match a group's `id`, and a `multiple` group's
   model must be an array — all three misuses throw.
 - Placeholder texts default to the config locale's "Loading…" / "No results"
   strings (`locale` plugin option) unless you set `loading-text` /
@@ -2158,7 +2169,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the dropdown within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant — the same ladder `BbSelect` uses, on both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The label size does not change; density here is height, as it is for a select. A menu row is a touch target in a way a select option is not quite — a mis-tap fires the neighbouring COMMAND rather than picking the wrong value — so the compact sheet stops at 36px and never follows the flyout down to 24px. That is the same floor the select's sheet holds. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
-| `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too). |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too), and keeps its rows after a close. Without it the rows mount on each open and go once the menu has closed. |
 | `emptyText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group resolves to no items. A group's own `emptyText` overrides this; both fall back to the localized `common.emptyText` (`'No data to display'`). |
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
 | `failedText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group's latest load FAILED (its `items` getter threw). A group's own `failedText` overrides this; both fall back to the localized `common.failedText` (`"Couldn't load items"`). |
@@ -2188,9 +2199,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `input` | A searchable group's search field — a broadcast: it lands on every searchable group's field, desktop and phone alike. Its magnifier glyph is chrome. |
 | `list` | The top-level items container between the bands — the node that lays the entries out (a flex column with a 1px gap; on a phone, the sheet's items container). A submenu's list is not reached. Groups, headings and dividers are not parts. |
 | `item` | One menu entry, submenus included — a broadcast resolved per entry. Also takes a per-item function, called with the entry. |
-| `itemText` | An entry's label (its `text`) — resolved with that entry's states. A per-entry `#<key>` slot replaces it. Also takes a per-item function. |
+| `itemText` | An entry's label (its `label`) — resolved with that entry's states. A per-entry `#<value>` slot replaces it. Also takes a per-item function. |
 | `itemIcon` | An entry's prepend / append icons — resolved with that entry's states. Also takes a per-item function. |
-| `itemDescription` | An entry's muted second line (its `description`) — resolved with that entry's states. A per-entry `#<key>` slot replaces it. Also takes a per-item function. |
+| `itemDescription` | An entry's muted second line (its `description`) — resolved with that entry's states. A per-entry `#<value>` slot replaces it. Also takes a per-item function. |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
 
@@ -2204,7 +2215,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `hidden` — `(): void` — Emitted once the menu has finished closing.
 - `hide` — `(): void` — Emitted as soon as the menu starts to close.
-- `item:selected` — `(value: any): void` — The user selected a row in a selectable group, at the click — also when a controlled companion's app then refuses the value. The payload is the item's resolved value (its `item-value` for pipeline groups, else its `key`) — symmetric with `BbTable`'s `item:selected`.
+- `item:selected` — `(value: any): void` — The user selected a row in a selectable group, at the click — also when a controlled companion's app then refuses the value. The payload is the row's value (its `item-value` for pipeline groups, else its `value`) — symmetric with `BbTable`'s `item:selected`.
 - `item:unselected` — `(value: any): void` — The user unselected a row (a multiple toggle, a `clearable` re-click, a chip ×, or the old value a single pick replaces). Payload is the item's resolved value, matching `item:selected`.
 - `show` — `(): void` — Emitted as soon as the menu (the popover, or the sheet on a phone) starts to open.
 - `shown` — `(): void` — Emitted once the menu is open and its open transition has finished.
@@ -2213,21 +2224,21 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `activator` — scope: `BbDropdownActivatorSlotProps` `{ disabled?: boolean; loading: boolean; open: boolean; placement: Placement \| "cursor"; props: BbDropdownActivatorProps }` — The element that triggers the dropdown to open. Spread `props` onto your trigger element.
 - `default` — scope: `any` — Hosts `<BbDropdownGroup>` companions. They register their group with the dropdown and render nothing themselves.
-- `empty` — scope: `BbDropdownPlaceholderSlotProps` `{ groupKey?: string; text: string; error?: unknown }` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group.
+- `empty` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; text: string; error?: unknown }` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group.
 - `footer` — scope: `BbDropdownEdgeSlotProps` `{ disabled?: boolean; open: boolean; placement: Placement \| "cursor" }` — Content pinned to the bottom of the dropdown panel, outside the scroll area. Stays visible while the items scroll and is separated from them by a divider — for action buttons.
 - `header` — scope: `BbDropdownEdgeSlotProps` `{ disabled?: boolean; open: boolean; placement: Placement \| "cursor" }` — Content pinned to the top of the dropdown panel, outside the scroll area. Stays visible while the items scroll and is separated from them by a divider — for a title or a filter field.
-- `item:append` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; text: string }` — The trailing region of every row (and group title line), replacing its `append:icon`. A named slot wins over it; the submenu chevron and the check on a selected row take its place.
-- `item:prepend` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; text: string }` — The leading region of every row (and group title line), replacing its `prepend:icon`. A row's own or its group's named slot wins over it.
-- `loading` — scope: `BbDropdownPlaceholderSlotProps` `{ groupKey?: string; text: string; error?: unknown }` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group.
-- `#<key>` (named from data) — scope: `BbDropdownItemSlotProps` — One row's content (text and description), by its key; in a fetched group, by its resolved `itemValue`. Reserved keys (their slot is one of this component's own, so a key spelled like them is an error): `activator`, `default`, `empty`, `footer`, `header`, `item`, `loading`.
-- `#<key>:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — One row's leading region; replaces its `prepend:icon`.
-- `#<key>:append` (named from data) — scope: `BbDropdownItemSlotProps` — One row's trailing region; replaces its `append:icon` and its submenu chevron. The check takes its place on the selected row.
-- `#<groupKey>:item` (named from data) — scope: `BbDropdownItemSlotProps` — The content of every row of that group, and no other; a row's own `#<key>` still wins.
-- `#<groupKey>:item:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — The leading region of every row of that group — e.g. an avatar per record, drawn from `item.meta`, while other rows keep their `prepend:icon`.
-- `#<groupKey>:item:append` (named from data) — scope: `BbDropdownItemSlotProps` — The trailing region of every row of that group; replaces their `append:icon`. The check takes its place on the selected row.
-- `#<groupKey>` (named from data) — scope: `BbDropdownItemSlotProps` — That group's title line (the group is passed as `item`, `groupTitle` is `true`). Reserved keys (their slot is one of this component's own, so a key spelled like them is an error): `activator`, `default`, `empty`, `footer`, `header`, `item`, `loading`.
-- `#<groupKey>:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — The leading region of that group's title line.
-- `#<groupKey>:append` (named from data) — scope: `BbDropdownItemSlotProps` — The trailing region of that group's title line.
+- `item:append` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; label: string }` — The trailing region of every row (and group title line), replacing its `append:icon`. A named slot wins over it; the submenu chevron and the check on a selected row take its place.
+- `item:prepend` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; label: string }` — The leading region of every row (and group title line), replacing its `prepend:icon`. A row's own or its group's named slot wins over it.
+- `loading` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; text: string; error?: unknown }` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group.
+- `#<value>` (named from data) — scope: `BbDropdownItemSlotProps` — One row's content (label and description), by its value; in a fetched group, by its resolved `itemValue`. Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `activator`, `default`, `empty`, `footer`, `header`, `item`, `loading`.
+- `#<value>:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — One row's leading region; replaces its `prepend:icon`.
+- `#<value>:append` (named from data) — scope: `BbDropdownItemSlotProps` — One row's trailing region; replaces its `append:icon` and its submenu chevron. The check takes its place on the selected row.
+- `#<groupId>:item` (named from data) — scope: `BbDropdownItemSlotProps` — The content of every row of that group, and no other; a row's own `#<value>` still wins.
+- `#<groupId>:item:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — The leading region of every row of that group — e.g. an avatar per record, drawn from `item.meta`, while other rows keep their `prepend:icon`.
+- `#<groupId>:item:append` (named from data) — scope: `BbDropdownItemSlotProps` — The trailing region of every row of that group; replaces their `append:icon`. The check takes its place on the selected row.
+- `#<groupId>` (named from data) — scope: `BbDropdownItemSlotProps` — That group's title line (the group is passed as `item`, `groupTitle` is `true`). Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `activator`, `default`, `empty`, `footer`, `header`, `item`, `loading`.
+- `#<groupId>:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — The leading region of that group's title line.
+- `#<groupId>:append` (named from data) — scope: `BbDropdownItemSlotProps` — The trailing region of that group's title line.
 
 ## CSS custom properties
 
@@ -2249,12 +2260,12 @@ Set these on the element, or on a class you put on it, to retune this component
 
 - `BbDropdown` _(this component)_ — its own template binds: `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`
   - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
-    - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
     - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
   - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
       - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
-    - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbBaseButton`, `BbSpinner`
+    - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
+      - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - Also mounts `CommonPopover`, `DropdownPipelineResolver`
 
 ## See Also