@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-fetch.mjs

@@ -0,0 +1,263 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { retryAsync } from "./retry-async.mjs";
+import { computed, readonly, shallowRef, toValue, watch } from "vue";
+//#region src/use-fetch.ts
+var RetryableFailure = class {
+	failure;
+	constructor(failure) {
+		this.failure = failure;
+	}
+};
+const TIMEOUT_REASON = "VIZE_COMPOSE_FETCH_TIMEOUT";
+function browserFetch() {
+	if (typeof window === "undefined" || typeof window.fetch !== "function") return void 0;
+	const fetchImplementation = window.fetch.bind(window);
+	return (input, init) => fetchImplementation(input, init);
+}
+function isRetryableStatus(status) {
+	return status === 408 || status === 429 || status >= 500;
+}
+function readBody(response, responseType) {
+	switch (responseType) {
+		case "text": return response.text();
+		case "blob": return response.blob();
+		case "arrayBuffer": return response.arrayBuffer();
+		case "formData": return response.formData();
+		default: return response.json();
+	}
+}
+function assertTimeout(timeoutMs) {
+	if (timeoutMs === void 0) return;
+	if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new RangeError(`[VIZE_COMPOSE_FETCH_INVALID_TIMEOUT] timeoutMs must be a finite non-negative number; received ${String(timeoutMs)}`);
+}
+/**
+* Reactive, abortable, retrying `fetch` with typed decoding and interceptors.
+*
+* Latest wins: starting an execution aborts the pending one, which then
+* settles as `"superseded"` without touching state. The pending request is
+* aborted when the owning reactive scope stops; outside a scope the caller
+* owns `abort()`. Automatic execution (initial and on reactive URL/`init`
+* changes) only happens in a browser or with an explicit `fetch`, so server
+* rendering performs no I/O unless you `await execute()` in
+* `onServerPrefetch`; state then holds `initialData` and status `"idle"`.
+*
+* @example
+* ```ts
+* const id = ref(1);
+* const { data, error } = useFetch(() => `/api/users/${id.value}`, {
+*   validate: isUser,
+*   retry: 2,
+*   timeoutMs: 5_000,
+* });
+* ```
+*
+* @param url Reactive URL; `null`/`undefined` keeps the resource idle.
+* @param options Decoding, retry, timeout, and interceptor options.
+* @default options {}
+* @throws {RangeError} `[VIZE_COMPOSE_FETCH_INVALID_TIMEOUT]` for an invalid timeout.
+* @returns Reactive state and controls.
+*/
+function useFetch(url, options = {}) {
+	assertTimeout(options.timeoutMs);
+	const data = shallowRef(options.initialData);
+	const error = shallowRef(void 0);
+	const status = shallowRef("idle");
+	const response = shallowRef(void 0);
+	const statusCode = computed(() => response.value?.status);
+	const pending = computed(() => status.value === "pending");
+	const scheduler = options.scheduler ?? {
+		setTimeout: (callback, delayMs) => {
+			const handle = globalThis.setTimeout(callback, delayMs);
+			return () => globalThis.clearTimeout(handle);
+		},
+		clearTimeout: (cancel) => {
+			if (typeof cancel === "function") cancel();
+		}
+	};
+	let active;
+	const resolveFetch = () => options.fetch ?? browserFetch();
+	const decode = async (result) => options.parse ? options.parse(result) : readBody(result, options.responseType ?? "json");
+	const accepts = (candidate) => options.validate ? options.validate(candidate) : true;
+	const fail = (failure, record) => {
+		if (active !== record) return { status: "superseded" };
+		active = void 0;
+		error.value = failure;
+		status.value = failure.kind === "aborted" ? "aborted" : "error";
+		options.onError?.(failure);
+		return {
+			status: "error",
+			error: failure
+		};
+	};
+	const abortFailure = (signal, timeoutMs) => signal.reason === TIMEOUT_REASON && timeoutMs !== void 0 ? {
+		kind: "timeout",
+		timeoutMs
+	} : {
+		kind: "aborted",
+		reason: signal.reason
+	};
+	const execute = async () => {
+		if (active !== void 0) {
+			active.superseded = true;
+			active.controller.abort(new DOMException("A newer fetch started.", "AbortError"));
+		}
+		const record = {
+			controller: new AbortController(),
+			superseded: false
+		};
+		active = record;
+		const { signal } = record.controller;
+		error.value = void 0;
+		status.value = "pending";
+		const target = toValue(url);
+		const fetchImplementation = resolveFetch();
+		if (target === null || target === void 0 || fetchImplementation === void 0) return fail({
+			kind: "network",
+			cause: /* @__PURE__ */ new TypeError(target === null || target === void 0 ? "[VIZE_COMPOSE_FETCH_NO_URL] no request URL is available" : "[VIZE_COMPOSE_FETCH_UNSUPPORTED] no fetch implementation is available")
+		}, record);
+		const timeoutMs = options.timeoutMs;
+		const timer = timeoutMs === void 0 ? void 0 : scheduler.setTimeout(() => record.controller.abort(TIMEOUT_REASON), timeoutMs);
+		try {
+			let request = {
+				url: String(target),
+				init: { ...toValue(options.init) }
+			};
+			if (options.beforeRequest) {
+				const replaced = await options.beforeRequest({
+					...request,
+					signal
+				});
+				if (replaced === false) record.controller.abort(new DOMException("beforeRequest cancelled the request.", "AbortError"));
+				else if (replaced) request = replaced;
+			}
+			if (signal.aborted) return record.superseded ? { status: "superseded" } : fail(abortFailure(signal, timeoutMs), record);
+			const retry = options.retry ?? 0;
+			const retryOptions = typeof retry === "number" ? {
+				maximumRetries: retry,
+				initialDelayMs: 0
+			} : retry;
+			const userShouldRetry = retryOptions.shouldRetry;
+			const attemptOutcome = await retryAsync(async () => {
+				let result;
+				try {
+					result = await fetchImplementation(request.url, {
+						...request.init,
+						signal
+					});
+				} catch (cause) {
+					throw new RetryableFailure({
+						kind: "network",
+						cause
+					});
+				}
+				if (!result.ok && isRetryableStatus(result.status)) throw new RetryableFailure({
+					kind: "http",
+					status: result.status,
+					response: result
+				});
+				return result;
+			}, {
+				...retryOptions,
+				signal,
+				scheduler,
+				shouldRetry: (context) => userShouldRetry ? userShouldRetry(context) : context.error instanceof RetryableFailure
+			}).then((result) => ({
+				ok: true,
+				result
+			}), (cause) => ({
+				ok: false,
+				cause
+			}));
+			if (!attemptOutcome.ok) {
+				if (signal.aborted) return record.superseded ? { status: "superseded" } : fail(abortFailure(signal, timeoutMs), record);
+				const { cause } = attemptOutcome;
+				if (active === record && cause instanceof RetryableFailure) {
+					if (cause.failure.kind === "http") response.value = cause.failure.response;
+					return fail(cause.failure, record);
+				}
+				return fail({
+					kind: "network",
+					cause
+				}, record);
+			}
+			const result = attemptOutcome.result;
+			if (active === record) response.value = result;
+			if (!result.ok) return fail({
+				kind: "http",
+				status: result.status,
+				response: result
+			}, record);
+			let decoded;
+			try {
+				decoded = await decode(result);
+			} catch (cause) {
+				if (signal.aborted) return record.superseded ? { status: "superseded" } : fail(abortFailure(signal, timeoutMs), record);
+				return fail({
+					kind: "parse",
+					cause
+				}, record);
+			}
+			if (!accepts(decoded)) return fail({
+				kind: "invalid",
+				data: decoded
+			}, record);
+			let value = decoded;
+			if (options.afterResponse) {
+				const transformed = await options.afterResponse({
+					request,
+					response: result,
+					data: value
+				});
+				if (transformed !== void 0) value = transformed;
+			}
+			if (active !== record) return { status: "superseded" };
+			active = void 0;
+			data.value = value;
+			status.value = "success";
+			return {
+				status: "success",
+				data: value,
+				response: result
+			};
+		} catch (cause) {
+			return fail({
+				kind: "network",
+				cause
+			}, record);
+		} finally {
+			if (timer !== void 0) scheduler.clearTimeout(timer);
+		}
+	};
+	const abort = (reason = new DOMException("The request was aborted.", "AbortError")) => {
+		if (active === void 0) return false;
+		active.controller.abort(reason);
+		return true;
+	};
+	if (options.fetch !== void 0 || typeof window !== "undefined") {
+		let initial = true;
+		tryOnScopeDispose(watch([() => toValue(url), () => toValue(options.init)], ([target]) => {
+			const first = initial;
+			initial = false;
+			if (target === null || target === void 0) return;
+			if (first ? options.immediate ?? true : options.refetch ?? true) execute();
+		}, {
+			immediate: true,
+			deep: true
+		}));
+	}
+	tryOnScopeDispose(() => {
+		abort(new DOMException("The reactive scope was disposed.", "AbortError"));
+	});
+	return {
+		data,
+		error,
+		status: readonly(status),
+		response,
+		statusCode,
+		pending,
+		execute,
+		abort
+	};
+}
+//#endregion
+export { useFetch };

