@vizejs/composable 0.426.3 → 0.428.0

package/dist/use-url-search-params.mjs

@@ -0,0 +1,295 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, onMounted, readonly, ref, shallowReactive, toValue, watch } from "vue";
+//#region src/use-url-search-params.ts
+function single(definition) {
+	return {
+		default: definition.default,
+		parse(values) {
+			const [first] = values;
+			return first === void 0 ? definition.default : definition.parse(first);
+		},
+		serialize(value) {
+			return [definition.serialize(value)];
+		}
+	};
+}
+function sameJsonKind(defaults, candidate) {
+	if (defaults === null) return true;
+	if (Array.isArray(defaults)) return Array.isArray(candidate);
+	if (typeof defaults === "object") return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
+	return typeof candidate === typeof defaults;
+}
+function arrayCodec(item) {
+	if (item === void 0) return {
+		default: [],
+		parse: (values) => [...values],
+		serialize: (value) => value
+	};
+	return {
+		default: [],
+		parse: (values) => values.map((value) => item.parse([value])),
+		serialize: (value) => value.flatMap((entry) => item.serialize(entry))
+	};
+}
+/** Built-in typed codecs for {@link useUrlSearchParams} schemas. */
+const searchParam = {
+	/**
+	* Raw string value.
+	*
+	* @param fallback Value for an absent key.
+	* @default fallback ""
+	* @returns A string codec.
+	*/
+	string(fallback = "") {
+		return single({
+			parse: (raw) => raw,
+			serialize: (value) => value,
+			default: fallback
+		});
+	},
+	/**
+	* Finite number; non-numeric input selects the default.
+	*
+	* @param fallback Value for an absent or invalid key.
+	* @default fallback 0
+	* @returns A number codec.
+	*/
+	number(fallback = 0) {
+		return single({
+			parse: (raw) => {
+				const value = raw.trim() === "" ? NaN : Number(raw);
+				return Number.isFinite(value) ? value : fallback;
+			},
+			serialize: String,
+			default: fallback
+		});
+	},
+	/**
+	* 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.
+	*/
+	boolean(fallback = false) {
+		return single({
+			parse: (raw) => {
+				if (raw === "" || raw === "true" || raw === "1") return true;
+				if (raw === "false" || raw === "0") return false;
+				return fallback;
+			},
+			serialize: String,
+			default: fallback
+		});
+	},
+	/**
+	* 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.
+	*/
+	enum(values, fallback) {
+		const allowed = new Set(values);
+		const isAllowed = (raw) => allowed.has(raw);
+		return single({
+			parse: (raw) => isAllowed(raw) ? raw : fallback,
+			serialize: (value) => value,
+			default: fallback
+		});
+	},
+	/**
+	* 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 `[]`.
+	*/
+	array: 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.
+	*/
+	json(fallback, validate) {
+		const accept = validate ?? ((candidate) => sameJsonKind(fallback, candidate));
+		return single({
+			parse: (raw) => {
+				const candidate = JSON.parse(raw);
+				return accept(candidate) ? candidate : fallback;
+			},
+			serialize: (value) => JSON.stringify(value),
+			default: fallback
+		});
+	},
+	/**
+	* Single-value codec from explicit parse/serialize functions.
+	*
+	* @param definition Parse, serialize, and default.
+	* @returns The codec.
+	*/
+	custom(definition) {
+		return single(definition);
+	}
+};
+function safeParse(codec, values) {
+	try {
+		return codec.parse(values);
+	} catch {
+		return codec.default;
+	}
+}
+function toSearch(source) {
+	if (source instanceof URLSearchParams) return new URLSearchParams(source);
+	if (source instanceof URL) return new URLSearchParams(source.search);
+	const withoutHash = source.split("#", 1)[0] ?? "";
+	const query = withoutHash.indexOf("?");
+	return new URLSearchParams(query === -1 ? "" : withoutHash.slice(query + 1));
+}
+/**
+* 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.
+*/
+function parseSearchParams(schema, search) {
+	const params = toSearch(search);
+	const entries = Object.keys(schema).map((key) => {
+		const codec = schema[key];
+		return [key, codec === void 0 ? void 0 : safeParse(codec, params.getAll(key))];
+	});
+	return Object.fromEntries(entries);
+}
+function sameValues(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+/**
+* 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.
+*/
+function serializeSearchParams(schema, values, options = {}) {
+	const params = options.base === void 0 ? new URLSearchParams() : toSearch(options.base);
+	const removeDefaults = options.removeDefaults ?? true;
+	for (const key of Object.keys(schema)) {
+		const codec = schema[key];
+		if (codec === void 0 || !(key in values)) continue;
+		const encoded = codec.serialize(values[key]);
+		const [first, ...rest] = encoded;
+		if (first === void 0 || removeDefaults && sameValues(encoded, codec.serialize(codec.default))) {
+			params.delete(key);
+			continue;
+		}
+		params.set(key, first);
+		for (const value of rest) params.append(key, value);
+	}
+	return params;
+}
+function browserHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+/**
+* 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.
+*/
+function useUrlSearchParams(schema, options = {}) {
+	const resolveHost = () => options.host === void 0 ? browserHost() : toValue(options.host) ?? void 0;
+	const removeDefaults = options.removeDefaults ?? true;
+	const params = shallowReactive(parseSearchParams(schema, toValue(options.ssrUrl) ?? ""));
+	const supported = ref(false);
+	let syncedSearch;
+	let applying = false;
+	const encode = (host) => serializeSearchParams(schema, params, {
+		base: host.location.search,
+		removeDefaults
+	}).toString();
+	const refresh = () => {
+		const host = resolveHost();
+		supported.value = host !== void 0;
+		const source = host === void 0 ? toValue(options.ssrUrl) ?? "" : host.location.search;
+		applying = true;
+		try {
+			Object.assign(params, parseSearchParams(schema, source));
+		} finally {
+			applying = false;
+		}
+		if (host !== void 0) syncedSearch = encode(host);
+	};
+	let stopHost = () => void 0;
+	const startHost = () => {
+		stopHost = watch(resolveHost, (host, _previous, onCleanup) => {
+			refresh();
+			if (host === void 0) return;
+			host.addEventListener("popstate", refresh);
+			onCleanup(() => host.removeEventListener("popstate", refresh));
+		}, {
+			immediate: true,
+			flush: "sync"
+		});
+	};
+	if (hasInjectionContext()) onMounted(startHost);
+	else startHost();
+	const stopWrite = watch(() => {
+		const host = resolveHost();
+		return host === void 0 ? void 0 : encode(host);
+	}, (search) => {
+		const host = resolveHost();
+		if (applying || search === void 0 || host === void 0) return;
+		if (search === syncedSearch) return;
+		syncedSearch = search;
+		const { pathname, hash } = host.location;
+		const url = `${pathname}${search === "" ? "" : `?${search}`}${hash}`;
+		if ((options.mode ?? "replace") === "push") host.history.pushState(null, "", url);
+		else host.history.replaceState(host.history.state, "", url);
+	}, { flush: "sync" });
+	const stop = () => {
+		stopHost();
+		stopWrite();
+	};
+	tryOnScopeDispose(stop);
+	return {
+		params,
+		supported: readonly(supported),
+		refresh,
+		stop
+	};
+}
+//#endregion
+export { parseSearchParams, searchParam, serializeSearchParams, useUrlSearchParams };

package/dist/use-usb.d.mts

@@ -0,0 +1,212 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-usb.d.ts
+/** Device filter for `requestDevice`. */
+interface USBDeviceFilter {
+  /** USB vendor id. */
+  readonly vendorId?: number;
+  /** USB product id. */
+  readonly productId?: number;
+  /** Device or interface class code. */
+  readonly classCode?: number;
+  /** Device or interface subclass code. */
+  readonly subclassCode?: number;
+  /** Device or interface protocol code. */
+  readonly protocolCode?: number;
+  /** Serial number. */
+  readonly serialNumber?: string;
+}
+/** Transfer status reported by WebUSB. */
+type USBTransferStatus = "ok" | "stall" | "babble";
+/** Result of an IN transfer. */
+interface USBInTransferResultLike {
+  /** Transfer status. */
+  readonly status: USBTransferStatus;
+  /** Received bytes. */
+  readonly data?: DataView | null;
+}
+/** Result of an OUT transfer. */
+interface USBOutTransferResultLike {
+  /** Transfer status. */
+  readonly status: USBTransferStatus;
+  /** Number of bytes written. */
+  readonly bytesWritten: number;
+}
+/** Setup packet of a control transfer. */
+interface USBControlTransferSetup {
+  /** Request category. */
+  readonly requestType: "standard" | "class" | "vendor";
+  /** Request target. */
+  readonly recipient: "device" | "interface" | "endpoint" | "other";
+  /** `bRequest`. */
+  readonly request: number;
+  /** `wValue`. */
+  readonly value: number;
+  /** `wIndex`. */
+  readonly index: number;
+}
+/** Minimal `USBDevice` used by {@link useUSB}. */
+interface USBDeviceLike {
+  /** USB vendor id. */
+  readonly vendorId: number;
+  /** USB product id. */
+  readonly productId: number;
+  /** Product name. */
+  readonly productName?: string | undefined;
+  /** Serial number. */
+  readonly serialNumber?: string | undefined;
+  /** Whether a session is open. */
+  readonly opened: boolean;
+  /** Start a session. */
+  open(): Promise<void>;
+  /** End the session. */
+  close(): Promise<void>;
+  /** Select a configuration by value. */
+  selectConfiguration(configurationValue: number): Promise<void>;
+  /** Claim an interface. */
+  claimInterface(interfaceNumber: number): Promise<void>;
+  /** Release a claimed interface. */
+  releaseInterface(interfaceNumber: number): Promise<void>;
+  /** Bulk/interrupt IN transfer. */
+  transferIn(endpointNumber: number, length: number): Promise<USBInTransferResultLike>;
+  /** Bulk/interrupt OUT transfer. */
+  transferOut(endpointNumber: number, data: BufferSource): Promise<USBOutTransferResultLike>;
+  /** Control IN transfer. */
+  controlTransferIn(setup: USBControlTransferSetup, length: number): Promise<USBInTransferResultLike>;
+  /** Control OUT transfer. */
+  controlTransferOut(setup: USBControlTransferSetup, data?: BufferSource): Promise<USBOutTransferResultLike>;
+}
+/** `navigator.usb`-like capability used by {@link useUSB}. */
+interface USBHost extends EventTarget {
+  /** Devices the page already has access to. */
+  getDevices(): Promise<USBDeviceLike[]>;
+  /** Prompt the user for a device. */
+  requestDevice(options: {
+    readonly filters: USBDeviceFilter[];
+  }): Promise<USBDeviceLike>;
+}
+/** Plain, reactive-friendly description of a granted device. */
+interface USBDeviceInfo {
+  /** The live device, for passing back to the actions. */
+  readonly device: USBDeviceLike;
+  /** USB vendor id. */
+  readonly vendorId: number;
+  /** USB product id. */
+  readonly productId: number;
+  /** Product name (empty when unknown). */
+  readonly productName: string;
+  /** Serial number (empty when unknown). */
+  readonly serialNumber: string;
+  /** Whether a session was open when the list was refreshed. */
+  readonly opened: boolean;
+}
+/** Options for {@link useUSB}. */
+interface UseUSBOptions {
+  /**
+   * `navigator.usb`-like capability.
+   *
+   * @default window.navigator.usb when it exists
+   */
+  readonly host?: MaybeRefOrGetter<USBHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useUSB}. */
+interface USBControls {
+  /** Whether WebUSB is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Granted devices, refreshed on `connect` / `disconnect` and after every action. */
+  readonly devices: Readonly<ShallowRef<readonly USBDeviceInfo[]>>;
+  /** Most recent failure. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Prompt the user for a device (requires user activation).
+   *
+   * @returns The chosen device, or `undefined` when cancelled or failed.
+   */
+  readonly requestDevice: (filters?: USBDeviceFilter[]) => Promise<USBDeviceLike | undefined>;
+  /**
+   * Refresh `devices`.
+   *
+   * @returns The granted devices.
+   */
+  readonly getDevices: () => Promise<readonly USBDeviceInfo[]>;
+  /**
+   * Open a session.
+   *
+   * @returns Whether it succeeded.
+   */
+  readonly open: (device: USBDeviceLike) => Promise<boolean>;
+  /**
+   * Close a session.
+   *
+   * @returns Whether it succeeded.
+   */
+  readonly close: (device: USBDeviceLike) => Promise<boolean>;
+  /**
+   * Select a configuration.
+   *
+   * @returns Whether it succeeded.
+   */
+  readonly selectConfiguration: (device: USBDeviceLike, value: number) => Promise<boolean>;
+  /**
+   * Claim an interface.
+   *
+   * @returns Whether it succeeded.
+   */
+  readonly claimInterface: (device: USBDeviceLike, interfaceNumber: number) => Promise<boolean>;
+  /**
+   * Release an interface.
+   *
+   * @returns Whether it succeeded.
+   */
+  readonly releaseInterface: (device: USBDeviceLike, interfaceNumber: number) => Promise<boolean>;
+  /**
+   * Bulk/interrupt IN transfer.
+   *
+   * @returns The result, or `undefined` on failure.
+   */
+  readonly transferIn: (device: USBDeviceLike, endpoint: number, length: number) => Promise<USBInTransferResultLike | undefined>;
+  /**
+   * Bulk/interrupt OUT transfer.
+   *
+   * @returns The result, or `undefined` on failure.
+   */
+  readonly transferOut: (device: USBDeviceLike, endpoint: number, data: BufferSource) => Promise<USBOutTransferResultLike | undefined>;
+  /**
+   * Control IN transfer.
+   *
+   * @returns The result, or `undefined` on failure.
+   */
+  readonly controlTransferIn: (device: USBDeviceLike, setup: USBControlTransferSetup, length: number) => Promise<USBInTransferResultLike | undefined>;
+  /**
+   * Control OUT transfer.
+   *
+   * @returns The result, or `undefined` on failure.
+   */
+  readonly controlTransferOut: (device: USBDeviceLike, setup: USBControlTransferSetup, data?: BufferSource) => Promise<USBOutTransferResultLike | undefined>;
+}
+/**
+ * Talk to USB devices with the WebUSB API.
+ *
+ * `devices` lists granted devices as plain snapshots and follows the host's
+ * `connect` / `disconnect` events. The device actions are thin wrappers over
+ * `USBDevice` that resolve to a boolean or the transfer result and record
+ * failures in `error` instead of rejecting. Host listeners are removed and
+ * sessions opened through `open()` are closed when the owning reactive scope
+ * stops; outside a scope call `close()` per device.
+ *
+ * Server rendering: `supported` is false and `devices` is empty.
+ *
+ * @example
+ * ```ts
+ * const usb = useUSB();
+ * const device = await usb.requestDevice([{ vendorId: 0x2341 }]);
+ * if (device && (await usb.open(device))) await usb.claimInterface(device, 0);
+ * ```
+ *
+ * @param options Capability host.
+ * @default options {}
+ * @returns USB state and actions.
+ */
+declare function useUSB(options?: UseUSBOptions): USBControls;
+//#endregion
+export { USBControlTransferSetup, USBControls, USBDeviceFilter, USBDeviceInfo, USBDeviceLike, USBHost, USBInTransferResultLike, USBOutTransferResultLike, USBTransferStatus, UseUSBOptions, useUSB };

package/dist/use-usb.mjs

@@ -0,0 +1,137 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, shallowReadonly, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-usb.ts
+function browserUSBHost() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator } = window;
+	const usb = "usb" in navigator ? navigator.usb : void 0;
+	return isUSBHost(usb) ? usb : void 0;
+}
+function isUSBHost(value) {
+	return typeof value === "object" && value !== null && "requestDevice" in value;
+}
+function describe(device) {
+	return {
+		device,
+		vendorId: device.vendorId,
+		productId: device.productId,
+		productName: device.productName ?? "",
+		serialNumber: device.serialNumber ?? "",
+		opened: device.opened
+	};
+}
+/**
+* Talk to USB devices with the WebUSB API.
+*
+* `devices` lists granted devices as plain snapshots and follows the host's
+* `connect` / `disconnect` events. The device actions are thin wrappers over
+* `USBDevice` that resolve to a boolean or the transfer result and record
+* failures in `error` instead of rejecting. Host listeners are removed and
+* sessions opened through `open()` are closed when the owning reactive scope
+* stops; outside a scope call `close()` per device.
+*
+* Server rendering: `supported` is false and `devices` is empty.
+*
+* @example
+* ```ts
+* const usb = useUSB();
+* const device = await usb.requestDevice([{ vendorId: 0x2341 }]);
+* if (device && (await usb.open(device))) await usb.claimInterface(device, 0);
+* ```
+*
+* @param options Capability host.
+* @default options {}
+* @returns USB state and actions.
+*/
+function useUSB(options = {}) {
+	const devices = shallowRef([]);
+	const error = shallowRef(void 0);
+	const owned = /* @__PURE__ */ new Set();
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => !hydrated.value ? void 0 : options.host === void 0 ? browserUSBHost() : toValue(options.host) ?? void 0;
+	const snapshot = () => {
+		devices.value = devices.value.map((entry) => describe(entry.device));
+	};
+	const attempt = async (action) => {
+		try {
+			const value = await action();
+			error.value = void 0;
+			return value;
+		} catch (cause) {
+			error.value = cause;
+			return;
+		} finally {
+			snapshot();
+		}
+	};
+	const succeeded = async (action) => await attempt(() => action().then(() => true)) === true;
+	const getDevices = async () => {
+		const host = resolveHost();
+		if (!host) return devices.value;
+		try {
+			devices.value = (await host.getDevices()).map(describe);
+		} catch (cause) {
+			error.value = cause;
+		}
+		return devices.value;
+	};
+	const requestDevice = async (filters = []) => {
+		const host = resolveHost();
+		if (!host) return void 0;
+		const chosen = await attempt(() => host.requestDevice({ filters }));
+		if (chosen) await getDevices();
+		return chosen;
+	};
+	const open = async (device) => {
+		const opened = await succeeded(() => device.open());
+		if (opened) owned.add(device);
+		return opened;
+	};
+	const close = (device) => {
+		owned.delete(device);
+		return succeeded(() => device.close());
+	};
+	const onConnectionChange = () => {
+		getDevices();
+	};
+	watch(resolveHost, (host, _previous, onCleanup) => {
+		if (!host) {
+			devices.value = [];
+			return;
+		}
+		host.addEventListener("connect", onConnectionChange);
+		host.addEventListener("disconnect", onConnectionChange);
+		onCleanup(() => {
+			host.removeEventListener("connect", onConnectionChange);
+			host.removeEventListener("disconnect", onConnectionChange);
+		});
+		getDevices();
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	tryOnScopeDispose(() => {
+		for (const device of owned) if (device.opened) close(device);
+	});
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		devices: shallowReadonly(devices),
+		error: readonly(error),
+		requestDevice,
+		getDevices,
+		open,
+		close,
+		selectConfiguration: (device, value) => succeeded(() => device.selectConfiguration(value)),
+		claimInterface: (device, number) => succeeded(() => device.claimInterface(number)),
+		releaseInterface: (device, number) => succeeded(() => device.releaseInterface(number)),
+		transferIn: (device, endpoint, length) => attempt(() => device.transferIn(endpoint, length)),
+		transferOut: (device, endpoint, data) => attempt(() => device.transferOut(endpoint, data)),
+		controlTransferIn: (device, setup, length) => attempt(() => device.controlTransferIn(setup, length)),
+		controlTransferOut: (device, setup, data) => attempt(() => data === void 0 ? device.controlTransferOut(setup) : device.controlTransferOut(setup, data))
+	};
+}
+//#endregion
+export { useUSB };