@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-stack.mjs

@@ -0,0 +1,93 @@
+import { computed, shallowRef } from "vue";
+//#region src/use-stack.ts
+function validateCapacity(capacity) {
+	if (capacity === Number.POSITIVE_INFINITY) return capacity;
+	if (!Number.isSafeInteger(capacity) || capacity < 1) throw new RangeError(`[VIZE_COMPOSE_STACK_INVALID_CAPACITY] capacity must be a positive integer or Infinity; received ${String(capacity)}`);
+	return capacity;
+}
+/**
+* Create a typed reactive LIFO stack.
+*
+* `push` and `pop` are O(1). A bounded stack either drops its bottom item
+* or rejects new pushes when full. Reactivity is driven by a version
+* counter, so `items`, `size`, `isEmpty`, and `peek` re-evaluate after
+* every mutation.
+*
+* Purely synchronous state: safe during server rendering (no host globals,
+* no timers) and nothing to dispose.
+*
+* @example
+* ```ts
+* const breadcrumbs = useStack<string>(["home"]);
+* breadcrumbs.push("settings");
+* breadcrumbs.pop(); // "settings"
+* ```
+*
+* @typeParam Item Stacked item type, inferred from `initial` when given.
+* @param initial Items pushed at creation, bottom first (overflow applies).
+* @param options Capacity and overflow policy.
+* @default initial []
+* @default options {}
+* @throws {RangeError} `[VIZE_COMPOSE_STACK_INVALID_CAPACITY]` when `capacity`
+* is not a positive integer or `Infinity`.
+* @returns The reactive stack and its controls.
+*/
+function useStack(initial = [], options = {}) {
+	const capacity = validateCapacity(options.capacity ?? Number.POSITIVE_INFINITY);
+	const overflow = options.overflow ?? "drop-oldest";
+	let buffer = [];
+	const version = shallowRef(0);
+	const touch = () => {
+		version.value += 1;
+	};
+	const append = (items) => {
+		let accepted = 0;
+		let dropped = 0;
+		for (const item of items) {
+			if (buffer.length - dropped >= capacity) {
+				if (overflow === "reject") continue;
+				dropped += 1;
+			}
+			buffer.push(item);
+			accepted += 1;
+		}
+		if (dropped > 0) buffer = buffer.slice(dropped);
+		return accepted;
+	};
+	append([...initial]);
+	const items = computed(() => {
+		version.value;
+		return buffer.slice();
+	});
+	const size = computed(() => {
+		version.value;
+		return buffer.length;
+	});
+	return {
+		items,
+		size,
+		isEmpty: computed(() => size.value === 0),
+		peek: () => {
+			version.value;
+			return buffer.at(-1);
+		},
+		push: (...added) => {
+			const accepted = append(added);
+			if (accepted > 0) touch();
+			return accepted;
+		},
+		pop: () => {
+			if (buffer.length === 0) return void 0;
+			const item = buffer.pop();
+			touch();
+			return item;
+		},
+		clear: () => {
+			if (buffer.length === 0) return;
+			buffer = [];
+			touch();
+		}
+	};
+}
+//#endregion
+export { useStack };

package/dist/use-stepper.d.mts

