@getdom/studio 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.2.4 - 2026-10-08
+
+Reliable chart hover values and optional sparkline tooltips.
+
+### Added
+
+- Opt-in sparkline tooltips with `tooltip`, showing the inspected label and
+  formatted series values on hover or keyboard navigation. The floating panel
+  stays outside the compact plot and escapes scrolling-table clipping.
+- Website privacy policy and terms pages, linked from checkout and the footer.
+
+### Improved
+
+- Documentation explains how component source, runnable examples and reference
+  pages live together, and how that structure supports human and AI development.
+
+### Fixed
+
+- Line and area chart tooltips update as the pointer moves between data points,
+  without requiring a click. Clicking preserves and selects the hovered record.
+- Shared chart bindings forward Unovis configuration using its expected names,
+  including crosshair callbacks and stacked-series inspection.
+- Chart values dismiss when the crosshair leaves the plot.
+- Website licence checkout no longer depends on email delivery being configured.
+  Existing installations receive a repair migration for missing licence columns.
+
+### Upgrade notes
+
+- Sparkline tooltips remain off by default. Add `tooltip` to `DomSparkline` to
+  enable them; existing value and label formatters also apply to the tooltip.
+- Email-based licence claiming and recovery still require a configured sender.
+
+## 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.4",
 	"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/charts/_shared/CompactChartTooltip.vue

@@ -0,0 +1,39 @@
+<script setup>
+import { onBeforeUnmount, onMounted, ref } from 'vue';
+import { applyFloatingPosition, autoUpdateFloating } from '../../lib/headless/floating.js';
+import ChartTooltip from './ChartTooltip.vue';
+
+const props = defineProps({
+	anchor: { type: Object, required: true },
+	label: { type: String, default: '' },
+	items: { type: Array, default: () => [] },
+});
+const panel = ref(null);
+let stopPositioning;
+
+/** Positions the compact tooltip outside the plot and within the viewport. @returns {void} */
+function position() {
+	applyFloatingPosition(props.anchor, panel.value, { placement: 'top', align: 'center', offset: 8, padding: 8 });
+}
+
+/** Opens in the top layer so table overflow cannot clip chart values. @returns {void} */
+function open() {
+	panel.value.showPopover();
+	position();
+	stopPositioning = autoUpdateFloating(props.anchor, panel.value, position);
+}
+
+/** Releases scroll/resize observers when inspection ends or the chart unmounts. @returns {void} */
+function cleanup() {
+	stopPositioning?.();
+}
+
+onMounted(open);
+onBeforeUnmount(cleanup);
+</script>
+
+<template>
+	<div ref="panel" popover="manual" class="pointer-events-none m-0 w-max max-w-[calc(100vw-1rem)] overflow-visible border-0 bg-transparent p-0 text-canvas-fg">
+		<ChartTooltip :label="label" :items="items" />
+	</div>
+</template>

package/src/pages/charts/_shared/XYChart.vue

@@ -5,6 +5,7 @@ import { chartPoints, chartSeries, formatChartValue, percentagePoints } from './
 import ChartContainer from './ChartContainer.vue';
 import ChartLegend from './ChartLegend.vue';
 import ChartTooltip from './ChartTooltip.vue';
