bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.64

package/dist/ai/source/BbDropdownGroup.md

@@ -263,10 +263,16 @@ import type {
 	PtItemMap,
 	PtItemResult,
 	PtValue,
+	PtVariantAttrs,
 } from '@/types/passthrough';
 import type { Placement } from '@/types/Placement';
 import type { IconType } from '@/types/Icon';
-import type { DropdownItemVariantType } from '@/types/DropdownItemVariant';
+import {
+	DROPDOWN_ITEM_VARIANTS,
+	type DropdownItemVariantBuiltIn,
+	type DropdownItemVariantRegistry,
+	type DropdownItemVariantType,
+} from '@/types/DropdownItemVariant';
 import type { BbOffCanvasProps } from '../BbOffCanvas/types';
 import type { ItemProps } from '@/types/ItemProps';
 import type { BbDropdownGroupItemsContext } from '@/types/ItemsProvider';
@@ -649,8 +655,18 @@ export type InternalGroup = DropdownEntryBase & {
 	/** Placeholder for this group's search field. Defaults to the localized label. */
 	searchPlaceholder?: string;
 	/**
-	 * When set, items act as selectable options that render a check on the right
-	 * and keep the menu open when toggled.
+	 * Sorts the group's rows under titled sections, inside the one group (one
+	 * `v-model`, one search field): a field path read off each row (a fetched
+	 * row: its raw item) or a getter returning the section title. Rows with a
+	 * nullish title are listed without a heading. Sections keep the order in
+	 * which their first row appears, like `BbSelect`'s `groupBy`; a search hides
+	 * a section with no matching row.
+	 */
+	groupBy?: string | ((row: any) => string | null | undefined);
+	/**
+	 * When set, items act as selectable options that render a check on the right.
+	 * A change closes the menu in a single-choice group and keeps it open in a
+	 * `multiple` one; the dropdown's `closeOnSelect` decides otherwise.
 	 *
 	 * Pass a function `(item) => boolean` to gate individual rows — the same
 	 * contract as `BbSelect` and the option groups. The group is still a
@@ -782,6 +798,8 @@ export type NormalizedGroup = {
 	searchable?: boolean;
 	/** Placeholder for this group's search field. */
 	searchPlaceholder?: string;
+	/** Section title per row (see {@link InternalGroup.groupBy}). */
+	groupBy?: InternalGroup['groupBy'];
 	selectable: boolean;
 	/** Selected row keys (`rowKey`; injected by `BbDropdown`; empty for non-selectable groups). */
 	selected: string[];
@@ -807,7 +825,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 `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_.
+ * 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), every state a boolean beside it, on for it (`selected`, `disabled`, …), and the entry's `variant` as a string (`default` when it has none) — 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
@@ -864,14 +882,25 @@ export type BbDropdownItemPtPart =
 	| 'itemIcon'
 	| 'itemDescription';
 /**
- * Passthrough states of `BbDropdown`, true while the matching `--` modifier is on.
+ * Passthrough states of `BbDropdown`, true while the matching `--` modifier is on
+ * (the link states: while the entry's `activeClass` / `exactActiveClass` are).
  *
+ * @state activeLink - Per node, on the entry parts: an entry whose link
+ *   (`to` / `href`) points at the current page or one of its ancestors —
+ *   exactly when its `activeClass` is on. The weakest state.
+ * @state exactActiveLink - Per node, on the entry parts: an entry whose link
+ *   points at the current page itself — its `exactActiveClass` is on.
  * @state selected - Per node, on the entry parts: a selectable group's
  *   checked entry.
  * @state disabled - Per node, on the entry parts: an entry that is disabled.
  * @state open - Component-wide: the menu is open.
  */
-export type BbDropdownPtState = 'open' | 'selected' | 'disabled';
+export type BbDropdownPtState =
+	| 'activeLink'
+	| 'exactActiveLink'
+	| 'open'
+	| 'selected'
+	| 'disabled';
 /** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
 export const BB_DROPDOWN_PT = {
 	parts: [
@@ -887,10 +916,22 @@ export const BB_DROPDOWN_PT = {
 		'itemIcon',
 		'itemDescription',
 	],
-	states: ['selected', 'disabled', 'open'],
+	states: ['activeLink', 'exactActiveLink', 'selected', 'disabled', 'open'],
+	// Each entry's `variant` is a state on the entry parts (Q76.7), below the
+	// real ones; an entry with none is `default`.
+	variant: {
+		names: DROPDOWN_ITEM_VARIANTS,
+		option: 'dropdownItemVariants',
+		parts: ['item', 'itemText', 'itemIcon', 'itemDescription'],
+	},
 } as const satisfies {
 	parts: readonly BbDropdownPtPart[];
 	states: readonly BbDropdownPtState[];
+	variant: {
+		names: readonly DropdownItemVariantBuiltIn[];
+		option: string;
+		parts: readonly BbDropdownItemPtPart[];
+	};
 };
 
 // Spelled INLINE with this component's own unions (Vue's SFC type resolver
@@ -901,170 +942,189 @@ export const BB_DROPDOWN_PT = {
 export type BbDropdownProps = {
 	[K in
 		| `pt:${BbDropdownSurfacePtPart}`
-		| `pt:${BbDropdownPtPart}:${BbDropdownPtState}`]?: PtValue;
-} & {
-	// The entry parts also take a per-item function, called with the menu
-	// entry — a literal function type, not `PtItemFn` (T23).
-	[K in `pt:${BbDropdownItemPtPart}`]?:
-		| PtValue
-		| ((ctx: PtItemCtx<InternalItem, BbDropdownPtState>) => PtItemResult);
-} & {
-	/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
-	/**
-	 * Passthrough, object form: the same keys as the `pt:*` attributes
-	 * without the prefix. See the `pt:<part>` row.
-	 */
-	pt?: PtItemMap<
-		BbDropdownPtPart,
-		BbDropdownItemPtPart,
-		BbDropdownPtState,
-		InternalItem
-	>;
-	/**
-	 * An external activator element or component ref: the activator slot is not
-	 * rendered, and the listeners and ARIA (`aria-haspopup` / `aria-expanded` /
-	 * `aria-controls`) are attached to it; don't add your own.
-	 */
-	activator?: HTMLElement | Record<string, any> | null;
-	/**
-	 * On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom
-	 * sheet that drills into submenus one level at a time instead of hover
-	 * flyouts; slots and selection are unchanged. Unset: the global
-	 * `config.adaptive`.
-	 *
-	 * @defaultValue `config.adaptive` (`true`)
-	 */
-	adaptive?: boolean;
-	/**
-	 * Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet
-	 * rows 44px → 36px (a sheet row stays a touch target). The label size does
-	 * not change.
-	 */
-	compact?: boolean;
-	/**
-	 * The element the panel positions against when it should differ from the
-	 * activator (a wrapper the activator is part of); an HTMLElement or
-	 * component ref. It also drives a percentage `width`. Ignored with
-	 * `placement="cursor"`.
-	 *
-	 * @defaultValue the activator element
-	 */
-	anchor?: HTMLElement | Record<string, any> | null;
-	/**
-	 * Keeps the panel inside this element alongside its trigger (sideways for
-	 * a menu above or below); away from the trigger it may pass the edge, and
-	 * only the viewport flips it. An HTMLElement, a component ref or a CSS
-	 * selector: a `useTemplateRef`, never `$refs.x` (not reactive).
-	 */
-	boundary?: HTMLElement | Record<string, any> | string | null;
-	/**
-	 * Disables the component
-	 */
-	disabled?: boolean;
-	/**
-	 * 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.
-	 */
-	eager?: boolean;
-	/**
-	 * 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.
-	 */
-	enforceCoherence?: boolean;
-	/**
-	 * Names this dropdown: the activator's id (unless it already has one),
-	 * the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a
-	 * companion `BbDropdownGroup` pair by. Generated when omitted.
-	 */
-	id?: string;
-	/**
-	 * The menu rows, each a `BbBaseButton` (`button`, `a` or `router-link`): a
-	 * flat array for one group, nested arrays for divider-separated groups, or
-	 * `InternalGroup` objects for titled / selectable sections. A row's own
-	 * `items` opens a submenu.
-	 *
-	 * @defaultValue `[]`
-	 */
-	items: Item[];
-	/**
-	 * Default placeholder text shown while a pipeline group's async items load.
-	 * A group's own `loadingText` overrides this; both fall back to the localized
-	 * `common.loadingText` (`'Loading...'`).
-	 */
-	loadingText?: string;
-	/**
-	 * 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'`).
-	 */
-	emptyText?: string;
-	/**
-	 * 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"`).
-	 */
-	failedText?: string;
-	/**
-	 * Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on
-	 * mobile), spread over its defaults. A `pt` inside it styles only the sheet
-	 * (passthrough guide § Inside the sheet). The sheet hides its ✕; `{
-	 * hideClose: false }` brings it back.
-	 */
-	offCanvasProps?: Partial<BbOffCanvasProps>;
-	/**
-	 * Space the floating container will maintain from the activator.
-	 *
-	 * @defaultValue `4`
-	 */
-	offset?: number;
-	/**
-	 * Minimum empty space to keep from the edge of the page
-	 *
-	 * @defaultValue `10`
-	 */
-	padding?: number;
-	/**
-	 * Position of the dropdown relative to the activator.
-	 * Use `'cursor'` to anchor at the mouse/touch coordinates.
-	 * (No arrow is drawn either way — arrows are tooltip-only in v3.)
-	 *
-	 * @defaultValue `'bottom'`
-	 */
-	placement?: Placement | 'cursor';
-	/**
-	 * Debounce (ms) applied to the async re-fetch a `searchable` group fires as the
-	 * user types. Applies to every searchable group in the menu.
-	 *
-	 * @defaultValue `300`
-	 */
-	queryDebounceTime?: number;
-	/**
-	 * How long the transition has to last in milliseconds. Menus use the fast
-	 * transition (150) rather than the medium one (250) the other popovers
-	 * default to: a menu is opened to pick one command and is gone again, so
-	 * it answers faster than a panel the user reads or edits in.
-	 *
-	 * @defaultValue `150`
-	 */
-	transitionDuration?: number;
-	/**
-	 * Interaction(s) that open the dropdown.
-	 * Accepts a single trigger or an array to combine them.
-	 * - `'click'` — left-click / tap (default)
-	 * - `'contextMenu'` — right-click on desktop, long-press on mobile
-	 *
-	 * @defaultValue `'click'`
-	 */
-	trigger?: DropdownTrigger | DropdownTrigger[];
-	/**
-	 * Width of the dropdown in pixels, percentage, or 'auto' to fit content.
-	 *
-	 * @defaultValue `'auto'`
-	 */
-	width?: number | string;
-};
+		| `pt:${BbDropdownPtPart}:${BbDropdownPtState}`
+		| `pt:${BbDropdownItemPtPart}:${DropdownItemVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	BbDropdownItemPtPart,
+	keyof DropdownItemVariantRegistry
+> & {
+		// The entry parts also take a per-item function, called with the menu
+		// entry — a literal function type, not `PtItemFn` (T23).
+		[K in `pt:${BbDropdownItemPtPart}`]?:
+			| PtValue
+			| ((
+					ctx: PtItemCtx<
+						InternalItem,
+						BbDropdownPtState,
+						DropdownItemVariantBuiltIn | keyof DropdownItemVariantRegistry
+					>
+			  ) => PtItemResult);
+	} & {
+		/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
+		/**
+		 * Passthrough, object form: the same keys as the `pt:*` attributes
+		 * without the prefix. See the `pt:<part>` row.
+		 */
+		pt?: PtItemMap<
+			BbDropdownPtPart,
+			BbDropdownItemPtPart,
+			BbDropdownPtState,
+			InternalItem,
+			DropdownItemVariantBuiltIn | keyof DropdownItemVariantRegistry
+		>;
+		/**
+		 * An external activator element or component ref: the activator slot is not
+		 * rendered, and the listeners and ARIA (`aria-haspopup` / `aria-expanded` /
+		 * `aria-controls`) are attached to it; don't add your own.
+		 */
+		activator?: HTMLElement | Record<string, any> | null;
+		/**
+		 * On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom
+		 * sheet that drills into submenus one level at a time instead of hover
+		 * flyouts; slots and selection are unchanged. Unset: the global
+		 * `config.adaptive`.
+		 *
+		 * @defaultValue `config.adaptive` (`true`)
+		 */
+		adaptive?: boolean;
+		/**
+		 * Whether a selection closes the menu. Unset: a change in a single-choice
+		 * group closes it (an untick too, at any depth); a `multiple` group stays
+		 * open. `true`: every selection change closes it. `false`: none does.
+		 *
+		 * @defaultValue unset (close after a single-choice change)
+		 */
+		closeOnSelect?: boolean;
+		/**
+		 * Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet
+		 * rows 44px → 36px (a sheet row stays a touch target). The label size does
+		 * not change.
+		 */
+		compact?: boolean;
+		/**
+		 * The element the panel positions against when it should differ from the
+		 * activator (a wrapper the activator is part of); an HTMLElement or
+		 * component ref. It also drives a percentage `width`. Ignored with
+		 * `placement="cursor"`.
+		 *
+		 * @defaultValue the activator element
+		 */
+		anchor?: HTMLElement | Record<string, any> | null;
+		/**
+		 * Keeps the panel inside this element alongside its trigger (sideways for
+		 * a menu above or below); away from the trigger it may pass the edge, and
+		 * only the viewport flips it. An HTMLElement, a component ref or a CSS
+		 * selector: a `useTemplateRef`, never `$refs.x` (not reactive).
+		 */
+		boundary?: HTMLElement | Record<string, any> | string | null;
+		/**
+		 * Disables the component
+		 */
+		disabled?: boolean;
+		/**
+		 * 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.
+		 */
+		eager?: boolean;
+		/**
+		 * 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.
+		 */
+		enforceCoherence?: boolean;
+		/**
+		 * Names this dropdown: the activator's id (unless it already has one),
+		 * the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a
+		 * companion `BbDropdownGroup` pair by. Generated when omitted.
+		 */
+		id?: string;
+		/**
+		 * The menu rows, each a `BbBaseButton` (`button`, `a` or `router-link`): a
+		 * flat array for one group, nested arrays for divider-separated groups, or
+		 * `InternalGroup` objects for titled / selectable sections. A row's own
+		 * `items` opens a submenu.
+		 *
+		 * @defaultValue `[]`
+		 */
+		items: Item[];
+		/**
+		 * Default placeholder text shown while a pipeline group's async items load.
+		 * A group's own `loadingText` overrides this; both fall back to the localized
+		 * `common.loadingText` (`'Loading...'`).
+		 */
+		loadingText?: string;
+		/**
+		 * 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'`).
+		 */
+		emptyText?: string;
+		/**
+		 * 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"`).
+		 */
+		failedText?: string;
+		/**
+		 * Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on
+		 * mobile), spread over its defaults. A `pt` inside it styles only the sheet
+		 * (passthrough guide § Inside the sheet). The sheet hides its ✕; `{
+		 * hideClose: false }` brings it back.
+		 */
+		offCanvasProps?: Partial<BbOffCanvasProps>;
+		/**
+		 * Space the floating container will maintain from the activator.
+		 *
+		 * @defaultValue `4`
+		 */
+		offset?: number;
+		/**
+		 * Minimum empty space to keep from the edge of the page
+		 *
+		 * @defaultValue `10`
+		 */
+		padding?: number;
+		/**
+		 * Position of the dropdown relative to the activator.
+		 * Use `'cursor'` to anchor at the mouse/touch coordinates.
+		 * (No arrow is drawn either way — arrows are tooltip-only in v3.)
+		 *
+		 * @defaultValue `'bottom'`
+		 */
+		placement?: Placement | 'cursor';
+		/**
+		 * Debounce (ms) applied to the async re-fetch a `searchable` group fires as the
+		 * user types. Applies to every searchable group in the menu.
+		 *
+		 * @defaultValue `300`
+		 */
+		queryDebounceTime?: number;
+		/**
+		 * How long the transition has to last in milliseconds. Menus use the fast
+		 * transition (150) rather than the medium one (250) the other popovers
+		 * default to: a menu is opened to pick one command and is gone again, so
+		 * it answers faster than a panel the user reads or edits in.
+		 *
+		 * @defaultValue `150`
+		 */
+		transitionDuration?: number;
+		/**
+		 * Interaction(s) that open the dropdown.
+		 * Accepts a single trigger or an array to combine them.
+		 * - `'click'` — left-click / tap (default)
+		 * - `'contextMenu'` — right-click on desktop, long-press on mobile
+		 *
+		 * @defaultValue `'click'`
+		 */
+		trigger?: DropdownTrigger | DropdownTrigger[];
+		/**
+		 * Width of the dropdown in pixels, percentage, or 'auto' to fit content.
+		 *
+		 * @defaultValue `'auto'`
+		 */
+		width?: number | string;
+	};
 
 export type BbDropdownEvents = {
 	/** Emitted as soon as the menu (the popover, or the sheet on a phone) starts to open. */
@@ -1179,12 +1239,28 @@ export type BbDropdownItemSlotProps = {
 	selected: boolean;
 	/** The row's label (on a group's title line, the group's label). */
 	label: InternalItem['label'];
+	/**
+	 * A link entry (`to` / `href`) pointing at the current page or one of its
+	 * ancestors: its `activeClass` is on. Not set on a group's title line.
+	 */
+	activeLink?: boolean;
+	/**
+	 * A link entry pointing at the current page itself: its `exactActiveClass`
+	 * is on. Not set on a group's title line.
+	 */
+	exactActiveLink?: boolean;
 };
 
 /** Props exposed by the `loading` and `empty` placeholder slots. */
 export type BbDropdownPlaceholderSlotProps = {
 	/** Id of the group this placeholder belongs to. */
 	groupId?: string;
+	/**
+	 * The group's current search text, as typed (`''` when it has no search
+	 * field or nothing is typed) — the same `query` BbSelect's `#empty` gets,
+	 * e.g. for "Type at least 2 characters" under a remote search's minimum.
+	 */
+	query: string;
 	/** Resolved placeholder text (group `loadingText`/`emptyText`/`failedText` → dropdown default). */
 	text: string;
 	/**
@@ -1311,6 +1387,16 @@ export type BbDropdownGroupEvents = {
 	--bg: var(--bb-panel);
 }
 
+/* The item size knobs (ATT-09), BbButton's names: `--fs` the row label,
+   `--icon-size` its prepend / append icons. Declared at specificity 0 on the
+   menu's root, so a consumer class or `pt` wins and a `--fs` an ancestor set
+   (a button, a badge) never leaks in; submenus inherit the root's. The adaptive
+   sheet reads neither: its rows keep `--sheet-option-fs` and their own icons. */
+:where(.bb-dropdown:not(.bb-dropdown--submenu)) {
+	--fs: var(--bb-fs);
+	--icon-size: 1rem;
+}
+
 /* @inherit --transition-duration — set inline by the adaptive surface;
    @inherit --py — the adaptive sheet's rules target BbOffCanvas elements, which
    declare it on the panel */
@@ -1542,8 +1628,9 @@ export type BbDropdownGroupEvents = {
 		/* `--bb-fs`, matching the select's option label. These two menus sit at
 		   the same 28px row height on the same screen and their labels were a
 		   pixel apart (13 against 14) — the desktop twin of the sheet drift, and
-		   the kind of difference nobody can name but everybody sees. */
-		font-size: var(--bb-fs);
+		   the kind of difference nobody can name but everybody sees. `--fs`
+		   (above) is the consumer's knob. */
+		font-size: var(--fs);
 		gap: 1px;
 		line-height: 1.2;
 		max-height: var(--max-h, none);
@@ -1706,9 +1793,9 @@ export type BbDropdownGroupEvents = {
 
 			.item__prepend-icon,
 			.item__append-icon {
-				--size: 16px;
+				--size: var(--icon-size);
 				flex-shrink: 0;
-				font-size: 15px;
+				font-size: calc(var(--icon-size) - 1px);
 			}
 
 			.item__content {
@@ -1769,6 +1856,11 @@ export type BbDropdownGroupEvents = {
 				flex-shrink: 0;
 				font-size: 19px;
 				margin-inline-start: auto;
+
+				/* Points where the flyout opens: the inline end. */
+				&:dir(rtl) {
+					transform: scaleX(-1);
+				}
 			}
 
 			/*
@@ -2161,9 +2253,15 @@ export type BbDropdownGroupEvents = {
 				position: absolute;
 				top: var(--bb-panel-p);
 
-				/* Same chevron_right asset the submenu rows use, pointed back. */
+				/* Same chevron_right asset the submenu rows use, pointed back:
+				   toward the inline start, which is already where it points in
+				   rtl. */
 				.bb-button__icon {
 					transform: rotate(180deg);
+
+					&:dir(rtl) {
+						transform: none;
+					}
 				}
 			}