@@ -0,0 +1,79 @@
+import { ComputedRef, ShallowRef } from "vue";
+
+//#region src/use-stepper.d.ts
+/** Step values keyed by step name. */
+type StepValues<Name extends string> = { readonly [Step in Name]: unknown };
+/** Stepper state and navigation returned by {@link useStepper}. */
+interface Stepper<Name extends string, Values extends StepValues<Name>> {
+  /** Step names in order. */
+  readonly stepNames: readonly Name[];
+  /** Zero-based index of the current step. */
+  readonly index: Readonly<ShallowRef<number>>;
+  /** Name of the current step. */
+  readonly current: ComputedRef<Name>;
+  /** Value of the current step (the name itself for array steps). */
+  readonly currentValue: ComputedRef<Values[Name]>;
+  /** Name of the next step, or `undefined` on the last. */
+  readonly next: ComputedRef<Name | undefined>;
+  /** Name of the previous step, or `undefined` on the first. */
+  readonly previous: ComputedRef<Name | undefined>;
+  /** Whether the current step is the first. */
+  readonly isFirst: ComputedRef<boolean>;
+  /** Whether the current step is the last. */
+  readonly isLast: ComputedRef<boolean>;
+  /** Step name at `index`, or `undefined`. */
+  readonly at: (index: number) => Name | undefined;
+  /** Value of a step. */
+  readonly get: <Step extends Name>(step: Step) => Values[Step];
+  /** Jump to a step. */
+  readonly goTo: (step: Name) => void;
+  /** Advance one step (no-op on the last). */
+  readonly goToNext: () => void;
+  /** Go back one step (no-op on the first). */
+  readonly goToPrevious: () => void;
+  /**
+   * Go back to an earlier step; later or current steps are ignored.
+   *
+   * @returns Whether the cursor moved.
+   */
+  readonly goBackTo: (step: Name) => boolean;
+  /** Whether `step` is the current step. */
+  readonly isCurrent: (step: Name) => boolean;
+  /** Whether `step` is the step right after the current one. */
+  readonly isNext: (step: Name) => boolean;
+  /** Whether `step` is the step right before the current one. */
+  readonly isPrevious: (step: Name) => boolean;
+  /** Whether `step` comes before the current step. */
+  readonly isBefore: (step: Name) => boolean;
+  /** Whether `step` comes after the current step. */
+  readonly isAfter: (step: Name) => boolean;
+}
+/**
+ * Linear multi-step flow (wizards, onboarding, checkout) with typed step
+ * names.
+ *
+ * Pass a tuple of names (`["account", "billing", "review"] as const`, or a
+ * plain array literal thanks to `const` inference) or an object whose keys
+ * are the names and whose values carry per-step data; every navigation
+ * method only accepts declared names. Synchronous state: SSR-safe and
+ * nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const wizard = useStepper(["account", "billing", "review"]);
+ * wizard.goTo("billing");
+ * wizard.goTo("shipping"); // type error
+ * ```
+ *
+ * @param steps Step names, or step values keyed by name.
+ * @param initial Step to start on.
+ * @default initial the first step
+ * @throws `RangeError` tagged `VIZE_COMPOSE_STEPPER_EMPTY` when there are no
+ * steps, and `RangeError` tagged `VIZE_COMPOSE_STEPPER_UNKNOWN_STEP` for an
+ * unknown step name at runtime.
+ * @returns Stepper state and navigation.
+ */
+declare function useStepper<const Steps extends readonly string[]>(steps: Steps, initial?: NoInfer<Steps[number]>): Stepper<Steps[number], { readonly [Step in Steps[number]]: Step }>;
+declare function useStepper<Steps extends Readonly<Record<string, unknown>>>(steps: Steps, initial?: NoInfer<keyof Steps & string>): Stepper<keyof Steps & string, Steps>;
+//#endregion
+export { StepValues, Stepper, useStepper };

package/dist/use-stepper.mjs

@@ -0,0 +1,52 @@
+import { computed, shallowRef } from "vue";
+//#region src/use-stepper.ts
+function useStepper(steps, initial) {
+	const names = isNameList(steps) ? [...steps] : Object.keys(steps);
+	const values = isNameList(steps) ? Object.fromEntries(steps.map((name) => [name, name])) : steps;
+	if (names.length === 0) throw new RangeError("[VIZE_COMPOSE_STEPPER_EMPTY] useStepper needs at least one step");
+	const indexOf = (step) => {
+		const found = names.indexOf(step);
+		if (found === -1) throw new RangeError(`[VIZE_COMPOSE_STEPPER_UNKNOWN_STEP] unknown step "${step}"`);
+		return found;
+	};
+	const index = shallowRef(initial === void 0 ? 0 : indexOf(initial));
+	const at = (position) => names[position];
+	const current = computed(() => names[index.value] ?? "");
+	return {
+		stepNames: names,
+		index,
+		current,
+		currentValue: computed(() => values[current.value]),
+		next: computed(() => at(index.value + 1)),
+		previous: computed(() => at(index.value - 1)),
+		isFirst: computed(() => index.value === 0),
+		isLast: computed(() => index.value === names.length - 1),
+		at,
+		get: (step) => values[step],
+		goTo: (step) => {
+			index.value = indexOf(step);
+		},
+		goToNext: () => {
+			if (index.value < names.length - 1) index.value += 1;
+		},
+		goToPrevious: () => {
+			if (index.value > 0) index.value -= 1;
+		},
+		goBackTo: (step) => {
+			const target = indexOf(step);
+			if (target >= index.value) return false;
+			index.value = target;
+			return true;
+		},
+		isCurrent: (step) => indexOf(step) === index.value,
+		isNext: (step) => indexOf(step) === index.value + 1,
+		isPrevious: (step) => indexOf(step) === index.value - 1,
+		isBefore: (step) => indexOf(step) < index.value,
+		isAfter: (step) => indexOf(step) > index.value
+	};
+}
+function isNameList(steps) {
+	return Array.isArray(steps);
+}
+//#endregion
+export { useStepper };

