bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/FlatListBox.md

@@ -0,0 +1,382 @@
+# FlatListBox
+
+## Template & Script
+
+```vue
+<template>
+	<span
+		class="bb-listbox"
+		: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`,
+		}"
+		@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="optionsMetaByIndex[row.index].valueHash"
+						:aria-selected="
+							optionsMetaByIndex[row.index].focused ? true : undefined
+						"
+						:class="{
+							'bb-listbox__option autocomplete-option': true,
+							'autocomplete-option--focused':
+								optionsMetaByIndex[row.index].focused,
+							'autocomplete-option--selected':
+								optionsMetaByIndex[row.index].selected,
+							'autocomplete-option--disabled':
+								optionsMetaByIndex[row.index].disabled,
+						}"
+						:data-index="row.index"
+						:id="getOptionId(optionsMetaByIndex[row.index].valueHash)"
+						role="option"
+						:style="{
+							transform: `translateY(${row.start}px)`,
+						}"
+					>
+						<slot
+							:disabled="optionsMetaByIndex[row.index].disabled"
+							:focused="optionsMetaByIndex[row.index].focused"
+							:index="row.index"
+							:item="optionsMetaByIndex[row.index].item"
+							name="option"
+							:selected="optionsMetaByIndex[row.index].selected"
+							:text="optionsMetaByIndex[row.index].text"
+							:value="optionsMetaByIndex[row.index].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">{{
+								optionsMetaByIndex[row.index].text
+							}}</span></slot
+						>
+					</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 { isNotNil } from '@/utilities/functions/isNotNil';
+import { computed, ref, useTemplateRef, watch } from 'vue';
+import { useVirtualizer } from '@tanstack/vue-virtual';
+import type { Option } from '@/types/Option';
+import type {
+	FlatListBoxProps,
+	FlatListBoxEvents,
+	FlatListBoxSlots,
+} from './types';
+export type { FlatListBoxProps, FlatListBoxEvents, FlatListBoxSlots };
+import { hash } from '@/utilities/functions/hash';
+import { useLocale } from '@/composables/useLocale';
+import { useListboxFocus } from '@/composables/useListboxFocus';
+import { indexBy } from '@/utilities/functions/indexBy';
+
+const props = withDefaults(defineProps<FlatListBoxProps<Item>>(), {
+	transitionDuration: 250,
+});
+
+const emit = defineEmits<FlatListBoxEvents>();
+
+defineSlots<FlatListBoxSlots<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 rowVirtualizer = useVirtualizer({
+	get count() {
+		return props.options.length;
+	},
+	getScrollElement: () => innerRef.value ?? null,
+	estimateSize: () => resolvedOptionHeight.value,
+	overscan: 5,
+});
+
+const virtualRows = computed(() => rowVirtualizer.value.getVirtualItems());
+const totalSize = computed(() => rowVirtualizer.value.getTotalSize());
+const optionsMeta = computed(() =>
+	props.options.map((o, index) => ({
+		index,
+		text: o.text,
+		value: o.value,
+		valueHash: o.valueHash,
+		item: o.item,
+		selected: !!o.selected,
+		disabled: !!o.disabled,
+		focused: index === focusedIndex.value,
+	}))
+);
+const optionsMetaByIndex = computed(() => indexBy(optionsMeta.value, 'index'));
+const getOptionId = (hash: Option['valueHash']) => `listbox-option-${hash}`;
+const activeDescendantId = computed(() => {
+	if (isNil(focusedIndex.value)) return undefined;
+	const option = optionsMetaByIndex.value[focusedIndex.value];
+	if (!option) return undefined;
+	return getOptionId(option.valueHash);
+});
+const hasOptions = computed(() => optionsMeta.value.length > 0);
+
+const {
+	focusedIndex,
+	focusNext,
+	focusPrevious,
+	focusFirst,
+	focusLast,
+	focusFirstSelected,
+	focusLastSelected,
+	focusByHash,
+	blur,
+	getHighlighted,
+} = useListboxFocus(() => props.options, { disabled: () => !props.open });
+
+watch(focusedIndex, (idx) => {
+	if (innerRef.value && isNotNil(idx)) {
+		rowVirtualizer.value.scrollToIndex(idx, {
+			align: 'center',
+			behavior: 'smooth',
+		});
+	}
+	emit('focused:change', activeDescendantId.value);
+});
+
+const confirmOption = () => {
+	if (isNil(focusedIndex.value) || !props.open) return;
+	const option = optionsMetaByIndex.value[focusedIndex.value];
+	if (option.disabled) return;
+	if (option.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 = optionsMetaByIndex.value[+index];
+			if (option && !option.disabled) {
+				focusedIndex.value = +index;
+				confirmOption();
+			}
+		}
+	}
+};
+
+watch(
+	() => props.open,
+	() => {
+		getScrollHeight();
+	},
+	{ flush: 'post' }
+);
+
+watch(
+	() => props.options,
+	(value, previous) => {
+		if (
+			hash(value.map((o) => o.valueHash)) !==
+			hash(previous.map((o) => o.valueHash))
+		) {
+			rowVirtualizer.value.calculateRange();
+			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 { Option } from '@/types/Option';
+
+export type FlatListBoxProps<Item = any> = {
+	/**
+	 * Sets the listbox in a compact state.
+	 */
+	compact?: boolean;
+	/**
+	 * List of options to display.
+	 */
+	options: Option<Item>[];
+	/**
+	 * Whether the listbox is open (visible).
+	 */
+	open?: boolean;
+	/**
+	 * Shows the listbox in a loading state.
+	 */
+	loading?: boolean;
+	/**
+	 * Allows multiple options to be selected simultaneously.
+	 */
+	multiple?: boolean;
+	/**
+	 * Duration of open/close transition in milliseconds.
+	 *
+	 * @defaultValue `250`
+	 */
+	transitionDuration?: number;
+	/**
+	 * Text shown while options are loading.
+	 */
+	loadingText?: string;
+	/**
+	 * Text shown when no options are available.
+	 */
+	noDataText?: string;
+	/**
+	 * Fixed height (in px) for each option row. Defaults to 40px (32px in compact mode).
+	 */
+	optionHeight?: number;
+};
+
+export type FlatListBoxEvents = {
+	/**
+	 * 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 FlatListBoxOptionSlotProps<Item = any> = {
+	/** Whether this option is disabled. */
+	disabled: boolean;
+	/** Whether this option currently has keyboard focus. */
+	focused: boolean;
+	/** Zero-based index of this option in the flat 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;
+};
+
+export type FlatListBoxSlots<Item = any> = {
+	/**
+	 * Content prepended inside the options list, before the first option.
+	 */
+	'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.
+	 */
+	option?: (props: FlatListBoxOptionSlotProps<Item>) => any;
+	/**
+	 * Content appended inside the options list, after the last option.
+	 */
+	'options:append'?: (props: object) => any;
+};
+```