package/dist/use-field.d.mts

@@ -0,0 +1,107 @@
+import { d as StandardSchemaV1 } from "./standard-schema-DmNgFVK5.mjs";
+import { ComputedRef, Ref, ShallowRef } from "vue";
+
+//#region src/use-field.d.ts
+/** Result of a standalone field validator: messages, one message, or nothing. */
+type FieldRuleResult = string | readonly string[] | null | undefined | void;
+/** Context passed to standalone field validators. */
+interface FieldRuleContext {
+  /** Aborted when a newer validation supersedes this one. */
+  readonly signal: AbortSignal;
+}
+/** Plain validator for a standalone field. */
+type FieldRule<Value> = (value: Value, context: FieldRuleContext) => FieldRuleResult | Promise<FieldRuleResult>;
+/** A plain validator or a Standard Schema v1 validator for the value. */
+type FieldRuleSource<Value> = FieldRule<Value> | StandardSchemaV1<Value, unknown>;
+/** When a standalone field validates automatically. */
+type FieldValidationTrigger = "change" | "blur" | "manual";
+/** Options for {@link useField}. */
+interface UseFieldOptions<Value> {
+  /**
+   * Validators run in order; their messages are concatenated.
+   *
+   * @default []
+   */
+  readonly rules?: FieldRuleSource<Value> | readonly FieldRuleSource<Value>[];
+  /**
+   * When validation runs automatically.
+   *
+   * @default "change"
+   */
+  readonly validateOn?: FieldValidationTrigger;
+  /**
+   * Field name exposed for `name` attributes and error summaries.
+   *
+   * @default ""
+   */
+  readonly name?: string;
+}
+/** Reactive state and actions returned by {@link useField}. */
+interface FieldControls<Value> {
+  /** Field name. */
+  readonly name: string;
+  /** Writable value (use with `v-model`). */
+  readonly value: Ref<Value>;
+  /** Current error messages. */
+  readonly errors: Readonly<ShallowRef<readonly string[]>>;
+  /** First error message. */
+  readonly error: ComputedRef<string | undefined>;
+  /** Whether no errors are recorded. */
+  readonly valid: ComputedRef<boolean>;
+  /** Whether the value differs from the initial value. */
+  readonly dirty: ComputedRef<boolean>;
+  /** Whether the field was blurred. */
+  readonly touched: Readonly<Ref<boolean>>;
+  /** Whether a validation is pending. */
+  readonly validating: Readonly<Ref<boolean>>;
+  /** Mark the field touched (wire to `blur`); validates when configured. */
+  readonly onBlur: () => void;
+  /**
+   * Run every rule, aborting an older validation still in flight.
+   *
+   * @returns Whether the value is valid (`false` also when superseded).
+   */
+  readonly validate: () => Promise<boolean>;
+  /**
+   * Replace errors (for example with server errors).
+   *
+   * @param errors New messages.
+   */
+  readonly setErrors: (errors: readonly string[]) => void;
+  /**
+   * Restore the initial value (or install a new one) and clear state.
+   *
+   * @param value New initial value.
+   */
+  readonly reset: (value?: Value) => void;
+}
+/**
+ * A standalone validated field, independent of any form.
+ *
+ * Rules may be plain (a)synchronous validators or Standard Schema v1
+ * validators (anything with a `~standard` property). A newer validation
+ * aborts older ones through their `signal`, and stale results are ignored.
+ * With `validateOn: "change"` validation runs after each value change,
+ * never during setup, so server-rendered markup matches the first client
+ * render. For multi-field state use `useForm`.
+ *
+ * Server rendering: pure state; nothing validates during setup. Pending
+ * validations are aborted when the owning scope stops.
+ *
+ * @example
+ * ```ts
+ * const email = useField("", {
+ *   name: "email",
+ *   rules: [(value) => (value.includes("@") ? undefined : "Invalid email")],
+ * });
+ * ```
+ *
+ * @typeParam Value Field value, inferred from `initialValue`.
+ * @param initialValue Initial value, or a factory returning it.
+ * @param options Rules, trigger, and name.
+ * @default options {}
+ * @returns Field state and actions.
+ */
+declare function useField<Value>(initialValue: Value | (() => Value), options?: UseFieldOptions<NoInfer<Value>>): FieldControls<Value>;
+//#endregion
+export { FieldControls, FieldRule, FieldRuleContext, FieldRuleResult, FieldRuleSource, FieldValidationTrigger, UseFieldOptions, useField };

