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

package/dist/ai/source/BbDropdownButton.md

@@ -249,26 +249,33 @@ watch(
 );
 
 /**
- * BbButton-bound props for the main action, taken from the first leaf item.
- * Icons and visual variant come from the component's own props instead, so they
- * are dropped here along with dropdown-only fields (`key`, `items`, `group`).
+ * BbButton-bound props for the main action, taken from the first leaf item: its
+ * `label` becomes the button's text. Icons and visual variant come from the
+ * component's own props instead, so they are dropped here along with the
+ * row-only fields (`value`, `label`, `meta`, `description`, `items`, `group`).
  */
 const OMITTED_MAIN_FIELDS = new Set([
-	'key',
+	'value',
+	'label',
+	'meta',
+	'description',
 	'items',
 	'group',
 	'variant',
 	'prepend:icon',
 	'append:icon',
 ]);
-const mainBtnProps = computed(
-	() =>
-		Object.fromEntries(
-			Object.entries(flatMappedItems.value[0] ?? {}).filter(
+const mainBtnProps = computed(() => {
+	const first = flatMappedItems.value[0];
+	return {
+		...Object.fromEntries(
+			Object.entries(first ?? {}).filter(
 				([key]) => !OMITTED_MAIN_FIELDS.has(key)
 			)
-		) as Partial<InternalItem>
-);
+		),
+		text: first?.label,
+	} as Omit<Partial<InternalItem>, 'text'> & { text?: string };
+});
 </script>
 
 <style lang="postcss">
@@ -570,8 +577,8 @@ export type BbDropdownButtonItemSlotProps = {
 	open: boolean;
 	/** The current placement of the dropdown panel. */
 	placement: BbDropdownProps['placement'];
-	/** The resolved display text for this item. */
-	text: MappedItem['text'];
+	/** The row's label. */
+	label: MappedItem['label'];
 };
 
 /**

package/dist/ai/source/BbDropdownGroup.md

@@ -276,9 +276,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 = {
 	/**
@@ -287,25 +287,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;
@@ -324,14 +310,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;
 	};
@@ -374,13 +360,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;
+		/**
+		 * 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 `text`. The row grows to fit it,
+		 * Muted descriptive line rendered below `label`. The row grows to fit it,
 		 * while icons/check/chevron stay aligned with the title line.
 		 */
 		description?: string;
@@ -407,7 +426,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';
@@ -427,8 +446,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;
 	};
@@ -469,6 +488,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. */
@@ -507,17 +538,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).
+	 *
+	 * Unset: own `label`, else `text` (`{ label, value }` needs no accessor).
 	 *
-	 * @defaultValue `JSON.stringify(item)`
+	 * @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.
 	 *
@@ -528,17 +561,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.
 	 *
-	 * @defaultValue the whole item
+	 * Unset: own `value`, even `null`.
+	 *
+	 * @defaultValue own `value`, else the whole item
 	 */
 	itemValue?: string | ((item: any) => any);
 	/** Pipeline groups only. Placeholder row text while async items load. */
@@ -629,7 +663,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
@@ -674,7 +708,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[];
 
@@ -719,10 +753,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;
@@ -730,11 +765,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. */
@@ -747,7 +782,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;
@@ -771,7 +806,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
@@ -791,13 +826,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 =
@@ -936,7 +971,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;
 	/**
@@ -1063,8 +1099,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;
 	/**
@@ -1110,11 +1146,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`. */
@@ -1162,14 +1198,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;
 	/**
@@ -1181,23 +1217,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 = {
 	/**
@@ -1245,17 +1282,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
@@ -1265,7 +1298,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;
@@ -1280,8 +1313,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. */
@@ -1656,7 +1689,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
@@ -2007,7 +2040,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. */
@@ -2034,7 +2067,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
@@ -2101,7 +2134,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 {
@@ -2145,7 +2178,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);
 

package/dist/ai/source/BbForm.md

