@getdom/studio 0.2.2 → 0.2.3

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

@@ -22,6 +22,7 @@ import {
 
 const OBSERVED = [
 	'value',
+	'value-label',
 	'open',
 	'align',
 	'offset',
@@ -30,24 +31,29 @@ const OBSERVED = [
 	'floating-mode',
 ];
 
+/** Read an option's plain-text label when no explicit label was supplied. */
 function textOf(option) {
 	return option.textContent.trim();
 }
 
+/** Resolve an option's stable committed value. */
 function valueOf(option) {
 	return option.dataset.value ?? option.getAttribute('value') ?? option.value ?? textOf(option);
 }
 
+/** Resolve display text independently of rich option markup. */
 function labelOf(option) {
 	return option.dataset.label ?? option.getAttribute('label') ?? textOf(option);
 }
 
+/** Match literal search text without interpreting HTML or regular expressions. */
 function matchesOption(option, query) {
 	if (!query) return true;
-	const haystack = `${option.dataset.value || ''} ${option.dataset.label || ''} ${option.textContent}`.toLowerCase();
+	const haystack = (option.dataset.search ?? `${option.dataset.value || ''} ${option.dataset.label || ''} ${option.textContent}`).toLowerCase();
 	return haystack.includes(query);
 }
 
+/** Dispatch a cancelable custom-value request before committing free text. */
 function dispatchCancelable(host, type, detail) {
 	const event = new CustomEvent(type, {
 		detail,
@@ -102,11 +108,14 @@ function hideListPopover(list) {
 export class ComboBase extends DomElementBase {
 	static get observedAttributes() { return OBSERVED; }
 
+	/** Initialize committed-selection, transient-query and owned listener state. */
 	constructor() {
 		super();
 		this._active = -1;
 		this._open = false;
 		this._options = [];
+		this._query = '';
+		this._selection = null;
 		this._unbindFloating = null;
 		this._mutationObserver = null;
 		this._wiredList = null;
@@ -120,6 +129,7 @@ export class ComboBase extends DomElementBase {
 	get _valueMode() { return 'option'; }
 	get _activeOnFilter() { return true; }
 
+	/** Read the shared floating placement contract from host attributes. */
 	_positionOpts() {
 		return {
 			align: this.getAttribute('align') || 'left',
@@ -130,6 +140,7 @@ export class ComboBase extends DomElementBase {
 		};
 	}
 
+	/** Wire the input and optional external list after the custom element connects. */
 	connectedCallback() {
 		this._input = this.querySelector('[slot="input"], [data-input]');
 		this._toggle = this.querySelector('[slot="toggle"], [data-toggle]');
@@ -149,12 +160,18 @@ export class ComboBase extends DomElementBase {
 		if (this._list) this._wireList();
 
 		this.on(this._input, 'input', () => this._handleInput());
-		this.on(this._input, 'focus', () => this._filter(this._input.value, { open: true }));
+		this.on(this._input, 'focus', () => {
+			if (!this._open) this._filter('', { open: true, preferSelected: true });
+		});
+		this.on(this._input, 'click', () => {
+			if (!this._open) this._filter('', { open: true, preferSelected: true });
+		});
 		this.on(this._input, 'keydown', (e) => this._onKey(e));
 		if (this.hasAttribute('value')) this._syncInputFromValue();
 		if (this.hasAttribute('open')) this._setOpen(true);
 	}
 
+	/** Release document listeners, observers, floating effects and list ownership. */
 	disconnectedCallback() {
 		this._setOpen(false);
 		clearFloatingEffectTimer(this._list);
@@ -163,11 +180,14 @@ export class ComboBase extends DomElementBase {
 		this._mutationObserver = null;
 		this._wiredList?.removeEventListener('mousedown', this._onListPointerDown);
 		this._wiredList?.removeEventListener('mousemove', this._onListPointerMove);
+		if (this._wiredList?.__elementComboOwner === this) delete this._wiredList.__elementComboOwner;
 		this._wiredList = null;
+		this._list = null;
 		super.disconnectedCallback();
 		document.removeEventListener('mousedown', this._onDocDown);
 	}
 
+	/** Resolve either a slotted list or its application-provided teleported target. */
 	_resolveList() {
 		const inner = this.querySelector('[slot="list"], [data-list]');
 		if (inner) return inner;
@@ -175,6 +195,7 @@ export class ComboBase extends DomElementBase {
 		return id ? document.getElementById(id) : null;
 	}
 
+	/** Reconnect the list after a framework replaces or teleports its element. */
 	_ensureList() {
 		if (!this._list || !this._list.isConnected) {
 			this._list = this._resolveList();
@@ -183,6 +204,7 @@ export class ComboBase extends DomElementBase {
 		return this._list;
 	}
 
+	/** Own one list's pointer events and observe async option changes without reopening it. */
 	_wireList() {
 		if (!this._list || this._list.__elementComboOwner === this) return;
 		const id = uid('cmb');
@@ -202,27 +224,46 @@ export class ComboBase extends DomElementBase {
 		this._list.addEventListener('mousemove', this._onListPointerMove);
 		this._mutationObserver?.disconnect();
 		this._mutationObserver = new MutationObserver(() => {
-			this._refreshOptions();
-			if (this._open || document.activeElement === this._input) {
-				this._filter(this._input.value, { open: true, emitQuery: false });
+			if (this._open) {
+				this._filter(this._query, { open: true, emitQuery: false, preserveActive: true });
 				this._positionList();
-			}
+			} else this._refreshOptions();
+		});
+		this._mutationObserver.observe(this._list, {
+			childList: true,
+			subtree: true,
+			characterData: true,
+			attributes: true,
+			attributeFilter: ['data-value', 'data-label', 'data-search', 'aria-disabled', 'disabled'],
 		});
-		this._mutationObserver.observe(this._list, { childList: true, subtree: true, characterData: true });
 		this._refreshOptions();
 		this._syncInputFromValue();
 	}
 
+	/** Refresh selectable rows while keeping status and paging controls out of navigation. */
 	_refreshOptions() {
 		if (!this._list) return;
 		const id = this._list.id || uid('cmb-list');
-		this._options = Array.from(this._list.children).filter((option) => !option.hasAttribute('data-disabled'));
+		this._options = Array.from(this._list.children).filter((option) => option.hasAttribute('data-value'));
 		this._options.forEach((option, index) => {
 			option.setAttribute('role', 'option');
 			option.id = option.id || `${id}-opt-${index}`;
+			option.setAttribute('aria-selected', String(this._isSelected(option)));
 		});
 	}
 
+	/** Test committed selection independently from the keyboard-active row. */
+	_isSelected(option) {
+		if (this._valueMode === 'text') return labelOf(option) === this.value && Boolean(this.value);
+		return String(valueOf(option)) === this.value;
+	}
+
+	/** Keep disabled rows visible but exclude them from navigation and commitment. */
+	_isDisabled(option) {
+		return option.hasAttribute('disabled') || option.hasAttribute('data-disabled') || option.getAttribute('aria-disabled') === 'true';
+	}
+
+	/** Emit intentional typing separately from the committed option value. */
 	_handleInput() {
 		const value = this._input.value;
 		this.emit('dom:input', { value });
@@ -230,24 +271,29 @@ export class ComboBase extends DomElementBase {
 		if (this._freeText) this.setAttribute('value', value);
 	}
 
+	/** Restore the committed label, including a selection outside the current page. */
 	_syncInputFromValue() {
 		if (!this._input || !this.hasAttribute('value')) return;
 		const value = this.getAttribute('value') || '';
+		this._refreshOptions();
 		if (this._valueMode === 'text') {
 			if (this._input.value !== value) this._input.value = value;
 			return;
 		}
 		const selected = this._options.find((option) => valueOf(option) === value);
-		const display = selected ? labelOf(selected) : value;
+		if (selected) this._selection = { value, label: labelOf(selected) };
+		const display = selected ? labelOf(selected) : this.getAttribute('value-label') ?? (this._selection?.value === value ? this._selection.label : value);
 		if (this._input.value !== display) this._input.value = display;
 	}
 
+	/** Close only when pointer interaction is outside both the host and its popup. */
 	_onDocDown(e) {
 		if (this.contains(e.target)) return;
 		if (this._list && this._list.contains(e.target)) return;
 		this._setOpen(false);
 	}
 
+	/** Size and position the floating list relative to its input. */
 	_positionList() {
 		if (!this._input || !this._list || this._list.hidden) return;
 		const rect = this._input.getBoundingClientRect();
@@ -255,16 +301,19 @@ export class ComboBase extends DomElementBase {
 		applyFloatingPosition(this._input, this._list, this._positionOpts());
 	}
 
+	/** Track viewport, content and anchor changes while the popup is open. */
 	_bindFloating() {
 		this._unbindFloating?.();
 		this._unbindFloating = autoUpdateFloating(this._input, this._list, () => this._positionList());
 	}
 
+	/** Stop all floating-position observers owned by this control. */
 	_unbindFloating() {
 		this._unbindFloating?.();
 		this._unbindFloating = null;
 	}
 
+	/** Hide the native popover and clear its completed animation state. */
 	_finishListClose(list = this._list) {
 		if (!list) return;
 		hideListPopover(list);
@@ -272,6 +321,7 @@ export class ComboBase extends DomElementBase {
 		resetFloatingEffectState(list);
 	}
 
+	/** Promote the list to the top layer and start the shared enter effect. */
 	_showList() {
 		const list = this._list;
 		list.hidden = false;
@@ -282,6 +332,7 @@ export class ComboBase extends DomElementBase {
 		});
 	}
 
+	/** Run the leave effect without allowing a stale close to hide a reopened list. */
 	_hideList() {
 		const list = this._list;
 		beginFloatingEffectLeave(list, {
@@ -290,8 +341,11 @@ export class ComboBase extends DomElementBase {
 		});
 	}
 
+	/** Synchronize logical state, ARIA, listeners and lifecycle events exactly once. */
 	_setOpen(open) {
 		if (!this._ensureList()) return;
+		if (open && (this._input.disabled || this._input.readOnly)) return;
+		const changed = open !== this._open;
 		if (open === this._open && this._list.hidden === !open) {
 			if (open) this._positionList();
 			return;
@@ -310,72 +364,104 @@ export class ComboBase extends DomElementBase {
 		} else {
 			this._unbindFloating();
 			this._setActive(-1);
+			this._query = '';
+			if (!this._freeText) this._syncInputFromValue();
 			document.removeEventListener('mousedown', this._onDocDown);
 		}
+		if (changed) this.emit(open ? 'dom:open' : 'dom:close');
 	}
 
-	_filter(value, { open = true, emitQuery = true } = {}) {
+	/** Filter transient input only; selection labels never become a reopening query. */
+	_filter(value, { open = true, emitQuery = true, preserveActive = false, preferSelected = false } = {}) {
+		this._query = value;
 		if (!this._ensureList()) {
 			if (emitQuery) this.emit('dom:query', { query: value });
 			return;
 		}
 		if (emitQuery) this.emit('dom:query', { query: value });
 
+		const activeOption = preserveActive ? this._options[this._active] : null;
 		this._refreshOptions();
 		const query = value.trim().toLowerCase();
 		let firstVisible = -1;
 
 		this._options.forEach((option, index) => {
-			const match = matchesOption(option, query);
+			const match = this.getAttribute('filter-options') === 'false' || matchesOption(option, query);
 			option.hidden = !match;
-			if (match && firstVisible === -1) firstVisible = index;
+			if (match && !this._isDisabled(option) && firstVisible === -1) firstVisible = index;
 		});
 
 		this._list.toggleAttribute('data-empty', firstVisible < 0);
-		this._setOpen(open && firstVisible >= 0);
-		this._setActive(this._activeOnFilter ? firstVisible : -1);
+		this._setOpen(open);
+		const selected = preferSelected ? this._options.findIndex((option) => !option.hidden && !this._isDisabled(option) && this._isSelected(option)) : -1;
+		const previous = activeOption && !activeOption.hidden ? this._options.indexOf(activeOption) : -1;
+		this._setActive(previous >= 0 ? previous : selected >= 0 ? selected : this._activeOnFilter ? firstVisible : -1);
+		if (preferSelected && selected >= 0) this._scrollActive();
+		else if (!preserveActive && this._list) this._list.scrollTop = 0;
 		this._positionList();
 	}
 
+	/** Mark navigation without changing aria-selected, which describes commitment. */
 	_setActive(index) {
 		this._active = index;
 		this._options.forEach((option, optionIndex) => {
 			const active = optionIndex === index;
 			option.toggleAttribute('data-active', active);
-			option.setAttribute('aria-selected', String(active));
+			option.setAttribute('aria-selected', String(this._isSelected(option)));
 		});
 		if (index >= 0 && this._options[index]) this._input.setAttribute('aria-activedescendant', this._options[index].id);
 		else this._input.removeAttribute('aria-activedescendant');
 	}
 
+	/** Scroll within the list only, without moving the containing page. */
+	_scrollActive() {
+		const option = this._options[this._active];
+		if (!option || !this._list) return;
+		const row = option.getBoundingClientRect();
+		const list = this._list.getBoundingClientRect();
+		const scale = list.height / this._list.offsetHeight || 1;
+		if (row.top < list.top) this._list.scrollTop += (row.top - list.top) / scale;
+		else if (row.bottom > list.bottom) this._list.scrollTop += (row.bottom - list.bottom) / scale;
+	}
+
+	/** Return enabled visible rows with their stable positions in the rendered list. */
 	_visible() {
 		this._refreshOptions();
 		return this._options
 			.map((option, index) => ({ option, index }))
-			.filter(({ option }) => !option.hidden);
+			.filter(({ option }) => !option.hidden && !this._isDisabled(option));
 	}
 
+	/** Move the active descendant, scrolling it into view or requesting another page. */
 	_move(delta) {
 		const visible = this._visible();
 		if (!visible.length) return;
 		const current = visible.findIndex(({ index }) => index === this._active);
+		if (delta > 0 && current === visible.length - 1 && this.hasAttribute('has-more')) {
+			this.emit('dom:load-more', { query: this._query });
+			return;
+		}
 		if (current === -1) {
 			this._setActive(delta > 0 ? visible[0].index : visible[visible.length - 1].index);
+			this._scrollActive();
 			return;
 		}
 		const next = visible[(current + delta + visible.length) % visible.length];
 		this._setActive(next.index);
+		this._scrollActive();
 	}
 
+	/** Handle selection, free-text commitment, dismissal and paginated navigation. */
 	_onKey(e) {
+		if (this._input.disabled || this._input.readOnly || e.isComposing) return;
 		if (e.key === 'ArrowDown') {
 			e.preventDefault();
-			if (!this._open) this._filter(this._input.value, { open: true });
-			this._move(1);
+			if (!this._open) this._filter('', { open: true, preferSelected: true });
+			else this._move(1);
 		} else if (e.key === 'ArrowUp') {
 			e.preventDefault();
-			if (!this._open) this._filter(this._input.value, { open: true });
-			this._move(-1);
+			if (!this._open) this._filter('', { open: true, preferSelected: true });
+			else this._move(-1);
 		} else if (e.key === 'Enter') {
 			if (this._active >= 0) {
 				e.preventDefault();
@@ -387,33 +473,41 @@ export class ComboBase extends DomElementBase {
 		} else if (e.key === 'Escape') {
 			e.preventDefault();
 			this._setOpen(false);
+			if (!this._freeText) this._syncInputFromValue();
+		} else if (e.key === 'Tab') {
+			this._setOpen(false);
 		}
 	}
 
+	/** Commit only an enabled option while keeping focus on the input. */
 	_onListPointerDown(e) {
 		const option = e.target.closest?.('[role="option"]');
-		if (!option || !this._list.contains(option) || option.hidden) return;
+		if (!option || !this._list.contains(option) || option.hidden || this._isDisabled(option)) return;
 		e.preventDefault();
 		this._commit(option);
 	}
 
+	/** Update pointer activity independently of committed selection. */
 	_onListPointerMove(e) {
 		const option = e.target.closest?.('[role="option"]');
-		if (!option || !this._list.contains(option) || option.hidden) return;
+		if (!option || !this._list.contains(option) || option.hidden || this._isDisabled(option)) return;
 		const index = this._options.indexOf(option);
 		if (index >= 0) this._setActive(index);
 	}
 
+	/** Toggle from committed state without using its display label as a search query. */
 	_toggleList() {
+		if (this._input.disabled || this._input.readOnly) return;
 		if (!this._ensureList()) return;
 		const wasOpen = this._open;
 		this._input.focus();
 		if (wasOpen) this._setOpen(false);
-		else this._filter('', { open: true });
+		else if (!this._open) this._filter('', { open: true, preferSelected: true });
 	}
 
+	/** Commit one enabled option, clear transient query state and notify consumers. */
 	_commit(option) {
-		if (!option) return;
+		if (!option || this._isDisabled(option) || this._input.disabled || this._input.readOnly) return;
 		const value = valueOf(option);
 		const detail = {
 			value,
@@ -423,6 +517,8 @@ export class ComboBase extends DomElementBase {
 		};
 		const inputValue = this._valueMode === 'text' ? detail.label : detail.label;
 		const hostValue = this._valueMode === 'text' ? detail.label : value;
+		this._selection = { value: hostValue, label: detail.label };
+		this._query = '';
 
 		this._input.value = inputValue;
 		this.setAttribute('value', hostValue);
@@ -431,6 +527,7 @@ export class ComboBase extends DomElementBase {
 		this.emit('dom:change', detail);
 	}
 
+	/** Commit permitted free text after a cancelable application validation event. */
 	_commitCustom(rawValue) {
 		const value = rawValue.trim();
 		if (!value) return;
@@ -443,9 +540,10 @@ export class ComboBase extends DomElementBase {
 		this.emit('dom:change', detail);
 	}
 
+	/** Apply external value, open-state and floating-placement updates. */
 	attributeChangedCallback(name, _old, value) {
 		if (!this.isConnected || !this._input) return;
-		if (name === 'value') this._syncInputFromValue();
+		if (name === 'value' || (name === 'value-label' && !this._open)) this._syncInputFromValue();
 		if (name === 'open') this._setOpen(value !== null);
 		if (['align', 'offset', 'placement', 'collision-padding', 'floating-mode'].includes(name) && this._open) this._positionList();
 	}
@@ -469,12 +567,18 @@ export class DomComboboxElement extends ComboBase {
 			{ name: 'placement', type: 'string', description: 'Preferred floating placement before collision handling.' },
 			{ name: 'floating-mode', type: "'viewport' | 'anchor'", description: 'viewport keeps the list inside the browser; anchor keeps it attached to the input while scrolling.' },
 			{ name: 'data-menu-id', type: 'string', description: 'Id of an external or teleported list element.' },
+			{ name: 'filter-options', type: 'string', description: 'Set false for server-filtered results. Query events still fire.' },
+			{ name: 'has-more', type: 'boolean', description: 'Request another application-owned page when navigating beyond the loaded options.' },
+			{ name: 'value-label', type: 'string', description: 'Resolved label for a committed value outside the current page.' },
 		],
 		events: [
 			{ name: 'dom:input', payload: '{ value }', description: 'Fired whenever the text value changes.' },
 			{ name: 'dom:query', payload: '{ query }', description: 'Fired whenever the user types. Useful for server lookups.' },
 			{ name: 'dom:select', payload: '{ value, label, option }', description: 'Fired when an option is selected.' },
 			{ name: 'dom:change', payload: '{ value, option, custom }', description: 'Fired when an option is committed.' },
+			{ name: 'dom:open', description: 'Fired when the list opens, including an empty/loading list.' },
+			{ name: 'dom:close', description: 'Fired when the list closes. Later option updates do not reopen it.' },
+			{ name: 'dom:load-more', payload: '{ query }', description: 'Fired at the loaded keyboard boundary when has-more is set.' },
 		],
 		keyboard: [
 			{ keys: '↑ / ↓', action: 'Move active option.' },

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

@@ -130,7 +130,7 @@ export class DomDropdownElement extends DomElementBase {
 			if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' || e.key === ' ') {
 				e.preventDefault();
 				const position = e.key === 'ArrowUp' ? 'last' : 'preferred';
-				if (this._open || isPopoverOpen(this._menu)) {
+				if (this._open) {
 					this._focusMenuStart(position, true);
 					return;
 				}
@@ -363,9 +363,10 @@ export class DomDropdownElement extends DomElementBase {
 		this._syncOpen(next, false);
 	}
 
+	/** Toggle logical state, including while a previous close animation is finishing. */
 	toggle() {
 		if (!this._ensureMenu()) return;
-		this._syncOpen(!isPopoverOpen(this._menu), false);
+		this._syncOpen(!this._open, false);
 	}
 
 	_select(el, ev) {

package/src/pages/lib/headless/listbox.d.ts

@@ -5,6 +5,7 @@ export declare class DomListboxElement extends DomElementBase {
 	static readonly observedAttributes?: Array<string>;
 	static readonly __doc?: HeadlessElementDoc;
 	value: string;
+	readonly values: Array<string>;
 	readonly options: Array<HTMLElement>;
 }
 export interface HeadlessElementDoc {

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

@@ -1,11 +1,12 @@
 import { DomElementBase, createRoving, defineDomElement } from './base.js';
 
+/** Resolve a listbox row's stable value, independent of its rich rendering. */
 function valueOf(option) {
 	return option.dataset.value ?? option.textContent.trim();
 }
 
 export class DomListboxElement extends DomElementBase {
-	static get observedAttributes() { return ['value', 'orientation']; }
+	static get observedAttributes() { return ['value', 'orientation', 'multiple']; }
 
 	static __doc = {
 		name: 'dom-listbox',
@@ -14,10 +15,13 @@ export class DomListboxElement extends DomElementBase {
 		attributes: [
 			{ name: 'value', type: 'string', description: 'Selected option value.' },
 			{ name: 'orientation', type: "'vertical' | 'horizontal'", description: 'Arrow-key direction. Defaults to vertical.' },
+			{ name: 'multiple', type: 'boolean', description: 'Toggle multiple choices. value is then a JSON array; values returns the parsed selected strings.' },
+			{ name: 'has-more', type: 'boolean', description: 'Emit dom:load-more instead of wrapping beyond the final loaded option.' },
 		],
 		events: [
 			{ name: 'dom:change', payload: '{ value, option }', description: 'Fired when selection changes.' },
 			{ name: 'dom:select', payload: '{ value, option }', description: 'Fired when an option is selected.' },
+			{ name: 'dom:load-more', description: 'Fired when ArrowDown reaches the last loaded option and has-more is set.' },
 		],
 		keyboard: [
 			{ keys: '↑ / ↓', action: 'Move active option.' },
@@ -26,6 +30,7 @@ export class DomListboxElement extends DomElementBase {
 		],
 	};
 
+	/** Initialize roving navigation and coalesced option refresh state. */
 	constructor() {
 		super();
 		this._roving = null;
@@ -36,6 +41,7 @@ export class DomListboxElement extends DomElementBase {
 		this._scheduleRefresh = this._scheduleRefresh.bind(this);
 	}
 
+	/** Observe dynamic option pages and attach list-level keyboard and pointer handlers. */
 	connectedCallback() {
 		this.setAttribute('role', this.getAttribute('role') || 'listbox');
 		this._refresh();
@@ -50,6 +56,7 @@ export class DomListboxElement extends DomElementBase {
 		});
 	}
 
+	/** Refresh selection and navigation when the public host state changes. */
 	attributeChangedCallback() {
 		this._refresh();
 	}
@@ -60,11 +67,23 @@ export class DomListboxElement extends DomElementBase {
 		else this.setAttribute('value', value);
 	}
 
+	/** Read selected values; multiple lists serialize the value attribute as JSON. */
+	get values() {
+		if (!this.hasAttribute('multiple')) return [this.value];
+		try {
+			const values = JSON.parse(this.value || '[]');
+			return Array.isArray(values) ? values.map(String) : [];
+		} catch {
+			return [];
+		}
+	}
+
 	get options() {
 		return Array.from(this.querySelectorAll('[role="option"]'))
 			.filter((option) => !option.hasAttribute('disabled') && option.getAttribute('aria-disabled') !== 'true');
 	}
 
+	/** Coalesce option mutations into one animation-frame navigation refresh. */
 	_scheduleRefresh() {
 		if (this._refreshFrame) return;
 		this._refreshFrame = requestAnimationFrame(() => {
@@ -73,37 +92,53 @@ export class DomListboxElement extends DomElementBase {
 		});
 	}
 
+	/** Preserve focused rows across page appends and expose committed ARIA selection. */
 	_refresh() {
 		const options = this.options;
 		const orientation = this.getAttribute('orientation') || 'vertical';
 		const focused = options.findIndex((option) => option === document.activeElement || option.contains(document.activeElement));
-		const selected = options.findIndex((option) => valueOf(option) === this.value);
+		const values = new Set(this.values);
+		const selected = options.findIndex((option) => values.has(valueOf(option)));
 		const active = focused >= 0 ? focused : Math.max(0, selected);
 		this.setAttribute('aria-orientation', orientation);
+		this.setAttribute('aria-multiselectable', String(this.hasAttribute('multiple')));
 		options.forEach((option, index) => {
 			option.tabIndex = index === active ? 0 : -1;
-			option.setAttribute('aria-selected', String(valueOf(option) === this.value));
+			option.setAttribute('aria-selected', String(values.has(valueOf(option))));
 		});
 		this._roving = createRoving({ items: options, orientation, loop: true });
 		this._roving.setActive(active, { focus: false, select: false });
 	}
 
+	/** Commit or toggle an enabled option while preserving multi-selection values. */
 	_select(option, event) {
+		if (!this.options.includes(option)) return;
 		const value = valueOf(option);
 		const changed = value !== this.value;
-		this.value = value;
+		if (this.hasAttribute('multiple')) {
+			const values = this.values;
+			this.value = JSON.stringify(values.includes(value) ? values.filter((item) => item !== value) : [...values, value]);
+		} else this.value = value;
 		this._refresh();
-		this.emit('dom:select', { value, option, event });
+		this.emit('dom:select', { value, values: this.values, option, event });
 		if (changed) this.emit('dom:change', { value, option, event });
 	}
 
+	/** Route clicks from rich option descendants to the containing selectable row. */
 	_onClick(event) {
 		const option = event.target.closest('[role="option"]');
 		if (!option || !this.contains(option)) return;
 		this._select(option, event);
 	}
 
+	/** Navigate enabled options and request more at a paginated keyboard boundary. */
 	_onKey(event) {
+		const options = this.options;
+		if (event.key === 'ArrowDown' && document.activeElement === options.at(-1) && this.hasAttribute('has-more')) {
+			event.preventDefault();
+			this.emit('dom:load-more');
+			return;
+		}
 		this._roving?.onKey(event);
 		if (event.key !== 'Enter' && event.key !== ' ') return;
 		const option = document.activeElement?.closest?.('[role="option"]');
@@ -112,6 +147,7 @@ export class DomListboxElement extends DomElementBase {
 		this._select(option, event);
 	}
 
+	/** Release the option observer, pending frame and registered event handlers. */
 	disconnectedCallback() {
 		this._observer?.disconnect();
 		this._observer = null;