@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-eye-dropper.mjs

@@ -0,0 +1,68 @@
+import { computed, readonly, ref, unref } from "vue";
+//#region src/use-eye-dropper.ts
+function isEyeDropperHost(candidate) {
+	return typeof candidate === "function";
+}
+function browserEyeDropper() {
+	if (typeof window === "undefined") return void 0;
+	const candidate = Reflect.get(window, "EyeDropper");
+	return isEyeDropperHost(candidate) ? candidate : void 0;
+}
+function isAbort(error) {
+	return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+/**
+* Pick a color from anywhere on screen with the EyeDropper API.
+*
+* `open` resolves to a discriminated {@link EyeDropperResult}; dismissing
+* the picker (Escape) or aborting via `signal` yields `"cancelled"`.
+* The composable holds no resources beyond an open picker, which the
+* caller controls through `signal`.
+*
+* Server rendering: `supported` is false and `sRGBHex` is `initialValue`.
+*
+* @example
+* ```ts
+* const { open, sRGBHex, supported } = useEyeDropper();
+* ```
+*
+* @param options Capability and initial color.
+* @default options {}
+* @returns Picker state and the open action.
+*/
+function useEyeDropper(options = {}) {
+	const sRGBHex = ref(options.initialValue ?? "");
+	const picking = ref(false);
+	const resolveHost = () => options.host === void 0 ? browserEyeDropper() : unref(options.host) ?? void 0;
+	const open = async (signal) => {
+		const Host = resolveHost();
+		if (!Host) return {
+			status: "unsupported",
+			error: void 0
+		};
+		picking.value = true;
+		try {
+			const color = await new Host().open(signal === void 0 ? {} : { signal });
+			sRGBHex.value = color.sRGBHex;
+			return {
+				status: "picked",
+				sRGBHex: color.sRGBHex
+			};
+		} catch (error) {
+			return {
+				status: isAbort(error) ? "cancelled" : "failed",
+				error
+			};
+		} finally {
+			picking.value = false;
+		}
+	};
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		sRGBHex: readonly(sRGBHex),
+		picking: readonly(picking),
+		open
+	};
+}
+//#endregion
+export { useEyeDropper };

package/dist/use-favicon.d.mts

@@ -0,0 +1,78 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-favicon.d.ts
+/** `<link>` subset updated by {@link useFavicon}. */
+interface FaviconLink {
+  /** Link relation. */
+  rel: string;
+  /** Icon URL. */
+  href: string;
+}
+/** Document capability used by {@link useFavicon}. */
+interface FaviconHost {
+  /** Find every `<link>` whose `rel` contains `rel`. */
+  findIcons(rel: string): Iterable<FaviconLink>;
+  /** Create (and attach to `<head>`) a new `<link rel={rel}>`. */
+  createIcon(rel: string): FaviconLink;
+}
+/** Options for {@link useFavicon}. */
+interface UseFaviconOptions {
+  /**
+   * Prefix prepended to every icon value.
+   *
+   * @default ""
+   */
+  readonly baseUrl?: string;
+  /**
+   * Link relation matched (substring) and used for created links.
+   *
+   * @default "icon"
+   */
+  readonly rel?: string;
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document's `<head>`
+   */
+  readonly host?: MaybeRefOrGetter<FaviconHost | null | undefined>;
+}
+/** Reactive state returned by {@link useFavicon}. */
+interface FaviconControls {
+  /**
+   * Icon URL (before `baseUrl`). Writable; `null`/`undefined` leaves the
+   * current icons untouched. When a getter was passed, the next getter
+   * change overwrites manual assignments.
+   */
+  readonly icon: Ref<string | null | undefined>;
+  /**
+   * Whether a document capability is attached. Inside a component it stays
+   * `false` until mounted, so hydration matches the server render.
+   */
+  readonly supported: ComputedRef<boolean>;
+}
+/**
+ * Bind the page favicon to reactive state.
+ *
+ * Every `<link>` whose `rel` contains `rel` (`icon`, `shortcut icon`,
+ * `apple-touch-icon`, …) gets `baseUrl + icon` as its `href`; when none
+ * exists, one `<link rel="icon">` is created. Accepts a writable ref (used
+ * as-is), a getter (followed), a plain string, or nothing (an owned ref).
+ *
+ * Server rendering: this is a client-only side effect. The document is
+ * never touched on the server, and `icon` keeps its given value; emit the
+ * initial `<link rel="icon">` through the application's head manager.
+ * Watchers are released with the owning reactive scope; the last icon stays.
+ *
+ * @example
+ * ```ts
+ * const { icon } = useFavicon(() => (unread.value ? "/unread.svg" : "/icon.svg"));
+ * ```
+ *
+ * @param icon Reactive icon source.
+ * @param options Base URL, relation, and capability.
+ * @default options {}
+ * @returns The icon ref and support flag.
+ */
+declare function useFavicon(icon?: MaybeRefOrGetter<string | null | undefined>, options?: UseFaviconOptions): FaviconControls;
+//#endregion
+export { FaviconControls, FaviconHost, FaviconLink, UseFaviconOptions, useFavicon };