package/dist/use-field.mjs

@@ -0,0 +1,117 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { isStandardSchema, validateStandardSchema } from "./standard-schema.mjs";
+import { computed, ref, shallowRef, toRaw, watch } from "vue";
+//#region src/use-field.ts
+function messagesOf(result) {
+	if (result === void 0 || result === null || result === "") return [];
+	return typeof result === "string" ? [result] : result.filter((message) => message !== "");
+}
+function sameValue(left, right) {
+	if (Object.is(left, right)) return true;
+	if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+	if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+	if (Array.isArray(left) !== Array.isArray(right)) return false;
+	const leftKeys = Object.keys(left);
+	const rightKeys = Object.keys(right);
+	return leftKeys.length === rightKeys.length && leftKeys.every((key) => sameValue(Reflect.get(left, key), Reflect.get(right, key)));
+}
+/**
+* A standalone validated field, independent of any form.
+*
+* Rules may be plain (a)synchronous validators or Standard Schema v1
+* validators (anything with a `~standard` property). A newer validation
+* aborts older ones through their `signal`, and stale results are ignored.
+* With `validateOn: "change"` validation runs after each value change,
+* never during setup, so server-rendered markup matches the first client
+* render. For multi-field state use `useForm`.
+*
+* Server rendering: pure state; nothing validates during setup. Pending
+* validations are aborted when the owning scope stops.
+*
+* @example
+* ```ts
+* const email = useField("", {
+*   name: "email",
+*   rules: [(value) => (value.includes("@") ? undefined : "Invalid email")],
+* });
+* ```
+*
+* @typeParam Value Field value, inferred from `initialValue`.
+* @param initialValue Initial value, or a factory returning it.
+* @param options Rules, trigger, and name.
+* @default options {}
+* @returns Field state and actions.
+*/
+function useField(initialValue, options = {}) {
+	const createInitial = () => initialValue instanceof Function ? initialValue() : structuredClone(toRaw(initialValue));
+	let initial = createInitial();
+	const value = ref(structuredClone(toRaw(initial)));
+	const errors = shallowRef([]);
+	const touched = ref(false);
+	const validating = ref(false);
+	const trigger = options.validateOn ?? "change";
+	const rules = options.rules === void 0 ? [] : Array.isArray(options.rules) ? options.rules : [options.rules];
+	let controller;
+	const runRule = async (rule, current, signal) => {
+		if (isStandardSchema(rule)) {
+			const result = await validateStandardSchema(rule, current);
+			return result.status === "valid" ? [] : result.issues.map((issue) => issue.message);
+		}
+		return messagesOf(await rule(current, { signal }));
+	};
+	const validate = async () => {
+		controller?.abort(new DOMException("A newer validation started.", "AbortError"));
+		const active = new AbortController();
+		controller = active;
+		validating.value = true;
+		try {
+			const current = value.value;
+			const results = await Promise.all(rules.map((rule) => runRule(rule, current, active.signal)));
+			if (active.signal.aborted) return false;
+			errors.value = results.flat();
+			return errors.value.length === 0;
+		} finally {
+			if (controller === active) {
+				controller = void 0;
+				validating.value = false;
+			}
+		}
+	};
+	let resetValue;
+	if (trigger === "change") watch(value, (current) => {
+		if (toRaw(current) === resetValue && sameValue(current, initial)) return;
+		validate();
+	}, { deep: true });
+	tryOnScopeDispose(() => controller?.abort());
+	return {
+		name: options.name ?? "",
+		value,
+		errors,
+		error: computed(() => errors.value[0]),
+		valid: computed(() => errors.value.length === 0),
+		dirty: computed(() => !sameValue(value.value, initial)),
+		touched,
+		validating,
+		onBlur: () => {
+			touched.value = true;
+			if (trigger === "blur") validate();
+		},
+		validate,
+		setErrors: (next) => {
+			errors.value = [...next];
+		},
+		reset: (next) => {
+			controller?.abort();
+			controller = void 0;
+			initial = next === void 0 ? createInitial() : structuredClone(toRaw(next));
+			const fresh = structuredClone(toRaw(initial));
+			resetValue = fresh;
+			value.value = fresh;
+			errors.value = [];
+			touched.value = false;
+			validating.value = false;
+		}
+	};
+}
+//#endregion
+export { useField };

