@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-timeout.mjs

@@ -0,0 +1,65 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, shallowRef, toValue } from "vue";
+//#region src/use-timeout.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+function resolveDelayMs(value) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_TIMEOUT_INVALID_DELAY] delayMs must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+function useTimeoutFn(callback, delayMs, options = {}) {
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const isPending = shallowRef(false);
+	let handle;
+	let scheduled = false;
+	resolveDelayMs(toValue(delayMs));
+	const clear = () => {
+		if (!scheduled) return;
+		scheduled = false;
+		scheduler.clearTimeout(handle);
+		handle = void 0;
+	};
+	const stop = () => {
+		const wasPending = isPending.value;
+		isPending.value = false;
+		clear();
+		return wasPending;
+	};
+	const start = (...args) => {
+		const delay = resolveDelayMs(toValue(delayMs));
+		clear();
+		isPending.value = true;
+		if (typeof window === "undefined" && !(options.runOnServer ?? false)) return;
+		scheduled = true;
+		handle = scheduler.setTimeout(() => {
+			scheduled = false;
+			handle = void 0;
+			isPending.value = false;
+			callback(...args);
+		}, delay);
+	};
+	if (options.immediate ?? true) start();
+	tryOnScopeDispose(() => {
+		stop();
+	});
+	return {
+		isPending,
+		start,
+		stop
+	};
+}
+function useTimeout(delayMs = 1e3, options = {}) {
+	const controls = useTimeoutFn(() => options.callback?.(), delayMs, options);
+	const ready = computed(() => !controls.isPending.value);
+	if (options.controls !== true) return ready;
+	return {
+		...controls,
+		ready
+	};
+}
+//#endregion
+export { useTimeout, useTimeoutFn };

package/dist/use-url-hash.d.mts

