@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-service-worker.mjs

@@ -0,0 +1,178 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowReadonly, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-service-worker.ts
+const emptyStates = {
+	installing: null,
+	waiting: null,
+	active: null
+};
+function browserContainer() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator } = window;
+	return "serviceWorker" in navigator && navigator.serviceWorker ? navigator.serviceWorker : void 0;
+}
+/**
+* Register a service worker and follow its update lifecycle.
+*
+* Tracks `updatefound` and each worker's `statechange` so `state` mirrors
+* the installing, waiting and active workers. `updateAvailable` turns true
+* once an installed worker waits while another one controls the page;
+* `skipWaiting()` then posts the configured message to it, and
+* `onControllerChange` runs once it takes control. Listeners are removed
+* when the owning reactive scope stops; outside a scope they live as long as
+* the registration.
+*
+* Server rendering: nothing is registered, `supported` is false and every
+* state is `null`.
+*
+* @example
+* ```ts
+* const sw = useServiceWorker("/sw.js", {
+*   onControllerChange: () => window.location.reload(),
+* });
+* const applyUpdate = () => sw.skipWaiting();
+* ```
+*
+* @param scriptUrl Service worker script URL.
+* @param options Container override, registration options and update hooks.
+* @default options {}
+* @returns Registration state and actions.
+*/
+function useServiceWorker(scriptUrl, options = {}) {
+	const registration = shallowRef(null);
+	const state = ref(emptyStates);
+	const controller = shallowRef(null);
+	const error = shallowRef(void 0);
+	const watched = /* @__PURE__ */ new Set();
+	let active = true;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveContainer = () => !hydrated.value ? void 0 : options.container === void 0 ? browserContainer() : toValue(options.container) ?? void 0;
+	const sync = () => {
+		const current = registration.value;
+		if (!current) {
+			state.value = emptyStates;
+			return;
+		}
+		for (const worker of [
+			current.installing,
+			current.waiting,
+			current.active
+		]) if (worker && !watched.has(worker)) {
+			watched.add(worker);
+			worker.addEventListener("statechange", sync);
+		}
+		state.value = {
+			installing: current.installing?.state ?? null,
+			waiting: current.waiting?.state ?? null,
+			active: current.active?.state ?? null
+		};
+	};
+	const unwatchWorkers = () => {
+		for (const worker of watched) worker.removeEventListener("statechange", sync);
+		watched.clear();
+	};
+	watch(registration, (current, _previous, onCleanup) => {
+		sync();
+		if (!current) return;
+		current.addEventListener("updatefound", sync);
+		onCleanup(() => {
+			current.removeEventListener("updatefound", sync);
+			unwatchWorkers();
+		});
+	}, { flush: "sync" });
+	watch(resolveContainer, (container, _previous, onCleanup) => {
+		controller.value = container?.controller ?? null;
+		if (!container) return;
+		const onChange = () => {
+			controller.value = container.controller;
+			sync();
+			options.onControllerChange?.(container.controller);
+		};
+		container.addEventListener("controllerchange", onChange);
+		onCleanup(() => container.removeEventListener("controllerchange", onChange));
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const register = async () => {
+		const container = resolveContainer();
+		if (!container) return null;
+		const registerOptions = {};
+		if (options.scope !== void 0) registerOptions.scope = options.scope;
+		if (options.type !== void 0) registerOptions.type = options.type;
+		if (options.updateViaCache !== void 0) registerOptions.updateViaCache = options.updateViaCache;
+		try {
+			const next = await container.register(toValue(scriptUrl), registerOptions);
+			if (!active) return next;
+			registration.value = next;
+			error.value = void 0;
+			return next;
+		} catch (cause) {
+			if (active) error.value = cause;
+			return null;
+		}
+	};
+	const update = async () => {
+		const current = registration.value;
+		if (!current) return false;
+		try {
+			await current.update();
+			error.value = void 0;
+			sync();
+			return true;
+		} catch (cause) {
+			error.value = cause;
+			return false;
+		}
+	};
+	const skipWaiting = () => {
+		const waiting = registration.value?.waiting;
+		if (!waiting) return false;
+		waiting.postMessage("skipWaitingMessage" in options ? options.skipWaitingMessage : { type: "SKIP_WAITING" });
+		return true;
+	};
+	const unregister = async () => {
+		const current = registration.value;
+		if (!current) return false;
+		try {
+			const removed = await current.unregister();
+			if (removed) registration.value = null;
+			error.value = void 0;
+			return removed;
+		} catch (cause) {
+			error.value = cause;
+			return false;
+		}
+	};
+	if (options.immediate ?? true) {
+		let registered = false;
+		watch(() => resolveContainer() !== void 0, (ready) => {
+			if (!ready || registered) return;
+			registered = true;
+			register();
+		}, {
+			immediate: true,
+			flush: "sync"
+		});
+	}
+	tryOnScopeDispose(() => {
+		active = false;
+		registration.value = null;
+	});
+	return {
+		supported: computed(() => resolveContainer() !== void 0),
+		registration: shallowReadonly(registration),
+		state: readonly(state),
+		updateAvailable: computed(() => state.value.waiting !== null && controller.value !== null),
+		error: readonly(error),
+		register,
+		update,
+		skipWaiting,
+		unregister
+	};
+}
+//#endregion
+export { useServiceWorker };

package/dist/use-set.d.mts

@@ -0,0 +1,96 @@
+import { ComputedRef } from "vue";
+
+//#region src/use-set.d.ts
+/** Reactive set wrapper returned by {@link useSet}. */
+interface SetControls<Item> {
+  /**
+   * Read-only reactive view of the set. `has`, iteration, and `size` on this
+   * view are tracked. Members are stored shallowly.
+   */
+  readonly set: ReadonlySet<Item>;
+  /** Number of members. */
+  readonly size: ComputedRef<number>;
+  /** Snapshot of the members in insertion order. */
+  readonly values: ComputedRef<readonly Item[]>;
+  /**
+   * Whether `item` is a member. Reactive when read inside an effect.
+   *
+   * @param item Candidate member.
+   * @returns Whether it is present.
+   */
+  readonly has: (item: Item) => boolean;
+  /**
+   * Add `item`.
+   *
+   * @param item Member to add.
+   * @returns Whether it was newly added.
+   */
+  readonly add: (item: Item) => boolean;
+  /**
+   * Remove `item`.
+   *
+   * @param item Member to remove.
+   * @returns Whether it was removed.
+   */
+  readonly delete: (item: Item) => boolean;
+  /**
+   * Add `item` when absent and remove it when present, or force membership.
+   * Passing an explicit `undefined` behaves like passing no argument.
+   *
+   * @param item Member to toggle.
+   * @param force Membership to force instead of inverting.
+   * @returns Whether `item` is a member afterwards.
+   */
+  readonly toggle: (item: Item, force?: boolean) => boolean;
+  /** Remove every member. */
+  readonly clear: () => void;
+  /**
+   * Members of this set or `other`.
+   *
+   * @param other Items to combine with.
+   * @returns A new, non-reactive set.
+   */
+  readonly union: (other: Iterable<Item>) => Set<Item>;
+  /**
+   * Members of this set that are also in `other`.
+   *
+   * @param other Items to intersect with.
+   * @returns A new, non-reactive set.
+   */
+  readonly intersection: (other: Iterable<Item>) => Set<Item>;
+  /**
+   * Members of this set that are not in `other`.
+   *
+   * @param other Items to subtract.
+   * @returns A new, non-reactive set.
+   */
+  readonly difference: (other: Iterable<Item>) => Set<Item>;
+  /** Restore the creation-time members. */
+  readonly reset: () => void;
+}
+/**
+ * Create a reactive `Set` with typed helpers.
+ *
+ * The member type is inferred from the initial items (`useSet(["a"])` is a
+ * `Set<string>`); pass a type argument for an initially empty set.
+ * Membership checks are tracked per item. The set-algebra helpers return
+ * new plain sets and do not require ES2025 `Set` methods.
+ *
+ * Purely synchronous state: safe during server rendering (no host globals,
+ * no timers) and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const selected = useSet<number>();
+ * selected.toggle(3); // true
+ * selected.has(3); // true
+ * ```
+ *
+ * @typeParam Item Member type, inferred from `initial`.
+ * @param initial Members added at creation and restored by `reset`.
+ * @default initial []
+ * @returns The reactive set and its helpers.
+ */
+declare function useSet<Item = unknown>(initial?: Iterable<Item>): SetControls<Item>;
+//#endregion
+export { SetControls, useSet };

package/dist/use-set.mjs

@@ -0,0 +1,74 @@
+import { computed, shallowReactive, shallowReadonly } from "vue";
+//#region src/use-set.ts
+/**
+* Create a reactive `Set` with typed helpers.
+*
+* The member type is inferred from the initial items (`useSet(["a"])` is a
+* `Set<string>`); pass a type argument for an initially empty set.
+* Membership checks are tracked per item. The set-algebra helpers return
+* new plain sets and do not require ES2025 `Set` methods.
+*
+* Purely synchronous state: safe during server rendering (no host globals,
+* no timers) and nothing to dispose.
+*
+* @example
+* ```ts
+* const selected = useSet<number>();
+* selected.toggle(3); // true
+* selected.has(3); // true
+* ```
+*
+* @typeParam Item Member type, inferred from `initial`.
+* @param initial Members added at creation and restored by `reset`.
+* @default initial []
+* @returns The reactive set and its helpers.
+*/
+function useSet(initial = []) {
+	const baseline = [...initial];
+	const set = shallowReactive(new Set(baseline));
+	const add = (item) => {
+		if (set.has(item)) return false;
+		set.add(item);
+		return true;
+	};
+	return {
+		set: shallowReadonly(set),
+		size: computed(() => set.size),
+		values: computed(() => [...set.values()]),
+		has: (item) => set.has(item),
+		add,
+		delete: (item) => set.delete(item),
+		toggle: (item, force) => {
+			const next = force ?? !set.has(item);
+			if (next) add(item);
+			else set.delete(item);
+			return next;
+		},
+		clear: () => {
+			set.clear();
+		},
+		union: (other) => {
+			const result = new Set(set);
+			for (const item of other) result.add(item);
+			return result;
+		},
+		intersection: (other) => {
+			const lookup = new Set(other);
+			const result = /* @__PURE__ */ new Set();
+			for (const item of set) if (lookup.has(item)) result.add(item);
+			return result;
+		},
+		difference: (other) => {
+			const lookup = new Set(other);
+			const result = /* @__PURE__ */ new Set();
+			for (const item of set) if (!lookup.has(item)) result.add(item);
+			return result;
+		},
+		reset: () => {
+			set.clear();
+			for (const item of baseline) set.add(item);
+		}
+	};
+}
+//#endregion
+export { useSet };

package/dist/use-share.d.mts

@@ -0,0 +1,92 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-share.d.ts
+/** Data shared through the Web Share API. */
+interface ShareDataLike {
+  /** Title of the shared content. */
+  readonly title?: string;
+  /** Body text of the shared content. */
+  readonly text?: string;
+  /** URL of the shared content. */
+  readonly url?: string;
+  /** Files to share (Level 2 of the Web Share API). */
+  readonly files?: File[];
+}
+/** Minimal Web Share capability (`navigator`). */
+interface ShareHost {
+  /** Open the platform share sheet. */
+  share(data: ShareDataLike): Promise<void>;
+  /** Whether the platform can share `data`. Absent in older engines. */
+  canShare?(data?: ShareDataLike): boolean;
+}
+/** Discriminated outcome of {@link ShareControls.share}. */
+type ShareResult = {
+  /** The share sheet completed. */readonly status: "shared"; /** Data that was shared. */
+  readonly data: ShareDataLike;
+} | {
+  /**
+   * `"cancelled"`: the user dismissed the sheet (AbortError).
+   * `"unsupported"`: no Web Share capability.
+   * `"invalid"`: the platform cannot share this data (canShare / TypeError).
+   * `"not-allowed"`: no transient user activation or blocked by policy.
+   * `"failed"`: any other failure.
+   */
+  readonly status: "cancelled" | "unsupported" | "invalid" | "not-allowed" | "failed"; /** Exact error thrown by the host, when one was thrown. */
+  readonly error: unknown;
+};
+/** Options for {@link useShare}. */
+interface UseShareOptions {
+  /**
+   * Web Share capability for alternate runtimes and tests.
+   *
+   * @default window.navigator when it implements `share`
+   */
+  readonly host?: MaybeRefOrGetter<ShareHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useShare}. */
+interface ShareControls {
+  /** Whether the Web Share API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether a share sheet opened by this composable is currently open. */
+  readonly sharing: Readonly<Ref<boolean>>;
+  /**
+   * Whether the platform can share the given (or default) data.
+   *
+   * @param data Data merged over the defaults.
+   * @returns `false` when unsupported.
+   */
+  readonly canShare: (data?: ShareDataLike) => boolean;
+  /**
+   * Open the share sheet. Must run inside a user gesture in browsers.
+   *
+   * @param overrides Data merged over the defaults.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly share: (overrides?: ShareDataLike) => Promise<ShareResult>;
+}
+/**
+ * Share text, links, and files through the platform share sheet.
+ *
+ * Reactive defaults are merged with per-call overrides. Outcomes are
+ * reported as a discriminated {@link ShareResult}, so a user dismissing the
+ * sheet (`"cancelled"`) is distinguishable from missing support or invalid
+ * data without try/catch.
+ *
+ * Server rendering: no capability is resolved, `supported` is false, and
+ * nothing is shared. No resources are retained, so nothing needs cleanup.
+ *
+ * @example
+ * ```ts
+ * const { share, supported } = useShare(() => ({ title: document.title, url: location.href }));
+ * const onClick = () => share();
+ * ```
+ *
+ * @param defaults Reactive default share data.
+ * @param options Web Share capability.
+ * @default defaults {}
+ * @default options {}
+ * @returns Share state and actions.
+ */
+declare function useShare(defaults?: MaybeRefOrGetter<ShareDataLike>, options?: UseShareOptions): ShareControls;
+//#endregion
+export { ShareControls, ShareDataLike, ShareHost, ShareResult, UseShareOptions, useShare };

package/dist/use-share.mjs

@@ -0,0 +1,99 @@
+import { computed, readonly, ref, toValue } from "vue";
+//#region src/use-share.ts
+function browserShareHost() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator } = window;
+	return typeof navigator.share === "function" ? navigator : void 0;
+}
+function errorName(error) {
+	return typeof error === "object" && error !== null && "name" in error ? String(error.name) : void 0;
+}
+/**
+* Share text, links, and files through the platform share sheet.
+*
+* Reactive defaults are merged with per-call overrides. Outcomes are
+* reported as a discriminated {@link ShareResult}, so a user dismissing the
+* sheet (`"cancelled"`) is distinguishable from missing support or invalid
+* data without try/catch.
+*
+* Server rendering: no capability is resolved, `supported` is false, and
+* nothing is shared. No resources are retained, so nothing needs cleanup.
+*
+* @example
+* ```ts
+* const { share, supported } = useShare(() => ({ title: document.title, url: location.href }));
+* const onClick = () => share();
+* ```
+*
+* @param defaults Reactive default share data.
+* @param options Web Share capability.
+* @default defaults {}
+* @default options {}
+* @returns Share state and actions.
+*/
+function useShare(defaults = {}, options = {}) {
+	const sharing = ref(false);
+	const resolveHost = () => options.host === void 0 ? browserShareHost() : toValue(options.host) ?? void 0;
+	const merge = (data) => ({
+		...toValue(defaults),
+		...data
+	});
+	const canShare = (data) => {
+		const host = resolveHost();
+		if (!host) return false;
+		if (!host.canShare) return true;
+		try {
+			return host.canShare(merge(data));
+		} catch {
+			return false;
+		}
+	};
+	const share = async (overrides) => {
+		const host = resolveHost();
+		if (!host) return {
+			status: "unsupported",
+			error: void 0
+		};
+		const data = merge(overrides);
+		if (host.canShare && !canShare(overrides)) return {
+			status: "invalid",
+			error: void 0
+		};
+		sharing.value = true;
+		try {
+			await host.share(data);
+			return {
+				status: "shared",
+				data
+			};
+		} catch (error) {
+			const name = errorName(error);
+			if (name === "AbortError") return {
+				status: "cancelled",
+				error
+			};
+			if (name === "NotAllowedError") return {
+				status: "not-allowed",
+				error
+			};
+			if (name === "TypeError" || name === "DataError") return {
+				status: "invalid",
+				error
+			};
+			return {
+				status: "failed",
+				error
+			};
+		} finally {
+			sharing.value = false;
+		}
+	};
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		sharing: readonly(sharing),
+		canShare,
+		share
+	};
+}
+//#endregion
+export { useShare };

