@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-script-tag.d.mts

@@ -0,0 +1,162 @@
+import { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-script-tag.d.ts
+/** `<script>` subset used by {@link useScriptTag}. */
+interface ScriptTagElement extends EventTarget {
+  /** Read an attribute. */
+  getAttribute(name: string): string | null;
+  /** Write an attribute. */
+  setAttribute(name: string, value: string): void;
+}
+/** Document capability used by {@link useScriptTag}. */
+interface ScriptTagHost {
+  /** Find an existing `<script>` whose `src` attribute equals `src`. */
+  findScript(src: string): ScriptTagElement | undefined;
+  /** Create a detached `<script>`. */
+  createScript(): ScriptTagElement;
+  /** Attach a script to `<head>`, starting its download. */
+  append(element: ScriptTagElement): void;
+  /** Detach a script. */
+  remove(element: ScriptTagElement): void;
+}
+/** Loading state of the script. */
+type ScriptTagStatus = "idle" | "loading" | "loaded" | "error";
+/** Discriminated outcome of {@link ScriptTagControls.load}. */
+type ScriptTagResult = {
+  /** The script executed. */readonly status: "loaded"; /** Script element. */
+  readonly element: ScriptTagElement;
+} | {
+  /** The script failed to load. */readonly status: "error"; /** Script element. */
+  readonly element: ScriptTagElement;
+} | {
+  /** No document is available (server rendering) or the load was superseded. */readonly status: "unsupported" | "cancelled";
+};
+/** Options for {@link useScriptTag}. */
+interface UseScriptTagOptions {
+  /**
+   * Called once the script has loaded.
+   *
+   * @default undefined
+   */
+  readonly onLoaded?: (element: ScriptTagElement) => void;
+  /**
+   * Load when created and whenever `src` changes.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Set the `async` attribute.
+   *
+   * @default true
+   */
+  readonly async?: boolean;
+  /**
+   * Set the `defer` attribute.
+   *
+   * @default false
+   */
+  readonly defer?: boolean;
+  /**
+   * Script `type` (for example `"module"`).
+   *
+   * @default "text/javascript"
+   */
+  readonly type?: string;
+  /**
+   * CORS mode (`crossorigin` attribute).
+   *
+   * @default undefined
+   */
+  readonly crossOrigin?: "anonymous" | "use-credentials";
+  /**
+   * Referrer policy.
+   *
+   * @default undefined
+   */
+  readonly referrerPolicy?: ReferrerPolicy;
+  /**
+   * Set the `nomodule` attribute.
+   *
+   * @default false
+   */
+  readonly noModule?: boolean;
+  /**
+   * CSP nonce.
+   *
+   * @default undefined
+   */
+  readonly nonce?: string;
+  /**
+   * Subresource integrity hash.
+   *
+   * @default undefined
+   */
+  readonly integrity?: string;
+  /**
+   * Additional attributes.
+   *
+   * @default {}
+   */
+  readonly attributes?: Readonly<Record<string, string>>;
+  /**
+   * Remove a script created by this composable when the owning scope stops.
+   *
+   * @default true
+   */
+  readonly removeOnDispose?: boolean;
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document's `<head>`
+   */
+  readonly host?: MaybeRefOrGetter<ScriptTagHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useScriptTag}. */
+interface ScriptTagControls {
+  /** Loading state. */
+  readonly status: Readonly<Ref<ScriptTagStatus>>;
+  /** Script element in use, if any. */
+  readonly element: Readonly<ShallowRef<ScriptTagElement | undefined>>;
+  /**
+   * Load the script (or reuse an existing tag with the same `src`).
+   * Concurrent calls share one load; `unload` and scope disposal resolve a
+   * pending load as `"cancelled"`.
+   *
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly load: () => Promise<ScriptTagResult>;
+  /** Remove a script created by this composable and reset the state. */
+  readonly unload: () => void;
+}
+/**
+ * Inject a `<script>` tag and track its loading state.
+ *
+ * An existing tag with the same `src` is reused instead of duplicated: if
+ * it was created by another `useScriptTag` call its state is shared through
+ * a `data-vize-script-status` attribute; a tag without that attribute (for
+ * example emitted in server-rendered HTML) is assumed to have executed.
+ * Changing the reactive `src` unloads the previous script and, with
+ * `immediate`, loads the new one.
+ *
+ * Server rendering: no document exists, so nothing is injected, `status`
+ * stays `"idle"`, and `load` resolves `"unsupported"`. Emit server-side
+ * script tags through the application's head manager. Scripts created by
+ * this composable are removed when the owning scope stops (configurable);
+ * already-executed code cannot be unloaded.
+ *
+ * @example
+ * ```ts
+ * const { status } = useScriptTag("https://example.com/widget.js", {
+ *   onLoaded: () => window.Widget.init(),
+ * });
+ * ```
+ *
+ * @param src Reactive script URL.
+ * @param options Attributes, lifecycle, and capability.
+ * @default options {}
+ * @returns Loading state and actions.
+ */
+declare function useScriptTag(src: MaybeRefOrGetter<string>, options?: UseScriptTagOptions): ScriptTagControls;
+//#endregion
+export { ScriptTagControls, ScriptTagElement, ScriptTagHost, ScriptTagResult, ScriptTagStatus, UseScriptTagOptions, useScriptTag };

package/dist/use-script-tag.mjs

@@ -0,0 +1,171 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/use-script-tag.ts
+const STATUS_ATTRIBUTE = "data-vize-script-status";
+function browserScriptHost() {
+	if (typeof window === "undefined") return void 0;
+	const { document, HTMLScriptElement, CSS } = window;
+	return {
+		findScript: (src) => {
+			const found = document.querySelector(`script[src="${CSS.escape(src)}"]`);
+			return found instanceof HTMLScriptElement ? found : void 0;
+		},
+		createScript: () => document.createElement("script"),
+		append: (element) => {
+			if (element instanceof HTMLScriptElement) document.head.append(element);
+		},
+		remove: (element) => {
+			if (element instanceof HTMLScriptElement) element.remove();
+		}
+	};
+}
+/**
+* Inject a `<script>` tag and track its loading state.
+*
+* An existing tag with the same `src` is reused instead of duplicated: if
+* it was created by another `useScriptTag` call its state is shared through
+* a `data-vize-script-status` attribute; a tag without that attribute (for
+* example emitted in server-rendered HTML) is assumed to have executed.
+* Changing the reactive `src` unloads the previous script and, with
+* `immediate`, loads the new one.
+*
+* Server rendering: no document exists, so nothing is injected, `status`
+* stays `"idle"`, and `load` resolves `"unsupported"`. Emit server-side
+* script tags through the application's head manager. Scripts created by
+* this composable are removed when the owning scope stops (configurable);
+* already-executed code cannot be unloaded.
+*
+* @example
+* ```ts
+* const { status } = useScriptTag("https://example.com/widget.js", {
+*   onLoaded: () => window.Widget.init(),
+* });
+* ```
+*
+* @param src Reactive script URL.
+* @param options Attributes, lifecycle, and capability.
+* @default options {}
+* @returns Loading state and actions.
+*/
+function useScriptTag(src, options = {}) {
+	const status = ref("idle");
+	const element = shallowRef(void 0);
+	let created = false;
+	let pending;
+	let generation = 0;
+	let cancelWait;
+	const resolveHost = () => options.host === void 0 ? browserScriptHost() : toValue(options.host) ?? void 0;
+	const configure = (script, url) => {
+		script.setAttribute("type", options.type ?? "text/javascript");
+		if (options.async ?? true) script.setAttribute("async", "");
+		if (options.defer ?? false) script.setAttribute("defer", "");
+		if (options.noModule ?? false) script.setAttribute("nomodule", "");
+		if (options.crossOrigin !== void 0) script.setAttribute("crossorigin", options.crossOrigin);
+		if (options.referrerPolicy !== void 0) script.setAttribute("referrerpolicy", options.referrerPolicy);
+		if (options.nonce !== void 0) script.setAttribute("nonce", options.nonce);
+		if (options.integrity !== void 0) script.setAttribute("integrity", options.integrity);
+		for (const [name, value] of Object.entries(options.attributes ?? {})) script.setAttribute(name, value);
+		script.setAttribute(STATUS_ATTRIBUTE, "loading");
+		script.setAttribute("src", url);
+	};
+	const waitFor = (script, current) => new Promise((resolve) => {
+		const finish = (outcome) => {
+			cancelWait = void 0;
+			script.removeEventListener("load", onLoad);
+			script.removeEventListener("error", onError);
+			script.setAttribute(STATUS_ATTRIBUTE, outcome);
+			if (current !== generation) {
+				resolve({ status: "cancelled" });
+				return;
+			}
+			status.value = outcome;
+			if (outcome === "loaded") options.onLoaded?.(script);
+			resolve({
+				status: outcome,
+				element: script
+			});
+		};
+		const onLoad = () => finish("loaded");
+		const onError = () => finish("error");
+		script.addEventListener("load", onLoad);
+		script.addEventListener("error", onError);
+		cancelWait = () => {
+			script.removeEventListener("load", onLoad);
+			script.removeEventListener("error", onError);
+			resolve({ status: "cancelled" });
+		};
+	});
+	const load = () => {
+		if (pending) return pending;
+		const host = resolveHost();
+		if (!host) return Promise.resolve({ status: "unsupported" });
+		const current = generation;
+		const url = toValue(src);
+		const existing = host.findScript(url);
+		if (existing) {
+			element.value = existing;
+			const state = existing.getAttribute(STATUS_ATTRIBUTE);
+			if (state === null || state === "loaded") {
+				status.value = "loaded";
+				options.onLoaded?.(existing);
+				return Promise.resolve({
+					status: "loaded",
+					element: existing
+				});
+			}
+			if (state === "error") {
+				status.value = "error";
+				return Promise.resolve({
+					status: "error",
+					element: existing
+				});
+			}
+		}
+		const script = existing ?? host.createScript();
+		status.value = "loading";
+		element.value = script;
+		const settled = waitFor(script, current).finally(() => {
+			if (pending === settled) pending = void 0;
+		});
+		pending = settled;
+		if (!existing) {
+			created = true;
+			configure(script, url);
+			host.append(script);
+		}
+		return settled;
+	};
+	const unload = () => {
+		generation += 1;
+		pending = void 0;
+		cancelWait?.();
+		cancelWait = void 0;
+		const script = element.value;
+		if (script && created) resolveHost()?.remove(script);
+		created = false;
+		element.value = void 0;
+		status.value = "idle";
+	};
+	if (options.immediate ?? true) watch(() => toValue(src), (_next, previous) => {
+		if (previous !== void 0) unload();
+		load();
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	tryOnScopeDispose(() => {
+		if (options.removeOnDispose ?? true) unload();
+		else {
+			generation += 1;
+			cancelWait?.();
+		}
+	});
+	return {
+		status: readonly(status),
+		element,
+		load,
+		unload
+	};
+}
+//#endregion
+export { useScriptTag };

package/dist/use-segmenter.d.mts

@@ -0,0 +1,78 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-segmenter.d.ts
+/** Segmentation units supported by `Intl.Segmenter`. */
+type SegmenterGranularity = "grapheme" | "word" | "sentence";
+/** One segment of the text. */
+interface TextSegment {
+  /** Segment text. */
+  readonly segment: string;
+  /** UTF-16 code-unit offset of the segment in the source text. */
+  readonly index: number;
+  /** Word granularity: whether the segment is a word (not spaces or punctuation). */
+  readonly isWordLike: boolean;
+}
+/** Options for {@link useSegmenter}. */
+interface UseSegmenterOptions {
+  /**
+   * Segmentation unit exposed through `segments` and `count`.
+   *
+   * @default "grapheme"
+   */
+  readonly granularity?: SegmenterGranularity;
+  /**
+   * Locale whose segmentation rules are used (word boundaries in Japanese or
+   * Thai depend on it). Pass it explicitly for hydration-stable output.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+/** Reactive segmentation returned by {@link useSegmenter}. */
+interface SegmenterControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+  /** Segments at the configured granularity. */
+  readonly segments: ComputedRef<readonly TextSegment[]>;
+  /** Number of segments at the configured granularity. */
+  readonly count: ComputedRef<number>;
+  /** User-perceived characters (grapheme clusters), independent of granularity. */
+  readonly graphemeCount: ComputedRef<number>;
+  /** Word-like segments, independent of granularity. */
+  readonly wordCount: ComputedRef<number>;
+  /**
+   * Truncate the text to at most `maxGraphemes` user-perceived characters,
+   * never splitting an emoji or combining sequence.
+   *
+   * @param maxGraphemes Maximum grapheme clusters kept, including the ellipsis.
+   * @param ellipsis Appended when the text was shortened.
+   * @default ellipsis "…"
+   * @returns The possibly truncated text.
+   * @throws {RangeError} `[VIZE_COMPOSE_SEGMENTER_INVALID_LENGTH]` for a
+   * negative or non-integer length.
+   */
+  readonly truncate: (maxGraphemes: number, ellipsis?: string) => string;
+}
+/**
+ * Split text into graphemes, words, or sentences with `Intl.Segmenter`.
+ *
+ * Counts reflect what users perceive: `"👨‍👩‍👧"` is one grapheme, and
+ * word counts skip spaces and punctuation while handling languages without
+ * spaces (Japanese, Thai) through the locale. `truncate` shortens text
+ * without splitting clusters. Derived state only; deterministic during
+ * server rendering when the locale is explicit.
+ *
+ * @example
+ * ```ts
+ * const { graphemeCount, truncate } = useSegmenter(bio, { locale: "en" });
+ * const remaining = computed(() => 160 - graphemeCount.value);
+ * ```
+ *
+ * @param text Reactive text.
+ * @param options Reactive granularity and locale.
+ * @default options {}
+ * @returns Reactive segments, counts, and truncation.
+ */
+declare function useSegmenter(text: MaybeRefOrGetter<string>, options?: MaybeRefOrGetter<UseSegmenterOptions>): SegmenterControls;
+//#endregion
+export { SegmenterControls, SegmenterGranularity, TextSegment, UseSegmenterOptions, useSegmenter };

package/dist/use-segmenter.mjs

@@ -0,0 +1,66 @@
+import { useLocale } from "./locale.mjs";
+import { computed, toValue } from "vue";
+//#region src/use-segmenter.ts
+function browserLanguage() {
+	return typeof window === "undefined" ? void 0 : window.navigator.language;
+}
+function toSegments(segmenter, text) {
+	return Array.from(segmenter.segment(text), (data) => ({
+		segment: data.segment,
+		index: data.index,
+		isWordLike: data.isWordLike ?? false
+	}));
+}
+/**
+* Split text into graphemes, words, or sentences with `Intl.Segmenter`.
+*
+* Counts reflect what users perceive: `"👨‍👩‍👧"` is one grapheme, and
+* word counts skip spaces and punctuation while handling languages without
+* spaces (Japanese, Thai) through the locale. `truncate` shortens text
+* without splitting clusters. Derived state only; deterministic during
+* server rendering when the locale is explicit.
+*
+* @example
+* ```ts
+* const { graphemeCount, truncate } = useSegmenter(bio, { locale: "en" });
+* const remaining = computed(() => 160 - graphemeCount.value);
+* ```
+*
+* @param text Reactive text.
+* @param options Reactive granularity and locale.
+* @default options {}
+* @returns Reactive segments, counts, and truncation.
+*/
+function useSegmenter(text, options = {}) {
+	const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+	const segmenterFor = (granularity) => computed(() => new Intl.Segmenter(localeControls.locale.value, { granularity }));
+	const graphemes = segmenterFor("grapheme");
+	const words = segmenterFor("word");
+	const sentences = segmenterFor("sentence");
+	const graphemeSegments = computed(() => toSegments(graphemes.value, toValue(text)));
+	const wordSegments = computed(() => toSegments(words.value, toValue(text)));
+	const segments = computed(() => {
+		const granularity = toValue(options).granularity ?? "grapheme";
+		if (granularity === "grapheme") return graphemeSegments.value;
+		if (granularity === "word") return wordSegments.value;
+		return toSegments(sentences.value, toValue(text));
+	});
+	const truncate = (maxGraphemes, ellipsis = "…") => {
+		if (!Number.isSafeInteger(maxGraphemes) || maxGraphemes < 0) throw new RangeError(`[VIZE_COMPOSE_SEGMENTER_INVALID_LENGTH] maxGraphemes must be a non-negative integer; received ${String(maxGraphemes)}`);
+		const all = graphemeSegments.value;
+		if (all.length <= maxGraphemes) return toValue(text);
+		const ellipsisLength = toSegments(graphemes.value, ellipsis).length;
+		const keep = Math.max(0, maxGraphemes - ellipsisLength);
+		return all.slice(0, keep).map((segment) => segment.segment).join("") + (maxGraphemes >= ellipsisLength ? ellipsis : "");
+	};
+	return {
+		locale: localeControls.locale,
+		segments,
+		count: computed(() => segments.value.length),
+		graphemeCount: computed(() => graphemeSegments.value.length),
+		wordCount: computed(() => wordSegments.value.filter((segment) => segment.isWordLike).length),
+		truncate
+	};
+}
+//#endregion
+export { useSegmenter };

package/dist/use-selection.d.mts

@@ -0,0 +1,125 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-selection.d.ts
+/** Options for {@link useSelection}. */
+interface UseSelectionOptions<Item, Key, Multiple extends boolean> {
+  /** Selectable items, in display order. Reactive. */
+  readonly items: MaybeRefOrGetter<readonly Item[]>;
+  /**
+   * Allow several selected items.
+   *
+   * @default false
+   */
+  readonly multiple?: Multiple;
+  /**
+   * Stable identity of an item, for example its id. Keys survive item
+   * objects being replaced (refetches, immutable updates).
+   *
+   * @default the item itself
+   */
+  readonly getKey?: (item: Item) => Key;
+  /**
+   * Keys selected initially.
+   *
+   * @default []
+   */
+  readonly initial?: readonly Key[];
+  /**
+   * Maximum number of selected items in multiple mode; selecting beyond it
+   * is refused.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly max?: number;
+  /**
+   * Refuse to deselect the last selected item.
+   *
+   * @default false
+   */
+  readonly required?: boolean;
+  /**
+   * Veto selecting an item (for example disabled rows).
+   *
+   * @default undefined (every item is selectable)
+   */
+  readonly isSelectable?: (item: Item) => boolean;
+}
+/** Selection state and commands returned by {@link useSelection}. */
+interface Selection<Item, Key, Multiple extends boolean> {
+  /** Selected keys in selection order. */
+  readonly selectedKeys: Readonly<ShallowRef<readonly Key[]>>;
+  /**
+   * Selected items in `items` order: an array in multiple mode, the single
+   * item (or `undefined`) otherwise. Keys whose item is currently absent are
+   * kept but not listed.
+   */
+  readonly selected: ComputedRef<Multiple extends true ? Item[] : Item | undefined>;
+  /** Number of selected keys. */
+  readonly count: ComputedRef<number>;
+  /** Whether every selectable item is selected (multiple mode). */
+  readonly isAllSelected: ComputedRef<boolean>;
+  /** Whether some but not all selectable items are selected (tri-state checkboxes). */
+  readonly isIndeterminate: ComputedRef<boolean>;
+  /** Item that anchors range selection (the last explicitly selected one). */
+  readonly anchor: Readonly<ShallowRef<Key | undefined>>;
+  /** Whether `item` is selected. */
+  readonly isSelected: (item: Item) => boolean;
+  /**
+   * Select `item` (replacing the selection in single mode).
+   *
+   * @returns Whether the selection changed.
+   */
+  readonly select: (item: Item) => boolean;
+  /**
+   * Deselect `item`.
+   *
+   * @returns Whether the selection changed.
+   */
+  readonly deselect: (item: Item) => boolean;
+  /**
+   * Toggle `item`.
+   *
+   * @returns Whether the selection changed.
+   */
+  readonly toggle: (item: Item) => boolean;
+  /**
+   * Select exactly `item`.
+   *
+   * @returns Whether the selection changed.
+   */
+  readonly selectOnly: (item: Item) => boolean;
+  /**
+   * Select every item between the anchor and `item` inclusive
+   * (shift-click); in single mode this selects `item`.
+   *
+   * @returns Whether the selection changed.
+   */
+  readonly extendTo: (item: Item) => boolean;
+  /** Select every selectable item, up to `max` (multiple mode). */
+  readonly selectAll: () => void;
+  /** Clear the selection (ignores `required`). */
+  readonly clear: () => void;
+}
+/**
+ * Generic single- or multi-select state for lists, tables, and grids.
+ *
+ * Keys (from `getKey`, the item itself by default) identify items, so the
+ * selection survives items being replaced. `multiple: true` switches the
+ * `selected` type to an array; `max`, `required`, and `isSelectable`
+ * constrain changes, and `extendTo` implements shift-click ranges from the
+ * anchor in display order. Synchronous state: SSR-safe and nothing to
+ * dispose.
+ *
+ * @example
+ * ```ts
+ * const rows = useSelection({ items: users, multiple: true, getKey: (user) => user.id });
+ * rows.toggle(user);
+ * rows.extendTo(other); // shift-click
+ * ```
+ *
+ * @param options Items, mode, identity, and constraints.
+ * @returns Selection state and commands.
+ */
+declare function useSelection<Item, Key = Item, const Multiple extends boolean = false>(options: UseSelectionOptions<Item, Key, Multiple>): Selection<Item, Key, Multiple>;
+//#endregion
+export { Selection, UseSelectionOptions, useSelection };

package/dist/use-selection.mjs

@@ -0,0 +1,77 @@
+import { computed, shallowRef, toValue } from "vue";
+//#region src/use-selection.ts
+function useSelection(options) {
+	const multiple = options.multiple ?? false;
+	const max = multiple ? options.max ?? Number.POSITIVE_INFINITY : 1;
+	const keyOf = options.getKey ?? ((item) => item);
+	const selectable = options.isSelectable ?? (() => true);
+	const selectedKeys = shallowRef((options.initial ?? []).slice(0, max));
+	const anchor = shallowRef(selectedKeys.value.at(-1));
+	const items = computed(() => toValue(options.items));
+	const has = (key) => selectedKeys.value.includes(key);
+	const commit = (next) => {
+		const current = selectedKeys.value;
+		if (next.length === current.length && next.every((key, index) => key === current[index])) return false;
+		selectedKeys.value = next;
+		return true;
+	};
+	const select = (item) => {
+		if (!selectable(item)) return false;
+		const key = keyOf(item);
+		anchor.value = key;
+		if (!multiple) return commit([key]);
+		if (has(key) || selectedKeys.value.length >= max) return false;
+		return commit([...selectedKeys.value, key]);
+	};
+	const deselect = (item) => {
+		const key = keyOf(item);
+		if (!has(key)) return false;
+		if ((options.required ?? false) && selectedKeys.value.length === 1) return false;
+		return commit(selectedKeys.value.filter((candidate) => candidate !== key));
+	};
+	const selectableKeys = computed(() => items.value.filter(selectable).map(keyOf));
+	const selectedItems = computed(() => items.value.filter((item) => has(keyOf(item))));
+	return {
+		selectedKeys,
+		selected: computed(() => multiple ? selectedItems.value : selectedItems.value[0]),
+		count: computed(() => selectedKeys.value.length),
+		isAllSelected: computed(() => selectableKeys.value.length > 0 && selectableKeys.value.every((key) => has(key))),
+		isIndeterminate: computed(() => {
+			const chosen = selectableKeys.value.filter((key) => has(key)).length;
+			return chosen > 0 && chosen < selectableKeys.value.length;
+		}),
+		anchor,
+		isSelected: (item) => has(keyOf(item)),
+		select,
+		deselect,
+		toggle: (item) => has(keyOf(item)) ? deselect(item) : select(item),
+		selectOnly: (item) => {
+			if (!selectable(item)) return false;
+			anchor.value = keyOf(item);
+			return commit([keyOf(item)]);
+		},
+		extendTo: (item) => {
+			if (!multiple) return select(item);
+			const keys = items.value.map(keyOf);
+			const from = keys.indexOf(anchor.value);
+			const to = keys.indexOf(keyOf(item));
+			if (to === -1) return false;
+			if (from === -1) return select(item);
+			const [start, end] = from <= to ? [from, to] : [to, from];
+			const range = items.value.slice(start, end + 1).filter(selectable).map(keyOf).filter((key) => !has(key));
+			const room = Math.max(0, max - selectedKeys.value.length);
+			return commit([...selectedKeys.value, ...range.slice(0, room)]);
+		},
+		selectAll: () => {
+			if (!multiple) return;
+			const missing = selectableKeys.value.filter((key) => !has(key));
+			const room = Math.max(0, max - selectedKeys.value.length);
+			commit([...selectedKeys.value, ...missing.slice(0, room)]);
+		},
+		clear: () => {
+			commit([]);
+		}
+	};
+}
+//#endregion
+export { useSelection };