@getdom/studio 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.2.3 - 2026-09-27
+
+Searchable Google Fonts previews, shared paginated option lists, and more reliable
+selection controls.
+
+### Added
+
+- `DomFontPicker` with searchable family previews, incremental browsing and a
+  lightweight snapshot of 1,946 Google Fonts families. Font files are not bundled;
+  the mounted picker requests only selected and visible preview families, with
+  text subsetting and component-owned stylesheet cleanup.
+- Multiple selection in `DomSelect`, with an array model, checked options and a
+  clear-all action. Selected labels are retained when searches replace remote pages.
+- Shared incremental loading for Select, Combobox, Autocomplete and Tag combobox,
+  using `hasMore` and `load-more` for scroll, keyboard and explicit-button paging.
+  Documentation includes real HTTP examples with retry and stale-request handling.
+- Query and selected-state slot data for custom option rendering, plus a matched-text
+  highlighting example that keeps HTML-like labels as plain text.
+
+### Improved
+
+- Opening a picker shows the loaded choices without treating its committed value
+  as a permanent search filter. Selected checkmarks remain distinct from keyboard
+  navigation, and loaded single selections open in context.
+- Select and Tag combobox documentation explains compact multi-selection versus
+  removable tokens, optional custom entries and paste support, alongside their
+  shared option, field-state and paging foundations.
+- Public TypeScript declarations cover the font picker, multiple selection,
+  retained selected records and paginated option lists.
+
+### Fixed
+
+- Dropdowns reopen reliably while an earlier close animation finishes, and late
+  option updates no longer reopen a dismissed combobox or autocomplete.
+- Selected options remain visible and checked in combobox and tag suggestions.
+  Disabled and read-only controls do not commit selections through their action buttons.
+- Select keeps its arrow at the right edge and centers the clear button to its
+  left. Long selections truncate within narrow containers, and clearing returns
+  keyboard focus to the trigger.
+
+### Upgrade notes
+
+- Single-select models remain scalar values. Use an array model when enabling
+  `multiple`; Tag combobox continues to use an array of selected values.
+- For server-filtered lists, set `filterOptions` to false and handle `query` and
+  `load-more` in the application. Supply `selectedOptions` for initial selected
+  records outside the loaded page. Seeking directly to a later remote page remains
+  application-owned; controls do not fetch or paginate an endpoint themselves.
+- Google Fonts previews need no API key. Applications own loading the selected
+  font for content outside the picker. A live Developer API catalogue should be
+  fetched and cached server-side or at build time, with its key kept out of client code.
+
 ## 0.2.2 - 2026-09-26
 
 More flexible calendar highlights, refined agent chat, and updated website

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@getdom/studio",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"description": "A Vue 3 and Web Component interface system for application UI.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE.md",

package/src/pages/_layout/componentCatalog.generated.js

@@ -3090,8 +3090,8 @@ export const componentCatalog = [
 			"slots": [
 				{
 					"name": "item",
-					"payload": "{ item, index }",
-					"description": "Replaces the rendering of each suggestion."
+					"payload": "{ item, index, selected, query }",
+					"description": "Replaces each suggestion body without replacing the selection checkmark."
 				}
 			],
 			"events": [
@@ -3109,6 +3109,19 @@ export const componentCatalog = [
 					"name": "commit",
 					"payload": "({ value, label, custom })",
 					"description": "Fired when the current text is committed with Enter."
+				},
+				{
+					"name": "load-more",
+					"payload": "{ query }",
+					"description": "Request the next page when hasMore is true."
+				},
+				{
+					"name": "open",
+					"description": "Fired when suggestions open."
+				},
+				{
+					"name": "close",
+					"description": "Fired when suggestions close."
 				}
 			]
 		},
@@ -3308,8 +3321,8 @@ export const componentCatalog = [
 			"slots": [
 				{
 					"name": "item",
-					"payload": "{ item, index }",
-					"description": "Replaces the rendering of each option."
+					"payload": "{ item, index, selected, query }",
+					"description": "Replaces each option body. The control keeps the selected checkmark."
 				}
 			],
 			"events": [
@@ -3322,6 +3335,24 @@ export const componentCatalog = [
 					"name": "select",
 					"payload": "({ item, value, label })",
 					"description": "Fired when an option is selected. item is the original option object."
+				},
+				{
+					"name": "list-scroll",
+					"payload": "(event: Event)",
+					"description": "Fired when the floating option list scrolls."
+				},
+				{
+					"name": "load-more",
+					"payload": "{ query }",
+					"description": "Request the next page when hasMore is true. The parent owns fetching and appending options."
+				},
+				{
+					"name": "open",
+					"description": "Fired when the options open with an empty transient query."
+				},
+				{
+					"name": "close",
+					"description": "Fired when the options close."
 				}
 			]
 		},