package/dist/use-storage-estimate.d.mts

@@ -0,0 +1,151 @@
+import { n as IntervalScheduler } from "./use-interval-BA55gTHT.mjs";
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-storage-estimate.d.ts
+/** Result of `navigator.storage.estimate()`. */
+interface StorageEstimateLike {
+  /** Bytes used by the origin. */
+  readonly usage?: number | undefined;
+  /** Bytes available to the origin. */
+  readonly quota?: number | undefined;
+  /** Per-storage-system usage in bytes (Chromium only). */
+  readonly usageDetails?: Readonly<Record<string, number>> | undefined;
+}
+/** Minimal `StorageManager` (`navigator.storage`) used by this module. */
+interface StorageManagerLike {
+  /** Estimate usage and quota. */
+  estimate?(): Promise<StorageEstimateLike>;
+  /** Whether storage is already persistent. */
+  persisted?(): Promise<boolean>;
+  /** Request persistent storage. */
+  persist?(): Promise<boolean>;
+}
+/** Options for {@link useStorageEstimate}. */
+interface UseStorageEstimateOptions {
+  /**
+   * Storage manager for alternate runtimes and tests.
+   *
+   * @default window.navigator.storage when it exists
+   */
+  readonly storage?: MaybeRefOrGetter<StorageManagerLike | null | undefined>;
+  /**
+   * Estimate as soon as the composable is created (browser only).
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Re-estimate every `interval` milliseconds; `0` disables polling.
+   *
+   * @default 0
+   */
+  readonly interval?: number;
+  /**
+   * Owns the polling timer.
+   *
+   * @default window timer functions (no timer without a browser window)
+   */
+  readonly scheduler?: IntervalScheduler;
+}
+/** Reactive state and actions returned by {@link useStorageEstimate}. */
+interface StorageEstimateControls {
+  /** Whether `navigator.storage.estimate` is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Bytes used, or `null` before the first estimate. */
+  readonly usage: Readonly<Ref<number | null>>;
+  /** Bytes available, or `null` before the first estimate. */
+  readonly quota: Readonly<Ref<number | null>>;
+  /** Per-storage-system usage, or `null` when the browser does not report it. */
+  readonly usageDetails: Readonly<ShallowRef<Readonly<Record<string, number>> | null>>;
+  /** Usage as a percentage (0..100) of quota, or `null` when unknown. */
+  readonly percentUsed: ComputedRef<number | null>;
+  /** Most recent estimate failure, cleared on success. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Re-read the estimate.
+   *
+   * @returns Whether a fresh estimate was stored.
+   */
+  readonly refresh: () => Promise<boolean>;
+}
+/** Options for {@link usePersistentStorage}. */
+interface UsePersistentStorageOptions {
+  /**
+   * Storage manager for alternate runtimes and tests.
+   *
+   * @default window.navigator.storage when it exists
+   */
+  readonly storage?: MaybeRefOrGetter<StorageManagerLike | null | undefined>;
+  /**
+   * Read `persisted()` as soon as the composable is created (browser only).
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+}
+/** Reactive state and actions returned by {@link usePersistentStorage}. */
+interface PersistentStorageControls {
+  /** Whether `navigator.storage.persist` is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether the origin's storage is persistent (`false` until known). */
+  readonly persisted: Readonly<Ref<boolean>>;
+  /** Most recent failure, cleared on success. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Request persistent storage.
+   *
+   * @returns Whether storage is persistent afterwards; `false` when unsupported.
+   */
+  readonly persist: () => Promise<boolean>;
+  /**
+   * Re-read `persisted()`.
+   *
+   * @returns The current persistence state.
+   */
+  readonly check: () => Promise<boolean>;
+}
+/**
+ * Track the origin's storage usage and quota with `navigator.storage.estimate()`.
+ *
+ * The estimate is read on creation (unless `immediate` is false), whenever a
+ * reactive `storage` host changes, on `refresh()`, and every `interval`
+ * milliseconds through the injectable `scheduler`. The polling timer stops
+ * with the owning reactive scope; outside a scope, polling runs until the
+ * page unloads, so leave `interval` at `0` there.
+ *
+ * Server rendering: nothing is read, no timer starts, `supported` is false
+ * and every value is `null`.
+ *
+ * @example
+ * ```ts
+ * const { usage, quota, percentUsed } = useStorageEstimate({ interval: 60_000 });
+ * ```
+ *
+ * @param options Storage host, polling interval and scheduler.
+ * @default options {}
+ * @returns Storage usage state and a refresh action.
+ */
+declare function useStorageEstimate(options?: UseStorageEstimateOptions): StorageEstimateControls;
+/**
+ * Read and request persistent storage with `navigator.storage.persist()`.
+ *
+ * Persistent storage is not evicted under storage pressure. `persist()` may
+ * show a prompt or be decided silently by the browser; the result is stored
+ * in `persisted`. Nothing needs cleanup; a pending read is ignored after the
+ * owning reactive scope stops.
+ *
+ * Server rendering: nothing is read, `supported` and `persisted` are false.
+ *
+ * @example
+ * ```ts
+ * const storage = usePersistentStorage();
+ * const keepOfflineData = () => storage.persist();
+ * ```
+ *
+ * @param options Storage host and initial read policy.
+ * @default options {}
+ * @returns Persistence state and actions.
+ */
+declare function usePersistentStorage(options?: UsePersistentStorageOptions): PersistentStorageControls;
+//#endregion
+export { PersistentStorageControls, StorageEstimateControls, StorageEstimateLike, StorageManagerLike, UsePersistentStorageOptions, UseStorageEstimateOptions, usePersistentStorage, useStorageEstimate };

package/dist/use-storage-estimate.mjs

@@ -0,0 +1,170 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-storage-estimate.ts
+function browserStorage() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator } = window;
+	return "storage" in navigator && navigator.storage ? navigator.storage : void 0;
+}
+function browserScheduler() {
+	if (typeof window === "undefined") return void 0;
+	return {
+		setInterval: (callback, intervalMs) => window.setInterval(callback, intervalMs),
+		clearInterval: (handle) => {
+			if (typeof handle === "number") window.clearInterval(handle);
+		}
+	};
+}
+function resolver(source) {
+	return () => source === void 0 ? browserStorage() : toValue(source) ?? void 0;
+}
+/**
+* Track the origin's storage usage and quota with `navigator.storage.estimate()`.
+*
+* The estimate is read on creation (unless `immediate` is false), whenever a
+* reactive `storage` host changes, on `refresh()`, and every `interval`
+* milliseconds through the injectable `scheduler`. The polling timer stops
+* with the owning reactive scope; outside a scope, polling runs until the
+* page unloads, so leave `interval` at `0` there.
+*
+* Server rendering: nothing is read, no timer starts, `supported` is false
+* and every value is `null`.
+*
+* @example
+* ```ts
+* const { usage, quota, percentUsed } = useStorageEstimate({ interval: 60_000 });
+* ```
+*
+* @param options Storage host, polling interval and scheduler.
+* @default options {}
+* @returns Storage usage state and a refresh action.
+*/
+function useStorageEstimate(options = {}) {
+	const { immediate = true, interval = 0 } = options;
+	if (!Number.isFinite(interval) || interval < 0) throw new RangeError(`[VIZE_COMPOSE_STORAGE_ESTIMATE_INVALID_INTERVAL] interval must be a non-negative finite number; received ${interval}.`);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveStorageNow = resolver(options.storage);
+	const resolveStorage = () => hydrated.value ? resolveStorageNow() : void 0;
+	const usage = ref(null);
+	const quota = ref(null);
+	const usageDetails = shallowRef(null);
+	const error = shallowRef(void 0);
+	let generation = 0;
+	const refresh = async () => {
+		const storage = resolveStorage();
+		if (!storage?.estimate) return false;
+		const current = ++generation;
+		try {
+			const estimate = await storage.estimate();
+			if (current !== generation) return false;
+			usage.value = estimate.usage ?? null;
+			quota.value = estimate.quota ?? null;
+			usageDetails.value = estimate.usageDetails ?? null;
+			error.value = void 0;
+			return true;
+		} catch (cause) {
+			if (current === generation) error.value = cause;
+			return false;
+		}
+	};
+	watch(resolveStorage, (storage, _previous, onCleanup) => {
+		generation += 1;
+		usage.value = null;
+		quota.value = null;
+		usageDetails.value = null;
+		error.value = void 0;
+		if (!storage?.estimate) return;
+		if (immediate) refresh();
+		const scheduler = options.scheduler ?? browserScheduler();
+		if (interval === 0 || !scheduler) return;
+		const handle = scheduler.setInterval(() => void refresh(), interval);
+		onCleanup(() => scheduler.clearInterval(handle));
+	}, { immediate: true });
+	tryOnScopeDispose(() => {
+		generation += 1;
+	});
+	return {
+		supported: computed(() => resolveStorage()?.estimate !== void 0),
+		usage: readonly(usage),
+		quota: readonly(quota),
+		usageDetails: readonly(usageDetails),
+		percentUsed: computed(() => usage.value === null || quota.value === null || quota.value <= 0 ? null : usage.value / quota.value * 100),
+		error: readonly(error),
+		refresh
+	};
+}
+/**
+* Read and request persistent storage with `navigator.storage.persist()`.
+*
+* Persistent storage is not evicted under storage pressure. `persist()` may
+* show a prompt or be decided silently by the browser; the result is stored
+* in `persisted`. Nothing needs cleanup; a pending read is ignored after the
+* owning reactive scope stops.
+*
+* Server rendering: nothing is read, `supported` and `persisted` are false.
+*
+* @example
+* ```ts
+* const storage = usePersistentStorage();
+* const keepOfflineData = () => storage.persist();
+* ```
+*
+* @param options Storage host and initial read policy.
+* @default options {}
+* @returns Persistence state and actions.
+*/
+function usePersistentStorage(options = {}) {
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveStorageNow = resolver(options.storage);
+	const resolveStorage = () => hydrated.value ? resolveStorageNow() : void 0;
+	const persisted = ref(false);
+	const error = shallowRef(void 0);
+	let active = true;
+	const call = async (method) => {
+		const storage = resolveStorage();
+		const read = storage?.[method];
+		if (!read) return false;
+		try {
+			const value = await read.call(storage);
+			if (active) {
+				persisted.value = value;
+				error.value = void 0;
+			}
+			return value;
+		} catch (cause) {
+			if (active) error.value = cause;
+			return false;
+		}
+	};
+	const check = () => call("persisted");
+	const persist = () => call("persist");
+	if (options.immediate ?? true) {
+		let checked = false;
+		watch(() => resolveStorage() !== void 0, (ready) => {
+			if (!ready || checked) return;
+			checked = true;
+			check();
+		}, {
+			immediate: true,
+			flush: "sync"
+		});
+	}
+	tryOnScopeDispose(() => {
+		active = false;
+	});
+	return {
+		supported: computed(() => resolveStorage()?.persist !== void 0),
+		persisted: readonly(persisted),
+		error: readonly(error),
+		persist,
+		check
+	};
+}
+//#endregion
+export { usePersistentStorage, useStorageEstimate };