package/dist/use-sorted-locale.d.mts

@@ -0,0 +1,62 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-sorted-locale.d.ts
+/** Options for {@link useSortedLocale}. */
+interface UseSortedLocaleOptions<Item> extends Intl.CollatorOptions {
+  /**
+   * Locale whose collation order is used. Pass it explicitly for
+   * hydration-stable server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+  /**
+   * Sort from Z to A.
+   *
+   * @default false
+   */
+  readonly descending?: boolean;
+  /**
+   * Text to compare for each item. Required for non-string items.
+   *
+   * @default String(item)
+   */
+  readonly key?: (item: Item) => string;
+}
+/** Reactive locale-aware sorting returned by {@link useSortedLocale}. */
+interface SortedLocaleControls<Item> {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+  /** Collator for the current locale and options. */
+  readonly collator: ComputedRef<Intl.Collator>;
+  /** New array sorted by locale collation; the source is never mutated. */
+  readonly sorted: ComputedRef<readonly Item[]>;
+  /**
+   * Compare two strings with the current collator (ignores `descending`).
+   *
+   * @param left First string.
+   * @param right Second string.
+   * @returns Negative, zero, or positive.
+   */
+  readonly compare: (left: string, right: string) => number;
+}
+/**
+ * Sort strings locale-aware with `Intl.Collator`.
+ *
+ * @param items Reactive strings.
+ * @param options Reactive locale, collation, and direction options.
+ * @returns Reactive sorted copy and collation helpers.
+ */
+declare function useSortedLocale(items: MaybeRefOrGetter<readonly string[]>, options?: MaybeRefOrGetter<UseSortedLocaleOptions<string>>): SortedLocaleControls<string>;
+/**
+ * Sort any items locale-aware by a string key with `Intl.Collator`.
+ *
+ * @param items Reactive items.
+ * @param options Reactive locale, collation, direction, and required key.
+ * @returns Reactive sorted copy and collation helpers.
+ */
+declare function useSortedLocale<Item>(items: MaybeRefOrGetter<readonly Item[]>, options: MaybeRefOrGetter<UseSortedLocaleOptions<Item> & {
+  readonly key: (item: Item) => string;
+}>): SortedLocaleControls<Item>;
+//#endregion
+export { SortedLocaleControls, UseSortedLocaleOptions, useSortedLocale };

