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

package/dist/ai/source/BbDropdownButton.md

@@ -21,11 +21,21 @@
 			:pt="
 				passthrough.forward(
 					{ main: 'root', icon: 'icon', spinner: 'spinner', text: 'text' },
-					BB_BUTTON_PT.states
+					BUTTON_STATES
 				)
 			"
 		>
 			<template v-if="slots.default" #default><slot /></template>
+			<!-- The main button's icon slots (Q81.4), with its states. -->
+			<template v-if="slots.icon" #icon="scope"
+				><slot name="icon" v-bind="scope"
+			/></template>
+			<template v-if="slots['prepend:icon']" #prepend:icon="scope"
+				><slot name="prepend:icon" v-bind="scope"
+			/></template>
+			<template v-if="slots['append:icon']" #append:icon="scope"
+				><slot name="append:icon" v-bind="scope"
+			/></template>
 		</BbButton>
 
 		<BbDropdown
@@ -33,6 +43,7 @@
 			:id="id"
 			:adaptive="adaptive"
 			:anchor="root"
+			:close-on-select="closeOnSelect"
 			:compact="compact"
 			:disabled="disabled"
 			:eager="eager"
@@ -85,9 +96,12 @@
 <script setup lang="ts">
 import { computed, ref, useAttrs, useTemplateRef } from 'vue';
 import BbButton from '../BbButton/BbButton.vue';
+import { useLinkState } from '../BbBaseButton/useLinkState';
 import BbDropdown from '../BbDropdown/BbDropdown.vue';
 import { BB_BUTTON_PT } from '../BbButton/types';
 import { BB_DROPDOWN_PT } from '../BbDropdown/types';
+import { BUTTON_VARIANTS } from '@/types/ButtonVariant';
+import { DROPDOWN_ITEM_VARIANTS } from '@/types/DropdownItemVariant';
 import { useLocale } from '@/composables/useLocale';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
@@ -98,18 +112,28 @@ import {
 	type BbDropdownButtonProps,
 	type BbDropdownButtonSlots,
 } from './types';
-import { usePassthrough } from '@/composables/usePassthrough';
+import {
+	registeredVariantNames,
+	usePassthrough,
+	variantPt,
+} from '@/composables/usePassthrough';
 export type {
 	BbDropdownButtonEvents,
 	BbDropdownButtonProps,
 	BbDropdownButtonSlots,
 };
 
-defineOptions({ inheritAttrs: false });
+defineOptions({
+	// An app's own variants as declared `pt:<part>:<name>` props (Q76.7).
+	mixins: [variantPt(BB_DROPDOWN_BUTTON_PT)],
+	inheritAttrs: false,
+});
 const props = withDefaults(defineProps<BbDropdownButtonProps>(), {
 	// Three-state, as on BbDropdown: `undefined` lets the menu fall back to the
 	// global `config.adaptive`; a Boolean default would pin it to `false`.
 	adaptive: undefined,
+	// Unset closes after a single-choice change: a Boolean default would pin it.
+	closeOnSelect: undefined,
 	size: 'md',
 	variant: 'primary',
 });
@@ -125,7 +149,14 @@ const slots = defineSlots<BbDropdownButtonSlots>();
  */
 // A function, not a computed: the slots object is not reactive, and a
 // conditional consumer slot must be re-read on every render.
-const OWN_SLOTS = new Set(['activator', 'default', 'dropdown']);
+const OWN_SLOTS = new Set([
+	'activator',
+	'default',
+	'dropdown',
+	'icon',
+	'prepend:icon',
+	'append:icon',
+]);
 const forwardedSlots = () =>
 	Object.keys(slots).filter((name) => !OWN_SLOTS.has(name));
 
