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

package/dist/ai/source/BbDropdown.md

@@ -83,7 +83,11 @@
 			:role="panelIsDialog ? 'none' : 'menu'"
 			v-bind="passthrough.list"
 		>
-			<BbDropdownList ref="root-list" :groups="renderGroups" />
+			<BbDropdownList
+				v-if="rowsMounted"
+				ref="root-list"
+				:groups="renderGroups"
+			/>
 		</span>
 		<!-- Announcement channel for the placeholder rows. Sits OUTSIDE the
 			menu container: `role="menu"` admits only items and groups, and a
@@ -261,6 +265,14 @@ const hasOpenedOnce = useUntil(open, { initialValue: props.eager });
  * CommonPopover fades it out, so it stays reachable until the fade ends.
  */
 const panelInert = useClosingInert(open, () => props.transitionDuration);
+/**
+ * The rows live while the panel shows: mounted on open, dropped once the
+ * fade-out ends (the moment the panel goes `inert`), so a closed menu doesn't
+ * keep a node tree per row — 20 MB at 1,000 rows (PERF-MEASURE § BbDropdown).
+ * The panel and its `menu` container stay, so `aria-controls` still points at
+ * something. `eager` keeps them, as it always has.
+ */
+const rowsMounted = computed(() => props.eager || !panelInert.value);
 
 /**
  * Bound on CommonPopover's bubble, which is the root panel. `--max-h` caps it
@@ -432,7 +444,7 @@ const { resume, pause } = useIntersectionObserver(
 
 // --- selection state (owned by the dropdown) ----------------------------
 
-/** Current selection (item keys) per selectable group, keyed by group key. */
+/** Current selection (row keys) per selectable group, keyed by group id. */
 const internalSelection = reactive<Record<string, string[]>>({});
 
 // --- group registry (for <BbDropdownGroup> companions) ------------------
