bitboss-ui 2.1.132 → 2.1.133

package/dist/ai/BbDropdown.md

@@ -49,13 +49,18 @@
 				:placement="placement"
 			></slot>
 			<template
-				v-for="({ original, ...item }, index) in mappedItems"
+				v-for="({ original, isGroupStart, ...item }, index) in mappedItems"
 				:key="item.key"
 			>
+				<hr
+					v-if="isGroupStart && index > 0"
+					aria-hidden="true"
+					class="bb-dropdown__divider"
+				/>
 				<slot
 					:disabled="item.disabled"
 					:index="index"
-					:item="items[index]"
+					:item="flatItems[index]"
 					:name="`item:prepend`"
 					:open="open"
 					:placement="placement"
@@ -66,7 +71,7 @@
 					class="bb-dropdown__item"
 					:class="{
 						'bb-dropdown__item--first': index === 0,
-						'bb-dropdown__item--last': index === items.length - 1,
+						'bb-dropdown__item--last': index === flatItems.length - 1,
 					}"
 					:data-dropdown-item="true"
 					v-bind="item"
@@ -91,7 +96,7 @@
 				><slot
 					:disabled="item.disabled"
 					:index="index"
-					:item="items[index]"
+					:item="flatItems[index]"
 					:name="`item:append`"
 					:open="open"
 					:placement="placement"
@@ -122,15 +127,19 @@ import type { ColumnName } from '@/types/ColumnName';
 import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
 import { useElementSize, useIntersectionObserver } from '@vueuse/core';
 import { parseWidthString } from '@/utilities/functions/parseWidthString';
+import { normalizeItemGroups } from '@/utilities/functions/normalizeItemGroups';
 import type {
 	BbDropdownProps,
 	BbDropdownSlots,
+	FlatItem,
 	Item,
 	MappedItem,
 	DropdownTrigger,
 } from './types';
 
