bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/GroupedListBox.md

@@ -0,0 +1,538 @@
+# GroupedListBox
+
+## Template & Script
+
+```vue
+<template>
+	<span
+		class="bb-listbox bb-listbox--grouped"
+		:class="{
+			'bb-listbox--compact': compact,
+			'bb-listbox--loading': loading,
+			'bb-listbox--multiple': multiple,
+			'bb-listbox--no-data': !hasOptions,
+			'bb-listbox--open': open,
+		}"
+		:style="{
+			'--transition-duration': `${transitionDuration}ms`,
+			'--overlay-min-height': `${height}px`,
+			'--option-height': `${resolvedOptionHeight}px`,
+			'--group-header-height': `${resolvedHeaderHeight}px`,
+		}"
+		@click.stop="handleClick"
+	>
+		<span class="bb-listbox__outer-container scrollbar-border">
+			<span ref="inner" class="bb-listbox__inner-container" tabindex="-1">
+				<slot name="options:prepend"></slot>
+				<span v-if="loading && !hasOptions" class="bb-listbox__loading">
+					<slot :name="'loading'">{{
+						loadingText || t('common.loadingText').value
+					}}</slot>
+				</span>
+				<span v-else-if="!hasOptions" class="bb-listbox__no-data">
+					<slot :name="'no-data'">{{
+						noDataText || t('common.noDataText').value
+					}}</slot>
+				</span>
+				<span
+					v-else
+					role="listbox"
+					ref="listbox"
+					:style="{ height: `${totalSize}px` }"
+					:aria-activedescendant="activeDescendantId"
+					:aria-multiselectable="multiple ? true : undefined"
+					tabindex="-1"
+				>
+					<span
+						v-for="row in virtualRows"
+						:key="groupMetaIndexedByIndex[row.index].id"
+						:style="{ transform: `translateY(${row.start}px)` }"
+						role="group"
+						:aria-labelledby="groupMetaIndexedByIndex[row.index].headerId"
+						:aria-disabled="
+							groupMetaIndexedByIndex[row.index].allOptionsAreDisabled
+						"
+						class="bb-listbox__group"
+					>
+						<span
+							class="bb-listbox__group-header"
+							role="presentation"
+							:id="groupMetaIndexedByIndex[row.index].headerId"
+						>
+							<slot
+								name="group"
+								:text="groupMetaIndexedByIndex[row.index].label"
+								:item="groupMetaIndexedByIndex[row.index].data"
+								:index="row.index"
+								:length="groupMetaIndexedByIndex[row.index].length"
+								:disabled="
+									groupMetaIndexedByIndex[row.index].allOptionsAreDisabled
+								"
+							>
+								<span class="bb-listbox__group-header-label">{{
+									groupMetaIndexedByIndex[row.index].label
+								}}</span>
+							</slot>
+						</span>
+
+						<span
+							v-for="option in groupMetaIndexedByIndex[row.index].options"
+							:key="option.valueHash"
+							:aria-selected="
+								optionsMetaIndexedById[option.valueHash].selected
+									? true
+									: undefined
+							"
+							:aria-setsize="groupMetaIndexedByIndex[row.index].length"
+							:aria-posinset="
+								optionsMetaIndexedById[option.valueHash].indexInGroup + 1
+							"
+							:id="getOptionId(option.valueHash)"
+							:class="{
+								'bb-listbox__option autocomplete-option': true,
+								'autocomplete-option--focused':
+									focusedIndex ===
+									optionsMetaIndexedById[option.valueHash].globalIndex,
+								'autocomplete-option--selected':
+									optionsMetaIndexedById[option.valueHash].selected,
+								'autocomplete-option--disabled':
+									optionsMetaIndexedById[option.valueHash].disabled,
+							}"
+							:data-index="optionsMetaIndexedById[option.valueHash].globalIndex"
+							role="option"
+						>
+							<slot
+								:disabled="!!optionsMetaIndexedById[option.valueHash].disabled"
+								:focused="
+									focusedIndex ===
+									optionsMetaIndexedById[option.valueHash].globalIndex
+								"
+								:index="optionsMetaIndexedById[option.valueHash].globalIndex"
+								:item="optionsMetaIndexedById[option.valueHash].item"
+								name="option"
+								:selected="!!optionsMetaIndexedById[option.valueHash].selected"
+								:text="optionsMetaIndexedById[option.valueHash].text"
+								:value="optionsMetaIndexedById[option.valueHash].value"
+							>
+								<svg
+									class="autocomplete-option__checkbox"
+									role="presentation"
+									viewBox="276.411 158.834 114.971 114.97"
+								>
+									<path
+										d="M 297.574 224.786 L 318.309 243.134 L 371.568 189.232"
+										fill="none"
+										stroke-linecap="round"
+										stroke-width="14px"
+									></path>
+								</svg>
+
+								<span class="autocomplete-option__label">{{
+									optionsMetaIndexedById[option.valueHash].text
+								}}</span>
+							</slot>
+						</span>
+					</span>
+				</span>
+				<slot name="options:append"></slot>
+			</span>
+		</span>
+	</span>
+</template>
+
+<script setup lang="ts" generic="Item = any">
+import { isNil } from '@/utilities/functions/isNil';
+import { computed, ref, useTemplateRef, watch } from 'vue';
+import { useVirtualizer } from '@tanstack/vue-virtual';
+import type { GroupedOptions, Option } from '@/types/Option';
+import type {
+	GroupedListBoxProps,
+	GroupedListBoxEvents,
+	GroupedListBoxSlots,
+} from './types';
+export type { GroupedListBoxProps, GroupedListBoxEvents, GroupedListBoxSlots };
+import { useLocale } from '@/composables/useLocale';
+import { useListboxFocus } from '@/composables/useListboxFocus';
+import { indexBy } from '@/utilities/functions/indexBy';
+
+type GroupMeta = {
+	allOptionsAreDisabled: boolean;
+	data: any;
+	headerId: string;
+	height: number;
+	id: string | symbol;
+	index: number;
+	label: string;
+	length: number;
+	offset: number;
+	options: Option[];
+};
+
+const props = withDefaults(defineProps<GroupedListBoxProps>(), {
+	transitionDuration: 250,
+});
+
+const emit = defineEmits<GroupedListBoxEvents>();
+
+defineSlots<GroupedListBoxSlots<Item>>();
+
+const { t } = useLocale();
+
+const innerRef = useTemplateRef('inner');
+const listboxRef = useTemplateRef('listbox');
+
+const resolvedOptionHeight = computed(() => {
+	if (props.optionHeight) return props.optionHeight;
+	if (props.compact) return 32;
+	return 40;
+});
+
+const resolvedHeaderHeight = computed(() => {
+	if (props.headerHeight) return props.headerHeight;
+	if (props.compact) return 24;
+	return 32;
+});
+
+const groupMeta = computed(() => {
+	let offsetAccumulator = 0;
+	return props.groups.map((group, index) => {
+		const id = group.id;
+
+		const offset = offsetAccumulator;
+		const length = group.options.length;
+		const height =
+			resolvedHeaderHeight.value + length * resolvedOptionHeight.value;
+		const headerId = `group-header-${group.id}`;
+		const label =
+			typeof group.data === 'string' ? group.data : JSON.stringify(group.data);
+		const allOptionsAreDisabled = group.options.every((o) => o.disabled);
+		const data = group.data;
+		const options = group.options;
+
+		offsetAccumulator += length;
+		return {
+			offset,
+			length,
+			height,
+			id,
+			headerId,
+			label,
+			index,
+			allOptionsAreDisabled,
+			data,
+			options,
+		};
+	});
+});
+
+const groupMetaIndexedByIndex = computed(() =>
+	indexBy(groupMeta.value, 'index')
+);
+
+const optionsMeta = computed(() => {
+	return props.groups.flatMap((g, groupIndex) =>
+		g.options.map((o, indexInGroup) => {
+			const id = o.valueHash;
+			const globalIndex =
+				groupMetaIndexedByIndex.value[groupIndex].offset + indexInGroup;
+			const groupId = g.id;
+			const selected = !!o.selected;
+			const disabled = !!o.disabled;
+
+			const item = o.item;
+			const text = o.text;
+			const value = o.value;
+			const focused = globalIndex === focusedIndex.value;
+			return {
+				id,
+				globalIndex,
+				groupIndex,
+				groupId,
+				indexInGroup,
+				selected,
+				disabled,
+				item: item,
+				text: text,
+				value: value,
+				valueHash: o.valueHash,
+				focused,
+			};
+		})
+	);
+});
+const optionsMetaIndexedById = computed(() => indexBy(optionsMeta.value, 'id'));
+const optionsMetaIndexedByIndex = computed(() =>
+	indexBy(optionsMeta.value, 'globalIndex')
+);
+const getOptionId = (hash: Option['valueHash']) => `listbox-option-${hash}`;
+const activeDescendantId = computed(() => {
+	if (isNil(focusedIndex.value)) return undefined;
+	const focusedOption = optionsMetaIndexedByIndex.value[focusedIndex.value];
+	if (!focusedOption) return undefined;
+	return getOptionId(focusedOption.valueHash);
+});
+
+const hasOptions = computed(() => optionsMeta.value.length > 0);
+
+const groupHeight = (groupIndex: number) =>
+	resolvedHeaderHeight.value +
+	props.groups[groupIndex].options.length * resolvedOptionHeight.value;
+
+const rowVirtualizer = useVirtualizer({
+	get count() {
+		return props.groups.length;
+	},
+	getScrollElement: () => innerRef.value ?? null,
+	estimateSize: (i) => groupHeight(i),
+	overscan: 2,
+});
+
+const virtualRows = computed(() => rowVirtualizer.value.getVirtualItems());
+const totalSize = computed(() => rowVirtualizer.value.getTotalSize());
+
+const {
+	focusedIndex,
+	focusNext,
+	focusPrevious,
+	focusFirst,
+	focusLast,
+	focusFirstSelected,
+	focusLastSelected,
+	focusByHash,
+	blur,
+	getHighlighted,
+} = useListboxFocus(
+	computed(() => optionsMeta.value),
+	{ disabled: () => !props.open }
+);
+
+const scrollToFocused = () => {
+	if (!innerRef.value || isNil(focusedIndex.value)) return;
+	const el = innerRef.value.querySelector<HTMLElement>(
+		`[data-index="${focusedIndex.value}"]`
+	);
+	if (el) {
+		el.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+	}
+};
+
+watch(focusedIndex, () => {
+	scrollToFocused();
+	emit('focused:change', activeDescendantId.value);
+});
+
+const confirmOption = () => {
+	if (isNil(focusedIndex.value) || !props.open) return;
+	const optionMeta = optionsMetaIndexedByIndex.value[focusedIndex.value];
+	if (!optionMeta || optionMeta.disabled) return;
+	const option: Option = {
+		text: optionMeta.text,
+		value: optionMeta.value,
+		item: optionMeta.item,
+		valueHash: optionMeta.valueHash,
+		selected: optionMeta.selected,
+		disabled: optionMeta.disabled,
+	};
+	if (optionMeta.selected) {
+		emit('option:unselected', option);
+	} else {
+		emit('option:selected', option);
+	}
+};
+
+const height = ref(0);
+const getScrollHeight = () => {
+	if (innerRef.value) {
+		height.value = innerRef.value.scrollHeight;
+	}
+};
+
+const handleClick = (event: MouseEvent) => {
+	event.preventDefault();
+	if (
+		innerRef.value &&
+		event.target instanceof HTMLElement &&
+		listboxRef.value
+	) {
+		let node: HTMLElement = event.target;
+		let index = node.dataset['index'];
+		while (isNil(index) && node.parentElement) {
+			node = node.parentElement;
+			index = node.dataset['index'];
+		}
+		if (index) {
+			const option = optionsMetaIndexedByIndex.value[+index];
+			if (option && !option.disabled) {
+				focusedIndex.value = +index;
+				confirmOption();
+			}
+		}
+	}
+};
+
+watch(() => props.open, getScrollHeight, { flush: 'post' });
+
+watch(
+	() => props.groups,
+	(value, previous) => {
+		const currentHash = value
+			.flatMap((g) => g.options.map((o) => o.valueHash))
+			.join(',');
+
+		const previousHash = previous
+			.flatMap((g) => g.options.map((o) => o.valueHash))
+			.join(',');
+		if (currentHash !== previousHash) {
+			rowVirtualizer.value.measure();
+			getScrollHeight();
+			blur();
+		}
+	},
+	{ flush: 'post' }
+);
+
+defineExpose({
+	focusNext,
+	focusPrevious,
+	focusFirst,
+	focusFirstSelected,
+	focusLast,
+	focusLastSelected,
+	blur,
+	confirmOption,
+	focusByHash,
+	getHighlighted,
+	getActiveDescendantId: () => activeDescendantId.value,
+});
+</script>
+
+<style lang="postcss"></style>
+```
+
+## Types
+
+```ts
+import type { GroupedOptions, Option } from '@/types/Option';
+
+export type GroupedListBoxProps = {
+	/**
+	 * Sets the listbox in a compact state.
+	 */
+	compact?: boolean;
+	/**
+	 * List of option groups to display.
+	 */
+	groups: GroupedOptions[];
+	/**
+	 * Height of group headers (px). Defaults to 24px (compact) or 32px.
+	 */
+	headerHeight?: number;
+	/**
+	 * Shows the listbox in a loading state.
+	 */
+	loading?: boolean;
+	/**
+	 * Text shown while options are loading.
+	 */
+	loadingText?: string;
+	/**
+	 * Allows multiple options to be selected simultaneously.
+	 */
+	multiple?: boolean;
+	/**
+	 * Text shown when no options are available.
+	 */
+	noDataText?: string;
+	/**
+	 * Whether the listbox is open (visible).
+	 */
+	open?: boolean;
+	/**
+	 * Fixed height (in px) for each option row. Defaults to 40px (32px in compact mode).
+	 */
+	optionHeight?: number;
+	/**
+	 * Duration of open/close transition in milliseconds.
+	 *
+	 * @defaultValue `250`
+	 */
+	transitionDuration?: number;
+};
+
+export type GroupedListBoxEvents = {
+	/**
+	 * Emitted when an option is selected by the user.
+	 * @param option - The selected option.
+	 */
+	(e: 'option:selected', option: Option): void;
+	/**
+	 * Emitted when a previously selected option is deselected.
+	 * @param option - The deselected option.
+	 */
+	(e: 'option:unselected', option: Option): void;
+	/**
+	 * Emitted when the keyboard-focused option changes.
+	 * @param id - The accessible id of the focused option, or `undefined` when focus is cleared.
+	 */
+	(e: 'focused:change', id: string | undefined): void;
+};
+
+/** Props exposed by the `option` slot. */
+export type GroupedListBoxOptionSlotProps<Item = any> = {
+	/** Whether this option is disabled. */
+	disabled: boolean;
+	/** Whether this option currently has keyboard focus. */
+	focused: boolean;
+	/** Absolute zero-based index of this option in the full list. */
+	index: number;
+	/** The raw item from the source list. */
+	item: Item;
+	/** Whether this option is currently selected. */
+	selected: boolean;
+	/** The resolved display text for this option. */
+	text: string;
+	/** The resolved value for this option. */
+	value: any;
+};
+
+/** Props exposed by the `group` slot. */
+export type GroupedListBoxGroupSlotProps<Item = any> = {
+	/** The display label for this group. */
+	text: string;
+	/** The raw group data item. */
+	item: Item;
+	/** Zero-based index of this group's first option in the full list. */
+	index: number;
+	/** Number of options in this group. */
+	length: number;
+	/** Whether all options in this group are disabled. */
+	disabled: boolean;
+};
+
+export type GroupedListBoxSlots<Item = any> = {
+	/**
+	 * Content prepended inside the options list, before the first group.
+	 */
+	'options:prepend'?: (props: object) => any;
+	/**
+	 * Content shown while items are loading (replaces the default loading text).
+	 */
+	loading?: (props: object) => any;
+	/**
+	 * Content shown when no options are available (replaces the default "no data" text).
+	 */
+	'no-data'?: (props: object) => any;
+	/**
+	 * Replaces the default rendering of each option row within a group.
+	 */
+	option?: (props: GroupedListBoxOptionSlotProps<Item>) => any;
+	/**
+	 * Replaces the default group header rendered above each group of options.
+	 */
+	group?: (props: GroupedListBoxGroupSlotProps<Item>) => any;
+	/**
+	 * Content appended inside the options list, after the last group.
+	 */
+	'options:append'?: (props: object) => any;
+};
+```