@@ -96,6 +96,7 @@ import {
 	schemaRequires,
 	toFormSchema,
 } from './formSchema';
+import { BB_FORM_SUBMIT_LOCK } from '@/composables/formSubmitLock';
 import {
 	BB_FORM_FIELDS,
 	type BbFormField,
@@ -173,6 +174,15 @@ const props = defineProps<{
 	 * drops once the user edits the field, call `setErrors` instead.
 	 */
 	fieldErrors?: Record<string, unknown> | null;
+	/**
+	 * Keep the fields editable while a save runs. By default, while a
+	 * `@submit` that returned a promise is pending, every field joined to the
+	 * form is read-only (never disabled: values stay readable and focusable)
+	 * and every `type="submit"` BbButton inside the form shows its spinner;
+	 * both end when the promise settles. A `@submit` that returns nothing
+	 * never locks.
+	 */
+	disableSubmitLock?: boolean;
 }>();
 
 // Declared for the public typing and the manifest. The submit handler is
@@ -312,6 +322,7 @@ provide(BB_FORM_CONNECTION, {
 });
 
 provide(BB_FORM_FIELDS, {
+	locked: () => submitLocked(),
 	isRequired: (name) => schemaRequires(unref(props.schema), name),
 	validationMode: () => props.validationMode,
 	fieldErrors: fieldErrorsAt,
@@ -653,6 +664,11 @@ const onInvalidSubmit = async (context: InvalidSubmissionContext) => {
  */
 const instance = getCurrentInstance();
 
+/** Q60.17: saves still pending (a second submit can overlap the first). */
+const savesInFlight = ref(0);
+const submitLocked = () => savesInFlight.value > 0 && !props.disableSubmitLock;
+provide(BB_FORM_SUBMIT_LOCK, { locked: submitLocked });
+
 type SubmitListener = (values: Record<string, unknown>) => unknown;
 
 /** `@submit.once` compiles to a SEPARATE `onSubmitOnce` prop — Vue's own emit
@@ -712,7 +728,15 @@ const runSubmitListeners = (formValues: Record<string, unknown>) => {
 	}
 	// Await only what is actually awaitable, so a sync handler keeps the exact
 	// timing it has today rather than being pushed a microtask later.
-	return pending.length ? Promise.all(pending) : undefined;
+	if (!pending.length) return undefined;
+	// Q60.17: the form locks for exactly as long as the save runs. Its own
+	// flag, not vee-validate's `isSubmitting`, which is also true while
+	// validation runs, so a sync submit would flash the lock.
+	const save = Promise.all(pending);
+	savesInFlight.value++;
+	return save.finally(() => {
+		savesInFlight.value--;
+	});
 };
 
 // With a schema, `formValues` is the schema's OUTPUT: vee-validate hands the

package/dist/ai/source/BbIndicator.md

@@ -278,12 +278,14 @@ export type BbIndicatorSlots = {
 		font-weight: 500;
 		gap: var(--gap);
 		justify-content: center;
+		/* stylelint-disable-next-line property-disallowed-list -- geometry: the `left` prop names a physical side */
 		left: auto;
 		line-height: 1;
 		min-height: var(--min-size);
 		min-width: var(--min-size);
 		padding: 0 var(--px);
 		position: absolute;
+		/* stylelint-disable-next-line property-disallowed-list -- geometry: the `left` prop names a physical side */
 		right: calc(0% - var(--position-offset));
 		top: calc(0% - var(--position-offset));
 		transition:
@@ -314,7 +316,9 @@ export type BbIndicatorSlots = {
 	}
 
 	&.bb-indicator--left .bb-indicator__bubble {
+		/* stylelint-disable-next-line property-disallowed-list -- geometry: the `left` prop names a physical side */
 		left: calc(0% - var(--position-offset));
+		/* stylelint-disable-next-line property-disallowed-list -- geometry: the `left` prop names a physical side */
 		right: auto;
 	}