bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbDropdown.md

@@ -0,0 +1,765 @@
+# BbDropdown
+
+## Template & Script
+
+```vue
+<template>
+	<slot
+		v-if="!hasExternalActivator"
+		name="activator"
+		v-bind="{
+			props: {
+				ref: setActivatorRef,
+			},
+			disabled,
+			open,
+			placement,
+		}"
+	></slot>
+	<CommonPopover
+		ref="popover"
+		v-model="open"
+		:anchor="effectiveAnchor"
+		:arrow-padding="arrowPadding"
+		:boundary="boundary"
+		class="bb-dropdown"
+		:class="{
+			[`bb-dropdown--${theme}`]: true,
+		}"
+		:eager="eager"
+		:offset="offset"
+		:hide-arrow="placement === 'cursor'"
+		:padding="padding"
+		:placement="placement === 'cursor' ? 'bottom-start' : placement"
+		:transition-duration="transitionDuration"
+		v-bind="$attrs"
+	>
+		<span
+			:id="`menu_${id}`"
+			:aria-labelledby="id"
+			aria-role="menu"
+			class="bb-dropdown__items-container"
+			:inert="!open"
+			:style="parsedWidth ? { width: parsedWidth } : undefined"
+		>
+			<slot
+				:disabled="disabled"
+				name="prepend"
+				:open="open"
+				:placement="placement"
+			></slot>
+			<template
+				v-for="({ original, ...item }, index) in mappedItems"
+				:key="item.key"
+			>
+				<slot
+					:disabled="item.disabled"
+					:index="index"
+					:item="items[index]"
+					:name="`item:prepend`"
+					:open="open"
+					:placement="placement"
+					:text="item.text"
+				></slot>
+				<BaseButton
+					:aria-role="'menuitem'"
+					class="bb-dropdown__item"
+					:class="{
+						'bb-dropdown__item--first': index === 0,
+						'bb-dropdown__item--last': index === items.length - 1,
+					}"
+					:data-dropdown-item="true"
+					v-bind="item"
+				>
+					<slot
+						:disabled="item.disabled"
+						:index="index"
+						:item="original"
+						:name="item.key"
+						:open="open"
+						:placement="placement"
+						:text="item.text"
+						><BbIcon
+							v-if="item['prepend:icon']"
+							class="item__prepend-icon"
+							:type="item['prepend:icon']" />
+						<span class="item__content">{{ item.text }}</span>
+						<BbIcon
+							v-if="item['append:icon']"
+							class="item__append-icon"
+							:type="item['append:icon']" /></slot></BaseButton
+				><slot
+					:disabled="item.disabled"
+					:index="index"
+					:item="items[index]"
+					:name="`item:append`"
+					:open="open"
+					:placement="placement"
+					:text="item.text"
+				></slot>
+			</template>
+			<slot
+				:disabled="disabled"
+				name="append"
+				:open="open"
+				:placement="placement"
+			></slot>
+		</span>
+	</CommonPopover>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, useTemplateRef, watch } from 'vue';
+import { findRightIndex } from '@/utilities/functions/findRightIndex';
+import { useId } from '@/composables/useId';
+import { useUntil } from '@/composables/useUntil';
+import { wait } from '@/utilities/functions/wait';
+import BaseButton from '../BaseButton/BaseButton.vue';
+import BbIcon from '../BbIcon/BbIcon.vue';
+import CommonPopover from '../CommonPopover/CommonPopover.vue';
+import selectors from 'focusable-selectors';
+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 type {
+	BbDropdownProps,
+	BbDropdownSlots,
+	Item,
+	MappedItem,
+	DropdownTrigger,
+} from './types';
+export type {
+	BbDropdownProps,
+	BbDropdownSlots,
+	Item,
+	MappedItem,
+	DropdownTrigger,
+};
+
+type InferredBodySlots = ColumnName<BbDropdownProps['items'][number]['key']>;
+defineSlots<BbDropdownSlots>();
+
+const props = withDefaults(defineProps<BbDropdownProps>(), {
+	arrowPadding: 10,
+	placement: 'bottom',
+	theme: 'default',
+	transitionDuration: 300,
+	trigger: 'click',
+	width: 'auto',
+	padding: 10,
+	offset: 3,
+});
+
+defineOptions({
+	inheritAttrs: false,
+});
+
+const id = props.id ?? `bb_${useId().id.value}`;
+const activator = ref<HTMLElement>();
+const activatorDom = computed(() => extractDomContainer(activator.value));
+const hasExternalActivator = computed(() => props.activator != null);
+const popoverRef = useTemplateRef('popover');
+const popoverDom = computed(() => extractDomContainer(popoverRef.value));
+const open = ref(false);
+const hasOpenedOnce = useUntil(open, { initialValue: props.eager });
+
+const triggers = computed(() => {
+	const raw = props.trigger;
+	return new Set(Array.isArray(raw) ? raw : [raw]);
+});
+
+const createVirtualElement = (x: number, y: number) => ({
+	getBoundingClientRect: () => ({
+		x,
+		y,
+		width: 0,
+		height: 0,
+		top: y,
+		left: x,
+		right: x,
+		bottom: y,
+		toJSON() {
+			return this;
+		},
+	}),
+});
+
+const cursorAnchor = ref<ReturnType<typeof createVirtualElement> | null>(null);
+
+const effectiveAnchor = computed(() =>
+	props.placement === 'cursor' && cursorAnchor.value
+		? cursorAnchor.value
+		: activator.value
+);
+
+const setActivatorRef = (reference: unknown) => {
+	const el = extractDomContainer(reference);
+	if (!el) return;
+	activator.value = el;
+};
+
+const { resume, pause } = useIntersectionObserver(
+	activatorDom,
+	async ([{ intersectionRatio }]) => {
+		if (intersectionRatio !== 1 && open.value) {
+			await closeDropdown();
+		}
+	},
+	{ threshold: [0, 1], immediate: false }
+);
+
+const mappedItems = computed(() => {
+	let firstFocusableIndex: number = props.items.findIndex((el) => !el.disabled);
+	let lastFocusableIndex: number = findRightIndex(
+		props.items,
+		(item) => !item.disabled
+	);
+
+	return props.items.map((item, index) => {
+		const itemid = `${id}-item-${item.key}`;
+		const { onClick: handler, ...rest } = item;
+
+		/* If a click handler has been passed close the dropdown,
+		 * return focus and run the handler
+		 */
+		const onClick = async (event: MouseEvent) => {
+			event.stopPropagation();
+			await closeDropdown();
+			const nextElement = document.querySelector<HTMLElement>(`#${id}`);
+			if (nextElement) nextElement.focus();
+			handler?.(event);
+		};
+
+		/**
+		 * On keydown
+		 * arrow down move to the next focusable element if it's not the last
+		 * arrow up move to the previous focusable element if it's not the first
+		 * on tab search the next focusable element after the button that opens the dropdown
+		 * if an element is found focus on that
+		 * (the menu is attached to body so it's not in order)
+		 */
+		const onKeydown = (event: KeyboardEvent) => {
+			if (
+				!(event.target instanceof HTMLElement) ||
+				!event.target.dataset['dropdownItem'] ||
+				!popoverDom.value
+			) {
+				return;
+			}
+
+			if (event.key === 'ArrowDown') {
+				event.preventDefault();
+				if (index !== lastFocusableIndex) {
+					const option = popoverDom.value.querySelector(
+						selectors.map((selector) => `#${itemid} ~ ${selector}`).join(',')
+					);
+					if (option instanceof HTMLElement) {
+						option.focus();
+					}
+				}
+			} else if (event.key === 'ArrowUp') {
+				event.preventDefault();
+				if (index !== firstFocusableIndex) {
+					const indexOfPrevious = findRightIndex(
+						props.items,
+						(item, i) => i < index && !item.disabled
+					);
+					const options = Array.from(
+						popoverDom.value.querySelectorAll(`.bb-dropdown__item`)
+					);
+					const option = options[indexOfPrevious];
+					if (option instanceof HTMLElement) {
+						option.focus();
+					}
+				}
+			} else if (event.key === 'Tab') {
+				if (index === lastFocusableIndex && !event.shiftKey) {
+					const focusableElements = Array.from(
+						document.querySelectorAll(selectors.join(','))
+					);
+					const indexOfButton = focusableElements.findIndex(
+						(el) => el.id === id
+					);
+					const nextElement = focusableElements[indexOfButton + 1];
+					if (nextElement instanceof HTMLElement) {
+						event.preventDefault();
+						closeDropdown();
+						nextElement.focus();
+					}
+				} else if (index === firstFocusableIndex && event.shiftKey) {
+					const nextElement = document.querySelector<HTMLElement>(`#${id}`);
+					if (nextElement) {
+						event.preventDefault();
+						nextElement.focus();
+					}
+				}
+			}
+		};
+
+		return {
+			...rest,
+			original: item,
+			key: item.key.split(/\W+/g).join('_').toLowerCase() as InferredBodySlots,
+			disabled: rest.disabled || props.disabled,
+			id: itemid,
+			onClick,
+			onKeydown,
+		};
+	});
+});
+
+const onClick = (event: MouseEvent) => {
+	if (props.disabled) return;
+	if (longPressTriggered) {
+		longPressTriggered = false;
+		event.preventDefault();
+		event.stopPropagation();
+		return;
+	}
+	event.stopPropagation();
+	if (props.placement === 'cursor') {
+		cursorAnchor.value = createVirtualElement(event.clientX, event.clientY);
+	}
+	open.value ? closeDropdown() : openDropdown();
+};
+
+const onContextMenu = (event: MouseEvent) => {
+	if (props.disabled) return;
+	event.preventDefault();
+	event.stopPropagation();
+	if (props.placement === 'cursor') {
+		cursorAnchor.value = createVirtualElement(event.clientX, event.clientY);
+		if (open.value) return;
+	}
+	open.value ? closeDropdown() : openDropdown();
+};
+
+// --- Long-press (mobile equivalent of contextMenu) ---
+
+const LONG_PRESS_DELAY = 500;
+const LONG_PRESS_MOVE_THRESHOLD = 10;
+let longPressTimer: ReturnType<typeof setTimeout> | undefined;
+let longPressOrigin: { x: number; y: number } | null = null;
+let longPressTriggered = false;
+
+const clearLongPress = () => {
+	clearTimeout(longPressTimer);
+	longPressOrigin = null;
+};
+
+const onPointerDown = (event: PointerEvent) => {
+	if (props.disabled || event.pointerType === 'mouse') return;
+	longPressTriggered = false;
+	longPressOrigin = { x: event.clientX, y: event.clientY };
+	longPressTimer = setTimeout(() => {
+		longPressTriggered = true;
+		if (props.placement === 'cursor' && longPressOrigin) {
+			cursorAnchor.value = createVirtualElement(
+				longPressOrigin.x,
+				longPressOrigin.y
+			);
+		}
+		longPressOrigin = null;
+		openDropdown();
+	}, LONG_PRESS_DELAY);
+};
+
+const onPointerMove = (event: PointerEvent) => {
+	if (!longPressOrigin) return;
+	const dx = event.clientX - longPressOrigin.x;
+	const dy = event.clientY - longPressOrigin.y;
+	if (Math.sqrt(dx * dx + dy * dy) > LONG_PRESS_MOVE_THRESHOLD) {
+		clearLongPress();
+	}
+};
+
+const onPointerUp = () => {
+	clearLongPress();
+};
+
+const onKeydown = async (event: KeyboardEvent) => {
+	if (props.disabled) return;
+	const firstFocusableIndex = props.items.findIndex((el) => !el.disabled);
+	const lastFocusableIndex = findRightIndex(
+		props.items,
+		(item) => !item.disabled
+	);
+
+	const focusItem = (index: number) => {
+		if (!popoverDom.value || !mappedItems.value.length || index === -1) return;
+		const idToFocus = mappedItems.value[index].id;
+		const option = popoverDom.value.querySelector<HTMLElement>(`#${idToFocus}`);
+		option?.focus();
+	};
+
+	if (event.key === 'ArrowDown') {
+		event.preventDefault();
+		if (!open.value) await openDropdown();
+		focusItem(firstFocusableIndex);
+	} else if (event.key === 'ArrowUp') {
+		event.preventDefault();
+		if (!open.value) await openDropdown();
+		focusItem(lastFocusableIndex);
+	} else if (event.key === 'Tab' && open.value && !event.shiftKey) {
+		event.preventDefault();
+		focusItem(firstFocusableIndex);
+	}
+};
+
+const onOutsideInteraction = (event: Event) => {
+	const target = event.target;
+	if (!(target instanceof HTMLElement)) return;
+
+	const isOutside = !popoverDom.value?.contains(target);
+	if (isOutside) closeDropdown();
+};
+
+const onEsc = (event: KeyboardEvent) => {
+	if (!open.value || event.key !== 'Escape') return;
+
+	event.stopImmediatePropagation();
+	event.preventDefault();
+
+	if (document.activeElement?.id !== id) {
+		const button = document.querySelector<HTMLElement>(`#${id}`);
+		button?.focus();
+	}
+	closeDropdown();
+};
+const openDropdown = async () => {
+	resume();
+	await wait(50);
+	open.value = true;
+	document.addEventListener('click', onOutsideInteraction, { passive: true });
+	document.addEventListener('contextmenu', onOutsideInteraction, {
+		passive: true,
+	});
+	document.addEventListener('focusin', onOutsideInteraction, { passive: true });
+	document.addEventListener('keydown', onEsc, { capture: true });
+};
+
+const closeDropdown = async () => {
+	open.value = false;
+	pause();
+};
+
+watch(open, (value) => {
+	if (!value) {
+		document.removeEventListener('click', onOutsideInteraction);
+		document.removeEventListener('contextmenu', onOutsideInteraction);
+		document.removeEventListener('focusin', onOutsideInteraction);
+		document.removeEventListener('keydown', onEsc, { capture: true });
+	}
+});
+
+watch(
+	() => props.activator,
+	(val) => {
+		if (val) setActivatorRef(val);
+	},
+	{ immediate: true }
+);
+
+let cleanupActivator: (() => void) | null = null;
+
+watch(
+	[activator, triggers] as const,
+	([el, active]) => {
+		if (cleanupActivator) {
+			cleanupActivator();
+			cleanupActivator = null;
+		}
+		if (!el) return;
+
+		el.id = id;
+
+		const removers: (() => void)[] = [];
+
+		if (active.has('click')) {
+			el.addEventListener('click', onClick);
+			removers.push(() => el.removeEventListener('click', onClick));
+		}
+
+		if (active.has('contextMenu')) {
+			el.addEventListener('contextmenu', onContextMenu);
+			el.addEventListener('pointerdown', onPointerDown);
+			el.addEventListener('pointermove', onPointerMove);
+			el.addEventListener('pointerup', onPointerUp);
+			el.addEventListener('pointercancel', onPointerUp);
+			removers.push(() => {
+				el.removeEventListener('contextmenu', onContextMenu);
+				el.removeEventListener('pointerdown', onPointerDown);
+				el.removeEventListener('pointermove', onPointerMove);
+				el.removeEventListener('pointerup', onPointerUp);
+				el.removeEventListener('pointercancel', onPointerUp);
+				clearLongPress();
+			});
+		}
+
+		el.addEventListener('keydown', onKeydown);
+		removers.push(() => el.removeEventListener('keydown', onKeydown));
+
+		cleanupActivator = () => {
+			removers.forEach((fn) => fn());
+			el.removeAttribute('id');
+			el.removeAttribute('aria-expanded');
+			el.removeAttribute('aria-controls');
+		};
+	},
+	{ immediate: true }
+);
+
+// Update reactive ARIA attributes
+watch(
+	[activator, open, hasOpenedOnce] as const,
+	([el, isOpen, opened]) => {
+		if (!el) return;
+
+		el.setAttribute('aria-expanded', opened ? String(isOpen) : 'false');
+		if (opened) {
+			el.setAttribute('aria-controls', `menu_${id}`);
+		} else {
+			el.removeAttribute('aria-controls');
+		}
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	cleanupActivator?.();
+});
+
+const { width: activatorWidth } = useElementSize(
+	activatorDom,
+	{ width: 0, height: 0 },
+	{
+		box: 'border-box',
+	}
+);
+const parsedWidth = computed(() => {
+	if (props.width === 'auto') return undefined;
+	if (props.width) {
+		const { value, unit } = parseWidthString(props.width);
+		if (unit === '%') {
+			if (!activatorDom.value) return '0px';
+			return `${activatorWidth.value * (value / 100)}px`;
+		}
+		return `${value}px`;
+	}
+	return '0px';
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { BaseButtonProps } from '../BaseButton/types';
+import type { CommonProps } from '@/types/CommonProps';
+import type { IconType } from '@/types/Icon';
+
+export type DropdownTrigger = 'click' | 'contextMenu';
+
+export type Item = Omit<BaseButtonProps, 'block' | 'tag' | 'type'> & {
+	/**
+	 * Click handler of the item.
+	 */
+	onClick?: (...args: any[]) => any;
+	/**
+	 * Key used to identify the element.
+	 */
+	key: string;
+	/**
+	 * Icon to be displayed before the text.
+	 */
+	'prepend:icon'?: IconType;
+	/**
+	 * Icon to be displayed after the text.
+	 */
+	'append:icon'?: IconType;
+};
+
+export type MappedItem = Item & {
+	/**
+	 * Identifier of the element among its siblings.
+	 */
+	id: string;
+	/**
+	 * Keydown event used to handle accessibility.
+	 */
+	onKeydown: (event: KeyboardEvent) => void;
+};
+
+export type BbDropdownProps = Pick<
+	CommonProps,
+	| 'arrowPadding'
+	| 'disabled'
+	| 'eager'
+	| 'id'
+	| 'offset'
+	| 'padding'
+	| 'transitionDuration'
+> & {
+	/**
+	 * Position of the dropdown relative to the activator.
+	 * Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow).
+	 *
+	 * @defaultValue `'bottom'`
+	 */
+	placement?: CommonProps['placement'] | 'cursor';
+	/**
+	 * External activator element or component ref.
+	 * When provided, the activator slot is not rendered and event listeners
+	 * are attached programmatically to the referenced element.
+	 */
+	activator?: HTMLElement | Record<string, any> | null;
+	/**
+	 * Constrains the dropdown within a bounding element.
+	 * Accepts an HTMLElement, a Vue component ref, or a CSS selector string.
+	 */
+	boundary?: HTMLElement | Record<string, any> | string | null;
+	/**
+	 * 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`.
+	 */
+	items: Item[];
+	/**
+	 * Name of the theme to apply to the component. It creates a CSS class with the name of the theme.
+	 *
+	 * @deprecated since the popover is local you should use a normal css class applied to the top level element
+	 * @defaultValue `'default'`
+	 */
+	theme?: string;
+	/**
+	 * 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;
+};
+
+/** Props spread onto the activator element to wire up the floating-UI anchor reference. */
+export type BbDropdownActivatorProps = {
+	/** Ref callback to register the activator element. */
+	ref: (reference: unknown) => void;
+};
+
+/** Props exposed by the `activator` slot. */
+export type BbDropdownActivatorSlotProps = {
+	/** Spread onto the trigger element to wire the floating-UI anchor reference. */
+	props: BbDropdownActivatorProps;
+	/** Whether the dropdown is globally disabled. */
+	disabled?: boolean;
+	/** Whether the dropdown panel is currently open. */
+	open: boolean;
+	/** The current placement of the dropdown panel. */
+	placement: BbDropdownProps['placement'];
+};
+
+/** Props exposed by the `prepend`, `append` slots. */
+export type BbDropdownEdgeSlotProps = {
+	/** Whether the dropdown is globally disabled. */
+	disabled?: boolean;
+	/** Whether the dropdown panel is currently open. */
+	open: boolean;
+	/** The current placement of the dropdown panel. */
+	placement: BbDropdownProps['placement'];
+};
+
+/** Props exposed by the `item:prepend` and `item:append` slots, and named item slots. */
+export type BbDropdownItemSlotProps = {
+	/** Whether this item is disabled. */
+	disabled?: MappedItem['disabled'];
+	/** The zero-based index of this item. */
+	index: number;
+	/** The raw item object from the `items` prop. */
+	item: BbDropdownProps['items'][number];
+	/** Whether the dropdown panel is currently open. */
+	open: boolean;
+	/** The current placement of the dropdown panel. */
+	placement: BbDropdownProps['placement'];
+	/** The resolved display text for this item. */
+	text: MappedItem['text'];
+};
+
+export type BbDropdownSlots = {
+	/**
+	 * The element that triggers the dropdown to open. Spread `props` onto your trigger element.
+	 */
+	activator?: (props: BbDropdownActivatorSlotProps) => any;
+	/**
+	 * Content rendered before the first item in the dropdown panel.
+	 */
+	prepend?: (props: BbDropdownEdgeSlotProps) => any;
+	/**
+	 * Content rendered before each dropdown item's default button content.
+	 */
+	'item:prepend'?: (props: BbDropdownItemSlotProps) => any;
+	/**
+	 * Content rendered after each dropdown item's default button content.
+	 */
+	'item:append'?: (props: BbDropdownItemSlotProps) => any;
+	/**
+	 * Content rendered after the last item in the dropdown panel.
+	 */
+	append?: (props: BbDropdownEdgeSlotProps) => any;
+} & {
+	/**
+	 * Named slot for a specific item, identified by `item.key`. Replaces the item's default label content.
+	 */
+	[key: string]: (props: BbDropdownItemSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-dropdown {
+	overflow: clip;
+
+	.bb-dropdown__items-container {
+		color: var(--bb-text);
+		display: inline-grid;
+		grid-template-columns: 1fr;
+		padding: 6px;
+		.bb-dropdown__item {
+			border-radius: var(--bb-radius);
+			column-gap: 6px;
+			display: inline-flex;
+			align-items: center;
+			padding: 6px 8px;
+			text-align: left;
+			min-width: 100px;
+
+			&:hover {
+				background-color: color-mix(in srgb, var(--bb-text) 5%, transparent);
+			}
+			&:focus {
+				background-color: color-mix(in srgb, var(--bb-text) 15%, transparent);
+			}
+			.item__prepend-icon,
+			.item__append-icon {
+				flex-shrink: 0;
+			}
+			.item__content {
+				flex: auto;
+			}
+		}
+	}
+}
+```