@@ -3637,6 +3668,49 @@ export const componentCatalog = [
 		},
 		"studio": {}
 	},
+	{
+		"id": "forms/font-picker",
+		"path": "../forms/font-picker/DomFontPicker.vue",
+		"section": "forms",
+		"slug": "font-picker",
+		"exportName": "DomFontPicker",
+		"route": "/forms/font-picker",
+		"doc": {
+			"name": "Font picker",
+			"tag": "<DomFontPicker>",
+			"description": "Searchable Google Fonts picker that previews only visible families and keeps font network loading inside the mounted control.",
+			"icon": "M5 5h14M12 5v14M8 19h8",
+			"playground": {
+				"initial": {
+					"label": "Font family",
+					"modelValue": "Lato",
+					"placeholder": "Search Google Fonts",
+					"category": "",
+					"pageSize": 24,
+					"previewText": "",
+					"loadFonts": true
+				}
+			},
+			"events": [
+				{
+					"name": "update:modelValue",
+					"payload": "string",
+					"description": "Fired with the selected font value."
+				},
+				{
+					"name": "select",
+					"payload": "{ item, value, label }",
+					"description": "Fired when a font family is selected."
+				},
+				{
+					"name": "query",
+					"payload": "string",
+					"description": "Fired as the user searches the catalog."
+				}
+			]
+		},
+		"studio": {}
+	},
 	{
 		"id": "forms/form",
 		"path": "../forms/form/DomForm.vue",
@@ -4053,13 +4127,13 @@ export const componentCatalog = [
 			"slots": [
 				{
 					"name": "value",
-					"payload": "{ option, value, label, placeholder }",
-					"description": "Custom selected-value markup inside the trigger."
+					"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, optionId }",
-					"description": "Custom option markup inside the floating list. optionId identifies the focusable option button for external floating UI."
+					"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",
@@ -4070,13 +4144,36 @@ export const componentCatalog = [
 			"events": [
 				{
 					"name": "update:modelValue",
-					"payload": "(value: string)",
-					"description": "Emitted when the selected option changes."
+					"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": [
@@ -4129,8 +4226,8 @@ export const componentCatalog = [
 			"slots": [
 				{
 					"name": "item",
-					"payload": "{ item, index, active, custom }",
-					"description": "Replaces each suggestion row."
+					"payload": "{ item, index, active, selected, query, custom }",
+					"description": "Replaces each suggestion row while retaining the selected checkmark."
 				},
 				{
 					"name": "tag",
@@ -4163,6 +4260,11 @@ export const componentCatalog = [
 					"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."
 				}
 			]
 		},

package/src/pages/forms/_shared/DomOptionStatus.vue

@@ -0,0 +1,18 @@
+<script setup>
+defineProps({
+	as: { type: String, default: 'div' },
+	loading: Boolean,
+	hasMore: Boolean,
+	empty: Boolean,
+	emptyText: { type: String, default: 'No options found' },
+});
+defineEmits(['load-more']);
+</script>
+
+<template>
+	<component :is="as" v-if="loading || hasMore || empty" role="presentation" class="px-3 py-3 text-center text-sm text-muted-fg">
+		<span v-if="loading" role="status">Loading options…</span>
+		<button v-else-if="hasMore" type="button" class="rounded-lg px-3 py-1 underline underline-offset-4 focus-visible:ring-2 focus-visible:ring-ring" @mousedown.prevent @click.stop="$emit('load-more')">Load more options</button>
+		<span v-else role="status">{{ emptyText }}</span>
+	</component>
+</template>

package/src/pages/forms/_shared/useOptionMenu.js

@@ -1,5 +1,6 @@
-import { computed, ref, watch } from 'vue';
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
 
+/** Manage transient token-query navigation independently from committed selections. */
 export function useOptionMenu(items, options = {}) {
 	const {
 		emitQuery,
@@ -11,6 +12,9 @@ export function useOptionMenu(items, options = {}) {
 	const isOpen = ref(false);
 	const activeIndex = ref(0);
 	const trimmedQuery = computed(() => query.value.trim());
+	let closeTimer = null;
+	onBeforeUnmount(() => clearTimeout(closeTimer));
+	watch(isOpen, (open) => { if (open) clearTimeout(closeTimer); });
 
 	watch(query, (value) => {
 		emitQuery?.(value);
@@ -24,28 +28,39 @@ export function useOptionMenu(items, options = {}) {
 		}
 	});
 
+	/** Wrap keyboard navigation within the currently available entries. */
 	function wrapIndex(index) {
 		if (!items.value.length) return 0;
 		return (index + items.value.length) % items.value.length;
 	}
 
+	/** Open the menu and move its active descendant by one step. */
 	function move(delta) {
 		isOpen.value = true;
 		activeIndex.value = wrapIndex(activeIndex.value + delta);
 	}
 
+	/** Reset transient input without changing any committed tokens. */
 	function reset() {
+		clearTimeout(closeTimer);
 		query.value = '';
 		isOpen.value = false;
 		activeIndex.value = 0;
 	}
 
+	/** Defer blur closure to allow a pointer-driven option click to commit. */
 	function closeSoon() {
-		window.setTimeout(() => {
+		clearTimeout(closeTimer);
+		closeTimer = window.setTimeout(() => {
 			isOpen.value = false;
 		}, closeDelay);
 	}
 
+	/** Cancel an outstanding blur when focus immediately returns to the input. */
+	function cancelClose() {
+		clearTimeout(closeTimer);
+	}
+
 	return {
 		query,
 		isOpen,
@@ -55,5 +70,6 @@ export function useOptionMenu(items, options = {}) {
 		move,
 		reset,
 		closeSoon,
+		cancelClose,
 	};
 }

package/src/pages/forms/_shared/useOptionPaging.js

@@ -0,0 +1,42 @@
+import { nextTick, watch } from 'vue';
+import { booleanProp } from './options.js';
+
+/**
+ * Share incremental-list requests without owning the application's cursor or fetch.
+ * One automatic request is allowed per query/result length; the explicit button
+ * can retry a failed page. Checking after render also fills short scroll viewports.
+ *
+ * @param {Object} props Reactive loading and hasMore props.
+ * @param {Function} emit Component event emitter.
+ * @param {Object} state Refs for list, options, query and open state.
+ * @returns {{ onScroll: Function, requestMore: Function }} Paging event handlers.
+ */
+export function useOptionPaging(props, emit, { list, options, query, open }) {
+	let requestedKey = null;
+
+	/** Request the next application-owned page, suppressing duplicate automatic requests. */
+	function requestMore(force = false) {
+		if (!open.value || booleanProp(props.loading) || !booleanProp(props.hasMore)) return;
+		const key = `${query.value}\u0000${options.value.length}`;
+		if (!force && requestedKey === key) return;
+		requestedKey = key;
+		emit('load-more', { query: query.value });
+	}
+
+	/** Ask for another page only while the open list is near its scroll boundary. */
+	function checkBoundary() {
+		const element = list.value;
+		if (!element || element.clientHeight <= 0) return;
+		if (element.scrollHeight - element.scrollTop - element.clientHeight <= 64) requestMore();
+	}
+
+	/** Forward scroll details for custom previews, then check the shared paging threshold. */
+	function onScroll(event) {
+		emit('list-scroll', event);
+		checkBoundary();
+	}
+
+	watch(query, () => { requestedKey = null; });
+	watch([open, () => props.loading, () => props.hasMore, () => options.value.length], () => nextTick(checkBoundary));
+	return { onScroll, requestMore };
+}

package/src/pages/forms/_shared/useSelectedOptions.js

@@ -0,0 +1,25 @@
+import { computed, shallowRef, watch } from 'vue';
+import { normalizeOption } from './options.js';
+
+/**
+ * Retain only selected records when a remote query replaces the current page.
+ * Applications can supply selectedOptions for initial values outside loaded pages;
+ * this does not insert, reorder or seek options in the application's result set.
+ *
+ * @param {import('vue').ComputedRef<Array>} options Current normalized page records.
+ * @param {import('vue').ComputedRef<Array>} values Committed selected values.
+ * @param {Function} supplied Getter for optional externally resolved selected records.
+ * @returns {import('vue').ComputedRef<Array>} Resolved selections in model order.
+ */
+export function useSelectedOptions(options, values, supplied = () => []) {
+	const cache = shallowRef(new Map());
+	watch([options, values, supplied], () => {
+		const records = new Map(cache.value);
+		for (const row of [...supplied(), ...options.value]) {
+			const option = normalizeOption(row, { allowEmptyValue: true });
+			if (option) records.set(String(option.value), option);
+		}
+		cache.value = new Map(values.value.map((value) => [String(value), records.get(String(value))]));
+	}, { immediate: true, flush: 'sync' });
+	return computed(() => values.value.map((value) => cache.value.get(String(value)) || { value, label: String(value ?? '') }));
+}

package/src/pages/forms/autocomplete/DomAutocomplete.vue

@@ -1,8 +1,10 @@
 <script setup>
-import { computed, onMounted, ref, shallowRef, useId, watch } from 'vue';
+import { computed, nextTick, onMounted, ref, shallowRef, useId, watch } from 'vue';
 import { resolveFloatingTeleportTarget } from '../../lib/vue/floatingTeleportTarget.js';
 import DomFieldLoadingSpinner from '../_shared/DomFieldLoadingSpinner.vue';
-import { booleanProp, normalizeOption } from '../_shared/options.js';
+import { booleanProp, normalizeOption, searchableText } from '../_shared/options.js';
+import DomOptionStatus from '../_shared/DomOptionStatus.vue';
+import { useOptionPaging } from '../_shared/useOptionPaging.js';
 import DomField from '../field/DomField.vue';
 import { fieldProps } from '../field/fieldProps.js';
 import { useField } from '../field/useField.js';
@@ -15,12 +17,15 @@ defineOptions({
 		tag: '<DomAutocomplete>',
 		description: 'Free-text autocomplete with optional suggestions, floating positioning, keyboard navigation, and query events for async lookups.',
 		slots: [
-			{ name: 'item', payload: '{ item, index }', description: 'Replaces the rendering of each suggestion.' },
+			{ name: 'item', payload: '{ item, index, selected, query }', description: 'Replaces each suggestion body without replacing the selection checkmark.' },
 		],
 		events: [
 			{ name: 'query', payload: '(query: string)', description: 'Fired as the user types. Use it to fetch or replace suggestions.' },
 			{ name: 'select', payload: '({ item, value, label, text, query })', description: 'Fired when a suggestion is chosen. item is the original option object.' },
 			{ name: 'commit', payload: '({ value, label, custom })', description: 'Fired when the current text is committed with Enter.' },
+			{ name: 'load-more', payload: '{ query }', description: 'Request the next page when hasMore is true.' },
+			{ name: 'open', description: 'Fired when suggestions open.' },
+			{ name: 'close', description: 'Fired when suggestions close.' },
 		],
 	},
 });
@@ -68,11 +73,16 @@ const props = defineProps({
 		default: false,
 		_edit: { group: 'Control props', description: 'Show an inline spinner while async suggestions are being fetched.' },
 	},
+	filterOptions: { type: [Boolean, String], default: true },
+	hasMore: { type: [Boolean, String], default: false },
 });
-const emit = defineEmits(['update:modelValue', 'query', 'select', 'commit', 'focus', 'blur']);
+const emit = defineEmits(['update:modelValue', 'query', 'select', 'commit', 'load-more', 'list-scroll', 'open', 'close', 'focus', 'blur']);
 
 const root = ref(null);
 const inputEl = ref(null);
+const list = ref(null);
+const query = ref('');
+const isOpen = ref(false);
 const isMounted = ref(false);
 const teleportTarget = shallowRef(null);
 const currentText = ref('');
@@ -80,6 +90,10 @@ const field = useField(props, emit, { idPrefix: 'dom-autocomplete' });
 const isLoading = computed(() => booleanProp(props.loading, false));
 
 const items = computed(() => props.options.map((option) => normalizeOption(option)).filter(Boolean));
+const hasMoreOptions = computed(() => booleanProp(props.hasMore));
+const filterLocally = computed(() => booleanProp(props.filterOptions, true));
+const matchingOptions = computed(() => items.value.filter((option) => !filterLocally.value || searchableText(option, ['label', 'value', 'description', 'group', 'email', 'role']).includes(query.value.trim().toLowerCase())));
+const paging = useOptionPaging(props, emit, { list, options: items, query, open: isOpen });
 
 /**
  * Synchronize the free-text input from the Vue model value.
@@ -94,13 +108,17 @@ function syncInputFromModel() {
 onMounted(async () => {
 	teleportTarget.value = resolveFloatingTeleportTarget(root.value);
 	isMounted.value = true;
+	await nextTick();
 	await import('../../lib/headless/autocomplete.js');
 	syncInputFromModel();
 	root.value?.addEventListener('dom:input', (event) => {
 		currentText.value = event.detail.value;
 		field.onInput(event.detail.value);
 	});
-	root.value?.addEventListener('dom:query', (event) => emit('query', event.detail.query));
+	root.value?.addEventListener('dom:query', (event) => { query.value = event.detail.query; emit('query', event.detail.query); });
+	root.value?.addEventListener('dom:open', () => { isOpen.value = true; emit('open'); });
+	root.value?.addEventListener('dom:close', () => { isOpen.value = false; emit('close'); });
+	root.value?.addEventListener('dom:load-more', () => paging.requestMore());
 	root.value?.addEventListener('dom:select', (event) => {
 		const index = Number(event.detail.option?.dataset.index);
 		const item = Number.isFinite(index) ? items.value[index] : null;
@@ -131,6 +149,8 @@ watch(field.value, syncInputFromModel);
 			:value="field.value.value ?? null"
 			:placement="placement"
 			:floating-mode="floatingMode"
+			:filter-options="String(filterLocally)"
+			:has-more="hasMoreOptions ? '' : null"
 			class="relative block"
 		>
 			<input
@@ -152,7 +172,7 @@ watch(field.value, syncInputFromModel);
 				type="button"
 				class="absolute right-1 top-1 inline-flex size-8 items-center justify-center rounded-md text-muted-fg transition hover:text-canvas-fg focus:outline-none focus-visible:ring-2 focus-visible:ring-ring/60 disabled:cursor-not-allowed disabled:opacity-50"
 				aria-label="Show suggestions"
-				:disabled="props.disabled || props.readOnly || undefined"
+				:disabled="field.disabled.value || field.readOnly.value || undefined"
 			>
 				<svg viewBox="0 0 20 20" class="size-4" fill="none" aria-hidden="true">
 					<path d="M6 8l4 4 4-4" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" />
@@ -161,6 +181,10 @@ watch(field.value, syncInputFromModel);
 			<Teleport :to="teleportTarget || 'body'" :disabled="!isMounted || !teleportTarget">
 				<ul
 					:id="listId"
+					ref="list"
+					hidden
+					:aria-busy="isLoading"
+					@scroll="paging.onScroll"
 					class="dom-floating-transition skin-popover z-50 max-h-[min(15rem,var(--dom-floating-available-height))] overflow-auto rounded-2xl p-1"
 				>
 					<li
@@ -169,10 +193,14 @@ watch(field.value, syncInputFromModel);
 						:data-value="option.value"
 						:data-label="option.label"
 						:data-index="index"
-						class="cursor-pointer rounded-xl px-3 py-2 text-sm text-canvas-fg transition hover:bg-accent hover:text-accent-fg data-[active]:bg-accent data-[active]:text-accent-fg aria-selected:bg-accent aria-selected:text-accent-fg"
+						:data-search="searchableText(option, ['label', 'value', 'description', 'group', 'email', 'role'])"
+						:aria-disabled="option.disabled || undefined"
+						class="flex cursor-pointer items-center gap-3 rounded-xl px-3 py-2 text-sm text-canvas-fg transition hover:bg-accent hover:text-accent-fg data-[active]:bg-accent data-[active]:text-accent-fg aria-selected:bg-accent aria-selected:text-accent-fg aria-disabled:cursor-not-allowed aria-disabled:opacity-50"
 					>
-						<slot name="item" :item="option" :index="index">{{ option.label }}</slot>
+						<span class="min-w-0 flex-1"><slot name="item" :item="option" :index="index" :selected="option.label === field.value.value" :query="query">{{ option.label }}</slot></span>
+						<svg v-if="option.label === field.value.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>
 					</li>
+					<DomOptionStatus as="li" :loading="isLoading" :has-more="hasMoreOptions" :empty="!matchingOptions.length" @load-more="paging.requestMore(true)" />
 				</ul>
 			</Teleport>
 		</dom-autocomplete>