@@ -146,6 +177,7 @@ const hasMenu = () => menuItems().length > 0 || !!slots.dropdown;
  */
 const NOT_MAIN = new Set([
 	'adaptive',
+	'closeOnSelect',
 	'compact',
 	'eager',
 	'id',
@@ -183,6 +215,12 @@ const splitAttrs = () => {
 	return { main, root };
 };
 
+/**
+ * The main button's link state, for the parts resolved here (`root`, `toggle`,
+ * the menu surface); the main button resolves its own parts itself.
+ */
+const linkState = useLinkState(props);
+
 /**
  * Passthrough (plans/passthrough/BbDropdownButton.md). `icon` / `spinner` / `text` are forwarded to the main button as its own `pt`; `panel` / `input` / `item` and the rows' `itemText` / `itemIcon` / `itemDescription` to the dropdown under the same words.
  */
@@ -196,8 +234,29 @@ const passthrough = usePassthrough({
 		loading: () => !!props.loading,
 		disabled: () => !!props.disabled,
 		open: () => dropdownOpen.value,
+		activeLink: () => linkState.value.activeLink,
+		exactActiveLink: () => linkState.value.exactActiveLink,
 	},
+	variant: [
+		{ ...BB_DROPDOWN_BUTTON_PT.variant[0], current: () => props.variant },
+		BB_DROPDOWN_BUTTON_PT.variant[1],
+	],
 });
+/**
+ * Both buttons and the menu resolve the variants themselves (Q76.7), so every
+ * registered name passes on under its own word.
+ */
+const BUTTON_STATES = [
+	...BB_BUTTON_PT.states,
+	...registeredVariantNames(BUTTON_VARIANTS, 'buttonVariants'),
+];
+const ENTRY_STATES = [
+	...BB_DROPDOWN_PT.states,
+	...registeredVariantNames(DROPDOWN_ITEM_VARIANTS, 'dropdownItemVariants'),
+];
+
+/** Resolved here for every part but the main button's and the entries. */
+const LINK_STATES: readonly string[] = ['activeLink', 'exactActiveLink'];
 
 /**
  * The menu's `pt`. The rows go with every dropdown state: the dropdown
@@ -213,16 +272,22 @@ const passthrough = usePassthrough({
  * `pt:toggle:loading` means this control's `loading` — so it is resolved here.
  */
 const toggleButtonPt = () =>
-	passthrough.forward({ toggle: 'root' }, ['disabled']);
+	passthrough.forward({ toggle: 'root' }, [
+		'disabled',
+		...registeredVariantNames(BUTTON_VARIANTS, 'buttonVariants'),
+	]);
 
 const menuPt = () => ({
 	...passthrough.forward(
 		['panel', 'sheet', 'header', 'footer', 'input'],
-		BB_DROPDOWN_PT.states.filter((state) => state !== 'disabled')
+		// The link states too: the surface's are the main button's, from here.
+		BB_DROPDOWN_PT.states.filter(
+			(state) => state !== 'disabled' && !LINK_STATES.includes(state)
+		)
 	),
 	...passthrough.forward(
 		['item', 'itemText', 'itemIcon', 'itemDescription'],
-		BB_DROPDOWN_PT.states
+		ENTRY_STATES
 	),
 });
 
@@ -269,9 +334,24 @@ import type {
 	PtItemFn,
 	PtItemResult,
 	PtValue,
+	PtVariantAttrs,
 } from '@/types/passthrough';
-import type { ButtonVariantType } from '@/types/ButtonVariant';
-import type { BbButtonOwnProps, BbButtonProps } from '../BbButton/types';
+import {
+	BUTTON_VARIANTS,
+	type ButtonVariantBuiltIn,
+	type ButtonVariantRegistry,
+	type ButtonVariantType,
+} from '@/types/ButtonVariant';
+import {
+	DROPDOWN_ITEM_VARIANTS,
+	type DropdownItemVariantBuiltIn,
+	type DropdownItemVariantRegistry,
+} from '@/types/DropdownItemVariant';
+import type {
+	BbButtonIconSlotProps,
+	BbButtonOwnProps,
+	BbButtonProps,
+} from '../BbButton/types';
 
 /**
  * Passthrough parts of `BbDropdownButton` (plans/passthrough/BbDropdownButton.md):
@@ -284,7 +364,7 @@ import type { BbButtonOwnProps, BbButtonProps } from '../BbButton/types';
  * resolve there (the flyout box on desktop, the sheet's menu on a phone). `loading` / `disabled` follow the props; `open` follows the
  * menu; `selected` exists on the entry parts only.
  *
- * 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, 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). The function is handed to the `BbDropdown` with the part and called there, per entry; 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, 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). The function is handed to the `BbDropdown` with the part and called there, per entry; 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_.
  */
 export type BbDropdownButtonPtPart =
 	| BbDropdownButtonOwnPtPart
@@ -337,15 +417,18 @@ export type BbDropdownButtonItemPtPart =
 	| 'itemDescription';
 /**
  * Passthrough states of `BbDropdownButton`: `loading` / `disabled` follow the
- * props and `open` the menu, on every part; `selected` (a selectable group's
- * checked entry, resolved by the `BbDropdown`) is declared on the entry parts
- * only — `pt:root:selected` is a type error, not a silent no-op.
+ * props, `open` the menu and `activeLink` / `exactActiveLink` the main
+ * button's link, on every part; `selected` (a selectable group's checked
+ * entry, resolved by the `BbDropdown`) is declared on the entry parts only —
+ * `pt:root:selected` is a type error, not a silent no-op.
  *
  * @state selected - Per node, on the entry parts only (`item`, `itemText`,
  *   `itemIcon`, `itemDescription`): a selectable group's checked entry.
  *   `pt:root:selected` is a type error, not a silent no-op.
  */
 export type BbDropdownButtonPtState =
+	| 'activeLink'
+	| 'exactActiveLink'
 	| 'selected'
 	| 'loading'
 	| 'disabled'
@@ -358,8 +441,19 @@ export type BbDropdownButtonPtState =
  * @state disabled - Component-wide while the control is `disabled`; also per
  *   node, on the entry parts: a menu entry that is disabled.
  * @state open - Component-wide: the menu is open.
+ * @state activeLink - Component-wide while the main button is a link to the
+ *   current page or one of its ancestors (its `activeClass` is on); also per
+ *   node, on the entry parts: a menu entry whose link is. The weakest state.
+ * @state exactActiveLink - Component-wide while the main button is a link to
+ *   the current page itself (its `exactActiveClass` is on); also per node, on
+ *   the entry parts.
  */
-export type BbDropdownButtonWidePtState = 'loading' | 'disabled' | 'open';
+export type BbDropdownButtonWidePtState =
+	| 'activeLink'
+	| 'exactActiveLink'
+	| 'loading'
+	| 'disabled'
+	| 'open';
 /** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
 export const BB_DROPDOWN_BUTTON_PT = {
 	parts: [
@@ -379,16 +473,57 @@ export const BB_DROPDOWN_BUTTON_PT = {
 		'itemIcon',
 		'itemDescription',
 	],
-	states: ['selected', 'disabled', 'open', 'loading'],
+	states: [
+		'activeLink',
+		'exactActiveLink',
+		'selected',
+		'disabled',
+		'open',
+		'loading',
+	],
 	/** `itemStates` are declared on `itemParts` only — the control's own parts never have them. */
 	itemParts: ['item', 'itemText', 'itemIcon', 'itemDescription'],
 	itemStates: ['selected'],
+	// Two variants as states (Q76.7), below the real ones: the button's on the
+	// control's parts, and each menu entry's on the entry parts.
+	variant: [
+		{
+			names: BUTTON_VARIANTS,
+			option: 'buttonVariants',
+			parts: ['root', 'main', 'toggle', 'icon', 'spinner', 'text'],
+		},
+		{
+			names: DROPDOWN_ITEM_VARIANTS,
+			option: 'dropdownItemVariants',
+			parts: ['item', 'itemText', 'itemIcon', 'itemDescription'],
+		},
+	],
 } as const satisfies {
 	parts: readonly BbDropdownButtonPtPart[];
 	states: readonly BbDropdownButtonPtState[];
 	itemParts: readonly BbDropdownButtonItemPtPart[];
 	itemStates: readonly BbDropdownButtonPtState[];
+	variant: readonly [
+		{
+			names: readonly ButtonVariantBuiltIn[];
+			option: string;
+			parts: readonly BbDropdownButtonControlPtPart[];
+		},
+		{
+			names: readonly DropdownItemVariantBuiltIn[];
+			option: string;
+			parts: readonly BbDropdownButtonItemPtPart[];
+		},
+	];
 };
