@vizejs/composable 0.426.3 → 0.427.0

package/dist/pointer-lock.mjs

@@ -0,0 +1,126 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/pointer-lock.ts
+/** Error thrown when pointer lock cannot be acquired or released. */
+var PointerLockError = class extends Error {
+	/** Machine-readable failure code. */
+	code;
+	/**
+	* @param code Machine-readable failure code.
+	* @param message Human-readable explanation.
+	*/
+	constructor(code, message) {
+		super(message);
+		this.name = "PointerLockError";
+		this.code = code;
+	}
+};
+/**
+* Reactive wrapper around the Pointer Lock API.
+*
+* Tracks `pointerlockchange` on the document and exposes promise-based lock
+* and unlock actions that settle on the platform confirmation events.
+* Rejections are {@link PointerLockError}s with stable codes. Nothing runs
+* during server rendering; listeners are removed with the owning scope.
+*
+* Inside a component the host is read after mounting, so hydration renders
+* the server fallback first and never mismatches.
+*
+* @param target Default reactive element to lock.
+* @param options Movement mode and document capability.
+* @default target undefined
+* @default options {}
+* @returns Support flag, lock state, and actions.
+*/
+function usePointerLock(target, options = {}) {
+	const isSupported = ref(false);
+	const element = shallowRef(null);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const host = () => !hydrated.value ? void 0 : options.host === void 0 ? browserPointerLockHost() : toValue(options.host);
+	const stop = watch(host, (current, _previous, onCleanup) => {
+		isSupported.value = Boolean(current && "pointerLockElement" in current);
+		element.value = current?.pointerLockElement ?? null;
+		if (!current) return;
+		const onChange = () => {
+			element.value = current.pointerLockElement;
+		};
+		current.addEventListener("pointerlockchange", onChange);
+		onCleanup(() => current.removeEventListener("pointerlockchange", onChange));
+	}, { immediate: true });
+	tryOnScopeDispose(() => stop.stop());
+	const isLocked = ref(false);
+	watch([element, () => target === void 0 ? null : resolveElement(target)], ([locked, own]) => {
+		isLocked.value = locked !== null && locked === own;
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const lock = async (override) => {
+		const current = host();
+		if (!current || !isSupported.value) throw new PointerLockError("VIZE_COMPOSE_POINTER_LOCK_UNSUPPORTED", "Pointer lock is not supported.");
+		const candidate = resolveElement(override ?? target);
+		if (!candidate || !isPointerLockable(candidate)) throw new PointerLockError("VIZE_COMPOSE_POINTER_LOCK_NO_TARGET", "No lockable element resolved.");
+		const confirmed = waitFor(current, () => current.pointerLockElement === candidate);
+		try {
+			await candidate.requestPointerLock(options.unadjustedMovement ? { unadjustedMovement: true } : void 0);
+		} catch (cause) {
+			confirmed.cancel();
+			throw new PointerLockError("VIZE_COMPOSE_POINTER_LOCK_FAILED", describe(cause));
+		}
+		await confirmed.promise;
+		return candidate;
+	};
+	const unlock = async () => {
+		const current = host();
+		if (!current?.pointerLockElement) return false;
+		const confirmed = waitFor(current, () => current.pointerLockElement === null);
+		current.exitPointerLock();
+		await confirmed.promise;
+		return true;
+	};
+	return {
+		isSupported: readonly(isSupported),
+		element,
+		isLocked: readonly(isLocked),
+		lock,
+		unlock
+	};
+}
+function waitFor(host, done) {
+	let cleanup = () => void 0;
+	return {
+		promise: new Promise((resolve, reject) => {
+			const onChange = () => {
+				if (!done()) return;
+				cleanup();
+				resolve();
+			};
+			const onError = () => {
+				cleanup();
+				reject(new PointerLockError("VIZE_COMPOSE_POINTER_LOCK_FAILED", "The pointer lock was refused."));
+			};
+			host.addEventListener("pointerlockchange", onChange);
+			host.addEventListener("pointerlockerror", onError);
+			cleanup = () => {
+				host.removeEventListener("pointerlockchange", onChange);
+				host.removeEventListener("pointerlockerror", onError);
+			};
+		}),
+		cancel: () => cleanup()
+	};
+}
+function isPointerLockable(element) {
+	return typeof element.requestPointerLock === "function";
+}
+function describe(cause) {
+	return cause instanceof Error ? cause.message : "The pointer lock request failed.";
+}
+function browserPointerLockHost() {
+	return typeof document !== "undefined" ? document : void 0;
+}
+//#endregion
+export { PointerLockError, usePointerLock };

package/dist/pointer.d.mts

@@ -0,0 +1,78 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/pointer.d.ts
+/** Pointer device kind reported by Pointer Events. */
+type PointerKind = "mouse" | "touch" | "pen";
+/** Snapshot of the latest pointer event. */
+interface PointerState {
+  /** Horizontal client coordinate. */
+  readonly x: number;
+  /** Vertical client coordinate. */
+  readonly y: number;
+  /** Normalized pressure in `[0, 1]`. */
+  readonly pressure: number;
+  /** Identifier of the pointer that produced the latest event. */
+  readonly pointerId: number;
+  /** Pen tilt around the Y axis in degrees. */
+  readonly tiltX: number;
+  /** Pen tilt around the X axis in degrees. */
+  readonly tiltY: number;
+  /** Contact geometry width in CSS pixels. */
+  readonly width: number;
+  /** Contact geometry height in CSS pixels. */
+  readonly height: number;
+  /** Pen rotation in degrees. */
+  readonly twist: number;
+  /** Device kind; `null` before the first event. */
+  readonly pointerType: PointerKind | null;
+}
+/** Options for {@link usePointer}. */
+interface UsePointerOptions {
+  /**
+   * Device kinds to track.
+   *
+   * @default ["mouse", "touch", "pen"]
+   */
+  readonly pointerTypes?: readonly PointerKind[];
+  /**
+   * Event target to listen on.
+   *
+   * @default globalThis.window when available
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+  /**
+   * State exposed before any input and during server rendering.
+   *
+   * @default all numbers `0`, `pointerType: null`
+   */
+  readonly initialValue?: Partial<PointerState>;
+}
+/** Reactive pointer state returned by {@link usePointer}. */
+interface PointerControls {
+  /** Latest pointer snapshot. */
+  readonly state: Readonly<PointerState>;
+  /** Whether the pointer is inside the target (between enter/move and leave). */
+  readonly isInside: Readonly<Ref<boolean>>;
+}
+/**
+ * Track the latest pointer (mouse, touch, or pen) state.
+ *
+ * Listens passively for `pointerdown`, `pointermove`, `pointerup`, and
+ * `pointerleave` on the reactive target and filters by device kind.
+ * Listeners are removed with the owning reactive scope; server renders expose
+ * the initial snapshot.
+ *
+ * @param options Device filter, target, and initial snapshot.
+ * @default options {}
+ * @returns Reactive snapshot and inside flag.
+ */
+declare function usePointer(options?: UsePointerOptions): PointerControls;
+/**
+ * Narrow a platform `pointerType` string to the closed {@link PointerKind} union.
+ *
+ * @param value Raw `PointerEvent.pointerType`.
+ * @returns The matching kind, or `null` for unknown/future device kinds.
+ */
+declare function toPointerKind(value: string): PointerKind | null;
+//#endregion
+export { PointerControls, PointerKind, PointerState, UsePointerOptions, toPointerKind, usePointer };

package/dist/pointer.mjs

@@ -0,0 +1,95 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { readonly, ref, shallowReactive, shallowReadonly, toValue, watch } from "vue";
+//#region src/pointer.ts
+/**
+* Track the latest pointer (mouse, touch, or pen) state.
+*
+* Listens passively for `pointerdown`, `pointermove`, `pointerup`, and
+* `pointerleave` on the reactive target and filters by device kind.
+* Listeners are removed with the owning reactive scope; server renders expose
+* the initial snapshot.
+*
+* @param options Device filter, target, and initial snapshot.
+* @default options {}
+* @returns Reactive snapshot and inside flag.
+*/
+function usePointer(options = {}) {
+	const pointerTypes = options.pointerTypes ?? [
+		"mouse",
+		"touch",
+		"pen"
+	];
+	const state = shallowReactive({
+		x: 0,
+		y: 0,
+		pressure: 0,
+		pointerId: 0,
+		tiltX: 0,
+		tiltY: 0,
+		width: 0,
+		height: 0,
+		twist: 0,
+		pointerType: null,
+		...options.initialValue
+	});
+	const isInside = ref(false);
+	const onPointer = (event) => {
+		if (!isPointerEvent(event)) return;
+		const kind = toPointerKind(event.pointerType);
+		if (!kind || !pointerTypes.includes(kind)) return;
+		isInside.value = true;
+		state.x = event.clientX;
+		state.y = event.clientY;
+		state.pressure = event.pressure;
+		state.pointerId = event.pointerId;
+		state.tiltX = event.tiltX;
+		state.tiltY = event.tiltY;
+		state.width = event.width;
+		state.height = event.height;
+		state.twist = event.twist;
+		state.pointerType = kind;
+	};
+	const onLeave = () => {
+		isInside.value = false;
+	};
+	const stop = watch(() => options.target === void 0 ? browserWindow() : toValue(options.target), (target, _previous, onCleanup) => {
+		if (!target) return;
+		const listenerOptions = { passive: true };
+		for (const type of [
+			"pointerdown",
+			"pointermove",
+			"pointerup"
+		]) target.addEventListener(type, onPointer, listenerOptions);
+		target.addEventListener("pointerleave", onLeave, listenerOptions);
+		onCleanup(() => {
+			for (const type of [
+				"pointerdown",
+				"pointermove",
+				"pointerup"
+			]) target.removeEventListener(type, onPointer);
+			target.removeEventListener("pointerleave", onLeave);
+		});
+	}, { immediate: true });
+	tryOnScopeDispose(() => stop.stop());
+	return {
+		state: shallowReadonly(state),
+		isInside: readonly(isInside)
+	};
+}
+/**
+* Narrow a platform `pointerType` string to the closed {@link PointerKind} union.
+*
+* @param value Raw `PointerEvent.pointerType`.
+* @returns The matching kind, or `null` for unknown/future device kinds.
+*/
+function toPointerKind(value) {
+	return value === "mouse" || value === "touch" || value === "pen" ? value : null;
+}
+function isPointerEvent(event) {
+	return "pointerId" in event && "pointerType" in event;
+}
+function browserWindow() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { toPointerKind, usePointer };

package/dist/preferences.d.mts

@@ -0,0 +1,55 @@
+import { UseMediaQueryOptions } from "./media-query.mjs";
+import { ComputedRef, Ref } from "vue";
+
+//#region src/preferences.d.ts
+/** Color scheme preference exposed by {@link usePreferredColorScheme}. */
+type ColorSchemePreference = "dark" | "light" | "no-preference";
+/** Contrast preference exposed by {@link usePreferredContrast}. */
+type ContrastPreference = "more" | "less" | "custom" | "no-preference";
+/** Options for the multi-valued preference composables. */
+interface UsePreferenceOptions<Preference extends string> extends Omit<UseMediaQueryOptions, "ssrValue"> {
+  /**
+   * Preference exposed during server rendering and whenever no media-query
+   * capability exists.
+   *
+   * @default "no-preference"
+   */
+  readonly ssrPreference?: Preference;
+}
+/**
+ * Whether the user prefers a dark color scheme.
+ *
+ * Shares {@link useMediaQuery} semantics: `ssrValue` (default `false`) during
+ * server rendering and subscription cleanup with the owning scope.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Readonly ref for `(prefers-color-scheme: dark)`.
+ */
+declare function usePreferredDark(options?: UseMediaQueryOptions): Readonly<Ref<boolean>>;
+/**
+ * Reactive color scheme preference.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Computed closed preference.
+ */
+declare function usePreferredColorScheme(options?: UsePreferenceOptions<ColorSchemePreference>): ComputedRef<ColorSchemePreference>;
+/**
+ * Reactive contrast preference.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Computed closed preference.
+ */
+declare function usePreferredContrast(options?: UsePreferenceOptions<ContrastPreference>): ComputedRef<ContrastPreference>;
+/**
+ * Whether the user prefers reduced transparency.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Readonly ref for `(prefers-reduced-transparency: reduce)`.
+ */
+declare function usePreferredReducedTransparency(options?: UseMediaQueryOptions): Readonly<Ref<boolean>>;
+//#endregion
+export { ColorSchemePreference, ContrastPreference, UsePreferenceOptions, usePreferredColorScheme, usePreferredContrast, usePreferredDark, usePreferredReducedTransparency };

package/dist/preferences.mjs

@@ -0,0 +1,63 @@
+import { useMediaQuery } from "./media-query.mjs";
+import { computed } from "vue";
+//#region src/preferences.ts
+/**
+* Whether the user prefers a dark color scheme.
+*
+* Shares {@link useMediaQuery} semantics: `ssrValue` (default `false`) during
+* server rendering and subscription cleanup with the owning scope.
+*
+* @param options Runtime capability and server fallback.
+* @default options {}
+* @returns Readonly ref for `(prefers-color-scheme: dark)`.
+*/
+function usePreferredDark(options = {}) {
+	return useMediaQuery("(prefers-color-scheme: dark)", options);
+}
+/**
+* Reactive color scheme preference.
+*
+* @param options Runtime capability and server fallback.
+* @default options {}
+* @returns Computed closed preference.
+*/
+function usePreferredColorScheme(options = {}) {
+	const fallback = options.ssrPreference ?? "no-preference";
+	const query = (value) => useMediaQuery(`(prefers-color-scheme: ${value})`, withSsr(options, fallback === value));
+	const dark = query("dark");
+	const light = query("light");
+	return computed(() => dark.value ? "dark" : light.value ? "light" : "no-preference");
+}
+/**
+* Reactive contrast preference.
+*
+* @param options Runtime capability and server fallback.
+* @default options {}
+* @returns Computed closed preference.
+*/
+function usePreferredContrast(options = {}) {
+	const fallback = options.ssrPreference ?? "no-preference";
+	const query = (value) => useMediaQuery(`(prefers-contrast: ${value})`, withSsr(options, fallback === value));
+	const more = query("more");
+	const less = query("less");
+	const custom = query("custom");
+	return computed(() => more.value ? "more" : less.value ? "less" : custom.value ? "custom" : "no-preference");
+}
+/**
+* Whether the user prefers reduced transparency.
+*
+* @param options Runtime capability and server fallback.
+* @default options {}
+* @returns Readonly ref for `(prefers-reduced-transparency: reduce)`.
+*/
+function usePreferredReducedTransparency(options = {}) {
+	return useMediaQuery("(prefers-reduced-transparency: reduce)", options);
+}
+function withSsr(options, ssrValue) {
+	return options.host === void 0 ? { ssrValue } : {
+		ssrValue,
+		host: options.host
+	};
+}
+//#endregion
+export { usePreferredColorScheme, usePreferredContrast, usePreferredDark, usePreferredReducedTransparency };

package/dist/preferred-languages.d.mts

@@ -0,0 +1,43 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/preferred-languages.d.ts
+/** Window-like capability observed by {@link usePreferredLanguages}. */
+interface PreferredLanguagesHost extends EventTarget {
+  /** Navigator exposing the user's languages. */
+  readonly navigator: {
+    readonly languages: readonly string[];
+    readonly language?: string;
+  };
+}
+/** Options for {@link usePreferredLanguages}. */
+interface UsePreferredLanguagesOptions {
+  /**
+   * Languages exposed during server rendering. Pass the request's
+   * `Accept-Language` list to keep hydration stable.
+   *
+   * @default ["en"]
+   */
+  readonly ssrLanguages?: readonly string[];
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<PreferredLanguagesHost | null | undefined>;
+}
+/**
+ * Track the user's preferred languages (`navigator.languages`).
+ *
+ * Updates on `languagechange`. The default host is gated on `window`, so
+ * Node's own `navigator` never leaks the server locale into the render;
+ * server renders expose `ssrLanguages`. Inside a component the languages are
+ * read after mounting, so hydration renders `ssrLanguages` first. The
+ * listener is removed with the owning reactive scope.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Readonly ref of BCP 47 language tags, most preferred first.
+ */
+declare function usePreferredLanguages(options?: UsePreferredLanguagesOptions): Readonly<Ref<readonly string[]>>;
+//#endregion
+export { PreferredLanguagesHost, UsePreferredLanguagesOptions, usePreferredLanguages };

package/dist/preferred-languages.mjs

@@ -0,0 +1,44 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, readonly, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/preferred-languages.ts
+/**
+* Track the user's preferred languages (`navigator.languages`).
+*
+* Updates on `languagechange`. The default host is gated on `window`, so
+* Node's own `navigator` never leaks the server locale into the render;
+* server renders expose `ssrLanguages`. Inside a component the languages are
+* read after mounting, so hydration renders `ssrLanguages` first. The
+* listener is removed with the owning reactive scope.
+*
+* @param options Server fallback and window capability.
+* @default options {}
+* @returns Readonly ref of BCP 47 language tags, most preferred first.
+*/
+function usePreferredLanguages(options = {}) {
+	const fallback = options.ssrLanguages ?? ["en"];
+	const languages = shallowRef(fallback);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const stop = watch(() => hydrated.value ? options.host === void 0 ? browserLanguagesHost() : toValue(options.host) : void 0, (host, _previous, onCleanup) => {
+		if (!host) {
+			languages.value = fallback;
+			return;
+		}
+		const update = () => {
+			const { languages: list, language } = host.navigator;
+			languages.value = list.length > 0 ? [...list] : language !== void 0 ? [language] : fallback;
+		};
+		update();
+		host.addEventListener("languagechange", update, { passive: true });
+		onCleanup(() => host.removeEventListener("languagechange", update));
+	}, { immediate: true });
+	tryOnScopeDispose(() => stop.stop());
+	return readonly(languages);
+}
+function browserLanguagesHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { usePreferredLanguages };

package/dist/reactify.d.mts

@@ -0,0 +1,28 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/reactify.d.ts
+/** Parameter list of a reactified function: every argument may be a ref or getter. */
+type ReactifiedArguments<Arguments extends readonly unknown[]> = { readonly [Index in keyof Arguments]: MaybeRefOrGetter<Arguments[Index]> };
+/** Function returned by {@link reactify}. */
+type Reactified<Arguments extends readonly unknown[], Result> = (...args: ReactifiedArguments<Arguments>) => ComputedRef<Result>;
+/**
+ * Turn a plain function into one that accepts refs/getters and returns a
+ * computed result.
+ *
+ * Arity and parameter names are preserved; each parameter additionally
+ * accepts `Ref<T>` or `() => T`. The computed re-runs the original function
+ * whenever a reactive argument changes. Pure derived state: SSR-safe and
+ * nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const add = reactify((left: number, right: number) => left + right);
+ * const sum = add(count, 1); // ComputedRef<number>
+ * ```
+ *
+ * @param fn Plain function to lift.
+ * @returns The reactified function.
+ */
+declare function reactify<Arguments extends readonly unknown[], Result>(fn: (...args: Arguments) => Result): Reactified<Arguments, Result>;
+//#endregion
+export { Reactified, ReactifiedArguments, reactify };

package/dist/reactify.mjs

@@ -0,0 +1,7 @@
+import { computed, toValue } from "vue";
+//#region src/reactify.ts
+function reactify(fn) {
+	return (...args) => computed(() => fn(...args.map((argument) => toValue(argument))));
+}
+//#endregion
+export { reactify };

package/dist/ref-auto-reset.d.mts

@@ -0,0 +1,47 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/ref-auto-reset.d.ts
+/** Options for {@link refAutoReset}. */
+interface RefAutoResetOptions {
+  /**
+   * Applies the reset timer when no browser `window` is available. When
+   * disabled, written values persist on the server (a render is a snapshot).
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Owns the reset timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/**
+ * Writable ref that falls back to a default value `afterMs` milliseconds
+ * after each write.
+ *
+ * Typical for transient UI state such as "Copied!" labels. Every write
+ * restarts the timer; the default (itself possibly reactive) is read when the
+ * reset happens, and the ref reads the current default until the first write.
+ * The pending reset is cancelled when the owning reactive scope stops.
+ * Without a browser `window` (and without `runOnServer`) no timer starts.
+ *
+ * @example
+ * ```ts
+ * const message = refAutoReset("", 2_000);
+ * message.value = "Copied!"; // back to "" after two seconds
+ * ```
+ *
+ * @param defaultValue Reactive value restored after the delay.
+ * @param afterMs Reactive delay in milliseconds, finite and at least zero.
+ * @param options Server and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_REF_AUTO_RESET_INVALID_DELAY` for
+ * invalid delays, synchronously at creation and on every write.
+ * @returns A writable ref.
+ */
+declare function refAutoReset<Value>(defaultValue: MaybeRefOrGetter<Value>, afterMs: MaybeRefOrGetter<number>, options?: RefAutoResetOptions): Ref<Value>;
+//#endregion
+export { RefAutoResetOptions, refAutoReset };

package/dist/ref-auto-reset.mjs

@@ -0,0 +1,70 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { customRef, toValue } from "vue";
+//#region src/ref-auto-reset.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+function resolveResetMs(value) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_REF_AUTO_RESET_INVALID_DELAY] afterMs must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+/**
+* Writable ref that falls back to a default value `afterMs` milliseconds
+* after each write.
+*
+* Typical for transient UI state such as "Copied!" labels. Every write
+* restarts the timer; the default (itself possibly reactive) is read when the
+* reset happens, and the ref reads the current default until the first write.
+* The pending reset is cancelled when the owning reactive scope stops.
+* Without a browser `window` (and without `runOnServer`) no timer starts.
+*
+* @example
+* ```ts
+* const message = refAutoReset("", 2_000);
+* message.value = "Copied!"; // back to "" after two seconds
+* ```
+*
+* @param defaultValue Reactive value restored after the delay.
+* @param afterMs Reactive delay in milliseconds, finite and at least zero.
+* @param options Server and scheduler policy.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_REF_AUTO_RESET_INVALID_DELAY` for
+* invalid delays, synchronously at creation and on every write.
+* @returns A writable ref.
+*/
+function refAutoReset(defaultValue, afterMs, options = {}) {
+	const scheduler = options.scheduler ?? defaultScheduler;
+	resolveResetMs(toValue(afterMs));
+	let handle;
+	let written = false;
+	let current = toValue(defaultValue);
+	const cancel = () => {
+		if (handle !== void 0) scheduler.clearTimeout(handle);
+		handle = void 0;
+	};
+	tryOnScopeDispose(cancel);
+	return customRef((track, trigger) => ({
+		get: () => {
+			track();
+			return written ? current : toValue(defaultValue);
+		},
+		set: (next) => {
+			const delay = resolveResetMs(toValue(afterMs));
+			current = next;
+			written = true;
+			trigger();
+			cancel();
+			if (typeof window === "undefined" && !(options.runOnServer ?? false)) return;
+			handle = scheduler.setTimeout(() => {
+				handle = void 0;
+				written = false;
+				trigger();
+			}, delay);
+		}
+	}));
+}
+//#endregion
+export { refAutoReset };