+import CompactChartTooltip from './CompactChartTooltip.vue';
 
 const props = defineProps({
 	...chartProps,
@@ -13,12 +14,14 @@ const props = defineProps({
 	percentage: { type: Boolean, default: false },
 	horizontal: { type: Boolean, default: false },
 	compact: { type: Boolean, default: false },
+	tooltip: { type: Boolean, default: true },
 });
 const emit = defineEmits(['retry', 'select']);
 const renderer = shallowRef(null);
 const loadError = ref('');
 const hiddenKeys = ref([]);
 const inspected = ref(null);
+const plot = ref(null);
 let disposed = false;
 const allSeries = computed(() => chartSeries(props.series));
 const visibleSeries = computed(() => allSeries.value.filter((item) => !hiddenKeys.value.includes(item.key)));
@@ -108,16 +111,18 @@ function scrub(event) { inspected.value = points.value[Number(event.target.value
 <template>
 	<ChartContainer :title="title" :description="description" :height="safeHeight" :compact="compact" :loading="loading" :error="error || validationError || loadError" :empty="!hasData" :empty-label="emptyLabel" @retry="retry">
 		<div
+			ref="plot"
 			class="relative rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
 			:style="{ height: `${safeHeight}px` }" tabindex="0" role="group"
 			:aria-label="`${title}. Use arrow keys to inspect values; Enter selects a row.`"
-			@keydown="navigate" @focus="inspect(points[0])" @blur="inspect(null)" @mouseleave="inspect(null)" @click="selectPoint"
+			@keydown="navigate" @focus="inspect(inspected || points[0])" @blur="inspect(null)" @mouseleave="inspect(null)" @click="selectPoint"
 		>
 			<div aria-hidden="true">
 				<component :is="renderer" v-if="renderer" :key="`${kind}-${horizontal}-${stacked}-${percentage}`" :points="renderPoints" :series="visibleSeries" :kind="kind" :height="safeHeight" :curve="curve" :stacked="stacked || percentage" :percentage="percentage" :horizontal="horizontal" :compact="compact" :grid="grid" :x-type="xType" :format-x="formatAxisLabel" :format-y="formatAxisValue" @inspect="inspect" />
 				<div v-else class="h-full w-full" />
 			</div>
-			<ChartTooltip v-if="inspected && !compact" class="absolute right-2 top-2 z-10" :label="formatLabel(inspected.row[xKey])" :items="tooltipItems" />
+			<CompactChartTooltip v-if="inspected && tooltip && compact" :anchor="plot" :label="formatLabel(inspected.row[xKey])" :items="tooltipItems" />
+			<ChartTooltip v-else-if="inspected && tooltip" class="absolute right-2 top-2 z-10" :label="formatLabel(inspected.row[xKey])" :items="tooltipItems" />
 			<span class="sr-only" aria-live="polite">{{ inspected ? `${formatLabel(inspected.row[xKey])}: ${tooltipItems.map(item => `${item.label} ${item.value}`).join(', ')}` : '' }}</span>
 		</div>
 		<template #legend>

package/src/pages/charts/_shared/XYRenderer.vue

@@ -56,35 +56,42 @@ function getX(point) { return point.x; }
 /** @param {unknown} _datum Unovis datum. @param {number} index Series index. @returns {string} Stable colour. */
 function getColor(_datum, index) { return props.series[index]?.color || 'var(--primary)'; }
 
-/** @param {number} _x Pointer coordinate. @param {object} point Nearest datum. @returns {void} */
-function inspectPoint(_x, point) { emit('inspect', point || null); }
+/**
+ * Synchronizes inspection with the crosshair, including plot-boundary dismissal.
+ * Unovis can retain the nearest datum while clearing the pointer coordinate.
+ * @param {number|Date|undefined} x Pointer coordinate; absent when hidden.
+ * @param {object|undefined} point Nearest datum.
+ * @returns {void}
+ */
+function inspectPoint(x, point) { emit('inspect', x == null ? null : point || null); }
 
 /** @param {object} datum Bar or stack datum. @returns {void} Inspects horizontal and touch-selected bars. */
 function inspectBar(datum) { emit('inspect', datum.datum || datum); }
 </script>
 
 <template>
+	<!-- Unovis 1.7 forwards undeclared attributes verbatim; config bindings must use camelCase. -->
 	<VisXYContainer
 		:data="points" :height="height" :duration="0" class="block w-full"
-		:x-domain="horizontal ? valueDomain : undefined" :y-domain="horizontal ? undefined : valueDomain"
-		:y-direction="horizontal ? 'south' : 'north'"
+		:xDomain="horizontal ? valueDomain : undefined" :yDomain="horizontal ? undefined : valueDomain"
+		:yDirection="horizontal ? 'south' : 'north'"
 		:margin="compact ? { top: 4, bottom: 4, left: 4, right: 4 } : { top: 12, right: 12 }"
 	>
 		<template v-if="kind === 'line'">
-			<VisLine v-for="(item, index) in series" :key="item.key" :x="getX" :y="accessors[index]" :color="item.color" :curve-type="curve" :line-width="2" :line-dash-array="item.dashed ? [5, 4] : undefined" :duration="0" />
+			<VisLine v-for="(item, index) in series" :key="item.key" :x="getX" :y="accessors[index]" :color="item.color" :curveType="curve" :lineWidth="2" :lineDashArray="item.dashed ? [5, 4] : undefined" :duration="0" />
 			<VisScatter v-if="points.length === 1" :x="getX" :y="accessors" :color="getColor" :size="24" :duration="0" />
 		</template>
 		<template v-else-if="kind === 'area'">
-			<VisArea v-if="stacked" :x="getX" :y="accessors" :color="getColor" :curve-type="curve" :opacity="0.45" :duration="0" />
-			<VisArea v-for="(item, index) in stacked ? [] : series" :key="item.key" :x="getX" :y="accessors[index]" :color="item.color" :curve-type="curve" :opacity="0.15" :line="true" :line-color="item.color" :duration="0" />
+			<VisArea v-if="stacked" :x="getX" :y="accessors" :color="getColor" :curveType="curve" :opacity="0.45" :duration="0" />
+			<VisArea v-for="(item, index) in stacked ? [] : series" :key="item.key" :x="getX" :y="accessors[index]" :color="item.color" :curveType="curve" :opacity="0.15" :line="true" :lineColor="item.color" :duration="0" />
 		</template>
 		<component
 			:is="stacked ? VisStackedBar : VisGroupedBar" v-else
 			:x="getX" :y="accessors" :color="getColor" :orientation="horizontal ? 'horizontal' : 'vertical'"
-			:bar-padding="stacked ? 0.3 : 0.1" :group-padding="0.3" :rounded-corners="3" :bar-min-height="0" :duration="0" :events="barEvents"
+			:barPadding="stacked ? 0.3 : 0.1" :groupPadding="0.3" :roundedCorners="3" :barMinHeight="0" :duration="0" :events="barEvents"
 		/>
-		<VisAxis v-if="!compact" :key="`category-${horizontal}`" :type="horizontal ? 'y' : 'x'" :tick-values="categoryTicks" :tick-format="formatX" :grid-line="false" :domain-line="false" :tick-line="false" :tick-text-width="horizontal ? 90 : 72" :tick-text-hide-overlapping="true" :tick-text-adaptive-sets="true" :duration="0" />
-		<VisAxis v-if="!compact" :key="`value-${horizontal}`" :type="horizontal ? 'x' : 'y'" :tick-format="formatY" :grid-line="grid" :domain-line="false" :tick-line="false" :tick-text-width="90" :tick-text-hide-overlapping="true" :num-ticks="4" :duration="0" />
-		<VisCrosshair v-if="!horizontal" :x="getX" :y="stacked ? [] : accessors" :y-stacked="stacked ? accessors : undefined" :color="getColor" :hide-when-far-from-pointer="false" :on-crosshair-move="inspectPoint" :duration="0" />
+		<VisAxis v-if="!compact" :key="`category-${horizontal}`" :type="horizontal ? 'y' : 'x'" :tickValues="categoryTicks" :tickFormat="formatX" :gridLine="false" :domainLine="false" :tickLine="false" :tickTextWidth="horizontal ? 90 : 72" :tickTextHideOverlapping="true" :tickTextAdaptiveSets="true" :duration="0" />
+		<VisAxis v-if="!compact" :key="`value-${horizontal}`" :type="horizontal ? 'x' : 'y'" :tickFormat="formatY" :gridLine="grid" :domainLine="false" :tickLine="false" :tickTextWidth="90" :tickTextHideOverlapping="true" :numTicks="4" :duration="0" />
+		<VisCrosshair v-if="!horizontal" :x="getX" :y="stacked ? [] : accessors" :yStacked="stacked ? accessors : undefined" :color="getColor" :hideWhenFarFromPointer="false" :onCrosshairMove="inspectPoint" :duration="0" />
 	</VisXYContainer>
 </template>

package/src/pages/charts/sparkline/DomSparkline.vue

@@ -21,6 +21,7 @@ const props = defineProps({
 	height: { type: Number, default: 48 },
 	legend: { type: Boolean, default: false },
 	showTable: { type: Boolean, default: false },
+	tooltip: { type: Boolean, default: false, _edit: { description: 'Show formatted values on hover or keyboard inspection in a floating tooltip outside the compact plot.' } },
 });
 defineEmits(['select', 'retry']);
 </script>

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 ?? '') }));
+}