+/** The split control's own parts: the ones its button `variant` styles. Spelled flat (T20). */
+export type BbDropdownButtonControlPtPart =
+	| 'root'
+	| 'main'
+	| 'toggle'
+	| 'icon'
+	| 'spinner'
+	| 'text';
 
 /**
  * The object form of the split control's `pt`: the same keys as its `pt:*`
@@ -400,13 +535,19 @@ export type BbDropdownButtonPtMap = {
 	[K in
 		| BbDropdownButtonOwnPtPart
 		| `${BbDropdownButtonPtPart}:${BbDropdownButtonWidePtState}`
-		| `${BbDropdownButtonItemPtPart}:selected`]?: PtValue;
+		| `${BbDropdownButtonItemPtPart}:selected`
+		| `${BbDropdownButtonControlPtPart}:${ButtonVariantBuiltIn | keyof ButtonVariantRegistry}`
+		| `${BbDropdownButtonItemPtPart}:${DropdownItemVariantBuiltIn | keyof DropdownItemVariantRegistry}`]?: PtValue;
 } & {
 	// An entry part's base key also takes a per-item function, called with
 	// the menu entry by the `BbDropdown` it is handed to.
 	[K in BbDropdownButtonItemPtPart]?:
 		| PtValue
-		| PtItemFn<InternalItem, BbDropdownButtonPtState>;
+		| PtItemFn<
+				InternalItem,
+				BbDropdownButtonPtState,
+				DropdownItemVariantBuiltIn | keyof DropdownItemVariantRegistry
+		  >;
 };
 /* eslint-enable @typescript-eslint/consistent-indexed-object-style */
 