package/dist/use-sorted-locale.mjs

@@ -0,0 +1,52 @@
+import { useLocale } from "./locale.mjs";
+import { computed, toValue } from "vue";
+//#region src/use-sorted-locale.ts
+function browserLanguage() {
+	return typeof window === "undefined" ? void 0 : window.navigator.language;
+}
+/**
+* Sort items with locale-aware collation (`Intl.Collator`): `"ä"` sorts
+* next to `"a"` in German but after `"z"` in Swedish, and `numeric: true`
+* orders `"item 10"` after `"item 9"`.
+*
+* The result is a new, stable-sorted array recomputed when the items,
+* options, or locale change; the source array is never mutated. Invalid
+* options surface as the platform `RangeError`. Derived state only: safe
+* and deterministic on the server when the locale is explicit.
+*
+* @example
+* ```ts
+* const { sorted } = useSortedLocale(users, { key: (user) => user.name, locale: "de", sensitivity: "base" });
+* ```
+*
+* @param items Reactive items.
+* @param options Reactive locale, collation, direction, and key.
+* @default options {}
+* @returns Reactive sorted copy and collation helpers.
+*/
+function useSortedLocale(items, options = {}) {
+	const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+	const collator = computed(() => {
+		const { locale: _locale, descending: _descending, key: _key, ...collatorOptions } = toValue(options);
+		return new Intl.Collator(localeControls.locale.value, collatorOptions);
+	});
+	const sorted = computed(() => {
+		const { key = String, descending = false } = toValue(options);
+		const active = collator.value;
+		const direction = descending ? -1 : 1;
+		const keyed = toValue(items).map((item) => ({
+			item,
+			text: key(item)
+		}));
+		keyed.sort((left, right) => direction * active.compare(left.text, right.text));
+		return keyed.map(({ item }) => item);
+	});
+	return {
+		locale: localeControls.locale,
+		collator,
+		sorted,
+		compare: (left, right) => collator.value.compare(left, right)
+	};
+}
+//#endregion
+export { useSortedLocale };