-type InferredBodySlots = ColumnName<BbDropdownProps['items'][number]['key']>;
+type InferredBodySlots = ColumnName<
+	FlatItem<BbDropdownProps['items'][number]>['key']
+>;
 defineSlots<BbDropdownSlots>();
 
 const props = withDefaults(defineProps<BbDropdownProps>(), {
@@ -208,14 +217,35 @@ const { resume, pause } = useIntersectionObserver(
 	{ threshold: [0, 1], immediate: false }
 );
 
+/**
+ * Items normalized into divider-separated groups. A flat `items` array yields a
+ * single group; nested arrays (or loose items around them) become their own
+ * groups. See {@link normalizeItemGroups}.
+ */
+const itemGroups = computed(() => normalizeItemGroups(props.items));
+/** Flattened view of {@link itemGroups}; keyboard navigation and indices are flat. */
+const flatItems = computed(() => itemGroups.value.flat());
+/** Flat indices that begin a new group, used to render dividers between groups. */
+const groupStartIndices = computed(() => {
+	const set = new Set<number>();
+	let offset = 0;
+	for (const group of itemGroups.value) {
+		set.add(offset);
+		offset += group.length;
+	}
+	return set;
+});
+
 const mappedItems = computed(() => {
-	let firstFocusableIndex: number = props.items.findIndex((el) => !el.disabled);
+	let firstFocusableIndex: number = flatItems.value.findIndex(
+		(el) => !el.disabled
+	);
 	let lastFocusableIndex: number = findRightIndex(
-		props.items,
+		flatItems.value,
 		(item) => !item.disabled
 	);
 
-	return props.items.map((item, index) => {
+	return flatItems.value.map((item, index) => {
 		const itemid = `${id}-item-${item.key}`;
 		const { onClick: handler, ...rest } = item;
 
@@ -261,7 +291,7 @@ const mappedItems = computed(() => {
 				event.preventDefault();
 				if (index !== firstFocusableIndex) {
 					const indexOfPrevious = findRightIndex(
-						props.items,
+						flatItems.value,
 						(item, i) => i < index && !item.disabled
 					);
 					const options = Array.from(
@@ -302,6 +332,7 @@ const mappedItems = computed(() => {
 			key: item.key.split(/\W+/g).join('_').toLowerCase() as InferredBodySlots,
 			disabled: rest.disabled || props.disabled,
 			id: itemid,
+			isGroupStart: groupStartIndices.value.has(index),
 			onClick,
 			onKeydown,
 		};
@@ -379,9 +410,9 @@ const onPointerUp = () => {
 
 const onKeydown = async (event: KeyboardEvent) => {
 	if (props.disabled) return;
-	const firstFocusableIndex = props.items.findIndex((el) => !el.disabled);
+	const firstFocusableIndex = flatItems.value.findIndex((el) => !el.disabled);
 	const lastFocusableIndex = findRightIndex(
-		props.items,
+		flatItems.value,
 		(item) => !item.disabled
 	);
 
@@ -592,6 +623,16 @@ export type Item = Omit<BaseButtonProps, 'block' | 'tag' | 'type'> & {
 	'append:icon'?: IconType;
 };
 
+/**
+ * Items accepted by the dropdown. A flat list renders a single group with no
+ * dividers; a nested array introduces a divider before and after the group.
+ * The two shapes can be mixed, e.g. `[item, item, [item, item], item]`.
+ */
+export type Items = (Item | Item[])[];
+
+/** Unwraps the item type out of the (possibly nested) {@link Items} shape. */
+export type FlatItem<T> = T extends (infer U)[] ? U : T;
+
 export type MappedItem = Item & {
 	/**
 	 * Identifier of the element among its siblings.
@@ -635,8 +676,12 @@ export type BbDropdownProps = Pick<
 	 * Array used to render each dropdown button.
 	 * They can act as `button`, as `a`, or as `router-link`
 	 * as they are based on the functionality provided by `BaseButton`.
+	 *
+	 * Pass a flat array for a single group, or nest arrays to split the items
+	 * into divider-separated groups. The two shapes can be mixed, e.g.
+	 * `[item, item, [item, item], item]`.
 	 */
-	items: Item[];
+	items: Items;
 	/**
 	 * Name of the theme to apply to the component. It creates a CSS class with the name of the theme.
 	 *
@@ -696,7 +741,7 @@ export type BbDropdownItemSlotProps = {
 	/** The zero-based index of this item. */
 	index: number;
 	/** The raw item object from the `items` prop. */
-	item: BbDropdownProps['items'][number];
+	item: FlatItem<BbDropdownProps['items'][number]>;
 	/** Whether the dropdown panel is currently open. */
 	open: boolean;
 	/** The current placement of the dropdown panel. */
@@ -745,6 +790,14 @@ export type BbDropdownSlots = {
 		display: inline-grid;
 		grid-template-columns: 1fr;
 		padding: 6px;
+		.bb-dropdown__divider {
+			/* Negative inline margins cancel the container padding so the rule
+			 * spans the full width of the dropdown panel, edge to edge. */
+			border: none;
+			border-top: 1px solid color-mix(in srgb, var(--bb-text) 15%, transparent);
+			height: 0;
+			margin: 6px -6px;
+		}
 		.bb-dropdown__item {
 			border-radius: var(--bb-radius);
 			column-gap: 6px;

package/dist/ai/BbDropdownButton.md

@@ -85,7 +85,7 @@
 				<slot name="item:prepend" v-bind="data" />
 			</template>
 			<!-- @vue-ignore - wrong inferred type -->
-			<template v-for="item in mappedItems" #[item.key]="data">
+			<template v-for="item in flatMappedItems" #[item.key]="data">
 				<slot :name="item.key" v-bind="data" />
 			</template>
 			<template #item:append="data">
@@ -103,6 +103,7 @@ import BbDropdown from '../BbDropdown/BbDropdown.vue';
 import { ref } from 'vue';
 import { BbIcon, BbSpinner } from '@/index';
 import { useLocale } from '@/composables/useLocale';
+import type { Item } from '../BbDropdown/types';
 import type { BbDropdownButtonProps, BbDropdownButtonSlots } from './types';
 
 type Sizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
@@ -131,23 +132,34 @@ const wrapClick =
 		internalLoading.value--;
 	};
 
-const mappedItems = computed(() =>
-	props.items.map((el) => {
-		if (el.onClick)
-			return {
-				...el,
-				key: el.key.split(/\W+/g).join('_').toLowerCase(),
-				onClick: wrapClick(el.onClick),
-			};
+const transformItem = (el: Item) => {
+	if (el.onClick)
 		return {
 			...el,
 			key: el.key.split(/\W+/g).join('_').toLowerCase(),
+			onClick: wrapClick(el.onClick),
 		};
-	})
+	return {
+		...el,
+		key: el.key.split(/\W+/g).join('_').toLowerCase(),
+	};
+};
+
+/**
+ * Items with leaf transforms applied while preserving the (possibly nested)
+ * group structure, so dividers passed down to `BbDropdown` are kept intact.
+ */
+const mappedItems = computed(() =>
+	props.items.map((entry) =>
+		Array.isArray(entry) ? entry.map(transformItem) : transformItem(entry)
+	)
 );
 
+/** Flattened view used for the main button and per-item named slots. */
+const flatMappedItems = computed(() => mappedItems.value.flat());
+
 const mainBtn = computed(() => {
-	const base = { ...mappedItems.value[0] };
+	const base = { ...flatMappedItems.value[0] };
 	base.disabled = base.disabled || props.disabled;
 	return base;
 });
@@ -178,7 +190,11 @@ const sizeAttributes = Object.entries<Sizes>(baseSize).reduce(
 ## Types
 
 ```ts
-import type { BbDropdownProps, MappedItem } from '../BbDropdown/types';
+import type {
+	BbDropdownProps,
+	FlatItem,
+	MappedItem,
+} from '../BbDropdown/types';
 import type { IconType } from '@/types/Icon';
 
 type Sizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
@@ -269,7 +285,7 @@ export type BbDropdownButtonItemSlotProps = {
 	/** The zero-based index of this item. */
 	index: number;
 	/** The raw item object from the `items` prop. */
-	item: BbDropdownProps['items'][number];
+	item: FlatItem<BbDropdownProps['items'][number]>;
 	/** Whether the dropdown panel is currently open. */
 	open: boolean;
 	/** The current placement of the dropdown panel. */

package/dist/components/BbDropdown/types.d.ts

@@ -20,6 +20,14 @@ export type Item = Omit<BaseButtonProps, 'block' | 'tag' | 'type'> & {
      */
     'append:icon'?: IconType;
 };
+/**
+ * Items accepted by the dropdown. A flat list renders a single group with no
+ * dividers; a nested array introduces a divider before and after the group.
+ * The two shapes can be mixed, e.g. `[item, item, [item, item], item]`.
+ */
+export type Items = (Item | Item[])[];
+/** Unwraps the item type out of the (possibly nested) {@link Items} shape. */
+export type FlatItem<T> = T extends (infer U)[] ? U : T;
 export type MappedItem = Item & {
     /**
      * Identifier of the element among its siblings.
@@ -53,8 +61,12 @@ export type BbDropdownProps = Pick<CommonProps, 'arrowPadding' | 'disabled' | 'e
      * Array used to render each dropdown button.
      * They can act as `button`, as `a`, or as `router-link`
      * as they are based on the functionality provided by `BaseButton`.
+     *
+     * Pass a flat array for a single group, or nest arrays to split the items
+     * into divider-separated groups. The two shapes can be mixed, e.g.
+     * `[item, item, [item, item], item]`.
      */
-    items: Item[];
+    items: Items;
     /**
      * Name of the theme to apply to the component. It creates a CSS class with the name of the theme.
      *
@@ -110,7 +122,7 @@ export type BbDropdownItemSlotProps = {
     /** The zero-based index of this item. */
     index: number;
     /** The raw item object from the `items` prop. */
-    item: BbDropdownProps['items'][number];
+    item: FlatItem<BbDropdownProps['items'][number]>;
     /** Whether the dropdown panel is currently open. */
     open: boolean;
     /** The current placement of the dropdown panel. */

package/dist/components/BbDropdownButton/types.d.ts

@@ -1,4 +1,4 @@
-import { BbDropdownProps, MappedItem } from '../BbDropdown/types';
+import { BbDropdownProps, FlatItem, MappedItem } from '../BbDropdown/types';
 import { IconType } from '../../types/Icon';
 type Sizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 export type BbDropdownButtonProps = Pick<BbDropdownProps, 'arrowPadding' | 'disabled' | 'eager' | 'id' | 'items' | 'offset' | 'padding' | 'placement' | 'theme' | 'transitionDuration' | 'width'> & {
@@ -63,7 +63,7 @@ export type BbDropdownButtonItemSlotProps = {
     /** The zero-based index of this item. */
     index: number;
     /** The raw item object from the `items` prop. */
-    item: BbDropdownProps['items'][number];
+    item: FlatItem<BbDropdownProps['items'][number]>;
     /** Whether the dropdown panel is currently open. */
     open: boolean;
     /** The current placement of the dropdown panel. */