@getdom/studio 0.2.1 → 0.2.3

package/src/pages/forms/select/DomSelect.vue

@@ -2,6 +2,9 @@
 import { computed, nextTick, onMounted, ref, shallowRef, useId, watch } from 'vue';
 import { resolveFloatingTeleportTarget } from '../../lib/vue/floatingTeleportTarget.js';
 import { booleanProp, normalizeOption, searchableText } from '../_shared/options.js';
+import DomOptionStatus from '../_shared/DomOptionStatus.vue';
+import { useOptionPaging } from '../_shared/useOptionPaging.js';
+import { useSelectedOptions } from '../_shared/useSelectedOptions.js';
 import DomField from '../field/DomField.vue';
 import { fieldProps } from '../field/fieldProps.js';
 import { useField } from '../field/useField.js';
@@ -16,13 +19,18 @@ defineOptions({
 		tag: '<DomSelect>',
 		description: 'A styled select control with a closed trigger, floating listbox, keyboard navigation, and rich option slots.',
 		slots: [
-			{ name: 'value', payload: '{ option, value, label, placeholder }', description: 'Custom selected-value markup inside the trigger.' },
-			{ name: 'option', payload: '{ option, index, selected, optionId }', description: 'Custom option markup inside the floating list. optionId identifies the focusable option button for external floating UI.' },
+			{ name: 'value', payload: '{ option, options, value, label, placeholder }', description: 'Custom selected-value markup inside the trigger. options contains all selected records in multiple mode.' },
+			{ name: 'option', payload: '{ option, index, selected, query, optionId }', description: 'Custom option markup with the transient query for safe text highlighting. optionId identifies the focusable row.' },
 			{ name: 'group', payload: '{ group, options, index }', description: 'Custom heading markup for options that share a group.' },
 		],
 		events: [
-			{ name: 'update:modelValue', payload: '(value: string)', description: 'Emitted when the selected option changes.' },
+			{ name: 'update:modelValue', payload: 'string | number | Array<string | number>', description: 'Emitted with one committed value or an array in multiple mode.' },
 			{ name: 'select', payload: '({ option, value, label })', description: 'Emitted with the selected option record.' },
+			{ name: 'query', payload: 'string', description: 'Emitted on open with an empty query and as the user types in the separate search input.' },
+			{ name: 'load-more', payload: '{ query }', description: 'Request another page when hasMore is true. The application owns cursors, requests, errors and appending options.' },
+			{ name: 'list-scroll', payload: 'Event', description: 'Scroll event for optional visibility-based previews.' },
+			{ name: 'open', description: 'Emitted when the panel opens.' },
+			{ name: 'close', description: 'Emitted when the panel closes.' },
 		],
 		keyboard: [
 			{ keys: 'Enter / Space / ↓', action: 'Open the listbox.' },
@@ -37,7 +45,7 @@ defineOptions({
 const props = defineProps({
 	...fieldProps,
 	modelValue: {
-		type: [String, Number],
+		type: [String, Number, Array],
 		default: '',
 		_edit: { group: 'Control props', description: 'Selected option value.' },
 	},
@@ -98,35 +106,50 @@ const props = defineProps({
 		default: 'Search options...',
 		_edit: { group: 'Control props', description: 'Placeholder shown inside the panel search input.' },
 	},
+	multiple: { type: [Boolean, String], default: false, _edit: { description: 'Toggle multiple values without closing the panel. Use an array v-model.' } },
+	filterOptions: { type: [Boolean, String], default: true, _edit: { description: 'Disable local filtering for server-ranked options.' } },
+	loading: { type: [Boolean, String], default: false },
+	hasMore: { type: [Boolean, String], default: false },
+	selectedOptions: { type: Array, default: () => [], _edit: { description: 'Resolved records for initial values outside the currently loaded server page.' } },
+	clearable: { type: [Boolean, String], default: false },
 });
-const emit = defineEmits(['update:modelValue', 'select', 'focus', 'blur']);
+const emit = defineEmits(['update:modelValue', 'select', 'query', 'load-more', 'list-scroll', 'open', 'close', 'focus', 'blur']);
 
 const root = ref(null);
 const listbox = ref(null);
 const searchInput = ref(null);
 const searchQuery = ref('');
+const isOpen = ref(false);
 const isMounted = ref(false);
 const teleportTarget = shallowRef(null);
 const field = useField(props, emit, { idPrefix: 'dom-select' });
 const isSearchable = computed(() => booleanProp(props.searchable, false));
+const isMultiple = computed(() => booleanProp(props.multiple));
+const isLoading = computed(() => booleanProp(props.loading));
+const hasMoreOptions = computed(() => booleanProp(props.hasMore));
+const filterLocally = computed(() => booleanProp(props.filterOptions, true));
 
 const optionList = computed(() => props.options.map((option) => normalizeOption(option, {
-	stringifyValue: true,
 	allowEmptyValue: true,
 })).filter(Boolean));
 const filteredOptions = computed(() => {
-	if (!isSearchable.value) return optionList.value;
+	if (!isSearchable.value || !filterLocally.value) return optionList.value;
 	const needle = searchQuery.value.trim().toLowerCase();
 	if (!needle) return optionList.value;
 	return optionList.value.filter((option) => searchableText(option).includes(needle));
 });
 const optionSections = computed(buildOptionSections);
 const hasOptionGroups = computed(() => optionSections.value.some((section) => section.group));
-const selectedOption = computed(() => optionList.value.find((option) => String(option.value) === String(field.value.value)) || null);
-const selectedLabel = computed(() => selectedOption.value?.label ?? '');
-const selectedValue = computed(() => String(field.value.value ?? ''));
+const selectedValues = computed(() => isMultiple.value ? (Array.isArray(field.value.value) ? field.value.value : []) : [field.value.value ?? '']);
+const selectedKeys = computed(() => new Set(selectedValues.value.map(String)));
+const selectedItems = useSelectedOptions(optionList, selectedValues, () => props.selectedOptions);
+const selectedOption = computed(() => selectedItems.value[0] && (selectedItems.value[0].value !== '' || optionList.value.some((option) => option.value === '')) ? selectedItems.value[0] : null);
+const selectedLabel = computed(() => selectedItems.value.map((option) => option.label).join(', '));
+const selectedValue = computed(() => isMultiple.value ? JSON.stringify(selectedValues.value.map(String)) : String(field.value.value ?? ''));
+const paging = useOptionPaging(props, emit, { list: listbox, options: filteredOptions, query: searchQuery, open: isOpen });
 const triggerClasses = computed(() => [
-	'skin-input flex h-auto min-h-10 cursor-pointer items-center justify-between gap-3 py-2 pr-3 text-left',
+	'skin-input relative flex h-auto min-h-10 cursor-pointer items-center py-2 text-left',
+	booleanProp(props.clearable) && selectedLabel.value ? 'pr-18' : 'pr-10',
 	(field.disabled.value || field.readOnly.value) && 'cursor-not-allowed opacity-60',
 	field.invalid.value && 'border-destructive focus:border-destructive focus:ring-destructive/25',
 ]);
@@ -205,7 +228,8 @@ onMounted(async () => {
 	]);
 	listbox.value?.addEventListener('dom:select', onSelect);
 	root.value?.addEventListener('dom:open', onOpen);
-	root.value?.addEventListener('dom:close', resetSearch);
+	root.value?.addEventListener('dom:close', onClose);
+	listbox.value?.addEventListener('dom:load-more', () => paging.requestMore());
 });
 
 watch(selectedValue, () => {
@@ -223,15 +247,19 @@ watch(isSearchable, () => {
  */
 function onSelect(event) {
 	if (field.disabled.value || field.readOnly.value) return;
-	const value = event.detail.value;
-	const option = optionList.value.find((item) => String(item.value) === String(value)) || null;
-	field.onInput(value);
+	const option = optionList.value.find((item) => String(item.value) === String(event.detail.value)) || null;
+	if (!option || option.disabled) return;
+	const value = option.value;
+	const nextValue = isMultiple.value
+		? selectedKeys.value.has(String(value)) ? selectedValues.value.filter((item) => String(item) !== String(value)) : [...selectedValues.value, value]
+		: value;
+	field.onInput(nextValue);
 	emit('select', {
 		option,
 		value,
 		label: option?.label ?? value,
 	});
-	close();
+	if (!isMultiple.value) close();
 }
 
 /**
@@ -240,9 +268,49 @@ function onSelect(event) {
  * @returns {void}
  */
 function onOpen() {
+	isOpen.value = true;
+	resetSearch();
+	emit('query', '');
+	emit('open');
+	nextTick(() => {
+		if (isSearchable.value) searchInput.value?.focus({ preventScroll: true });
+		const selected = listbox.value?.querySelector('[aria-selected="true"]');
+		if (!isMultiple.value && selected && listbox.value) {
+			const row = selected.getBoundingClientRect();
+			const viewport = listbox.value.getBoundingClientRect();
+			// Enter animations scale the panel; scrollTop uses untransformed CSS pixels.
+			const scale = viewport.height / listbox.value.offsetHeight || 1;
+			listbox.value.scrollTop += (row.top - viewport.top) / scale - (listbox.value.clientHeight - selected.offsetHeight) / 2;
+		} else if (listbox.value) listbox.value.scrollTop = 0;
+	});
+}
+
+/** Reset only transient search on close, without launching another server request. */
+function onClose() {
+	isOpen.value = false;
 	resetSearch();
-	if (!isSearchable.value) return;
-	nextTick(() => searchInput.value?.focus());
+	emit('close');
+}
+
+/**
+ * Clear committed values while preserving the single/multiple value contract.
+ * Restore focus to the persistent trigger when the clear button disappears.
+ *
+ * @returns {void}
+ */
+function clearSelection() {
+	if (field.disabled.value || field.readOnly.value) return;
+	const value = isMultiple.value ? [] : '';
+	field.onInput(value);
+	emit('select', { option: null, value, label: '' });
+	close();
+	nextTick(() => root.value?.querySelector('[slot="trigger"]')?.focus({ preventScroll: true }));
+}
+
+/** Forward intentional typing and reset the result viewport for the new query. */
+function onQuery() {
+	if (listbox.value) listbox.value.scrollTop = 0;
+	emit('query', searchQuery.value);
 }
 
 /**
@@ -313,7 +381,7 @@ function onSearchKeydown(event) {
 	if (event.key === 'Enter') {
 		event.preventDefault();
 		event.stopPropagation();
-		selectOption(filteredOptions.value[0]);
+		selectOption(filteredOptions.value.find((option) => !option.disabled));
 		return;
 	}
 	if (event.key === 'Home' || event.key === 'End') {
@@ -323,12 +391,14 @@ function onSearchKeydown(event) {
 </script>
 
 <template>
-	<DomField v-bind="field.fieldAttrs.value" :chrome="chrome">
+	<DomField v-bind="field.fieldAttrs.value" :chrome="chrome" class="min-w-0">
 		<input
-			v-if="field.htmlName.value"
+			v-for="(value, index) in (isMultiple ? selectedValues : [field.value.value ?? ''])"
+			:key="index"
 			type="hidden"
 			:name="field.htmlName.value"
-			:value="field.value.value ?? ''"
+			:value="value"
+			:disabled="field.disabled.value"
 		/>
 		<dom-dropdown
 			ref="root"
@@ -358,7 +428,8 @@ function onSearchKeydown(event) {
 					<slot
 						name="value"
 						:option="selectedOption"
-						:value="selectedValue"
+						:options="selectedItems"
+						:value="field.value.value"
 						:label="selectedLabel"
 						:placeholder="placeholder"
 					>
@@ -367,10 +438,23 @@ function onSearchKeydown(event) {
 						</span>
 					</slot>
 				</span>
-				<svg viewBox="0 0 20 20" class="size-4 shrink-0 text-muted-fg" fill="none" aria-hidden="true">
+				<svg viewBox="0 0 20 20" class="pointer-events-none absolute right-3 top-1/2 size-4 -translate-y-1/2 text-muted-fg" fill="none" aria-hidden="true">
 					<path d="M6 8l4 4 4-4" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" />
 				</svg>
 			</button>
+			<button
+				v-if="booleanProp(clearable) && selectedLabel"
+				type="button"
+				aria-label="Clear selection"
+				class="absolute right-9 top-1/2 inline-flex size-8 -translate-y-1/2 items-center justify-center rounded-full text-muted-fg hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-60"
+				:disabled="field.disabled.value || field.readOnly.value"
+				@click.stop="clearSelection"
+				@mousedown.prevent
+			>
+				<svg viewBox="0 0 20 20" class="size-4" fill="none" aria-hidden="true">
+					<path d="M6 6l8 8M14 6l-8 8" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" />
+				</svg>
+			</button>
 			<Teleport :to="teleportTarget || 'body'" :disabled="!isMounted || !teleportTarget">
 				<div
 					:id="panelId"
@@ -394,12 +478,17 @@ function onSearchKeydown(event) {
 							@focus="field.onFocus"
 							@blur="field.onBlur"
 							@keydown="onSearchKeydown"
+							@input="onQuery"
 						/>
 					</div>
 					<dom-listbox
 						:id="listId"
 						ref="listbox"
 						:value="selectedValue"
+						:multiple="isMultiple ? '' : null"
+						:has-more="hasMoreOptions ? '' : null"
+						:aria-busy="isLoading"
+						@scroll="paging.onScroll"
 						class="min-h-0 overflow-auto"
 						:class="hasOptionGroups ? 'px-1 pb-1' : 'p-1'"
 					>
@@ -431,6 +520,7 @@ function onSearchKeydown(event) {
 								role="option"
 								type="button"
 								:data-value="entry.option.value"
+								:aria-selected="selectedKeys.has(String(entry.option.value))"
 								:disabled="entry.option.disabled || undefined"
 								class="dom-select-option flex w-full cursor-pointer items-center justify-between gap-3 rounded-xl px-3 py-2 text-left text-sm text-canvas-fg outline-none transition disabled:cursor-not-allowed disabled:opacity-50"
 							>
@@ -439,7 +529,8 @@ function onSearchKeydown(event) {
 										name="option"
 										:option="entry.option"
 										:index="entry.index"
-										:selected="String(entry.option.value) === selectedValue"
+										:selected="selectedKeys.has(String(entry.option.value))"
+										:query="searchQuery"
 										:option-id="`${listId}-option-${entry.index}`"
 									>
 										<span class="block font-medium">{{ entry.option.label }}</span>
@@ -447,7 +538,7 @@ function onSearchKeydown(event) {
 									</slot>
 								</span>
 								<svg
-									v-if="String(entry.option.value) === selectedValue"
+									v-if="selectedKeys.has(String(entry.option.value))"
 									viewBox="0 0 20 20"
 									class="size-4 shrink-0"
 									fill="none"
@@ -457,9 +548,7 @@ function onSearchKeydown(event) {
 								</svg>
 							</button>
 						</div>
-						<div v-if="isSearchable && !filteredOptions.length" class="px-3 py-6 text-center text-sm text-muted-fg">
-							No options found
-						</div>
+						<DomOptionStatus :loading="isLoading" :has-more="hasMoreOptions" :empty="!filteredOptions.length" @load-more="paging.requestMore(true)" />
 					</dom-listbox>
 				</div>
 			</Teleport>

package/src/pages/forms/tag-combobox/DomTagCombobox.vue

@@ -1,8 +1,11 @@
 <script setup>
-import { computed, nextTick, ref } from 'vue';
+import { computed, nextTick, ref, watch } from 'vue';
 import DomFieldLoadingSpinner from '../_shared/DomFieldLoadingSpinner.vue';
 import { booleanProp, normalizeOption, optionKey, searchableText, splitTokens as splitOptionTokens } from '../_shared/options.js';
 import { useOptionMenu } from '../_shared/useOptionMenu.js';
+import { useOptionPaging } from '../_shared/useOptionPaging.js';
+import { useSelectedOptions } from '../_shared/useSelectedOptions.js';
+import DomOptionStatus from '../_shared/DomOptionStatus.vue';
 import DomField from '../field/DomField.vue';
 import { fieldProps } from '../field/fieldProps.js';
 import { useField } from '../field/useField.js';
@@ -14,7 +17,7 @@ defineOptions({
 		description: 'A tokenizing multi-select combobox for class lists, recipients, labels, and other values that need autocomplete plus optional custom entries.',
 		icon: 'M7 5h5l5 5-7 7-5-5 7-7Zm1.5 4.5h.01M15 15h4M17 13v4',
 		slots: [
-			{ name: 'item', payload: '{ item, index, active, custom }', description: 'Replaces each suggestion row.' },
+			{ name: 'item', payload: '{ item, index, active, selected, query, custom }', description: 'Replaces each suggestion row while retaining the selected checkmark.' },
 			{ name: 'tag', payload: '{ item, value, label, remove }', description: 'Replaces each selected token.' },
 		],
 		events: [
@@ -23,6 +26,7 @@ defineOptions({
 			{ name: 'remove', payload: '({ item, value, label })', description: 'Fired when a tag is removed.' },
 			{ name: 'select', payload: '({ item, value, label, custom })', description: 'Fired when a suggestion or custom value is committed.' },
 			{ name: 'change', payload: 'Array', description: 'Fired after the selected values array changes.' },
+			{ name: 'load-more', payload: '{ query }', description: 'Request the next server page when hasMore is true.' },
 		],
 	},
 });
@@ -95,17 +99,20 @@ const props = defineProps({
 		default: false,
 		_edit: { group: 'Control props', description: 'Show a clear-all button when tags are selected.' },
 	},
+	hasMore: { type: [Boolean, String], default: false },
+	selectedOptions: { type: Array, default: () => [] },
 });
 
-const emit = defineEmits(['update:modelValue', 'query', 'add', 'remove', 'select', 'change', 'focus', 'blur']);
+const emit = defineEmits(['update:modelValue', 'query', 'add', 'remove', 'select', 'change', 'load-more', 'list-scroll', 'focus', 'blur']);
 
 const inputEl = ref(null);
+const list = ref(null);
 const query = ref('');
 const field = useField(props, emit, { idPrefix: 'dom-tag-combobox' });
 
 const selectedValues = computed(() => Array.isArray(field.value.value) ? field.value.value : []);
 const normalizedOptions = computed(() => props.options.map((option) => normalizeOption(option)).filter(Boolean));
-const selectedItems = computed(() => selectedValues.value.map((value) => optionForValue(value) || customOption(value)));
+const selectedItems = useSelectedOptions(normalizedOptions, selectedValues, () => props.selectedOptions);
 const selectedValueKeys = computed(() => new Set(selectedValues.value.map(optionKey)));
 const isClearable = computed(() => booleanProp(props.clearable, false));
 const isCustomAllowed = computed(() => booleanProp(props.allowCustom, false));
@@ -126,12 +133,11 @@ const matchingOptions = computed(() => {
 	const needle = trimmedQuery.value.toLowerCase();
 	return normalizedOptions.value
 		.filter((option) => !option.disabled)
-		.filter((option) => !selectedValueKeys.value.has(optionKey(option.value)))
 		.filter((option) => {
 			if (!needle || !isFilteringOptions.value) return true;
 			return searchableText(option).includes(needle);
 		})
-		.slice(0, Math.max(1, props.maxOptions));
+		.slice(0, isFilteringOptions.value ? Math.max(1, props.maxOptions) : undefined);
 });
 const menuItems = computed(() => {
 	const items = matchingOptions.value.map((item) => ({ item, value: item.value, label: item.label, custom: false }));
@@ -150,23 +156,31 @@ const optionMenu = useOptionMenu(menuItems, {
 	emitQuery: (value) => emit('query', value),
 });
 const { activeIndex, isOpen } = optionMenu;
-const hasEmptyState = computed(() => !isLoading.value && !menuItems.value.length && trimmedQuery.value && !isCustomAllowed.value);
-const showMenu = computed(() => isOpen.value && (menuItems.value.length > 0 || hasEmptyState.value) && !field.disabled.value && !field.readOnly.value);
+const hasMoreOptions = computed(() => booleanProp(props.hasMore));
+const showMenu = computed(() => isOpen.value && !field.disabled.value && !field.readOnly.value);
 const hasTags = computed(() => selectedValues.value.length > 0);
+const paging = useOptionPaging(props, emit, { list, options: normalizedOptions, query, open: isOpen });
 
+watch(activeIndex, () => nextTick(scrollActiveOption));
+
+/** Build a plain-text record for an allowed free-entry token. */
 function customOption(value) {
 	return { value, label: String(value), custom: true };
 }
 
+/** Resolve a loaded or retained selected record by token value. */
 function optionForValue(value) {
-	return normalizedOptions.value.find((option) => optionKey(option.value) === optionKey(value));
+	return [...normalizedOptions.value, ...selectedItems.value].find((option) => optionKey(option.value) === optionKey(value));
 }
 
+/** Toggle the chosen suggestion; selected rows remain visible with a checkmark. */
 function commitItem(entry) {
 	if (!entry) return;
+	if (selectedValueKeys.value.has(optionKey(entry.value))) { removeValue(entry.value); return; }
 	commitValue(entry.value, entry.item, entry.custom);
 }
 
+/** Add a unique token, preserving existing selections across remote page changes. */
 function commitValue(value, item = null, custom = false) {
 	if (field.disabled.value || field.readOnly.value) return;
 	if (value == null || value === '') return;
@@ -185,6 +199,7 @@ function commitValue(value, item = null, custom = false) {
 	nextTick(() => inputEl.value?.focus());
 }
 
+/** Remove one committed token without altering the remaining values. */
 function removeValue(value) {
 	if (field.disabled.value || field.readOnly.value) return;
 	const item = optionForValue(value) || customOption(value);
@@ -195,6 +210,7 @@ function removeValue(value) {
 	nextTick(() => inputEl.value?.focus());
 }
 
+/** Clear all tokens unless the field is disabled or read-only. */
 function clearAll() {
 	if (field.disabled.value || field.readOnly.value) return;
 	field.setValue([]);
@@ -202,23 +218,49 @@ function clearAll() {
 	nextTick(() => inputEl.value?.focus());
 }
 
+/** Clear only transient search after adding a token and keep multi-selection open. */
 function resetQuery() {
 	optionMenu.reset();
+	isOpen.value = true;
 }
 
+/** Open suggestions and request the initial remote page when focus enters. */
 function onFocus(event) {
 	field.onFocus(event);
+	optionMenu.cancelClose();
+	openMenu();
+}
+
+/** Reopen on a click even when Escape left the input focused. */
+function openMenu() {
+	if (field.disabled.value || field.readOnly.value) return;
+	if (!isOpen.value) emit('query', query.value);
 	isOpen.value = true;
 }
 
+/** Allow a pointer selection to finish before closing on blur. */
 function onBlur(event) {
 	optionMenu.closeSoon();
 	field.onBlur(event);
 }
 
+/** Keep the active descendant visible without scrolling the outer document. */
+function scrollActiveOption() {
+	const option = list.value?.querySelectorAll('[role="option"]')[activeIndex.value];
+	if (!option || !list.value) return;
+	const row = option.getBoundingClientRect();
+	const viewport = list.value.getBoundingClientRect();
+	const scale = viewport.height / list.value.offsetHeight || 1;
+	if (row.top < viewport.top) list.value.scrollTop += (row.top - viewport.top) / scale;
+	else if (row.bottom > viewport.bottom) list.value.scrollTop += (row.bottom - viewport.bottom) / scale;
+}
+
+/** Navigate, toggle selections and request another page at the loaded boundary. */
 function onKeydown(event) {
+	if (field.disabled.value || field.readOnly.value || event.isComposing) return;
 	if (event.key === 'ArrowDown') {
 		event.preventDefault();
+		if (isOpen.value && activeIndex.value === menuItems.value.length - 1 && hasMoreOptions.value) { paging.requestMore(); return; }
 		optionMenu.move(1);
 		return;
 	}
@@ -243,6 +285,7 @@ function onKeydown(event) {
 	}
 }
 
+/** Paste tokens through the same deduplication and permission checks as typing. */
 function onPaste(event) {
 	const text = event.clipboardData?.getData('text') || '';
 	const tokens = splitTokens(text);
@@ -255,6 +298,7 @@ function onPaste(event) {
 	}
 }
 
+/** Split user text into literal tokens using the configured separators. */
 function splitTokens(value) {
 	return splitOptionTokens(value, props.tokenSeparators);
 }
@@ -279,6 +323,7 @@ function splitTokens(value) {
 							type="button"
 							class="-mr-1 inline-flex size-4 items-center justify-center rounded-full text-muted-fg hover:bg-canvas hover:text-canvas-fg focus:outline-none focus-visible:ring-2 focus-visible:ring-ring/60"
 							:aria-label="`Remove ${entry.label}`"
+							:disabled="field.disabled.value || field.readOnly.value"
 							@click.stop="removeValue(entry.value)"
 							@mousedown.prevent
 						>
@@ -296,9 +341,12 @@ function splitTokens(value) {
 					role="combobox"
 					:aria-expanded="showMenu"
 					:aria-controls="`${field.id.value}-listbox`"
+					:aria-activedescendant="showMenu && menuItems[activeIndex] ? `${field.id.value}-option-${activeIndex}` : undefined"
+					aria-autocomplete="list"
 					:placeholder="hasTags ? '' : placeholder"
 					class="min-w-28 flex-1 bg-transparent px-1 py-1 text-sm outline-none placeholder:text-muted-fg disabled:cursor-not-allowed"
 					@focus="onFocus"
+					@click="openMenu"
 					@blur="onBlur"
 					@keydown="onKeydown"
 						@paste="onPaste"
@@ -311,6 +359,7 @@ function splitTokens(value) {
 					type="button"
 					class="inline-flex size-7 shrink-0 items-center justify-center rounded-full text-muted-fg transition hover:bg-secondary hover:text-canvas-fg focus:outline-none focus-visible:ring-2 focus-visible:ring-ring/60"
 					aria-label="Clear tags"
+					:disabled="field.disabled.value || field.readOnly.value"
 					@click.stop="clearAll"
 					@mousedown.prevent
 				>
@@ -323,24 +372,26 @@ function splitTokens(value) {
 			<ul
 				v-if="showMenu"
 				:id="`${field.id.value}-listbox`"
+				ref="list"
 				role="listbox"
+				aria-multiselectable="true"
+				:aria-busy="isLoading"
+				@scroll="paging.onScroll"
 					class="skin-popover absolute z-40 mt-2 max-h-72 w-full overflow-auto rounded-2xl p-1"
 				>
-					<li v-if="hasEmptyState" class="rounded-xl px-3 py-2 text-sm text-muted-fg">
-						{{ emptyText }}
-					</li>
 				<li
 					v-for="(entry, index) in menuItems"
 					:key="`${entry.custom ? 'custom' : 'option'}-${optionKey(entry.value)}`"
 					role="option"
-					:aria-selected="activeIndex === index"
+					:id="`${field.id.value}-option-${index}`"
+					:aria-selected="selectedValueKeys.has(optionKey(entry.value))"
 					class="cursor-pointer rounded-xl px-3 py-2 text-sm transition"
 					:class="activeIndex === index ? 'bg-accent text-accent-fg' : 'hover:bg-accent/70'"
 					@mouseenter="activeIndex = index"
 					@mousedown.prevent
 					@click="commitItem(entry)"
 				>
-					<slot name="item" :item="entry.item" :index="index" :active="activeIndex === index" :custom="entry.custom">
+					<div class="flex items-center gap-3"><span class="min-w-0 flex-1"><slot name="item" :item="entry.item" :index="index" :active="activeIndex === index" :selected="selectedValueKeys.has(optionKey(entry.value))" :query="query" :custom="entry.custom">
 						<div class="flex min-w-0 items-center justify-between gap-3">
 							<span class="min-w-0">
 								<span class="block truncate font-medium">{{ entry.custom ? `Add "${entry.label}"` : entry.label }}</span>
@@ -350,8 +401,9 @@ function splitTokens(value) {
 							</span>
 							<span v-if="entry.custom" class="shrink-0 rounded-full bg-canvas/70 px-2 py-0.5 text-[11px] text-muted-fg ring-1 ring-border">custom</span>
 						</div>
-					</slot>
+					</slot></span><svg v-if="selectedValueKeys.has(optionKey(entry.value))" viewBox="0 0 20 20" class="size-4 shrink-0" fill="none" aria-hidden="true"><path d="M4.5 10.5 8 14l7.5-8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" /></svg></div>
 				</li>
+				<DomOptionStatus as="li" :loading="isLoading" :has-more="hasMoreOptions" :empty="!menuItems.length" :empty-text="emptyText" @load-more="paging.requestMore(true)" />
 			</ul>
 		</div>
 	</DomField>

package/src/pages/lib/headless/autocomplete.js

@@ -15,6 +15,8 @@ export class DomAutocompleteElement extends ComboBase {
 			{ name: 'placement', type: 'string', description: 'Preferred floating placement before collision handling.' },
 			{ name: 'floating-mode', type: "'viewport' | 'anchor'", description: 'viewport keeps suggestions inside the browser; anchor keeps them attached to the input while scrolling.' },
 			{ name: 'data-menu-id', type: 'string', description: 'Id of an external or teleported suggestion list.' },
+			{ name: 'filter-options', type: 'string', description: 'Set false for server-filtered suggestions.' },
+			{ name: 'has-more', type: 'boolean', description: 'Request another page at the loaded keyboard boundary.' },
 		],
 		events: [
 			{ name: 'dom:input', payload: '{ value }', description: 'Fired whenever the text value changes.' },
@@ -22,6 +24,9 @@ export class DomAutocompleteElement extends ComboBase {
 			{ name: 'dom:select', payload: '{ value, label, option }', description: 'Fired when a suggestion is selected.' },
 			{ name: 'dom:custom', payload: '{ value, label }', description: 'Cancelable event fired when Enter commits free text.' },
 			{ name: 'dom:change', payload: '{ value, option, custom }', description: 'Fired when text or a suggestion is committed.' },
+			{ name: 'dom:open', description: 'Fired when suggestions open.' },
+			{ name: 'dom:close', description: 'Fired when suggestions close.' },
+			{ name: 'dom:load-more', payload: '{ query }', description: 'Fired when keyboard navigation reaches the loaded page boundary.' },
 		],
 	};