package/dist/use-sorted.d.mts

@@ -0,0 +1,29 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-sorted.d.ts
+/** Comparator with `Array.prototype.sort` semantics. */
+type SortComparator<Item> = (left: Item, right: Item) => number;
+/** Values with a natural order used by the default comparator. */
+type NaturallyOrdered = number | bigint | string | Date;
+/**
+ * Sorted copy of a reactive array; the source is never mutated.
+ *
+ * Numbers, bigints, strings, and dates sort in natural ascending order by
+ * default (numerically, unlike `Array.prototype.sort`); any other item type
+ * requires a comparator. The sort is stable. Pure derived state: SSR-safe
+ * and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const ranked = useSorted(players, (a, b) => b.score - a.score);
+ * const ascending = useSorted([10, 9, 100]); // [9, 10, 100]
+ * ```
+ *
+ * @param source Reactive array.
+ * @param compare Comparator; optional for naturally ordered items.
+ * @returns Computed sorted copy.
+ */
+declare function useSorted<Item extends NaturallyOrdered>(source: MaybeRefOrGetter<readonly Item[]>, compare?: SortComparator<Item>): ComputedRef<Item[]>;
+declare function useSorted<Item>(source: MaybeRefOrGetter<readonly Item[]>, compare: SortComparator<Item>): ComputedRef<Item[]>;
+//#endregion
+export { NaturallyOrdered, SortComparator, useSorted };

package/dist/use-sorted.mjs

@@ -0,0 +1,14 @@
+import { computed, toValue } from "vue";
+//#region src/use-sorted.ts
+function naturalOrder(left, right) {
+	const a = left instanceof Date ? left.getTime() : left;
+	const b = right instanceof Date ? right.getTime() : right;
+	if (a < b) return -1;
+	if (a > b) return 1;
+	return 0;
+}
+function useSorted(source, compare = naturalOrder) {
+	return computed(() => [...toValue(source)].sort(compare));
+}
+//#endregion
+export { useSorted };