@@ -469,7 +481,7 @@ const findGroupById = (
 ): InternalGroup | undefined => {
 	for (const entry of items) {
 		if (isGroup(entry)) {
-			if (entry.key === groupId) return entry;
+			if (entry.id === groupId) return entry;
 			for (const child of groupItemsAsArray(entry.items)) {
 				const list = Array.isArray(child) ? child : [child];
 				for (const childItem of list) {
@@ -513,11 +525,11 @@ const findEntryKindById = (
 			continue;
 		}
 		if (isGroup(entry)) {
-			if (entry.key === key) return 'group';
+			if (entry.id === key) return 'group';
 			for (const child of groupItemsAsArray(entry.items)) {
 				const list = Array.isArray(child) ? child : [child];
 				for (const childItem of list) {
-					if (childItem.key === key) return 'item';
+					if (childItem.value === key) return 'item';
 					if (childItem.items) {
 						const found = findEntryKindById(childItem.items, key);
 						if (found) return found;
@@ -526,7 +538,7 @@ const findEntryKindById = (
 			}
 			continue;
 		}
-		if (entry.key === key) return 'item';
+		if (entry.value === key) return 'item';
 		if (entry.items) {
 			const found = findEntryKindById(entry.items, key);
 			if (found) return found;
@@ -545,7 +557,7 @@ const companionGroups = computed<DropdownGroupDescriptor[]>(() =>
 /**
  * Merges a companion descriptor onto the inline group it references. The
  * companion only overrides the fields it actually declares: anything it leaves
- * `undefined` (e.g. `items`/`text` on a bare `<BbDropdownGroup id v-model />`)
+ * `undefined` (e.g. `items`/`label` on a bare `<BbDropdownGroup id v-model />`)
  * falls back to the inline definition, so a companion can simply attach a
  * `v-model` to a group already declared in `items`.
  */
@@ -555,7 +567,7 @@ const mergeCompanionGroup = (
 ): InternalGroup => ({
 	...inline,
 	group: true,
-	key: inline.key,
+	id: inline.id,
 	// Propagate the raw values; the selectable/non-selectable decision is made
 	// once in `normalizeGroups` (a group is selectable only when `selectable` or
 	// `multiple` is explicitly set).
@@ -576,7 +588,7 @@ const toGroupFromCompanion = (
 ): InternalGroup => {
 	return {
 		group: true,
-		key: companion.key,
+		id: companion.key,
 		label: companion.label ?? baseline?.label,
 		hideLabel: companion.hideLabel ?? baseline?.hideLabel,
 		items: companion.items ?? baseline?.items ?? [],
@@ -607,7 +619,7 @@ const applyCompanionToItems = (
 
 	const nextItems = items.map((entry) => {
 		if (isGroup(entry)) {
-			if (entry.key === group.key) {
+			if (entry.id === group.id) {
 				found = true;
 				return mergeCompanionGroup(entry, group);
 			}
@@ -638,7 +650,7 @@ const applyCompanionToItems = (
 
 /**
  * `props.items` with companion groups merged in: a companion merges onto the
- * inline group sharing its `key` (inheriting any fields it doesn't declare),
+ * inline group sharing its `id` (inheriting any fields it doesn't declare),
  * otherwise it is appended.
  */
 const mergedItems = computed<Item[]>(() => {
@@ -653,12 +665,12 @@ const mergedItems = computed<Item[]>(() => {
 				logger.throw(
 					`[BbDropdownGroup] "${companion.key}" refers to a menu item, not a selectable group. ` +
 						'`<BbDropdownGroup>` can only attach to a group (an entry with `selectable`, `multiple`, or `group: true`). ' +
-						'Point `id` at a group key.'
+						'Point `id` at a group `id`.'
 				);
 			}
 			logger.throw(
 				`[BbDropdownGroup] Missing minimum config for group "${companion.key}". ` +
-					'Provide `items`, `selectable`, `multiple`, or `group` keys in order to identify a group or define a baseline group with the same key in `BbDropdown.items`.'
+					'Provide `items`, `selectable`, `multiple`, or `group` keys in order to identify a group or define a baseline group with the same `id` in `BbDropdown.items`.'
 			);
 		}
 
@@ -669,15 +681,39 @@ const mergedItems = computed<Item[]>(() => {
 	return base;
 });
 
+/**
+ * What a group shows checked: its selection, or — on a single group with
+ * nothing selected, i.e. a `null` model — its "None" row, the row whose value
+ * is `null` (Q64.3, owner 2026-10-07): BbSelect and BbRadioGroup show a `null`
+ * model the same way, matching by hash. Display only: the selection stays
+ * empty, so the model stays `null` and no event fires.
+ */
+const displayedSelection = (group: NormalizedGroup): string[] => {
+	const keys = internalSelection[group.id ?? ''] ?? [];
+	if (group.multiple || keys.length || !group.id) return keys;
+	const pipeline = pipelineGroupKeys.value.includes(group.id);
+	const none = group.items.find(
+		(item) =>
+			!item.keyless &&
+			!item.placeholder &&
+			(pipeline
+				? pipelineMaps[group.id!]?.valueByKey.get(item.rowKey) === null
+				: item.value === null)
+	);
+	return none ? [none.rowKey] : keys;
+};
+
+const normalizedGroups = computed(() => normalizeGroups(mergedItems.value));
+
 /**
  * Groups handed to the panel, with the live selection injected from
- * {@link internalSelection} for selectable groups.
+ * {@link internalSelection} for selectable groups. Normalized in a step of its
+ * own so a pick re-runs only this map: the rows keep their objects, and a row
+ * whose state didn't change isn't re-rendered (PERF-MEASURE § BbDropdown).
  */
 const renderGroups = computed(() =>
-	normalizeGroups(mergedItems.value).map((group) =>
-		group.selectable
-			? { ...group, selected: internalSelection[group.key ?? ''] ?? [] }
-			: group
+	normalizedGroups.value.map((group) =>
+		group.selectable ? { ...group, selected: displayedSelection(group) } : group
 	)
 );
 
@@ -733,11 +769,11 @@ const isPipelineGroup = (group: InternalGroup) =>
 	group.itemValue != null ||
 	group.max != null;
 
-/** Keys of every pipeline group declared in `items`, at any nesting depth. */
+/** Ids of every pipeline group declared in `items`, at any nesting depth. */
 const collectPipelineKeys = (items: Item[], acc: string[] = []): string[] => {
 	for (const entry of items) {
 		if (isGroup(entry)) {
-			if (entry.key && isPipelineGroup(entry)) acc.push(entry.key);
+			if (entry.id && isPipelineGroup(entry)) acc.push(entry.id);
 			for (const child of groupItemsAsArray(entry.items)) {
 				for (const item of Array.isArray(child) ? child : [child]) {
 					if (item.items) collectPipelineKeys(item.items, acc);
@@ -765,10 +801,10 @@ const pipelineGroupKeys = computed(() =>
 const topLevelPipelineKeys = computed(() =>
 	(props.items ?? [])
 		.filter(
-			(entry): entry is InternalGroup & { key: string } =>
-				isGroup(entry) && !!entry.key && isPipelineGroup(entry)
+			(entry): entry is InternalGroup & { id: string } =>
+				isGroup(entry) && !!entry.id && isPipelineGroup(entry)
 		)
-		.map((entry) => entry.key as string)
+		.map((entry) => entry.id as string)
 );
 
 /** Per-pipeline-group key⇄value/item/text maps, published by the resolvers. */
@@ -791,15 +827,18 @@ const groupLoading = reactive<Record<string, boolean>>({});
 const groupFetching = reactive<Record<string, boolean>>({});
 
 /**
- * Resolve a selection key to the item's value — the mapped `item-value` for
- * pipeline groups, else the key itself (legacy groups: the key *is* the value).
- * Shared by the registry and the panel's own `toggleSelect` so both emit the
- * same value in `item:selected`/`item:unselected` (symmetric with `BbTable`).
+ * Resolve a selection key to the row's value — the mapped `item-value` for
+ * pipeline groups, else the hand-written row's `value` (`undefined` when no
+ * row has that key). Shared by the registry and the panel's own
+ * `toggleSelect` so both emit the same value in
+ * `item:selected`/`item:unselected` (symmetric with `BbTable`).
  */
 const valueForItemKey = (groupKey: string, itemKey: string) =>
 	pipelineGroupKeys.value.includes(groupKey)
 		? pipelineMaps[groupKey]?.valueByKey.get(itemKey)
-		: itemKey;
+		: findRenderGroupDeep(groupKey)?.items.find(
+				(item) => item.rowKey === itemKey && !item.keyless
+			)?.value;
 
 /**
  * A group's `multiple`/`selectable` flags, derived from its raw config at ANY
@@ -818,11 +857,11 @@ const groupFlagsFor = (key: string) => {
 	};
 };
 
-/** A normalized group (with resolved items) by key at any nesting depth. */
+/** A normalized group (with resolved items) by id at any nesting depth. */
 const findRenderGroupDeep = (key: string): NormalizedGroup | undefined => {
 	const walk = (items: Item[]): NormalizedGroup | undefined => {
 		for (const group of normalizeGroups(items)) {
-			if (group.key === key) return group;
+			if (group.id === key) return group;
 			for (const item of group.items) {
 				if (item.items) {
 					const found = walk(item.items);
@@ -835,9 +874,8 @@ const findRenderGroupDeep = (key: string): NormalizedGroup | undefined => {
 	return walk(mergedItems.value);
 };
 
-/** Selection key for a value — `hash` for pipeline groups, the value for legacy. */
-const keyForValue = (key: string, value: any) =>
-	pipelineGroupKeys.value.includes(key) ? hash(value) : value;
+/** Selection key for a value: its `hash`, the key every row is stored under. */
+const keyForValue = (_key: string, value: any) => hash(value);
 
 /**
  * A group's current selection in `v-model` shape: a companion's raw v-model when
@@ -907,14 +945,14 @@ provideDropdownGroupRegistry({
 		else companionModels.set(key, value);
 	},
 	modelValueFor,
-	// Pipeline groups resolve to the mapped value (or `undefined` when items
-	// aren't loaded yet — the companion uses that to avoid clobbering an
-	// externally-set v-model). Legacy groups: the key *is* the value.
+	// Pipeline groups resolve to the mapped value, hand-written ones to the
+	// row's `value` (`undefined` when items aren't loaded yet — the companion
+	// uses that to avoid clobbering an externally-set v-model).
 	valueForKey: valueForItemKey,
 	keyForValue,
 	itemForKey: (key, itemKey) =>
 		pipelineMaps[key]?.itemByKey.get(itemKey) ??
-		findRenderGroupDeep(key)?.items.find((item) => item.key === itemKey),
+		findRenderGroupDeep(key)?.items.find((item) => item.rowKey === itemKey),
 	// Raw, pre-merge group definition: the companion reads its pipeline config
 	// (items getter, itemText/itemValue, max, …) from here. Must come from
 	// `props.items`, not `mergedItems` — the latter already has this group's
@@ -927,11 +965,11 @@ provideDropdownGroupRegistry({
 
 // --- public read-only context (`useBbDropdownContext`) -------------------
 
-/** Keys of every selectable group declared in `items`, at any nesting depth. */
+/** Ids of every selectable group declared in `items`, at any nesting depth. */
 const collectSelectableKeys = (items: Item[], acc: string[] = []): string[] => {
 	for (const entry of items) {
 		if (isGroup(entry)) {
-			if (entry.key && isSelectableGroup(entry)) acc.push(entry.key);
+			if (entry.id && isSelectableGroup(entry)) acc.push(entry.id);
 			for (const child of groupItemsAsArray(entry.items)) {
 				for (const item of Array.isArray(child) ? child : [child]) {
 					if (item.items) collectSelectableKeys(item.items, acc);
@@ -950,7 +988,7 @@ const collectSelectableKeys = (items: Item[], acc: string[] = []): string[] => {
  * Per-group state mirrored to `useBbDropdownContext`. Built from data the
  * dropdown already holds — selection + the resolvers' published value/text/item
  * maps — so reading it costs no fetch. A selected value the owning group has not
- * yet loaded resolves to `{ value }` alone (text/original fill in lazily).
+ * yet loaded resolves to `{ value }` alone (label/original fill in lazily).
  */
 const contextGroups = computed<Record<string, BbDropdownContextGroup>>(() => {
 	const result: Record<string, BbDropdownContextGroup> = {};
@@ -974,24 +1012,19 @@ const contextGroups = computed<Record<string, BbDropdownContextGroup>>(() => {
 		result[key] = {
 			// Config first, live state second: the fields below always win.
 			...(config as Omit<InternalGroup, 'items'>),
-			key,
+			id: key,
 			value: model,
 			multiple: declared?.multiple ?? false,
 			selectable: declared ? isSelectableGroup(declared) : false,
 			loading: !!groupFetching[key],
 			selectedOptions: values.map((value) => {
 				const itemKey = keyForValue(key, value);
+				const row = group?.items.find((item) => item.rowKey === itemKey);
 				return {
 					value,
-					text:
-						maps?.textByKey.get(itemKey) ??
-						group?.items.find((item) => item.key === itemKey)?.text,
-					description:
-						maps?.descriptionByKey.get(itemKey) ??
-						group?.items.find((item) => item.key === itemKey)?.description,
-					original:
-						maps?.itemByKey.get(itemKey) ??
-						group?.items.find((item) => item.key === itemKey),
+					label: maps?.textByKey.get(itemKey) ?? row?.label,
+					description: maps?.descriptionByKey.get(itemKey) ?? row?.description,
+					original: maps?.itemByKey.get(itemKey) ?? row,
 				};
 			}),
 		};
@@ -1012,7 +1045,7 @@ const selectableGroupCount = computed(
 
 /**
  * Toggles `item` in `group` (passed by the panel, so nested-submenu groups work
- * too). Single-select groups are radios: they keep one key, and re-clicking the
+ * too). Single-select groups are radios: they keep one row, and re-clicking the
  * selected item keeps it — unless the group is `clearable`, when the re-click
  * clears it (Q47.2, owner 2026-09-22). Multi-select groups toggle. Emits
  * `item:selected`/`item:unselected` per changed item (none for a no-op
@@ -1025,18 +1058,20 @@ const selectableGroupCount = computed(
  * below still describe the click, refused or not (D2a, D4).
  */
 const toggleSelect = (group: NormalizedGroup, item: KeyedItem) => {
-	const groupId = group.key;
+	const groupId = group.id;
 	if (!groupId) return;
 
-	const prev = internalSelection[groupId] ?? [];
+	// What the group shows (the "None" row of a `null` model included), so a
+	// click on the row already shown checked is a re-click, not a new pick.
+	const prev = displayedSelection(group);
 	const set = new Set(prev);
 	if (group.multiple) {
-		set.has(item.key) ? set.delete(item.key) : set.add(item.key);
-	} else if (set.has(item.key)) {
+		set.has(item.rowKey) ? set.delete(item.rowKey) : set.add(item.rowKey);
+	} else if (set.has(item.rowKey)) {
 		if (group.clearable) set.clear();
 	} else {
 		set.clear();
-		set.add(item.key);
+		set.add(item.rowKey);
 	}
 	const next = [...set];
 	const added = next.filter((key) => !prev.includes(key));
@@ -1044,8 +1079,8 @@ const toggleSelect = (group: NormalizedGroup, item: KeyedItem) => {
 
 	const controlled = isControlled(groupId);
 	if (controlled) {
-		const value = valueForItemKey(groupId, item.key);
-		if (added.length) pickListeners.get(groupId)?.(item.key);
+		const value = valueForItemKey(groupId, item.rowKey);
+		if (added.length) pickListeners.get(groupId)?.(item.rowKey);
 		if (group.multiple) {
 			if (added.length) requestChange(groupId, { add: value });
 			else if (removed.length) requestChange(groupId, { remove: value });
@@ -1056,7 +1091,7 @@ const toggleSelect = (group: NormalizedGroup, item: KeyedItem) => {
 	}
 
 	const itemByKey = (key: string) =>
-		group.items.find((candidate) => candidate.key === key);
+		group.items.find((candidate) => candidate.rowKey === key);
 	// Emit the item's resolved value, symmetric with `BbTable` and the companion.
 	added.forEach((key) => {
 		if (itemByKey(key)) emit('item:selected', valueForItemKey(groupId, key));
@@ -1072,10 +1107,11 @@ const toggleSelect = (group: NormalizedGroup, item: KeyedItem) => {
 	// Radio-like sole top-level selectable group: close once a selection is made.
 	const isTopLevelSole =
 		selectableGroupCount.value === 1 &&
-		renderGroups.value.some((g) => g.selectable && g.key === groupId);
+		renderGroups.value.some((g) => g.selectable && g.id === groupId);
 	// A re-click that kept the pick is a pick of the same value: close too.
 	const picked =
-		added.length > 0 || (prev.includes(item.key) && next.includes(item.key));
+		added.length > 0 ||
+		(prev.includes(item.rowKey) && next.includes(item.rowKey));
 	if (picked && !group.multiple && isTopLevelSole) {
 		closeDropdown();
 		focusActivator();
@@ -1123,11 +1159,11 @@ const runItemAction = async (
 
 	if (!isThenable(result)) return;
 
-	loadingKeys.add(item.key);
+	loadingKeys.add(item.rowKey);
 	try {
 		await result;
 	} finally {
-		loadingKeys.delete(item.key);
+		loadingKeys.delete(item.rowKey);
 	}
 };
 
@@ -1168,7 +1204,10 @@ provideDropdownContext({
 	isGroupLoading: (key) => !!groupLoading[key],
 	isTopLevelPipeline: (key) => topLevelPipelineKeys.value.includes(key),
 	queryDebounceTime: computed(() => props.queryDebounceTime ?? 300),
-	selectedFor: (key) => internalSelection[key] ?? [],
+	selectedFor: (key) => {
+		const group = findRenderGroupDeep(key);
+		return group ? displayedSelection(group) : (internalSelection[key] ?? []);
+	},
 	loadingText: computed(() => props.loadingText),
 	emptyText: computed(() => props.emptyText),
 	failedText: computed(() => props.failedText),
@@ -1182,7 +1221,7 @@ provideDropdownContext({
 			key: itemKey,
 			text:
 				maps?.textByKey.get(itemKey) ??
-				group?.items.find((item) => item.key === itemKey)?.text ??
+				group?.items.find((item) => item.rowKey === itemKey)?.label ??
 				readableValue(
 					valueForItemKey(key, itemKey) ?? appValueFor(key, itemKey)
 				),
@@ -1617,9 +1656,9 @@ export type { DropdownItemVariantType };
 export type DropdownTrigger = 'click' | 'contextMenu';
 
 /**
- * Props shared between {@link InternalItem} and {@link InternalGroup}. Both are
- * dropdown entries identified by `key` with optional icons, a variant, and a
- * click handler.
+ * Props shared between {@link InternalItem} and {@link InternalGroup}: optional
+ * icons, a variant, a click handler and `meta`. A row is identified by its
+ * `value`, a group by its `id`.
  */
 type DropdownEntryBase = {
 	/**
@@ -1628,25 +1667,11 @@ type DropdownEntryBase = {
 	 * group (the check is), or when an append slot fills the region.
 	 */
 	'append:icon'?: IconType;
-	/**
-	 * Key used to identify the entry. REQUIRED when anything outside the menu
-	 * reads it: a row in a `selectable` group (the v-model holds it), a row or
-	 * group with its own slot (`#<key>` is named by it), a group bound by a
-	 * `<BbDropdownGroup id>` or selectable. Optional on a plain action row (it
-	 * runs its `onClick`) and a layout-only group: the dropdown then derives an
-	 * internal identity from the text that nothing outside ever sees. A keyless
-	 * row in a selectable group renders but can't be selected. Load-bearing
-	 * identifiers are written, never derived — `bitboss-ui check` flags a
-	 * missing required key where the items are in the same file.
-	 */
-	key?: string;
-	/** @internal Set by the dropdown on a row it derived a key for (Q53.17). */
-	keyless?: true;
 	/**
 	 * Your own data for this entry, carried untouched to its slots (as
 	 * `item.meta`) and to per-item `pt` functions. The dropdown never reads it
 	 * and never puts it on the DOM. Typically the record the entry stands for,
-	 * e.g. `{ key: clinic.id, text: clinic.name, meta: clinic }`; a fetched
+	 * e.g. `{ value: clinic.id, label: clinic.name, meta: clinic }`; a fetched
 	 * group sets it through `itemProps` (`(clinic) => ({ meta: clinic })`).
 	 */
 	meta?: any;
@@ -1665,14 +1690,14 @@ type DropdownEntryBase = {
 
 /**
  * The `itemProps` fields of a fetched (pipeline) dropdown group: everything a
- * hand-written row accepts except its identity and structure (`key`, `text`,
- * `items`, `group`) and `disabled`. See {@link InternalGroup.itemProps}.
+ * hand-written row accepts except its identity and structure (`value`,
+ * `label`, `items`, `group`) and `disabled`. See {@link InternalGroup.itemProps}.
  */
 export type DropdownItemFields = Omit<
 	BbBaseButtonProps,
 	'block' | 'tag' | 'type' | 'text' | 'disabled'
 > &
-	Omit<DropdownEntryBase, 'key'> & {
+	DropdownEntryBase & {
 		/** Muted second line under the row text. */
 		description: string;
 	};
@@ -1715,13 +1740,46 @@ type SubmenuExclusive =
 	  }
 	| { items?: undefined };
 
-export type InternalItem = Omit<BbBaseButtonProps, 'block' | 'tag' | 'type'> &
+export type InternalItem = Omit<
+	BbBaseButtonProps,
+	'block' | 'tag' | 'type' | 'text'
+> &
 	SubmenuExclusive &
 	DropdownEntryBase & {
-		/** Display text rendered as the button label. */
-		text: string;
+		/** The row's text. */
+		label: string;
 		/**
-		 * Muted descriptive line rendered below `text`. The row grows to fit it,
+		 * The row's identity, any type: what `v-model` holds when its group is
+		 * `selectable` (compared by `hash()`, like `BbSelect` options, so `null`
+		 * and objects are values too: a `value: null` row is the group's "None"),
+		 * the name of its own slots (`#<value>`, a string or number value
+		 * through `slotKey`; any other type gets the shared slots only) and the
+		 * seed of its submenu's id.
+		 *
+		 * REQUIRED when anything outside the menu reads it: a row in a
+		 * `selectable` group, a row with its own slot. Optional on a plain
+		 * action row (it runs its `onClick`): the dropdown then derives an
+		 * internal identity from the label that nothing outside ever sees. A row
+		 * without a `value` in a selectable group renders disabled. Load-bearing
+		 * identifiers are written, never derived — `bitboss-ui check` flags a
+		 * missing required `value` where the items are in the same file.
+		 */
+		value?: unknown;
+		/** Rows have no `key` (that is `value`). Guards against the old shape. */
+		key?: never;
+		/** Rows have no `text` (that is `label`). Guards against the old shape. */
+		text?: never;
+		/** @internal Set by the dropdown on a row it derived an identity for (Q53.17). */
+		keyless?: true;
+		/**
+		 * @internal The row's selection key, set by the dropdown: `hash(value)`,
+		 * or the identity it derived for a row without a `value`.
+		 */
+		rowKey?: string;
+		/** @internal The row's readable DOM token, set by the dropdown (submenu ids). */
+		domKey?: string;
+		/**
+		 * Muted descriptive line rendered below `label`. The row grows to fit it,
 		 * while icons/check/chevron stay aligned with the title line.
 		 */
 		description?: string;
@@ -1748,7 +1806,7 @@ export type InternalItem = Omit<BbBaseButtonProps, 'block' | 'tag' | 'type'> &
 		 * async items load (`'loading'`), when it resolved empty (`'empty'`), or
 		 * when its latest load FAILED (`'failed'`: the footer under whatever rows a
 		 * `stash` keeps listed, Q61.15). Rendered as a non-interactive row that
-		 * shows `text` or, when provided, the dropdown's `loading` / `empty` slot.
+		 * shows `label` or, when provided, the dropdown's `loading` / `empty` slot.
 		 * Internal — set by `BbDropdownGroup`.
 		 */
 		placeholder?: 'loading' | 'empty' | 'failed';
@@ -1768,8 +1826,8 @@ export type InternalItem = Omit<BbBaseButtonProps, 'block' | 'tag' | 'type'> &
 		/**
 		 * Optional slot token used to resolve per-item named slots. Primarily set
 		 * by the pipeline resolver so slot names can be derived from the resolved
-		 * `itemValue` (readable), while `key` remains the hash-based selection id.
-		 * Internal.
+		 * `itemValue` (readable), while `rowKey` remains the hash-based selection
+		 * id. Internal.
 		 */
 		slotKey?: string;
 	};
@@ -1810,6 +1868,18 @@ export type DropdownGroupItemsGetter =
 	  ) => any[] | Promise<any[]>);
 
 export type InternalGroup = DropdownEntryBase & {
+	/**
+	 * The group's identity: REQUIRED on a `selectable` group (its picks are
+	 * stored under it, and `useBbDropdownContext` keys the group by it), on a
+	 * group bound by a `<BbDropdownGroup id>` (the same word) and on a group
+	 * with its own slots (`#<id>:item`, `#<id>`). Optional on a layout-only
+	 * group; a selectable group without one renders as a plain group.
+	 */
+	id?: string;
+	/** Groups have no `key` (that is `id`). Guards against the old shape. */
+	key?: never;
+	/** Groups have no `value`; their rows do. */
+	value?: never;
 	/** Pipeline groups only. Re-run the async getter when any of these change. */
 	dependencies?: unknown[];
 	/** Pipeline groups only. Debounce (ms) for `dependencies`-driven re-fetch. */
@@ -1848,17 +1918,19 @@ export type InternalGroup = DropdownEntryBase & {
 		| any[]
 		| DropdownGroupItemsGetter;
 	/**
-	 * Pipeline groups only. Path/getter producing each item's display text.
-	 * Defaults to `JSON.stringify(item)` (or the string itself for strings).
+	 * Pipeline groups only. Path/getter producing each item's display text
+	 * (a string item is its own text).
 	 *
-	 * @defaultValue `JSON.stringify(item)`
+	 * Unset: own `label`, else `text` (`{ label, value }` needs no accessor).
+	 *
+	 * @defaultValue own `label`, else `text`, else `JSON.stringify(item)`
 	 */
 	itemText?: string | ((item: any) => string);
 	/**
 	 * Pipeline groups only. The ADDITIONAL fields of each fetched row — never its
 	 * text or value, which stay on `itemText` / `itemValue`. A fetched row takes
 	 * every field a hand-written row accepts except its identity and structure
-	 * (`key`, `text`, `items`, `group`) and `disabled`: `description`, the icons,
+	 * (`value`, `label`, `items`, `group`) and `disabled`: `description`, the icons,
 	 * `variant`, `onClick`, `href` / `to` and the rest of the link and Inertia
 	 * options.
 	 *
@@ -1869,17 +1941,18 @@ export type InternalGroup = DropdownEntryBase & {
 	 * the handler: `onClick: (user) => () => open(user)`.
 	 *
 	 * Nothing is read off the raw item implicitly — without `itemProps` a row
-	 * has only its text. An empty value means the field is absent. To disable
+	 * has only its label. An empty value means the field is absent. To disable
 	 * individual rows use a `selectable` predicate on the group; fetched groups
 	 * are for selection (see plans/ITEM-DESCRIPTION.md v2.4).
 	 */
 	itemProps?: BbDropdownItemProps;
 	/**
 	 * Pipeline groups only. Path/getter producing each item's value — what
-	 * `v-model` surfaces; its hash is the internal selection key. Defaults to the
-	 * whole item (so the key is the hash of the entire object).
+	 * `v-model` surfaces; its hash is the internal selection key.
+	 *
+	 * Unset: own `value`, even `null`.
 	 *
-	 * @defaultValue the whole item
+	 * @defaultValue own `value`, else the whole item
 	 */
 	itemValue?: string | ((item: any) => any);
 	/** Pipeline groups only. Placeholder row text while async items load. */
@@ -1970,7 +2043,7 @@ export type InternalGroup = DropdownEntryBase & {
 	 */
 	selectable?: boolean | ((item: any) => boolean);
 	/**
-	 * Searchable pipeline groups only. Accumulate the items behind *selected* keys
+	 * Searchable pipeline groups only. Accumulate the items behind *selected* values
 	 * so they stay resolvable across searches. Without it, selecting an item in one
 	 * search and then searching for something else leaves the earlier selection
 	 * unresolvable (its value/text is gone from the current results) — which in a
@@ -2015,7 +2088,7 @@ export const groupItemsAsArray = (
  * - an array of items — rendered as an anonymous divider-separated group;
  * - a {@link InternalGroup} object — a titled / selectable section.
  *
- * The shapes can be mixed, e.g. `[item, [item, item], { key, title, items }]`.
+ * The shapes can be mixed, e.g. `[item, [item, item], { id, label, items }]`.
  */
 export type Item = InternalItem | InternalGroup | Item[];
 
@@ -2060,10 +2133,11 @@ export const isGroup = (entry: Item): entry is InternalGroup =>
  * defaults are resolved here. Produced by `normalizeGroups`.
  */
 /**
- * A row after normalization: its `key` is always set — the consumer's, or one
- * the dropdown derived for a keyless action row (`keyless`, Q53.17).
+ * A row after normalization: its `rowKey` is always set — `hash(value)`, or an
+ * identity the dropdown derived for an action row without a `value`
+ * (`keyless`, Q53.17).
  */
-export type KeyedItem = InternalItem & { key: string };
+export type KeyedItem = InternalItem & { rowKey: string; domKey: string };
 
 export type NormalizedGroup = {
 	'append:icon'?: IconType;
@@ -2071,11 +2145,11 @@ export type NormalizedGroup = {
 	clearable?: boolean;
 	/** Whether a divider is rendered before this group. */
 	divider: boolean;
-	/** Keys matched against each raw item when searching (empty ⇒ match text). */
+	/** Keys matched against each raw item when searching (empty ⇒ match the label). */
 	filterBy?: string[];
 	items: KeyedItem[];
-	/** Group key (when it originated from a {@link InternalGroup} object). */
-	key?: string;
+	/** Group id (when it originated from a {@link InternalGroup} object). */
+	id?: string;
 	/** Fixed max-height (px number or CSS length) of this group's item region. */
 	maxHeight?: number | string;
 	/** The group's own `meta`, untouched. */
@@ -2088,7 +2162,7 @@ export type NormalizedGroup = {
 	/** Placeholder for this group's search field. */
 	searchPlaceholder?: string;
 	selectable: boolean;
-	/** Selected item keys (injected by `BbDropdown`; empty for non-selectable groups). */
+	/** Selected row keys (`rowKey`; injected by `BbDropdown`; empty for non-selectable groups). */
 	selected: string[];
 	/** The group's label. Loose/anonymous groups have none. */
 	label?: string;
@@ -2112,7 +2186,7 @@ export type MappedItem = InternalItem & {
  * Passthrough parts of `BbDropdown` (plans/passthrough/BbDropdown.md). Groups,
  * headings and dividers are not parts.
  *
- * Per-item functions: on the instance, an entry part (`item`, `itemText`, `itemIcon`, `itemDescription`) also accepts `({ item, selected, … }) => PtValue | false | null | undefined` — `item` is the menu entry (an `Item`: its `text`, `key`, `description`, whatever else you put on it), and every state a boolean beside it, on for it (`selected`, `disabled`, …) — in the `pt` object or the `:pt:<part>` attribute, never on a `<part>:<state>` key and never in the global map or a scope (they ship as JSON). Its result is merged last, after every state entry, through the same deduper; a falsy result leaves the entry as it was. See the passthrough guide, _Per-item functions_.
+ * Per-item functions: on the instance, an entry part (`item`, `itemText`, `itemIcon`, `itemDescription`) also accepts `({ item, selected, … }) => PtValue | false | null | undefined` — `item` is the menu entry (an `Item`: its `label`, `value`, `description`, whatever else you put on it), and every state a boolean beside it, on for it (`selected`, `disabled`, …) — in the `pt` object or the `:pt:<part>` attribute, never on a `<part>:<state>` key and never in the global map or a scope (they ship as JSON). Its result is merged last, after every state entry, through the same deduper; a falsy result leaves the entry as it was. See the passthrough guide, _Per-item functions_.
  *
  * @part root - The floating element — an invisible positioning wrapper; a
  *   `class` on the component lands here. No node on the phone sheet: style
@@ -2132,13 +2206,13 @@ export type MappedItem = InternalItem & {
  *   headings and dividers are not parts.
  * @part item - One menu entry, submenus included — a broadcast resolved per
  *   entry. Also takes a per-item function, called with the entry.
- * @part itemText - An entry's label (its `text`) — resolved with that
- *   entry's states. A per-entry `#<key>` slot replaces it. Also takes a
+ * @part 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.
  * @part itemIcon - An entry's prepend / append icons — resolved with that
  *   entry's states. Also takes a per-item function.
  * @part itemDescription - An entry's muted second line (its `description`) —
- *   resolved with that entry's states. A per-entry `#<key>` slot replaces it.
+ *   resolved with that entry's states. A per-entry `#<value>` slot replaces it.
  *   Also takes a per-item function.
  */
 export type BbDropdownPtPart =
@@ -2277,7 +2351,8 @@ export type BbDropdownProps = {
 	disabled?: boolean;
 	/**
 	 * Renders the menu panel at mount instead of on the first open (the phone
-	 * sheet's too).
+	 * 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.
 	 */
 	eager?: boolean;
 	/**
@@ -2404,8 +2479,8 @@ export type BbDropdownEvents = {
 	/**
 	 * 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`.
+	 * row's value (its `item-value` for pipeline groups, else its `value`) —
+	 * symmetric with `BbTable`'s `item:selected`.
 	 */
 	(e: 'item:selected', value: any): void;
 	/**
@@ -2451,11 +2526,11 @@ export type BbDropdownEdgeSlotProps = {
 
 /**
  * The group a slot renders in, as item slots see it. Anonymous groups (loose
- * items, plain arrays) have no `key` and no `label`.
+ * items, plain arrays) have no `id` and no `label`.
  */
 export type BbDropdownSlotGroup = {
-	/** The group's key, when it was declared as a group object. */
-	key?: string;
+	/** The group's id, when it was declared as a group object. */
+	id?: string;
 	/** The group's label, when it has one (also when `hideLabel` hides it). */
 	label?: string;
 	/** The group's own `meta`. */
@@ -2503,14 +2578,14 @@ export type BbDropdownItemSlotProps = {
 	placement: BbDropdownProps['placement'];
 	/** Whether the item currently sits in a selectable group and is selected. */
 	selected: boolean;
-	/** The resolved display text for this item. */
-	text: InternalItem['text'];
+	/** The row's label (on a group's title line, the group's label). */
+	label: InternalItem['label'];
 };
 
 /** Props exposed by the `loading` and `empty` placeholder slots. */
 export type BbDropdownPlaceholderSlotProps = {
-	/** Key of the group this placeholder belongs to. */
-	groupKey?: string;
+	/** Id of the group this placeholder belongs to. */
+	groupId?: string;
 	/** Resolved placeholder text (group `loadingText`/`emptyText`/`failedText` → dropdown default). */
 	text: string;
 	/**
@@ -2522,23 +2597,24 @@ export type BbDropdownPlaceholderSlotProps = {
 };
 
 /**
- * Besides the fixed slots, every entry gets named slots from its key run
- * through `slotKey` (`'practice-switcher'` → `practice_switcher`). The most
- * specific slot a row has wins: its own, then its group's, then the shared
- * `item:prepend` / `item:append`. Each edge has ONE occupant: a slot replaces
- * the `prepend:icon` / `append:icon`. On the trailing edge the selected row's
- * check beats every slot, a row's own `#<key>:append` beats the submenu
- * chevron, and the chevron beats the group-wide and shared slots.
+ * Besides the fixed slots, every row gets named slots from its `value` (a
+ * string or number) run through `slotKey` (`'practice-switcher'` →
+ * `practice-switcher`, `'Delete file'` → `delete-file`), and every group from
+ * its `id`. The most specific slot a row has wins: its own, then its group's,
+ * then the shared `item:prepend` / `item:append`. Each edge has ONE occupant: a
+ * slot replaces the `prepend:icon` / `append:icon`. On the trailing edge the
+ * selected row's check beats every slot, a row's own `#<value>:append` beats
+ * the submenu chevron, and the chevron beats the group-wide and shared slots.
  *
- * @dynamicSlot `<key>` {BbDropdownItemSlotProps} - One row's content (text and description), by its key; in a fetched group, by its resolved `itemValue`.
- * @dynamicSlot `<key>:prepend` {BbDropdownItemSlotProps} - One row's leading region; replaces its `prepend:icon`.
- * @dynamicSlot `<key>:append` {BbDropdownItemSlotProps} - One row's trailing region; replaces its `append:icon` and its submenu chevron. The check takes its place on the selected row.
- * @dynamicSlot `<groupKey>:item` {BbDropdownItemSlotProps} - The content of every row of that group, and no other; a row's own `#<key>` still wins.
- * @dynamicSlot `<groupKey>:item:prepend` {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`.
- * @dynamicSlot `<groupKey>:item:append` {BbDropdownItemSlotProps} - The trailing region of every row of that group; replaces their `append:icon`. The check takes its place on the selected row.
- * @dynamicSlot `<groupKey>` {BbDropdownItemSlotProps} - That group's title line (the group is passed as `item`, `groupTitle` is `true`).
- * @dynamicSlot `<groupKey>:prepend` {BbDropdownItemSlotProps} - The leading region of that group's title line.
- * @dynamicSlot `<groupKey>:append` {BbDropdownItemSlotProps} - The trailing region of that group's title line.
+ * @dynamicSlot `<value>` {BbDropdownItemSlotProps} - One row's content (label and description), by its value; in a fetched group, by its resolved `itemValue`.
+ * @dynamicSlot `<value>:prepend` {BbDropdownItemSlotProps} - One row's leading region; replaces its `prepend:icon`.
+ * @dynamicSlot `<value>:append` {BbDropdownItemSlotProps} - One row's trailing region; replaces its `append:icon` and its submenu chevron. The check takes its place on the selected row.
+ * @dynamicSlot `<groupId>:item` {BbDropdownItemSlotProps} - The content of every row of that group, and no other; a row's own `#<value>` still wins.
+ * @dynamicSlot `<groupId>:item:prepend` {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`.
+ * @dynamicSlot `<groupId>:item:append` {BbDropdownItemSlotProps} - The trailing region of every row of that group; replaces their `append:icon`. The check takes its place on the selected row.
+ * @dynamicSlot `<groupId>` {BbDropdownItemSlotProps} - That group's title line (the group is passed as `item`, `groupTitle` is `true`).
+ * @dynamicSlot `<groupId>:prepend` {BbDropdownItemSlotProps} - The leading region of that group's title line.
+ * @dynamicSlot `<groupId>:append` {BbDropdownItemSlotProps} - The trailing region of that group's title line.
  */
 export type BbDropdownSlots = {
 	/**
@@ -2586,17 +2662,13 @@ export type BbDropdownSlots = {
 } & Record<string, (props: BbDropdownItemSlotProps) => any>;
 
 /**
- * `v-model` value of `<BbDropdownGroup>`.
- *
- * - **Legacy group** (pre-shaped `items` with explicit `key`/`text` in
- *   `BbDropdown.items`): the model mirrors the selected item *keys* —
- *   `string | null` (single) or `string[]` (multiple).
- * - **Pipeline group** (`items` getter + `item-text`/`item-value` in
- *   `BbDropdown.items`): the model mirrors the selected *values* produced by
- *   `item-value` (the whole object by default) — `T | null` (single) or `T[]`
- *   (multiple).
+ * `v-model` value of `<BbDropdownGroup>`: the selected rows' values — a
+ * hand-written row's `value`, or what `item-value` produces in a pipeline group
+ * (its own `value`, else the whole item). `T | null` (single) or `T[]`
+ * (multiple). A single group whose model is `null` shows its `value: null` row
+ * (the "None" row) checked, when it has one.
  */
-export type BbDropdownGroupModel<T = any> = T[] | T | string[] | string | null;
+export type BbDropdownGroupModel<T = any> = T[] | T | null;
 
 /**
  * Props of the `<BbDropdownGroup>` companion. Intentionally minimal: the group
@@ -2606,7 +2678,7 @@ export type BbDropdownGroupModel<T = any> = T[] | T | string[] | string | null;
  */
 export type BbDropdownGroupProps = {
 	/**
-	 * Identifier of the group to bind to — must match the `key` of a group
+	 * Identifier of the group to bind to — must match the `id` of a group
 	 * declared in the host `BbDropdown`'s `items`.
 	 */
 	id: string;
@@ -2621,8 +2693,8 @@ export type BbDropdownGroupEvents = {
 	(e: 'update:modelValue', value: BbDropdownGroupModel): void;
 	/**
 	 * The user picked a row, at the click, a pick you then refuse included —
-	 * with the item's resolved value (its `item-value` for pipeline groups, else
-	 * its `key`), symmetric with `BbTable`. Your own `v-model` changes fire none.
+	 * with the row's value (its `item-value` for pipeline groups, else its
+	 * `value`), symmetric with `BbTable`. Your own `v-model` changes fire none.
 	 */
 	(e: 'item:selected', value: any): void;
 	/** The user unpicked a row (or a single pick replaced it), with its resolved value. */
@@ -2997,7 +3069,7 @@ export type BbDropdownGroupEvents = {
 			min-width: 0;
 			padding: 2px 6px;
 			position: relative;
-			text-align: left;
+			text-align: start;
 			width: 100%;
 
 			/* `:focus-visible`, NOT `:focus`. Rows are `tabindex="-1"` (ARIA menu
@@ -3348,7 +3420,7 @@ export type BbDropdownGroupEvents = {
 			height: var(--sheet-row-h, 44px);
 			/* Flyout rows are `2px 6px`. +4px start so the label shares the
 			   search field's text edge (`padding-inline: 0.75rem` on the fill). */
-			padding-left: calc(6px + 4px);
+			padding-inline-start: calc(6px + 4px);
 			/* iOS treats a <button> as a tap target and will not hand the pan to
 			   the sheet body unless the control itself opts into vertical panning.
 			   Without this, dismiss/scroll work on the handle and miss on rows. */
@@ -3375,7 +3447,7 @@ export type BbDropdownGroupEvents = {
 
 		.bb-dropdown__placeholder {
 			min-height: var(--sheet-row-h, 44px);
-			padding-left: calc(6px + 4px);
+			padding-inline-start: calc(6px + 4px);
 		}
 
 		/* Icons scale with the label they sit beside. The desktop sizes (16px
@@ -3442,7 +3514,7 @@ export type BbDropdownGroupEvents = {
 	.bb-dropdown__sheet-selection {
 		flex-shrink: 0;
 		padding: 0 0 0.5rem;
-		text-align: left;
+		text-align: start;
 	}
 
 	.bb-dropdown__sheet-chips {
@@ -3486,7 +3558,7 @@ export type BbDropdownGroupEvents = {
 			   Use `--bb-panel-p`, not `--px`: BbButton redefines `--px` as its
 			   own padding token, which collapsed the inset to 10px. */
 			.bb-dropdown__nav-back {
-				left: var(--bb-panel-p);
+				inset-inline-start: var(--bb-panel-p);
 				position: absolute;
 				top: var(--bb-panel-p);