@@ -0,0 +1,88 @@
+import { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-url-hash.d.ts
+/** Minimal `window` surface used by {@link useUrlHash}. */
+interface UrlHashHost extends Pick<EventTarget, "addEventListener" | "removeEventListener"> {
+  /** Current location; only the URL parts are read. */
+  readonly location: {
+    /** Fragment including the leading `#`, or `""`. */readonly hash: string; /** Path component. */
+    readonly pathname: string; /** Query component including the leading `?`, or `""`. */
+    readonly search: string;
+  };
+  /** Session history used to write the fragment without scrolling. */
+  readonly history: {
+    /** Current history entry state, preserved when replacing. */readonly state: unknown; /** Replace the current entry's URL. */
+    readonly replaceState: (data: unknown, unused: string, url: string) => void; /** Push a new entry with the given URL. */
+    readonly pushState: (data: unknown, unused: string, url: string) => void;
+  };
+}
+/** How a changed hash is written to session history. */
+type UrlHistoryMode = "replace" | "push";
+/** Options shared by both {@link useUrlHash} overloads. */
+interface UseUrlHashOptions {
+  /**
+   * Browser host. `null`/`undefined` keeps the default (server rendering).
+   *
+   * @default window when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<UrlHashHost | null | undefined>;
+  /**
+   * History write mode for changes made through `state`.
+   *
+   * @default "replace"
+   */
+  readonly mode?: UrlHistoryMode;
+  /**
+   * Raw hash (without `#`) to use while no host is attached. Browsers never
+   * send the fragment to servers, so pass it only when it is known (for
+   * example from a client-side redirect).
+   *
+   * @default undefined (the default value is used)
+   */
+  readonly ssrHash?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * When the browser hash is first read. `"post-flush"` keeps the server
+   * value through hydration and reads the real hash after mounting.
+   *
+   * @default "post-flush" inside a component, "sync" otherwise
+   */
+  readonly initialRead?: "sync" | "post-flush";
+}
+/** Options for a typed {@link useUrlHash} with an explicit codec. */
+interface UseTypedUrlHashOptions<Value> extends UseUrlHashOptions {
+  /** Decode the raw (percent-decoded, `#`-less) hash. Throwing selects `default`. */
+  readonly parse: (raw: string) => Value;
+  /** Encode a value to a raw hash. An empty string removes the fragment. */
+  readonly serialize: (value: Value) => string;
+  /** Value used for an empty or unparsable hash. */
+  readonly default: Value;
+}
+/** Reactive state and controls returned by {@link useUrlHash}. */
+interface UrlHashControls<Value> {
+  /** Writable hash value; assignments update the URL. */
+  readonly state: Ref<Value>;
+  /** Whether a browser host is attached. */
+  readonly supported: Readonly<Ref<boolean>>;
+  /** Most recent parse failure, cleared by the next successful read. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /** Re-read the current location hash. */
+  readonly refresh: () => void;
+}
+/**
+ * Track the URL fragment as a typed value decoded by `parse`.
+ *
+ * @typeParam Value Hash value type, inferred from the codec.
+ * @param options Codec, host, history mode, and server fallback.
+ * @returns The typed hash value and its controls.
+ */
+declare function useUrlHash<Value>(options: UseTypedUrlHashOptions<Value>): UrlHashControls<Value>;
+/**
+ * Track the URL fragment as a plain string (without the leading `#`).
+ *
+ * @param options Host, history mode, and server fallback.
+ * @default options {}
+ * @returns The hash string and its controls.
+ */
+declare function useUrlHash(options?: UseUrlHashOptions): UrlHashControls<string>;
+//#endregion
+export { UrlHashControls, UrlHashHost, UrlHistoryMode, UseTypedUrlHashOptions, UseUrlHashOptions, useUrlHash };

package/dist/use-url-hash.mjs

@@ -0,0 +1,145 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/use-url-hash.ts
+function browserHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+function decodeFragment(hash) {
+	const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+	try {
+		return decodeURIComponent(raw);
+	} catch {
+		return raw;
+	}
+}
+function encodeFragment(raw) {
+	return encodeURI(raw).replaceAll("#", "%23");
+}
+/**
+* Synchronize a typed value with the URL fragment (`location.hash`).
+*
+* Reading follows `hashchange` and `popstate`. Writing `state` updates the
+* fragment through `history.replaceState` (or `pushState` with
+* `mode: "push"`), which neither scrolls to an anchor nor fires
+* `hashchange`; an empty serialized value removes the fragment. Values are
+* percent-decoded on read and minimally encoded on write.
+*
+* Server rendering: browsers never send the fragment, so without a host the
+* value is `ssrHash` (when given) or the default, and no global is read.
+* Inside a component the browser hash is first read after mounting
+* (`initialRead` defaults to `"post-flush"` there), so hydration never
+* mismatches. Listeners are removed with the owning reactive scope.
+*
+* @example
+* ```ts
+* const { state: tab } = useUrlHash({
+*   parse: (raw) => (raw === "settings" ? "settings" : "profile"),
+*   serialize: (value) => value,
+*   default: "profile" as "profile" | "settings",
+* });
+* ```
+*
+* @param options Codec, host, history mode, and server fallback.
+* @default options {}
+* @returns The synchronized value and its controls.
+*/
+function useUrlHash(options = {}) {
+	if ("parse" in options) return createUrlHash({
+		parse: options.parse,
+		serialize: options.serialize,
+		default: options.default
+	}, options);
+	return createUrlHash({
+		parse: (raw) => raw,
+		serialize: String,
+		default: ""
+	}, options);
+}
+function createUrlHash(codec, options) {
+	const supported = ref(false);
+	const error = shallowRef(void 0);
+	let ready = false;
+	let syncedRaw;
+	const resolveHost = () => options.host === void 0 ? browserHost() : toValue(options.host) ?? void 0;
+	const parse = (raw) => {
+		if (raw === "") return codec.default;
+		try {
+			const value = codec.parse(raw);
+			error.value = void 0;
+			return value;
+		} catch (cause) {
+			error.value = cause;
+			return codec.default;
+		}
+	};
+	const ssrRaw = toValue(options.ssrHash);
+	const state = shallowRef(ssrRaw === void 0 ? codec.default : parse(ssrRaw));
+	const assign = (raw) => {
+		syncedRaw = raw;
+		state.value = parse(raw);
+	};
+	const refresh = () => {
+		const host = resolveHost();
+		supported.value = host !== void 0;
+		if (host === void 0) {
+			assign(toValue(options.ssrHash) ?? "");
+			return;
+		}
+		assign(decodeFragment(host.location.hash));
+	};
+	const onNavigate = () => {
+		if (ready) refresh();
+	};
+	const stopHost = watch(resolveHost, (host, _previous, onCleanup) => {
+		if (ready) refresh();
+		if (host === void 0) return;
+		host.addEventListener("hashchange", onNavigate);
+		host.addEventListener("popstate", onNavigate);
+		onCleanup(() => {
+			host.removeEventListener("hashchange", onNavigate);
+			host.removeEventListener("popstate", onNavigate);
+		});
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const stopWrite = watch(state, (value) => {
+		const host = resolveHost();
+		if (!ready || host === void 0) return;
+		const raw = codec.serialize(value);
+		if (raw === syncedRaw) return;
+		syncedRaw = raw;
+		const { pathname, search } = host.location;
+		const url = `${pathname}${search}${raw === "" ? "" : `#${encodeFragment(raw)}`}`;
+		if ((options.mode ?? "replace") === "push") host.history.pushState(null, "", url);
+		else host.history.replaceState(host.history.state, "", url);
+	}, { flush: "sync" });
+	const start = () => {
+		ready = true;
+		refresh();
+	};
+	let stopDeferred;
+	if ((options.initialRead ?? (hasInjectionContext() ? "post-flush" : "sync")) === "sync") start();
+	else {
+		const trigger = ref(0);
+		stopDeferred = watch(trigger, () => {
+			stopDeferred?.();
+			start();
+		}, { flush: "post" });
+		trigger.value += 1;
+	}
+	tryOnScopeDispose(() => {
+		ready = false;
+		stopDeferred?.();
+		stopHost();
+		stopWrite();
+	});
+	return {
+		state,
+		supported: readonly(supported),
+		error,
+		refresh
+	};
+}
+//#endregion
+export { useUrlHash };

package/dist/use-url-search-params.d.mts

@@ -0,0 +1,223 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-url-search-params.d.ts
+/**
+ * Typed codec for one search parameter.
+ *
+ * `parse` receives every value of the key (`URLSearchParams.getAll`), which
+ * is empty when the key is absent; throwing selects `default`. `serialize`
+ * returns the values to write; an empty array removes the key.
+ */
+interface SearchParamCodec<Value> {
+  /** Value used when the key is absent or unparsable. */
+  readonly default: Value;
+  /** Decode all values of the key. */
+  parse(values: readonly string[]): Value;
+  /** Encode a value to zero or more raw values. */
+  serialize(value: Value): readonly string[];
+}
+/** Schema mapping parameter names to codecs. */
+type SearchParamSchema = Readonly<Record<string, SearchParamCodec<unknown>>>;
+/** Values described by a {@link SearchParamSchema}, inferred per key. */
+type InferSearchParams<Schema extends SearchParamSchema> = { -readonly [Key in keyof Schema]: Schema[Key] extends SearchParamCodec<infer Value> ? Value : never };
+/** Single-value codec definition accepted by {@link searchParam}.custom. */
+interface CustomSearchParam<Value> {
+  /** Decode the first raw value. Throwing selects `default`. */
+  readonly parse: (raw: string) => Value;
+  /** Encode a value to one raw value. */
+  readonly serialize: (value: Value) => string;
+  /** Value used when the key is absent or unparsable. */
+  readonly default: Value;
+}
+/**
+ * Repeated-key codec of raw strings.
+ *
+ * @returns A string array codec.
+ */
+declare function arrayCodec(): SearchParamCodec<string[]>;
+declare function arrayCodec<Item>(item: SearchParamCodec<Item>): SearchParamCodec<Item[]>;
+/** Built-in typed codecs for {@link useUrlSearchParams} schemas. */
+declare const searchParam: {
+  /**
+   * Raw string value.
+   *
+   * @param fallback Value for an absent key.
+   * @default fallback ""
+   * @returns A string codec.
+   */
+  readonly string: (fallback?: string) => SearchParamCodec<string>;
+  /**
+   * Finite number; non-numeric input selects the default.
+   *
+   * @param fallback Value for an absent or invalid key.
+   * @default fallback 0
+   * @returns A number codec.
+   */
+  readonly number: (fallback?: number) => SearchParamCodec<number>;
+  /**
+   * Boolean: `true`/`1`/empty read as `true`, `false`/`0` as `false`.
+   *
+   * @param fallback Value for an absent or unrecognized key.
+   * @default fallback false
+   * @returns A boolean codec.
+   */
+  readonly boolean: (fallback?: boolean) => SearchParamCodec<boolean>;
+  /**
+   * One of a closed set of string literals.
+   *
+   * @param values Allowed values.
+   * @param fallback Value for an absent or unknown key.
+   * @returns A literal-union codec.
+   */
+  readonly enum: <const Values extends readonly [string, ...string[]]>(values: Values, fallback: NoInfer<Values[number]>) => SearchParamCodec<Values[number]>;
+  /**
+   * Repeated key (`?tag=a&tag=b`) decoded item by item.
+   *
+   * @param item Single-value codec applied to every value.
+   * @default item searchParam.string()
+   * @returns An array codec whose default is `[]`.
+   */
+  readonly array: typeof arrayCodec;
+  /**
+   * JSON value checked by `validate`, or by kind against the default.
+   *
+   * @param fallback Value for an absent or invalid key.
+   * @param validate Type guard applied to the decoded JSON.
+   * @default validate the decoded value has the default's kind
+   * @returns A JSON codec.
+   */
+  readonly json: <Value>(fallback: Value, validate?: (candidate: unknown) => candidate is Value) => SearchParamCodec<Value>;
+  /**
+   * Single-value codec from explicit parse/serialize functions.
+   *
+   * @param definition Parse, serialize, and default.
+   * @returns The codec.
+   */
+  readonly custom: <Value>(definition: CustomSearchParam<Value>) => SearchParamCodec<Value>;
+};
+/**
+ * Decode search parameters with a schema. Pure and SSR-safe.
+ *
+ * @typeParam Schema Parameter codecs.
+ * @param schema Parameter codecs.
+ * @param search URL, URL string, query string, or parsed parameters.
+ * @returns One typed value per schema key.
+ */
+declare function parseSearchParams<Schema extends SearchParamSchema>(schema: Schema, search: string | URL | URLSearchParams): InferSearchParams<Schema>;
+/** Options for {@link serializeSearchParams}. */
+interface SerializeSearchParamsOptions {
+  /**
+   * Existing parameters to keep for keys outside the schema.
+   *
+   * @default no base parameters
+   */
+  readonly base?: string | URL | URLSearchParams;
+  /**
+   * Omit keys whose value serializes like the codec default.
+   *
+   * @default true
+   */
+  readonly removeDefaults?: boolean;
+}
+/**
+ * Encode typed values with a schema. Pure and SSR-safe.
+ *
+ * @typeParam Schema Parameter codecs.
+ * @param schema Parameter codecs.
+ * @param values Values to encode; keys absent from `values` keep the base.
+ * @param options Base parameters and default removal.
+ * @default options {}
+ * @returns The encoded parameters.
+ */
+declare function serializeSearchParams<Schema extends SearchParamSchema>(schema: Schema, values: Partial<InferSearchParams<Schema>>, options?: SerializeSearchParamsOptions): URLSearchParams;
+/** Minimal `window` surface used by {@link useUrlSearchParams}. */
+interface UrlSearchParamsHost extends Pick<EventTarget, "addEventListener" | "removeEventListener"> {
+  /** Current location; only the URL parts are read. */
+  readonly location: {
+    /** Query including the leading `?`, or `""`. */readonly search: string; /** Fragment including the leading `#`, or `""`. */
+    readonly hash: string; /** Path component. */
+    readonly pathname: string;
+  };
+  /** Session history used to write the query. */
+  readonly history: {
+    /** Current history entry state, preserved when replacing. */readonly state: unknown; /** Replace the current entry's URL. */
+    readonly replaceState: (data: unknown, unused: string, url: string) => void; /** Push a new entry with the given URL. */
+    readonly pushState: (data: unknown, unused: string, url: string) => void;
+  };
+}
+/** Options for {@link useUrlSearchParams}. */
+interface UseUrlSearchParamsOptions {
+  /**
+   * Browser host. `null`/`undefined` keeps server values.
+   *
+   * @default window when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<UrlSearchParamsHost | null | undefined>;
+  /**
+   * History write mode for changes made through `params`.
+   *
+   * @default "replace"
+   */
+  readonly mode?: "replace" | "push";
+  /**
+   * Omit parameters equal to their codec default from the URL.
+   *
+   * @default true
+   */
+  readonly removeDefaults?: boolean;
+  /**
+   * Request URL used while no host is attached, so server markup matches
+   * the client's first render.
+   *
+   * @default undefined (codec defaults are used)
+   */
+  readonly ssrUrl?: MaybeRefOrGetter<string | URL | URLSearchParams | undefined>;
+}
+/** Reactive state and controls returned by {@link useUrlSearchParams}. */
+interface UrlSearchParamsControls<Schema extends SearchParamSchema> {
+  /**
+   * Writable typed parameters. Assign whole values (including new arrays);
+   * the object is shallowly reactive.
+   */
+  readonly params: InferSearchParams<Schema>;
+  /** Whether a browser host is attached. */
+  readonly supported: Readonly<Ref<boolean>>;
+  /** Re-read the current location. */
+  readonly refresh: () => void;
+  /** Stop following the URL. Idempotent; also runs on scope disposal. */
+  readonly stop: () => void;
+}
+/**
+ * Two-way bind typed URL search parameters described by a codec schema.
+ *
+ * Every property type is inferred from its codec. Assigning a property
+ * rewrites the query through `history.replaceState` (or `pushState` with
+ * `mode: "push"`), keeping parameters outside the schema and the fragment,
+ * and dropping values equal to their default. Back/forward navigation
+ * (`popstate`) re-reads the URL.
+ *
+ * Server rendering: no global is read. Pass `ssrUrl` (the request URL) so
+ * the server renders the same values the client reads during hydration.
+ * Inside a component the browser URL is first read after mounting, so the
+ * hydrating client renders the `ssrUrl` state before switching to it.
+ * Listeners are removed with the owning reactive scope or `stop()`.
+ *
+ * @example
+ * ```ts
+ * const { params } = useUrlSearchParams({
+ *   page: searchParam.number(1),
+ *   sort: searchParam.enum(["new", "top"], "new"),
+ *   tags: searchParam.array(),
+ * });
+ * params.page += 1; // ?page=2
+ * ```
+ *
+ * @typeParam Schema Parameter codecs.
+ * @param schema Parameter codecs.
+ * @param options Host, history mode, default removal, and server URL.
+ * @default options {}
+ * @returns Typed reactive parameters and controls.
+ */
+declare function useUrlSearchParams<const Schema extends SearchParamSchema>(schema: Schema, options?: UseUrlSearchParamsOptions): UrlSearchParamsControls<Schema>;
+//#endregion
+export { CustomSearchParam, InferSearchParams, SearchParamCodec, SearchParamSchema, SerializeSearchParamsOptions, UrlSearchParamsControls, UrlSearchParamsHost, UseUrlSearchParamsOptions, parseSearchParams, searchParam, serializeSearchParams, useUrlSearchParams };