vectis-ui 0.11.0 → 0.13.0

package/dist/composables/useFileField.js

@@ -1,86 +1,84 @@
 import { isDev as e } from "../utils/env.js";
-import { screenFiles as t } from "../utils/file.js";
-import { computed as n, getCurrentInstance as r, ref as i, watch as a, watchEffect as o } from "vue";
+import { partitionAttrs as t } from "../utils/attrs.js";
+import { screenFiles as n } from "../utils/file.js";
+import { computed as r, getCurrentInstance as i, ref as a, watch as o, watchEffect as s } from "vue";
 //#region src/composables/useFileField.ts
-var s = [
+var c = [
 	"name",
 	"required",
 	"form",
 	"capture"
 ];
-function c(c) {
-	let { model: l, props: u, emit: d } = c, f = i(null), p = () => c.disabled?.value ?? u.disabled, m = n(() => !p() && !u.readonly), h = n(() => {
-		let e = c.excludeFromControl ?? [];
-		return Object.fromEntries(Object.entries(c.forwardedAttrs.value).filter(([t]) => !s.includes(t) && !e.includes(t)));
-	});
-	function g() {
-		let e = f.value;
+function l(l) {
+	let { model: u, props: d, emit: f } = l, p = a(null), m = () => l.disabled?.value ?? d.disabled, h = r(() => !m() && !d.readonly), g = r(() => t(l.forwardedAttrs.value, c)), _ = r(() => t(g.value.rest, l.excludeFromControl ?? []).rest);
+	function v() {
+		let e = p.value;
 		if (!e) return;
 		if (typeof DataTransfer > "u") {
 			e.value = "";
 			return;
 		}
 		let t = new DataTransfer();
-		for (let e of l.value) t.items.add(e);
+		for (let e of u.value) t.items.add(e);
 		e.files = t.files;
 	}
-	a(l, g, { flush: "post" });
-	function _(e) {
-		let n = u.multiple ? l.value : [], { accepted: r, rejected: i } = t(e, n, {
-			accept: u.accept,
-			maxSize: u.maxSize,
-			maxFiles: u.multiple ? u.maxFiles : 1,
-			maxTotalSize: u.maxTotalSize
+	o(u, v, { flush: "post" });
+	function y(e) {
+		let t = d.multiple ? u.value : [], { accepted: r, rejected: i } = n(e, t, {
+			accept: d.accept,
+			maxSize: d.maxSize,
+			maxFiles: d.multiple ? d.maxFiles : 1,
+			maxTotalSize: d.maxTotalSize
 		});
-		for (let e of i) d("reject", e);
-		if (g(), r.length === 0) return;
-		let a = u.multiple ? void 0 : l.value[0];
-		l.value = [...n, ...r], a && a !== l.value[0] && d("remove", a, 0), d("change", l.value);
+		for (let e of i) f("reject", e);
+		if (v(), r.length === 0) return;
+		let a = d.multiple ? void 0 : u.value[0];
+		u.value = [...t, ...r], a && a !== u.value[0] && f("remove", a, 0), f("change", u.value);
 	}
-	function v(e) {
-		_([...e.target.files ?? []]);
+	function b(e) {
+		y([...e.target.files ?? []]);
 	}
-	let y = n(() => ({
-		...Object.fromEntries(Object.entries(c.forwardedAttrs.value).filter(([e]) => s.includes(e))),
+	let x = r(() => ({
+		...g.value.picked,
 		type: "file",
 		tabindex: -1,
 		"aria-hidden": "true",
-		accept: u.accept,
-		multiple: u.multiple || void 0,
-		disabled: p() || void 0,
-		onChange: v
+		accept: d.accept,
+		multiple: d.multiple || void 0,
+		disabled: m() || void 0,
+		onChange: b
 	}));
-	function b() {
-		m.value && f.value?.click();
+	function S() {
+		h.value && p.value?.click();
 	}
-	function x(e) {
-		let t = l.value[e];
-		if (!(!t || !m.value)) return l.value = l.value.filter((t, n) => n !== e), g(), d("remove", t, e), d("change", l.value), t;
+	function C(e) {
+		let t = u.value[e];
+		if (!(!t || !h.value)) return u.value = u.value.filter((t, n) => n !== e), v(), f("remove", t, e), f("change", u.value), t;
 	}
-	function S() {
-		!m.value || l.value.length === 0 || (l.value = [], g(), c.onClear?.(), d("change", l.value));
+	function w() {
+		!h.value || u.value.length === 0 || (u.value = [], v(), l.onClear?.(), f("change", u.value));
 	}
 	if (e) {
-		let e = r()?.type.__name, t = /* @__PURE__ */ new Set(), n = (n) => {
+		let e = i()?.type.__name, t = /* @__PURE__ */ new Set(), n = (n) => {
 			t.has(n) || (t.add(n), console.warn(`[${e}] ${n}`));
 		};
-		o(() => {
-			u.maxFiles !== void 0 && !u.multiple && n("`maxFiles` ignored without `multiple`: single mode already caps at one file."), c.forwardedAttrs.value.required !== void 0 && n("`required` lands on the hidden file input: the browser does block an empty submission, but its message points at an input nobody can see. Validate the v-model yourself and use the `invalid` prop.");
-			for (let e of c.warnings?.() ?? []) e && n(e);
+		s(() => {
+			d.maxFiles !== void 0 && !d.multiple && n("`maxFiles` ignored without `multiple`: single mode already caps at one file."), l.forwardedAttrs.value.required !== void 0 && n("`required` lands on the hidden file input: the browser does block an empty submission, but its message points at an input nobody can see. Validate the v-model yourself and use the `invalid` prop.");
+			for (let e of l.warnings?.() ?? []) e && n(e);
 		});
 	}
 	return {
-		fileEl: f,
-		enabled: m,
-		nativeInputAttrs: y,
-		controlAttrs: h,
-		acceptFiles: _,
-		openPicker: b,
-		removeAt: x,
-		clear: S
+		fileEl: p,
+		enabled: h,
+		nativeInputAttrs: x,
+		controlAttrs: _,
+		acceptFiles: y,
+		openPicker: S,
+		removeAt: C,
+		clear: w
 	};
 }
 //#endregion
-export { c as useFileField };
+export { l as useFileField };
 
 //# sourceMappingURL=useFileField.js.map

package/dist/composables/useFileField.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFileField.js","names":[],"sources":["../../src/composables/useFileField.ts"],"sourcesContent":["// @core\n/**\n * Bridge native file selection, screening and form state for both file components. Synchronize\n * the accepted File[] through DataTransfer where supported.\n */\nimport {\n  computed,\n  getCurrentInstance,\n  ref,\n  watch,\n  watchEffect,\n  type ComputedRef,\n  type Ref,\n} from 'vue'\n\nimport { isDev } from '../utils/env'\nimport { screenFiles, type FileRejection } from '../utils/file'\n\n// @a11y\n/** The attributes belonging on the hidden file input rather than on the visible control. */\nconst NATIVE_ONLY = ['name', 'required', 'form', 'capture']\n\n/** The props both components declare under the same names, read at the moment they matter. */\nexport interface FileFieldProps {\n  multiple: boolean\n  accept?: string\n  maxSize?: number\n  maxFiles?: number\n  maxTotalSize?: number\n  disabled: boolean\n  readonly: boolean\n}\n\n/** The events both components declare under the same names and with the same payloads. */\nexport interface FileFieldEmit {\n  (event: 'change', files: File[]): void\n  (event: 'reject', rejection: FileRejection): void\n  (event: 'remove', file: File, index: number): void\n}\n\nexport interface FileFieldOptions {\n  /** The component's value: always a list of files, whether one or several are allowed. */\n  model: Ref<File[]>\n  props: FileFieldProps\n  emit: FileFieldEmit\n  /** The attributes the consumer wrote, minus styling, still to be split in two. */\n  forwardedAttrs: ComputedRef<Record<string, unknown>>\n  /**\n   * Whether the component is disabled, the row it sits in taken into account. Left out, the\n   * `disabled` prop answers alone.\n   */\n  disabled?: Ref<boolean>\n  /** Attributes to withhold from the visible control too. */\n  excludeFromControl?: readonly string[]\n  /** Called once the selection has been emptied by `clear`, before `change` is emitted. */\n  onClear?: () => void\n  /**\n   * The component's own development warnings, one message per condition that holds. They\n   * follow the same rule as the shared ones: each is given once per instance.\n   */\n  warnings?: () => (string | false)[]\n}\n\nexport function useFileField(options: FileFieldOptions) {\n  const { model, props, emit } = options\n\n  const fileEl = ref<HTMLInputElement | null>(null)\n\n  const disabled = () => options.disabled?.value ?? props.disabled\n\n  /** Whether files may come in or go out; no dialog, no drop and no removal otherwise. */\n  const enabled = computed(() => !disabled() && !props.readonly)\n\n  const controlAttrs = computed(() => {\n    const excluded = options.excludeFromControl ?? []\n    return Object.fromEntries(\n      Object.entries(options.forwardedAttrs.value).filter(\n        ([key]) => !NATIVE_ONLY.includes(key) && !excluded.includes(key),\n      ),\n    )\n  })\n\n  // @core\n  /**\n   * It also keeps every file that LEFT the selection pickable again. The input holds exactly\n   * the selection, so choosing a file that was cleared, removed or refused differs from what it\n   * holds and fires `change`; left holding it, the dialog would answer the same file with no\n   * event at all.\n   */\n  function syncNative() {\n    const el = fileEl.value\n    if (!el) return\n    // @fallback\n    // An environment without `DataTransfer` (jsdom) can only empty the input,\n    // which keeps a file pickable again and leaves the form without it.\n    if (typeof DataTransfer === 'undefined') {\n      el.value = ''\n      return\n    }\n    const transfer = new DataTransfer()\n    for (const file of model.value) transfer.items.add(file)\n    el.files = transfer.files\n  }\n\n  // A value set from outside, a consumer emptying the list after an upload, reaches the\n  // input the same way.\n  watch(model, syncNative, { flush: 'post' })\n\n  /** The single entry into the model: the dialog and a drop both arrive here. */\n  function acceptFiles(incoming: File[]) {\n    const current = props.multiple ? model.value : []\n    const { accepted, rejected } = screenFiles(incoming, current, {\n      accept: props.accept,\n      maxSize: props.maxSize,\n      // A single-file field is a list capped at one, so extra files are refused for the\n      // same reason as anywhere else: too many.\n      maxFiles: props.multiple ? props.maxFiles : 1,\n      maxTotalSize: props.maxTotalSize,\n    })\n\n    for (const rejection of rejected) emit('reject', rejection)\n\n    syncNative()\n    if (accepted.length === 0) return\n\n    // A single file replaced by another has left the selection as surely as one taken out\n    // by its cross, and `remove` is how an upload already under way for it is cancelled.\n    const replaced = props.multiple ? undefined : model.value[0]\n    model.value = [...current, ...accepted]\n    if (replaced && replaced !== model.value[0]) emit('remove', replaced, 0)\n    emit('change', model.value)\n  }\n\n  function onNativeChange(event: Event) {\n    acceptFiles([...((event.target as HTMLInputElement).files ?? [])])\n  }\n\n  /**\n   * Everything the hidden input is bound with, the consumer's form attributes included. It\n   * is taken out of the tab order and hidden from screen readers, which leaves the visible\n   * control as the single stop and the single announcement; it stays disabled only when the\n   * component is, since a read-only one still submits what it holds (`syncNative`).\n   */\n  const nativeInputAttrs = computed(() => ({\n    ...Object.fromEntries(\n      Object.entries(options.forwardedAttrs.value).filter(([key]) => NATIVE_ONLY.includes(key)),\n    ),\n    type: 'file',\n    tabindex: -1,\n    'aria-hidden': 'true' as const,\n    accept: props.accept,\n    multiple: props.multiple || undefined,\n    disabled: disabled() || undefined,\n    onChange: onNativeChange,\n  }))\n\n  // @fallback\n  /** `.click()` and not `showPicker()`. */\n  function openPicker() {\n    if (!enabled.value) return\n    fileEl.value?.click()\n  }\n\n  /**\n   * Takes ONE file out of the selection, and says which: `remove` with the file and the\n   * position it held, then `change` with what is left. It returns the file removed, or\n   * `undefined` when nothing was; so the component knows whether it has a focus to catch.\n   */\n  function removeAt(index: number): File | undefined {\n    const file = model.value[index]\n    if (!file || !enabled.value) return undefined\n\n    model.value = model.value.filter((_, i) => i !== index)\n    syncNative()\n    emit('remove', file, index)\n    emit('change', model.value)\n    return file\n  }\n\n  /**\n   * Empties the selection, and the hidden input with it. Refused where `removeAt` is, and\n   * silent when there is nothing to empty: no `change` for a selection that did not change.\n   */\n  function clear() {\n    if (!enabled.value || model.value.length === 0) return\n    model.value = []\n    syncNative()\n    options.onClear?.()\n    emit('change', model.value)\n  }\n\n  // @devwarn\n  /*\n   * Both shared guards describe something that fails SILENTLY at runtime. Each message is given\n   * once per instance: they sit in an effect, which re-runs on every change of what it reads,\n   * and the same sentence repeated at every keystroke is how a warning stops being read.\n   */\n  if (isDev) {\n    // The prefix is the component's own name, read off the instance rather than passed in:\n    // this whole block is dropped from a production build, and the name with it.\n    const name = getCurrentInstance()?.type.__name\n    const warned = new Set<string>()\n    const warn = (message: string) => {\n      if (warned.has(message)) return\n      warned.add(message)\n      console.warn(`[${name}] ${message}`)\n    }\n    watchEffect(() => {\n      if (props.maxFiles !== undefined && !props.multiple)\n        warn('`maxFiles` ignored without `multiple`: single mode already caps at one file.')\n      if (options.forwardedAttrs.value.required !== undefined)\n        warn(\n          '`required` lands on the hidden file input: the browser does block an empty submission, but its message points at an input nobody can see. Validate the v-model yourself and use the `invalid` prop.',\n        )\n      for (const message of options.warnings?.() ?? []) if (message) warn(message)\n    })\n  }\n\n  return {\n    fileEl,\n    enabled,\n    nativeInputAttrs,\n    controlAttrs,\n    acceptFiles,\n    openPicker,\n    removeAt,\n    clear,\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"useFileField.js","names":[],"sources":["../../src/composables/useFileField.ts"],"sourcesContent":["// @core\n/**\n * Bridge native file selection, screening and form state for both file components. Synchronize\n * the accepted File[] through DataTransfer where supported.\n */\nimport {\n  computed,\n  getCurrentInstance,\n  ref,\n  watch,\n  watchEffect,\n  type ComputedRef,\n  type Ref,\n} from 'vue'\n\nimport { partitionAttrs } from '../utils/attrs'\nimport { isDev } from '../utils/env'\nimport { screenFiles, type FileRejection } from '../utils/file'\n\n// @a11y\n/** The attributes belonging on the hidden file input rather than on the visible control. */\nconst NATIVE_ONLY = ['name', 'required', 'form', 'capture']\n\n/** The props both components declare under the same names, read at the moment they matter. */\nexport interface FileFieldProps {\n  multiple: boolean\n  accept?: string\n  maxSize?: number\n  maxFiles?: number\n  maxTotalSize?: number\n  disabled: boolean\n  readonly: boolean\n}\n\n/** The events both components declare under the same names and with the same payloads. */\nexport interface FileFieldEmit {\n  (event: 'change', files: File[]): void\n  (event: 'reject', rejection: FileRejection): void\n  (event: 'remove', file: File, index: number): void\n}\n\nexport interface FileFieldOptions {\n  /** The component's value: always a list of files, whether one or several are allowed. */\n  model: Ref<File[]>\n  props: FileFieldProps\n  emit: FileFieldEmit\n  /** The attributes the consumer wrote, minus styling, still to be split in two. */\n  forwardedAttrs: ComputedRef<Record<string, unknown>>\n  /**\n   * Whether the component is disabled, the row it sits in taken into account. Left out, the\n   * `disabled` prop answers alone.\n   */\n  disabled?: Ref<boolean>\n  /** Attributes to withhold from the visible control too. */\n  excludeFromControl?: readonly string[]\n  /** Called once the selection has been emptied by `clear`, before `change` is emitted. */\n  onClear?: () => void\n  /**\n   * The component's own development warnings, one message per condition that holds. They\n   * follow the same rule as the shared ones: each is given once per instance.\n   */\n  warnings?: () => (string | false)[]\n}\n\nexport function useFileField(options: FileFieldOptions) {\n  const { model, props, emit } = options\n\n  const fileEl = ref<HTMLInputElement | null>(null)\n\n  const disabled = () => options.disabled?.value ?? props.disabled\n\n  /** Whether files may come in or go out; no dialog, no drop and no removal otherwise. */\n  const enabled = computed(() => !disabled() && !props.readonly)\n\n  const split = computed(() => partitionAttrs(options.forwardedAttrs.value, NATIVE_ONLY))\n\n  const controlAttrs = computed(\n    () => partitionAttrs(split.value.rest, options.excludeFromControl ?? []).rest,\n  )\n\n  // @core\n  /**\n   * It also keeps every file that LEFT the selection pickable again. The input holds exactly\n   * the selection, so choosing a file that was cleared, removed or refused differs from what it\n   * holds and fires `change`; left holding it, the dialog would answer the same file with no\n   * event at all.\n   */\n  function syncNative() {\n    const el = fileEl.value\n    if (!el) return\n    // @fallback\n    // An environment without `DataTransfer` (jsdom) can only empty the input,\n    // which keeps a file pickable again and leaves the form without it.\n    if (typeof DataTransfer === 'undefined') {\n      el.value = ''\n      return\n    }\n    const transfer = new DataTransfer()\n    for (const file of model.value) transfer.items.add(file)\n    el.files = transfer.files\n  }\n\n  // A value set from outside, a consumer emptying the list after an upload, reaches the\n  // input the same way.\n  watch(model, syncNative, { flush: 'post' })\n\n  /** The single entry into the model: the dialog and a drop both arrive here. */\n  function acceptFiles(incoming: File[]) {\n    const current = props.multiple ? model.value : []\n    const { accepted, rejected } = screenFiles(incoming, current, {\n      accept: props.accept,\n      maxSize: props.maxSize,\n      // A single-file field is a list capped at one, so extra files are refused for the\n      // same reason as anywhere else: too many.\n      maxFiles: props.multiple ? props.maxFiles : 1,\n      maxTotalSize: props.maxTotalSize,\n    })\n\n    for (const rejection of rejected) emit('reject', rejection)\n\n    syncNative()\n    if (accepted.length === 0) return\n\n    // A single file replaced by another has left the selection as surely as one taken out\n    // by its cross, and `remove` is how an upload already under way for it is cancelled.\n    const replaced = props.multiple ? undefined : model.value[0]\n    model.value = [...current, ...accepted]\n    if (replaced && replaced !== model.value[0]) emit('remove', replaced, 0)\n    emit('change', model.value)\n  }\n\n  function onNativeChange(event: Event) {\n    acceptFiles([...((event.target as HTMLInputElement).files ?? [])])\n  }\n\n  /**\n   * Everything the hidden input is bound with, the consumer's form attributes included. It\n   * is taken out of the tab order and hidden from screen readers, which leaves the visible\n   * control as the single stop and the single announcement; it stays disabled only when the\n   * component is, since a read-only one still submits what it holds (`syncNative`).\n   */\n  const nativeInputAttrs = computed(() => ({\n    ...split.value.picked,\n    type: 'file',\n    tabindex: -1,\n    'aria-hidden': 'true' as const,\n    accept: props.accept,\n    multiple: props.multiple || undefined,\n    disabled: disabled() || undefined,\n    onChange: onNativeChange,\n  }))\n\n  // @fallback\n  /** `.click()` and not `showPicker()`. */\n  function openPicker() {\n    if (!enabled.value) return\n    fileEl.value?.click()\n  }\n\n  /**\n   * Takes ONE file out of the selection, and says which: `remove` with the file and the\n   * position it held, then `change` with what is left. It returns the file removed, or\n   * `undefined` when nothing was; so the component knows whether it has a focus to catch.\n   */\n  function removeAt(index: number): File | undefined {\n    const file = model.value[index]\n    if (!file || !enabled.value) return undefined\n\n    model.value = model.value.filter((_, i) => i !== index)\n    syncNative()\n    emit('remove', file, index)\n    emit('change', model.value)\n    return file\n  }\n\n  /**\n   * Empties the selection, and the hidden input with it. Refused where `removeAt` is, and\n   * silent when there is nothing to empty: no `change` for a selection that did not change.\n   */\n  function clear() {\n    if (!enabled.value || model.value.length === 0) return\n    model.value = []\n    syncNative()\n    options.onClear?.()\n    emit('change', model.value)\n  }\n\n  // @devwarn\n  /*\n   * Both shared guards describe something that fails SILENTLY at runtime. Each message is given\n   * once per instance: they sit in an effect, which re-runs on every change of what it reads,\n   * and the same sentence repeated at every keystroke is how a warning stops being read.\n   */\n  if (isDev) {\n    // The prefix is the component's own name, read off the instance rather than passed in:\n    // this whole block is dropped from a production build, and the name with it.\n    const name = getCurrentInstance()?.type.__name\n    const warned = new Set<string>()\n    const warn = (message: string) => {\n      if (warned.has(message)) return\n      warned.add(message)\n      console.warn(`[${name}] ${message}`)\n    }\n    watchEffect(() => {\n      if (props.maxFiles !== undefined && !props.multiple)\n        warn('`maxFiles` ignored without `multiple`: single mode already caps at one file.')\n      if (options.forwardedAttrs.value.required !== undefined)\n        warn(\n          '`required` lands on the hidden file input: the browser does block an empty submission, but its message points at an input nobody can see. Validate the v-model yourself and use the `invalid` prop.',\n        )\n      for (const message of options.warnings?.() ?? []) if (message) warn(message)\n    })\n  }\n\n  return {\n    fileEl,\n    enabled,\n    nativeInputAttrs,\n    controlAttrs,\n    acceptFiles,\n    openPicker,\n    removeAt,\n    clear,\n  }\n}\n"],"mappings":"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"}

package/dist/composables/useHotkeyListener.d.ts

@@ -0,0 +1,17 @@
+import { HotkeysPlatform } from '../components/VHotkeys/platform.js';
+/**
+ * Listens on the document for one keyboard shortcut, shared by VHotkeys and VCommandPalette. The
+ * listener exists only while `enabled` holds and the component is mounted and active, so a page
+ * displaying fifty shortcuts installs no listener at all.
+ */
+export declare function useHotkeyListener(options: {
+    /** The combination, as `parseHotkeys` returns it. */
+    tokens: () => string[];
+    platform: () => HotkeysPlatform;
+    enabled: () => boolean;
+    /** Lets the browser go on doing whatever the combination normally does. */
+    allowDefault?: () => boolean;
+    /** Fires even when the reader is typing in a field. */
+    allowInInput?: () => boolean;
+    onTrigger: (event: KeyboardEvent) => void;
+}): void;

package/dist/composables/useHotkeyListener.js

@@ -0,0 +1,26 @@
+import { isEditableTarget as e, matchesEvent as t } from "../components/VHotkeys/platform.js";
+import { onActivated as n, onBeforeUnmount as r, onDeactivated as i, onMounted as a, watch as o } from "vue";
+//#region src/composables/useHotkeyListener.ts
+function s(s) {
+	let c = !1;
+	function l(n) {
+		if (!s.enabled() || n.repeat || n.defaultPrevented || n.isComposing || !s.allowInInput?.() && e(n.composedPath()[0] ?? n.target)) return;
+		let r = s.tokens();
+		t(n, r, s.platform()) && (!s.allowDefault?.() && !r.includes("esc") && n.preventDefault(), s.onTrigger(n));
+	}
+	function u() {
+		c || typeof document > "u" || (document.addEventListener("keydown", l), c = !0);
+	}
+	function d() {
+		c &&= (document.removeEventListener("keydown", l), !1);
+	}
+	a(() => {
+		s.enabled() && u();
+	}), o(s.enabled, (e) => e ? u() : d()), r(d), i(d), n(() => {
+		s.enabled() && u();
+	});
+}
+//#endregion
+export { s as useHotkeyListener };
+
+//# sourceMappingURL=useHotkeyListener.js.map

package/dist/composables/useHotkeyListener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyListener.js","names":[],"sources":["../../src/composables/useHotkeyListener.ts"],"sourcesContent":["import { onActivated, onBeforeUnmount, onDeactivated, onMounted, watch } from 'vue'\n\nimport { isEditableTarget, matchesEvent } from '../components/VHotkeys/platform'\nimport type { HotkeysPlatform } from '../components/VHotkeys/platform'\n\n// @keyboard @core\n/**\n * Listens on the document for one keyboard shortcut, shared by VHotkeys and VCommandPalette. The\n * listener exists only while `enabled` holds and the component is mounted and active, so a page\n * displaying fifty shortcuts installs no listener at all.\n */\nexport function useHotkeyListener(options: {\n  /** The combination, as `parseHotkeys` returns it. */\n  tokens: () => string[]\n  platform: () => HotkeysPlatform\n  enabled: () => boolean\n  /** Lets the browser go on doing whatever the combination normally does. */\n  allowDefault?: () => boolean\n  /** Fires even when the reader is typing in a field. */\n  allowInInput?: () => boolean\n  onTrigger: (event: KeyboardEvent) => void\n}) {\n  let listening = false\n\n  function onKeydown(event: KeyboardEvent) {\n    /* A held-down combination repeats at the system's auto-repeat rate, which would\n       reopen the consumer's palette a dozen times a second; only the first press\n       counts. */\n    if (!options.enabled() || event.repeat) return\n    /* A key another handler has already dealt with (a menu's arrow, a field's Enter) is not\n       a shortcut any more. And the Enter that confirms an input method's candidate is the\n       end of a word being typed, not a command. */\n    if (event.defaultPrevented || event.isComposing) return\n    /* The document sees a key typed inside a shadow root as coming from the shadow HOST, a\n       plain element: the field itself is the first entry of the composed path. */\n    if (!options.allowInInput?.() && isEditableTarget(event.composedPath()[0] ?? event.target)) {\n      return\n    }\n    const tokens = options.tokens()\n    if (!matchesEvent(event, tokens, options.platform())) return\n    /*\n     * Escape is never cancelled. A cancelled Escape is not turned into a close request, so every\n     * open dialog and light-dismiss popover on the page would stop closing on it.\n     */\n    if (!options.allowDefault?.() && !tokens.includes('esc')) event.preventDefault()\n    options.onTrigger(event)\n  }\n\n  function attach() {\n    if (listening || typeof document === 'undefined') return\n    document.addEventListener('keydown', onKeydown)\n    listening = true\n  }\n\n  function detach() {\n    if (!listening) return\n    document.removeEventListener('keydown', onKeydown)\n    listening = false\n  }\n\n  onMounted(() => {\n    if (options.enabled()) attach()\n  })\n  watch(options.enabled, (on) => (on ? attach() : detach()))\n  onBeforeUnmount(detach)\n  /* A view kept alive by <KeepAlive> is never unmounted, only put aside: its shortcut must\n     stop with it, or a hidden page would go on answering the keyboard. */\n  onDeactivated(detach)\n  onActivated(() => {\n    if (options.enabled()) attach()\n  })\n}\n"],"mappings":";;;AAWA,SAAgB,EAAkB,GAU/B;CACD,IAAI,IAAY;CAEhB,SAAS,EAAU,GAAsB;EAWvC,IAPI,CAAC,EAAQ,QAAQ,KAAK,EAAM,UAI5B,EAAM,oBAAoB,EAAM,eAGhC,CAAC,EAAQ,eAAe,KAAK,EAAiB,EAAM,aAAa,CAAC,CAAC,MAAM,EAAM,MAAM,GACvF;EAEF,IAAM,IAAS,EAAQ,OAAO;EACzB,EAAa,GAAO,GAAQ,EAAQ,SAAS,CAAC,MAK/C,CAAC,EAAQ,eAAe,KAAK,CAAC,EAAO,SAAS,KAAK,KAAG,EAAM,eAAe,GAC/E,EAAQ,UAAU,CAAK;CACzB;CAEA,SAAS,IAAS;EACZ,KAAa,OAAO,WAAa,QACrC,SAAS,iBAAiB,WAAW,CAAS,GAC9C,IAAY;CACd;CAEA,SAAS,IAAS;EACX,AAEL,OADA,SAAS,oBAAoB,WAAW,CAAS,GACrC;CACd;CAUA,AARA,QAAgB;EACd,AAAI,EAAQ,QAAQ,KAAG,EAAO;CAChC,CAAC,GACD,EAAM,EAAQ,UAAU,MAAQ,IAAK,EAAO,IAAI,EAAO,CAAE,GACzD,EAAgB,CAAM,GAGtB,EAAc,CAAM,GACpB,QAAkB;EAChB,AAAI,EAAQ,QAAQ,KAAG,EAAO;CAChC,CAAC;AACH"}

package/dist/composables/useIconClickHandlers.d.ts

@@ -3,16 +3,8 @@
  * Require accessible names before turning decorative icons into buttons.
  */
 /**
- * Whether the component being set up was handed a `@click:icon-start` / `@click:icon-end`
- * listener, in either spelling.
- */
-export declare function iconClickHandlers(): {
-    start: boolean;
-    end: boolean;
-};
-/**
- * The start-icon listener a field COMPOSED on top of VInput: VCombobox, VDateInput, VTimeInput,
- * VFileInput, binds onto that inner VInput, ready to spread beside the consumer's attributes.
+ * The start-icon listener a field composed on top of VInput binds onto that inner VInput, ready
+ * to spread beside the consumer's attributes. Absent when the consumer attached none.
  */
 export declare function iconStartListener(relay: (event: MouseEvent) => void): {
     'onClick:icon-start': (event: MouseEvent) => void;

package/dist/composables/useIconClickHandlers.js

@@ -19,6 +19,6 @@ function i(t) {
 	};
 }
 //#endregion
-export { n as iconClickHandlers, r as iconStartListener, i as useIconClickHandlers };
+export { r as iconStartListener, i as useIconClickHandlers };
 
 //# sourceMappingURL=useIconClickHandlers.js.map

package/dist/composables/useIconClickHandlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"useIconClickHandlers.js","names":[],"sources":["../../src/composables/useIconClickHandlers.ts"],"sourcesContent":["// @core\n/**\n * Detect declared icon-click listeners from vnode props because emits removes them from attrs.\n * Require accessible names before turning decorative icons into buttons.\n */\n\nimport { getCurrentInstance } from 'vue'\n\nimport { isDev } from '../utils/env'\n\n/**\n * Whether the component being set up was handed a `@click:icon-start` / `@click:icon-end`\n * listener, in either spelling.\n */\nexport function iconClickHandlers(): { start: boolean; end: boolean } {\n  const vnodeProps = getCurrentInstance()?.vnode.props ?? {}\n  return {\n    start: 'onClick:iconStart' in vnodeProps || 'onClick:icon-start' in vnodeProps,\n    end: 'onClick:iconEnd' in vnodeProps || 'onClick:icon-end' in vnodeProps,\n  }\n}\n\n/**\n * The start-icon listener a field COMPOSED on top of VInput: VCombobox, VDateInput, VTimeInput,\n * VFileInput, binds onto that inner VInput, ready to spread beside the consumer's attributes.\n */\nexport function iconStartListener(\n  relay: (event: MouseEvent) => void,\n): { 'onClick:icon-start': (event: MouseEvent) => void } | undefined {\n  return iconClickHandlers().start ? { 'onClick:icon-start': relay } : undefined\n}\n\nexport function useIconClickHandlers(options: {\n  name: string\n  iconStartLabel?: string\n  iconEndLabel?: string\n}): { hasIconStartHandler: boolean; hasIconEndHandler: boolean } {\n  const { start: hasIconStartHandler, end: hasIconEndHandler } = iconClickHandlers()\n\n  // @a11y @devwarn\n  if (isDev) {\n    if (hasIconStartHandler && !options.iconStartLabel)\n      console.warn(\n        `[${options.name}] clickable start icon without iconStartLabel — provide an accessible label.`,\n      )\n    if (hasIconEndHandler && !options.iconEndLabel)\n      console.warn(\n        `[${options.name}] clickable end icon without iconEndLabel — provide an accessible label.`,\n      )\n  }\n\n  return { hasIconStartHandler, hasIconEndHandler }\n}\n"],"mappings":";;;AAcA,SAAgB,IAAsD;CACpE,IAAM,IAAa,EAAmB,CAAC,EAAE,MAAM,SAAS,CAAC;CACzD,OAAO;EACL,OAAO,uBAAuB,KAAc,wBAAwB;EACpE,KAAK,qBAAqB,KAAc,sBAAsB;CAChE;AACF;AAMA,SAAgB,EACd,GACmE;CACnE,OAAO,EAAkB,CAAC,CAAC,QAAQ,EAAE,sBAAsB,EAAM,IAAI,KAAA;AACvE;AAEA,SAAgB,EAAqB,GAI4B;CAC/D,IAAM,EAAE,OAAO,GAAqB,KAAK,MAAsB,EAAkB;CAcjF,OAXI,MACE,KAAuB,CAAC,EAAQ,kBAClC,QAAQ,KACN,IAAI,EAAQ,KAAK,6EACnB,GACE,KAAqB,CAAC,EAAQ,gBAChC,QAAQ,KACN,IAAI,EAAQ,KAAK,yEACnB,IAGG;EAAE;EAAqB;CAAkB;AAClD"}
+{"version":3,"file":"useIconClickHandlers.js","names":[],"sources":["../../src/composables/useIconClickHandlers.ts"],"sourcesContent":["// @core\n/**\n * Detect declared icon-click listeners from vnode props because emits removes them from attrs.\n * Require accessible names before turning decorative icons into buttons.\n */\n\nimport { getCurrentInstance } from 'vue'\n\nimport { isDev } from '../utils/env'\n\n/**\n * Whether the component being set up was handed a `@click:icon-start` / `@click:icon-end`\n * listener, in either spelling.\n */\nfunction iconClickHandlers(): { start: boolean; end: boolean } {\n  const vnodeProps = getCurrentInstance()?.vnode.props ?? {}\n  return {\n    start: 'onClick:iconStart' in vnodeProps || 'onClick:icon-start' in vnodeProps,\n    end: 'onClick:iconEnd' in vnodeProps || 'onClick:icon-end' in vnodeProps,\n  }\n}\n\n/**\n * The start-icon listener a field composed on top of VInput binds onto that inner VInput, ready\n * to spread beside the consumer's attributes. Absent when the consumer attached none.\n */\nexport function iconStartListener(\n  relay: (event: MouseEvent) => void,\n): { 'onClick:icon-start': (event: MouseEvent) => void } | undefined {\n  return iconClickHandlers().start ? { 'onClick:icon-start': relay } : undefined\n}\n\nexport function useIconClickHandlers(options: {\n  name: string\n  iconStartLabel?: string\n  iconEndLabel?: string\n}): { hasIconStartHandler: boolean; hasIconEndHandler: boolean } {\n  const { start: hasIconStartHandler, end: hasIconEndHandler } = iconClickHandlers()\n\n  // @a11y @devwarn\n  if (isDev) {\n    if (hasIconStartHandler && !options.iconStartLabel)\n      console.warn(\n        `[${options.name}] clickable start icon without iconStartLabel — provide an accessible label.`,\n      )\n    if (hasIconEndHandler && !options.iconEndLabel)\n      console.warn(\n        `[${options.name}] clickable end icon without iconEndLabel — provide an accessible label.`,\n      )\n  }\n\n  return { hasIconStartHandler, hasIconEndHandler }\n}\n"],"mappings":";;;AAcA,SAAS,IAAsD;CAC7D,IAAM,IAAa,EAAmB,CAAC,EAAE,MAAM,SAAS,CAAC;CACzD,OAAO;EACL,OAAO,uBAAuB,KAAc,wBAAwB;EACpE,KAAK,qBAAqB,KAAc,sBAAsB;CAChE;AACF;AAMA,SAAgB,EACd,GACmE;CACnE,OAAO,EAAkB,CAAC,CAAC,QAAQ,EAAE,sBAAsB,EAAM,IAAI,KAAA;AACvE;AAEA,SAAgB,EAAqB,GAI4B;CAC/D,IAAM,EAAE,OAAO,GAAqB,KAAK,MAAsB,EAAkB;CAcjF,OAXI,MACE,KAAuB,CAAC,EAAQ,kBAClC,QAAQ,KACN,IAAI,EAAQ,KAAK,6EACnB,GACE,KAAqB,CAAC,EAAQ,gBAChC,QAAQ,KACN,IAAI,EAAQ,KAAK,yEACnB,IAGG;EAAE;EAAqB;CAAkB;AAClD"}

package/dist/{components/VCombobox/infiniteScroll.d.ts → composables/useInfiniteScroll.d.ts}

@@ -2,6 +2,12 @@ import { Ref } from 'vue';
 export interface InfiniteScrollOptions {
     /** The marker at the foot of the list. It is absent when there is nothing left to load. */
     sentinelEl: Ref<HTMLElement | null>;
+    /**
+     * The scrolling frame the marker is watched within. Left to the viewport, a marker inside a
+     * panel floating above the page would count as visible from the very first moment, firing a
+     * burst of requests for every page at once.
+     */
+    root: (sentinel: HTMLElement) => Element | null;
     /** Whether a page may be asked for right now: the panel open, more to come, none in flight. */
     canLoad: () => boolean;
     /**

package/dist/{components/VCombobox/infiniteScroll.js → composables/useInfiniteScroll.js}

@@ -1,17 +1,17 @@
 import { watch as e } from "vue";
-//#region src/components/VCombobox/infiniteScroll.ts
+//#region src/composables/useInfiniteScroll.ts
 function t(t) {
 	let n = null, r = !1, i = !1;
 	function a(e) {
 		e.some((e) => e.isIntersecting) && (r || !t.canLoad() || (r = !0, t.onLoadMore()));
 	}
-	return e(t.sentinelEl, (e, t, r) => {
+	return e(t.sentinelEl, (e, r, i) => {
 		if (!e || typeof IntersectionObserver > "u") return;
-		let i = e.closest("[role=\"listbox\"]");
-		i && (n = new IntersectionObserver(a, {
-			root: i,
+		let o = t.root(e);
+		o && (n = new IntersectionObserver(a, {
+			root: o,
 			rootMargin: "0px 0px 50% 0px"
-		}), n.observe(e), r(() => {
+		}), n.observe(e), i(() => {
 			n?.disconnect(), n = null;
 		}));
 	}, { flush: "post" }), e(t.loaded, (e, a) => {
@@ -31,4 +31,4 @@ function t(t) {
 //#endregion
 export { t as useInfiniteScroll };
 
-//# sourceMappingURL=infiniteScroll.js.map
+//# sourceMappingURL=useInfiniteScroll.js.map

package/dist/composables/useInfiniteScroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInfiniteScroll.js","names":[],"sources":["../../src/composables/useInfiniteScroll.ts"],"sourcesContent":["// @core\n/**\n * Observe a list's sentinel to request another page, for VCombobox and VVirtualList; retain\n * ownership of data fetching with the consumer.\n */\nimport { watch, type Ref } from 'vue'\n\nexport interface InfiniteScrollOptions {\n  /** The marker at the foot of the list. It is absent when there is nothing left to load. */\n  sentinelEl: Ref<HTMLElement | null>\n  /**\n   * The scrolling frame the marker is watched within. Left to the viewport, a marker inside a\n   * panel floating above the page would count as visible from the very first moment, firing a\n   * burst of requests for every page at once.\n   */\n  root: (sentinel: HTMLElement) => Element | null\n  /** Whether a page may be asked for right now: the panel open, more to come, none in flight. */\n  canLoad: () => boolean\n  /**\n   * The options loaded so far. A change in their NUMBER is the signal that a page has\n   * arrived; a new array of the same length counts only after `restart`.\n   */\n  loaded: () => readonly unknown[]\n  /** Asks for the next page. */\n  onLoadMore: () => void\n}\n\nexport interface InfiniteScroll {\n  /** Releases the lock that stops two requests overlapping. */\n  reset: () => void\n  /**\n   * Releases the lock and takes the next list handed over as an arrival, whatever its length.\n   * For a new search: the page asked for under the old term never lands, and the new first page\n   * may be exactly as long as the list it replaces.\n   */\n  restart: () => void\n}\n\nexport function useInfiniteScroll(options: InfiniteScrollOptions): InfiniteScroll {\n  let observer: IntersectionObserver | null = null\n  /*\n   * The consumer's loading flag cannot serve: they raise it when their request starts, which is\n   * at best a tick later, and the gap between the two is wide enough for several requests to go\n   * out.\n   */\n  let pending = false\n  let rearm = false\n\n  function onIntersect(entries: IntersectionObserverEntry[]) {\n    if (!entries.some((entry) => entry.isIntersecting)) return\n    if (pending || !options.canLoad()) return\n    pending = true\n    options.onLoadMore()\n  }\n\n  watch(\n    options.sentinelEl,\n    (el, _previous, onCleanup) => {\n      // @fallback\n      // The observer does not exist in the unit-test environment, so its absence has to\n      // be tolerated rather than assumed away; the behaviour is checked in a real\n      // browser.\n      if (!el || typeof IntersectionObserver === 'undefined') return\n      const root = options.root(el)\n      if (!root) return\n      observer = new IntersectionObserver(onIntersect, {\n        root,\n        // The next page is asked for half a frame before the marker is actually reached,\n        // so the list is already growing by the time the reader gets there. It is\n        // expressed as a proportion of the frame rather than as a number of pixels.\n        rootMargin: '0px 0px 50% 0px',\n      })\n      observer.observe(el)\n      onCleanup(() => {\n        observer?.disconnect()\n        observer = null\n      })\n    },\n    { flush: 'post' },\n  )\n\n  // An observer only reports a CROSSING. If the page that arrives is too short to push the\n  // marker out of view, the marker stays visible without ever crossing anything again, and the\n  // loading would stop dead at the second page.\n  watch(options.loaded, (list, previous) => {\n    if (list.length === previous.length && !rearm) return\n    rearm = false\n    pending = false\n    const el = options.sentinelEl.value\n    if (!observer || !el) return\n    observer.unobserve(el)\n    observer.observe(el)\n  })\n\n  return {\n    reset: () => {\n      pending = false\n    },\n    restart: () => {\n      pending = false\n      rearm = true\n    },\n  }\n}\n"],"mappings":";;AAsCA,SAAgB,EAAkB,GAAgD;CAChF,IAAI,IAAwC,MAMxC,IAAU,IACV,IAAQ;CAEZ,SAAS,EAAY,GAAsC;EACpD,EAAQ,MAAM,MAAU,EAAM,cAAc,MAC7C,KAAW,CAAC,EAAQ,QAAQ,MAChC,IAAU,IACV,EAAQ,WAAW;CACrB;CAyCA,OAvCA,EACE,EAAQ,aACP,GAAI,GAAW,MAAc;EAK5B,IAAI,CAAC,KAAM,OAAO,uBAAyB,KAAa;EACxD,IAAM,IAAO,EAAQ,KAAK,CAAE;EACvB,MACL,IAAW,IAAI,qBAAqB,GAAa;GAC/C;GAIA,YAAY;EACd,CAAC,GACD,EAAS,QAAQ,CAAE,GACnB,QAAgB;GAEd,AADA,GAAU,WAAW,GACrB,IAAW;EACb,CAAC;CACH,GACA,EAAE,OAAO,OAAO,CAClB,GAKA,EAAM,EAAQ,SAAS,GAAM,MAAa;EACxC,IAAI,EAAK,WAAW,EAAS,UAAU,CAAC,GAAO;EAE/C,AADA,IAAQ,IACR,IAAU;EACV,IAAM,IAAK,EAAQ,WAAW;EAC1B,CAAC,KAAY,CAAC,MAClB,EAAS,UAAU,CAAE,GACrB,EAAS,QAAQ,CAAE;CACrB,CAAC,GAEM;EACL,aAAa;GACX,IAAU;EACZ;EACA,eAAe;GAEb,AADA,IAAU,IACV,IAAQ;EACV;CACF;AACF"}

package/dist/composables/useListbox.d.ts

@@ -0,0 +1,132 @@
+import { ComputedRef, Ref } from 'vue';
+import { IconSource } from '../components/VIcon/types.js';
+import { ItemValue, ListboxItem, ListboxOption, ListboxOptionSlotProps } from '../types.js';
+import { VirtualList } from './useVirtualList.js';
+/**
+ * The chosen values as a list, whatever the model holds. An empty string is what an emptied
+ * single field says, and it is not a value. A NUMBER is a value even at zero; hence the test on
+ * the empty string alone rather than on falsiness, which would drop the option keyed `0`.
+ */
+export declare function selectionOf(value: ItemValue | ItemValue[], multiple: boolean): ItemValue[];
+type ListboxSize = 'sm' | 'md' | 'lg';
+export interface ListboxOptions {
+    /** What the list offers, as the consumer gave it. */
+    items: () => ListboxItem[];
+    /**
+     * Narrows the flattened options, read inside a computed so it may follow reactive state. Left
+     * out, every option stays.
+     */
+    filter?: (options: ListboxOption[]) => ListboxOption[];
+    /** The chosen values. */
+    selected: () => ItemValue[];
+    /** Whether the panel is showing; the highlight is kept on a valid option only while it is. */
+    open: () => boolean;
+    /** The panel's id, and the prefix of every option's and heading's id. */
+    id: string;
+    /** The scrolling panel, which the virtual mode windows. */
+    panelEl: () => HTMLElement | null;
+    /** Renders only the rows near the visible part of the panel. */
+    virtual: () => boolean;
+    /** More pages are coming, so the last block's size is unknown. */
+    hasMore?: () => boolean;
+    size: () => ListboxSize;
+    compact: () => boolean;
+}
+/** An option the panel renders, with its index in the visible options. */
+export interface ListboxRenderedOption {
+    kind: 'option';
+    key: string;
+    option: ListboxOption;
+    index: number;
+}
+/**
+ * The panel as one flat sequence of rows, the unit the virtual mode windows: a block's name is a
+ * row of its own, above its options. Each row knows its block, so the rows rendered can be
+ * gathered back into their groups. `set` and `position` are the option's place in its block, or
+ * among the options outside any block.
+ */
+type FlatOption = ListboxRenderedOption & {
+    group?: string;
+    set: number;
+    position: number;
+};
+/**
+ * A rendered option with its state worked out, once per row: `row` is what the option element
+ * takes, `slot` what the `#option` slot receives, and both read the same two answers. `at` is
+ * the row's place in the flat sequence, which the virtual mode measures it under.
+ */
+export type ListboxOptionRow = FlatOption & {
+    at: number;
+    row: {
+        id: string;
+        icon?: IconSource;
+        active: boolean;
+        selected: boolean;
+        disabled?: boolean;
+        'aria-setsize'?: number;
+        'aria-posinset'?: number;
+    };
+    slot: ListboxOptionSlotProps;
+};
+export type ListboxRow = ListboxOptionRow | {
+    kind: 'heading';
+    key: string;
+    id: string;
+    label: string;
+    at: number;
+} | {
+    kind: 'separator';
+    key: string;
+    at: number;
+} | {
+    kind: 'spacer';
+    key: string;
+    size: number;
+};
+/** What the panel renders: rows, and blocks of rows gathered under their name. */
+export type ListboxBlock = ListboxRow | {
+    kind: 'group';
+    key: string;
+    label: string;
+    labelId?: string;
+    children: ListboxRow[];
+};
+export interface Listbox {
+    /** Every option, the blocks unwrapped and the separators dropped, in the order given. */
+    allOptions: ComputedRef<ListboxOption[]>;
+    /** The options left by the filter: what the keyboard counts through. */
+    visible: ComputedRef<ListboxOption[]>;
+    /** The selection as a set, so that asking "is this one chosen?" costs nothing. */
+    selectedSet: ComputedRef<Set<ItemValue>>;
+    /** The option holding a value, found among the options or in the memory of chosen ones. */
+    optionOf: (value: ItemValue) => ListboxOption | undefined;
+    /** The label of a value, or the value itself spelled out when no option holds it. */
+    labelOf: (value: ItemValue) => string;
+    /** Keeps an option just chosen in memory, before the parent passes the value back down. */
+    remember: (option: ListboxOption) => void;
+    /** The index of the highlighted option among `visible`, or -1. */
+    activeIndex: Ref<number>;
+    /** The id of the option at an index of `visible`. */
+    optionId: (index: number) => string;
+    /** Highlights the first option that can be chosen, or nothing. */
+    highlightFirst: () => void;
+    /** Highlights the last option that can be chosen, or nothing. */
+    highlightLast: () => void;
+    /** Highlights the first chosen option, or the first that can be chosen. */
+    highlightSelected: () => void;
+    /** Moves the highlight by `delta` options, wrapping around and skipping disabled ones. */
+    move: (delta: number) => void;
+    /**
+     * Moves the highlight by `delta` options without wrapping, the step of Page Up and Page Down:
+     * it stops at the first or last option that can be chosen.
+     */
+    page: (delta: number) => void;
+    /** Highlights the option under the pointer. */
+    hover: (row: ListboxRenderedOption) => void;
+    /** What the panel renders. */
+    blocks: ComputedRef<ListboxBlock[]>;
+    /** Measures a rendered row, in the virtual mode. */
+    measureRow: VirtualList['measure'];
+}
+export declare function useListbox(options: ListboxOptions): Listbox;
+export {};