@@ -418,22 +559,38 @@ export type BbDropdownButtonProps = {
 	[K in
 		| `pt:${BbDropdownButtonOwnPtPart}`
 		| `pt:${BbDropdownButtonPtPart}:${BbDropdownButtonWidePtState}`
-		| `pt:${BbDropdownButtonItemPtPart}:selected`]?: PtValue;
-} & {
-	// A literal function type, not `PtItemFn` (T23).
-	[K in `pt:${BbDropdownButtonItemPtPart}`]?:
-		| PtValue
-		| ((ctx: PtItemCtx<InternalItem, BbDropdownButtonPtState>) => 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?: BbDropdownButtonPtMap;
-} & Pick<
+		| `pt:${BbDropdownButtonItemPtPart}:selected`
+		| `pt:${BbDropdownButtonControlPtPart}:${ButtonVariantBuiltIn}`
+		| `pt:${BbDropdownButtonItemPtPart}:${DropdownItemVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	BbDropdownButtonControlPtPart,
+	keyof ButtonVariantRegistry
+> &
+	/* @vue-ignore */ PtVariantAttrs<
+		BbDropdownButtonItemPtPart,
+		keyof DropdownItemVariantRegistry
+	> & {
+		// A literal function type, not `PtItemFn` (T23).
+		[K in `pt:${BbDropdownButtonItemPtPart}`]?:
+			| PtValue
+			| ((
+					ctx: PtItemCtx<
+						InternalItem,
+						BbDropdownButtonPtState,
+						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?: BbDropdownButtonPtMap;
+	} & Pick<
 		BbDropdownProps,
 		| 'adaptive'
+		| 'closeOnSelect'
 		| 'compact'
 		| 'eager'
 		| 'id'
@@ -573,6 +730,15 @@ export type BbDropdownButtonSlots = {
 	 * The main button's label (falls back to `text`).
 	 */
 	default?: () => any;
+	/**
+	 * The main button's icon, replacing the `icon` prop; inside its `icon` part
+	 * (`pt:icon`, `--icon-size`, the loading spinner), with its states.
+	 */
+	icon?: (props: BbButtonIconSlotProps) => any;
+	/** The main button's leading icon, replacing `prepend:icon`. */
+	'prepend:icon'?: (props: BbButtonIconSlotProps) => any;
+	/** The main button's trailing icon, replacing `append:icon`. */
+	'append:icon'?: (props: BbButtonIconSlotProps) => any;
 	/**
 	 * Menu companions, forwarded into the dropdown: a `<BbDropdownGroup>`
 	 * binding a group of `items` by id. A `#dropdown` slot keeps the toggle even