package/dist/use-file-dialog.d.mts

@@ -0,0 +1,139 @@
+import { MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-file-dialog.d.ts
+/** Camera facing hint for capture-capable file inputs. */
+type FileDialogCapture = "user" | "environment";
+/** Minimal `<input type="file">` consumed by {@link useFileDialog}. */
+interface FileInputLike extends EventTarget {
+  /** Input type; set to `"file"`. */
+  type: string;
+  /** Accepted MIME types / extensions. */
+  accept: string;
+  /** Allow selecting multiple files. */
+  multiple: boolean;
+  /** Selected files. */
+  readonly files: ArrayLike<File> | null;
+  /** Serialized value; cleared to reset the selection. */
+  value: string;
+  /** Open the native dialog. */
+  click(): void;
+  /** Set an attribute (`capture`, `webkitdirectory`). */
+  setAttribute(name: string, value: string): void;
+  /** Remove an attribute. */
+  removeAttribute(name: string): void;
+}
+/** Document capability used to create the hidden input. */
+interface FileDialogHost {
+  /** Create an `<input>` element. */
+  createElement(tagName: "input"): FileInputLike;
+}
+/** Per-dialog settings accepted by {@link useFileDialog} and `open`. */
+interface FileDialogSettings {
+  /** Accepted MIME types / extensions, for example `"image/*,.pdf"`. */
+  readonly accept?: string;
+  /** Allow selecting multiple files. */
+  readonly multiple?: boolean;
+  /** Capture from a camera on supporting devices. */
+  readonly capture?: FileDialogCapture;
+  /** Select a directory (`webkitdirectory`). */
+  readonly directory?: boolean;
+  /** Clear the current selection before the dialog opens. */
+  readonly reset?: boolean;
+}
+/** Options for {@link useFileDialog}. */
+interface UseFileDialogOptions {
+  /**
+   * Accepted MIME types / extensions.
+   *
+   * @default "*"
+   */
+  readonly accept?: MaybeRefOrGetter<string>;
+  /**
+   * Allow selecting multiple files.
+   *
+   * @default true
+   */
+  readonly multiple?: MaybeRefOrGetter<boolean>;
+  /**
+   * Capture from a camera on supporting devices.
+   *
+   * @default undefined
+   */
+  readonly capture?: MaybeRefOrGetter<FileDialogCapture | undefined>;
+  /**
+   * Select a directory instead of files.
+   *
+   * @default false
+   */
+  readonly directory?: MaybeRefOrGetter<boolean>;
+  /**
+   * Clear the current selection whenever the dialog opens.
+   *
+   * @default false
+   */
+  readonly reset?: boolean;
+  /**
+   * Selection before the dialog was used.
+   *
+   * @default null
+   */
+  readonly initialFiles?: readonly File[] | null;
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<FileDialogHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useFileDialog}. */
+interface FileDialogControls {
+  /** Current selection; `null` before any selection or after `reset`. */
+  readonly files: Readonly<ShallowRef<readonly File[] | null>>;
+  /**
+   * Open the native dialog. Browsers require a user gesture.
+   *
+   * @param overrides Settings overriding the options for this dialog.
+   * @returns Whether a dialog could be opened.
+   */
+  readonly open: (overrides?: FileDialogSettings) => boolean;
+  /** Clear the selection. */
+  readonly reset: () => void;
+  /**
+   * Observe selections.
+   *
+   * @param handler Called with the new selection.
+   * @returns Unsubscribe function.
+   */
+  readonly onChange: (handler: (files: readonly File[] | null) => void) => () => void;
+  /**
+   * Observe dialogs dismissed without a selection.
+   *
+   * @param handler Called on cancel.
+   * @returns Unsubscribe function.
+   */
+  readonly onCancel: (handler: () => void) => () => void;
+}
+/**
+ * Open the native file picker without rendering an input.
+ *
+ * A detached `<input type="file">` is created lazily on the first `open`
+ * (never during setup or server rendering), configured from reactive
+ * options plus per-call overrides, and observed for `change` and `cancel`.
+ * The selection is exposed as a readonly `File[]`. Listeners are removed
+ * when the owning reactive scope stops.
+ *
+ * Server rendering: `files` is `initialFiles` and `open` returns false.
+ *
+ * @example
+ * ```ts
+ * const { files, open, onChange } = useFileDialog({ accept: "image/*" });
+ * onChange((selection) => upload(selection));
+ * ```
+ *
+ * @param options Dialog settings, initial selection, and capability.
+ * @default options {}
+ * @returns Selection state and dialog actions.
+ */
+declare function useFileDialog(options?: UseFileDialogOptions): FileDialogControls;
+//#endregion
+export { FileDialogCapture, FileDialogControls, FileDialogHost, FileDialogSettings, FileInputLike, UseFileDialogOptions, useFileDialog };