package/dist/use-favicon.mjs

@@ -0,0 +1,68 @@
+import { useMounted } from "./use-mounted.mjs";
+import { computed, hasInjectionContext, isRef, ref, toValue, watch } from "vue";
+//#region src/use-favicon.ts
+function browserFaviconHost() {
+	if (typeof window === "undefined") return void 0;
+	const { document, HTMLLinkElement, CSS } = window;
+	return {
+		findIcons: (rel) => [...document.head.querySelectorAll(`link[rel*="${CSS.escape(rel)}"]`)].filter((element) => element instanceof HTMLLinkElement),
+		createIcon: (rel) => {
+			const link = document.createElement("link");
+			link.rel = rel;
+			document.head.append(link);
+			return link;
+		}
+	};
+}
+/**
+* Bind the page favicon to reactive state.
+*
+* Every `<link>` whose `rel` contains `rel` (`icon`, `shortcut icon`,
+* `apple-touch-icon`, …) gets `baseUrl + icon` as its `href`; when none
+* exists, one `<link rel="icon">` is created. Accepts a writable ref (used
+* as-is), a getter (followed), a plain string, or nothing (an owned ref).
+*
+* Server rendering: this is a client-only side effect. The document is
+* never touched on the server, and `icon` keeps its given value; emit the
+* initial `<link rel="icon">` through the application's head manager.
+* Watchers are released with the owning reactive scope; the last icon stays.
+*
+* @example
+* ```ts
+* const { icon } = useFavicon(() => (unread.value ? "/unread.svg" : "/icon.svg"));
+* ```
+*
+* @param icon Reactive icon source.
+* @param options Base URL, relation, and capability.
+* @default options {}
+* @returns The icon ref and support flag.
+*/
+function useFavicon(icon, options = {}) {
+	const baseUrl = options.baseUrl ?? "";
+	const rel = options.rel ?? "icon";
+	const resolveHost = () => options.host === void 0 ? browserFaviconHost() : toValue(options.host) ?? void 0;
+	const state = isRef(icon) ? icon : ref(toValue(icon));
+	if (typeof icon === "function") watch(icon, (next) => {
+		state.value = next;
+	});
+	watch([state, resolveHost], ([next, host]) => {
+		if (!host || next === null || next === void 0) return;
+		const href = `${baseUrl}${next}`;
+		let found = false;
+		for (const link of host.findIcons(rel)) {
+			found = true;
+			if (link.href !== href) link.href = href;
+		}
+		if (!found) host.createIcon(rel).href = href;
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const mounted = hasInjectionContext() ? useMounted() : void 0;
+	return {
+		icon: state,
+		supported: computed(() => (mounted?.value ?? true) && resolveHost() !== void 0)
+	};
+}
+//#endregion
+export { useFavicon };

package/dist/use-fetch.d.mts

@@ -0,0 +1,230 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { RetryAsyncOptions } from "./retry-async.mjs";
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-fetch.d.ts
+/** Minimal `fetch` implementation accepted by {@link useFetch}. */
+type FetchImplementation = (input: string, init: RequestInit) => Promise<Response>;
+/** Built-in body readers selectable with `responseType`. */
+type FetchResponseType = "json" | "text" | "blob" | "arrayBuffer" | "formData";
+/** Data type produced by each built-in {@link FetchResponseType}. */
+interface FetchResponseTypeMap {
+  /** Parsed JSON; narrow it with `validate`. */
+  readonly json: unknown;
+  /** Response text. */
+  readonly text: string;
+  /** Binary body as a `Blob`. */
+  readonly blob: Blob;
+  /** Binary body as an `ArrayBuffer`. */
+  readonly arrayBuffer: ArrayBuffer;
+  /** Multipart or URL-encoded form body. */
+  readonly formData: FormData;
+}
+/** Lifecycle status of a {@link useFetch} resource. */
+type FetchStatus = "idle" | "pending" | "success" | "error" | "aborted";
+/** Discriminated failure reported by {@link useFetch}. */
+type FetchFailure = {
+  /** The server answered with a non-2xx status. */readonly kind: "http"; /** HTTP status code. */
+  readonly status: number; /** The complete response, body unread. */
+  readonly response: Response;
+} | {
+  /** The request could not be performed (DNS, CORS, offline, ...). */readonly kind: "network"; /** Exact value thrown by the fetch implementation. */
+  readonly cause: unknown;
+} | {
+  /** The body could not be decoded. */readonly kind: "parse"; /** Exact value thrown by the body reader or `parse`. */
+  readonly cause: unknown;
+} | {
+  /** The decoded body was rejected by `validate`. */readonly kind: "invalid"; /** Rejected decoded body. */
+  readonly data: unknown;
+} | {
+  /** The request was aborted by `abort()`, a newer execution, or the scope. */readonly kind: "aborted"; /** Abort reason. */
+  readonly reason: unknown;
+} | {
+  /** The request exceeded `timeoutMs`. */readonly kind: "timeout"; /** Configured timeout in milliseconds. */
+  readonly timeoutMs: number;
+};
+/** Explicit outcome of one {@link FetchControls.execute} call. */
+type FetchResult<Data> = {
+  /** The request succeeded. */readonly status: "success"; /** Decoded, validated data. */
+  readonly data: Data; /** Response the data was read from. */
+  readonly response: Response;
+} | {
+  /** The request failed; see {@link FetchFailure}. */readonly status: "error"; /** Failure details. */
+  readonly error: FetchFailure;
+} | {
+  /** A newer execution replaced this one before it settled. */readonly status: "superseded";
+};
+/** Request description passed through the `beforeRequest` interceptor. */
+interface FetchRequest {
+  /** Resolved request URL. */
+  readonly url: string;
+  /** Request options (headers, method, body, ...). */
+  readonly init: RequestInit;
+}
+/** Context supplied to the `beforeRequest` interceptor. */
+interface FetchBeforeRequestContext extends FetchRequest {
+  /** Signal aborted when the execution is aborted, superseded, or times out. */
+  readonly signal: AbortSignal;
+}
+/** Context supplied to the `afterResponse` interceptor. */
+interface FetchAfterResponseContext<Data> {
+  /** Request that produced the response. */
+  readonly request: FetchRequest;
+  /** Successful response. */
+  readonly response: Response;
+  /** Decoded, validated data. */
+  readonly data: Data;
+}
+/** Retry policy accepted by {@link UseFetchOptions.retry}. */
+type FetchRetryOptions = Omit<RetryAsyncOptions, "signal" | "scheduler">;
+/** Options for {@link useFetch}. */
+interface UseFetchOptions<Data> {
+  /**
+   * Reactive request options. Changes trigger a refetch when `refetch` is on.
+   *
+   * @default {}
+   */
+  readonly init?: MaybeRefOrGetter<RequestInit | undefined>;
+  /**
+   * Fetch implementation. Passing one explicitly also enables automatic
+   * execution on the server.
+   *
+   * @default window.fetch when a browser window exists
+   */
+  readonly fetch?: FetchImplementation;
+  /**
+   * Built-in body reader. Ignored when `parse` is supplied.
+   *
+   * @default "json"
+   */
+  readonly responseType?: FetchResponseType;
+  /**
+   * Custom body decoder. Throwing produces a `"parse"` failure.
+   *
+   * @default the `responseType` reader
+   */
+  readonly parse?: (response: Response) => Promise<Data>;
+  /**
+   * Type guard applied to the decoded body. Rejection produces an
+   * `"invalid"` failure. Without it, JSON is trusted to match `Data`.
+   *
+   * @default accepts every decoded body
+   */
+  readonly validate?: (data: unknown) => data is Data;
+  /**
+   * Execute as soon as a URL is available. Automatic execution only happens
+   * in a browser or when `fetch` is supplied explicitly.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Re-execute when the reactive URL or `init` changes.
+   *
+   * @default true
+   */
+  readonly refetch?: boolean;
+  /**
+   * Data exposed before the first success and after `reset`-like failures.
+   *
+   * @default undefined
+   */
+  readonly initialData?: Data;
+  /**
+   * Abort the request after this many milliseconds (`"timeout"` failure).
+   *
+   * @default undefined (no timeout)
+   */
+  readonly timeoutMs?: number;
+  /**
+   * Retry count or full retry policy (see `retryAsync`). By default only
+   * network failures and HTTP 408, 429, and 5xx responses are retried.
+   *
+   * @default 0
+   */
+  readonly retry?: number | FetchRetryOptions;
+  /**
+   * Timer host for timeouts and retry backoff.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+  /**
+   * Inspect or rewrite the request before it is sent. Return a replacement
+   * request, nothing to keep it, or `false` to abort the execution.
+   *
+   * @default undefined
+   */
+  readonly beforeRequest?: (context: FetchBeforeRequestContext) => FetchRequest | false | void | Promise<FetchRequest | false | void>;
+  /**
+   * Observe or transform successful data before it is committed.
+   *
+   * @default undefined
+   */
+  readonly afterResponse?: (context: FetchAfterResponseContext<Data>) => Data | void | Promise<Data | void>;
+  /**
+   * Observe failures of the newest execution.
+   *
+   * @default undefined
+   */
+  readonly onError?: (failure: FetchFailure) => void;
+}
+/** Reactive state and controls returned by {@link useFetch}. */
+interface FetchControls<Data> {
+  /** Data of the newest successful execution, or `initialData`. */
+  readonly data: Readonly<ShallowRef<Data | undefined>>;
+  /** Failure of the newest settled execution. */
+  readonly error: Readonly<ShallowRef<FetchFailure | undefined>>;
+  /** Lifecycle status driven by the newest execution. */
+  readonly status: Readonly<Ref<FetchStatus>>;
+  /** Response of the newest execution that reached the server. */
+  readonly response: Readonly<ShallowRef<Response | undefined>>;
+  /** HTTP status of `response`. */
+  readonly statusCode: ComputedRef<number | undefined>;
+  /** Whether an execution is pending. */
+  readonly pending: ComputedRef<boolean>;
+  /**
+   * Run the request now, superseding any pending one. Never rejects. Await it
+   * in `onServerPrefetch` to fetch during server rendering.
+   */
+  readonly execute: () => Promise<FetchResult<Data>>;
+  /**
+   * Abort the pending execution.
+   *
+   * @returns Whether an execution was aborted.
+   */
+  readonly abort: (reason?: unknown) => boolean;
+}
+/**
+ * Fetch typed data with a custom `parse` decoder.
+ *
+ * @typeParam Data Value produced by `parse`.
+ * @param url Reactive URL; `null`/`undefined` keeps the resource idle.
+ * @param options Options including the decoder.
+ * @returns Reactive state and controls.
+ */
+declare function useFetch<Data>(url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseFetchOptions<Data> & {
+  readonly parse: (response: Response) => Promise<Data>;
+}): FetchControls<Data>;
+/**
+ * Fetch a non-JSON body whose type follows `responseType`.
+ *
+ * @param url Reactive URL; `null`/`undefined` keeps the resource idle.
+ * @param options Options including the body reader.
+ * @returns Reactive state and controls.
+ */
+declare function useFetch<const Kind extends Exclude<FetchResponseType, "json">>(url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseFetchOptions<FetchResponseTypeMap[Kind]> & {
+  readonly responseType: Kind;
+}): FetchControls<FetchResponseTypeMap[Kind]>;
+/**
+ * Fetch JSON. Supply `validate` to narrow `unknown` to a checked type.
+ *
+ * @param url Reactive URL; `null`/`undefined` keeps the resource idle.
+ * @param options Options.
+ * @returns Reactive state and controls.
+ */
+declare function useFetch<Data = unknown>(url: MaybeRefOrGetter<string | URL | null | undefined>, options?: UseFetchOptions<Data> & {
+  readonly responseType?: "json";
+}): FetchControls<Data>;
+//#endregion
+export { FetchAfterResponseContext, FetchBeforeRequestContext, FetchControls, FetchFailure, FetchImplementation, FetchRequest, FetchResponseType, FetchResponseTypeMap, FetchResult, FetchRetryOptions, FetchStatus, UseFetchOptions, useFetch };