@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-async-state.d.mts

@@ -0,0 +1,86 @@
+import { ShallowRef } from "vue";
+
+//#region src/use-async-state.d.ts
+/** Options for {@link useAsyncState}. */
+interface UseAsyncStateOptions<Data> {
+  /**
+   * Execute once right away. Only available for producers without
+   * parameters; pass `false` to run a producer that takes arguments through
+   * {@link AsyncState.execute}.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Restore the initial state at the start of every execution.
+   *
+   * @default false
+   */
+  readonly resetOnExecute?: boolean;
+  /**
+   * Re-throw failures from `execute` in addition to storing them.
+   *
+   * @default false
+   */
+  readonly throwError?: boolean;
+  /**
+   * Called with every failure of the newest execution.
+   *
+   * @default undefined
+   */
+  readonly onError?: (error: unknown) => void;
+  /**
+   * Called with every successful result of the newest execution.
+   *
+   * @default undefined
+   */
+  readonly onSuccess?: (data: Data) => void;
+}
+/** Reactive state and controls returned by {@link useAsyncState}. */
+interface AsyncState<Data, Initial, Parameters extends readonly unknown[]> {
+  /** Newest result, or the initial state. */
+  readonly state: Readonly<ShallowRef<Data | Initial>>;
+  /** Whether at least one execution succeeded. */
+  readonly isReady: Readonly<ShallowRef<boolean>>;
+  /** Whether an execution is in flight. */
+  readonly isLoading: Readonly<ShallowRef<boolean>>;
+  /** Failure of the newest execution, cleared when a new one starts. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Run the producer. Only the newest execution may update the state.
+   *
+   * @returns The resulting state (the previous state for failed or
+   * superseded executions unless `throwError` is set).
+   */
+  readonly execute: (...args: Parameters) => Promise<Data | Initial>;
+}
+/**
+ * Reactive state for an async producer.
+ *
+ * Tracks the result, loading, readiness, and error of the newest execution;
+ * out-of-order completions of older executions are ignored, so the state
+ * always reflects the latest request. The typing is arity-aware: producers
+ * with parameters require `{ immediate: false }` and `execute` keeps their
+ * parameter tuple. On the server an immediate execution starts but is not
+ * awaited, so both sides render the initial state with `isLoading: true`.
+ *
+ * @example
+ * ```ts
+ * const { state, isLoading, execute } = useAsyncState((id: string) => fetchUser(id), null, {
+ *   immediate: false,
+ * });
+ * await execute("u-1");
+ * ```
+ *
+ * @param producer Async function producing the data.
+ * @param initial State before the first success.
+ * @param options Immediate execution, reset, error, and success policy.
+ * @default options {}
+ * @returns Reactive state and the `execute` control.
+ */
+declare function useAsyncState<Data, Initial>(producer: () => Promise<Data>, initial: Initial, options?: UseAsyncStateOptions<Data>): AsyncState<Data, Initial, []>;
+declare function useAsyncState<Data, Initial, Parameters extends readonly unknown[]>(producer: (...args: Parameters) => Promise<Data>, initial: Initial, options: UseAsyncStateOptions<Data> & {
+  readonly immediate: false;
+}): AsyncState<Data, Initial, Parameters>;
+//#endregion
+export { AsyncState, UseAsyncStateOptions, useAsyncState };

package/dist/use-async-state.mjs

@@ -0,0 +1,41 @@
+import { shallowRef } from "vue";
+//#region src/use-async-state.ts
+function useAsyncState(producer, initial, options = {}) {
+	const state = shallowRef(initial);
+	const isReady = shallowRef(false);
+	const isLoading = shallowRef(false);
+	const error = shallowRef(void 0);
+	let generation = 0;
+	const execute = async (...args) => {
+		generation += 1;
+		const own = generation;
+		if (options.resetOnExecute ?? false) state.value = initial;
+		error.value = void 0;
+		isLoading.value = true;
+		try {
+			const data = await producer(...args);
+			if (own !== generation) return state.value;
+			state.value = data;
+			isReady.value = true;
+			options.onSuccess?.(data);
+		} catch (failure) {
+			if (own !== generation) return state.value;
+			error.value = failure;
+			options.onError?.(failure);
+			if (options.throwError ?? false) throw failure;
+		} finally {
+			if (own === generation) isLoading.value = false;
+		}
+		return state.value;
+	};
+	if (options.immediate ?? true) execute().catch(() => void 0);
+	return {
+		state,
+		isReady,
+		isLoading,
+		error,
+		execute
+	};
+}
+//#endregion
+export { useAsyncState };

package/dist/use-barcode-detector.d.mts

@@ -0,0 +1,159 @@
+import { FrameScheduler } from "./use-raf-fn.mjs";
+import { ComputedRef, MaybeRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-barcode-detector.d.ts
+/** Barcode symbology supported by the Barcode Detection API. */
+type BarcodeFormat = "aztec" | "code_128" | "code_39" | "code_93" | "codabar" | "data_matrix" | "ean_13" | "ean_8" | "itf" | "pdf417" | "qr_code" | "upc_a" | "upc_e" | "unknown";
+/** Axis-aligned bounds of a detected barcode, in source pixels. */
+interface BarcodeBoundingBox {
+  /** Left edge. */
+  readonly x: number;
+  /** Top edge. */
+  readonly y: number;
+  /** Width. */
+  readonly width: number;
+  /** Height. */
+  readonly height: number;
+}
+/** Corner of a detected barcode, in source pixels. */
+interface BarcodePoint {
+  /** Horizontal coordinate. */
+  readonly x: number;
+  /** Vertical coordinate. */
+  readonly y: number;
+}
+/** Normalized detection result. */
+interface DetectedBarcode {
+  /** Decoded text. */
+  readonly rawValue: string;
+  /** Symbology (`"unknown"` for formats this module does not know). */
+  readonly format: BarcodeFormat;
+  /** Bounding box. */
+  readonly boundingBox: BarcodeBoundingBox;
+  /** Corner points, clockwise from top-left. */
+  readonly cornerPoints: readonly BarcodePoint[];
+}
+/** Raw detection result produced by a host detector. */
+interface DetectedBarcodeLike {
+  /** Decoded text. */
+  readonly rawValue: string;
+  /** Symbology name. */
+  readonly format: string;
+  /** Bounding box. */
+  readonly boundingBox: BarcodeBoundingBox;
+  /** Corner points. */
+  readonly cornerPoints: readonly BarcodePoint[];
+}
+/** Minimal `BarcodeDetector` instance. */
+interface BarcodeDetectorLike {
+  /** Detect barcodes in an image source. */
+  detect(source: ImageBitmapSource): Promise<readonly DetectedBarcodeLike[]>;
+}
+/** Minimal `BarcodeDetector` constructor. */
+interface BarcodeDetectorHost {
+  /** Create a detector restricted to `formats`. */
+  new (options?: {
+    formats?: BarcodeFormat[];
+  }): BarcodeDetectorLike;
+  /** Formats the platform can detect. */
+  getSupportedFormats?(): Promise<readonly string[]>;
+}
+/** Options for {@link useBarcodeDetector}. */
+interface UseBarcodeDetectorOptions {
+  /**
+   * `BarcodeDetector` constructor for alternate runtimes and tests. A ref
+   * (not a getter) because the host is a constructor function.
+   *
+   * @default window.BarcodeDetector when it exists
+   */
+  readonly BarcodeDetector?: MaybeRef<BarcodeDetectorHost | null | undefined>;
+  /**
+   * Formats to detect. Reactive; a new detector is created when it changes.
+   *
+   * @default undefined (every supported format)
+   */
+  readonly formats?: MaybeRefOrGetter<readonly BarcodeFormat[] | undefined>;
+  /**
+   * Source scanned continuously (for example a camera `<video>`). Video
+   * frames are skipped until `readyState >= 2`.
+   *
+   * @default undefined
+   */
+  readonly source?: MaybeRefOrGetter<ImageBitmapSource | null | undefined>;
+  /**
+   * Start continuous detection immediately.
+   *
+   * @default true when `source` is set
+   */
+  readonly immediate?: boolean;
+  /**
+   * Maximum continuous detections per second. A frame is also skipped while
+   * the previous detection is still running.
+   *
+   * @default 10
+   */
+  readonly fpsLimit?: MaybeRefOrGetter<number | undefined>;
+  /**
+   * Frame host for continuous detection. An injected scheduler also drives
+   * frames without a browser `window` (native or offscreen hosts, tests).
+   *
+   * @default globalThis animation-frame functions when available
+   */
+  readonly scheduler?: FrameScheduler;
+}
+/** Reactive state and actions returned by {@link useBarcodeDetector}. */
+interface BarcodeDetectorControls {
+  /** Whether the Barcode Detection API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Barcodes found by the most recent successful detection. */
+  readonly barcodes: Readonly<ShallowRef<readonly DetectedBarcode[]>>;
+  /** Most recent detection failure, cleared on success. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /** Whether continuous detection is running. */
+  readonly isActive: Readonly<ShallowRef<boolean>>;
+  /**
+   * Detect barcodes once.
+   *
+   * @param source Image, video, canvas, bitmap, blob, or image data.
+   * @returns Detected barcodes; empty when unsupported or failing (see `error`).
+   */
+  readonly detect: (source: ImageBitmapSource) => Promise<readonly DetectedBarcode[]>;
+  /**
+   * Formats the platform supports.
+   *
+   * @returns Known supported formats; empty when unsupported or failing.
+   */
+  readonly getSupportedFormats: () => Promise<BarcodeFormat[]>;
+  /** Start continuous detection of `source`. */
+  readonly start: () => void;
+  /** Stop continuous detection. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Detect barcodes and QR codes with the Barcode Detection API.
+ *
+ * `detect(source)` scans once; with a `source` (typically a camera video),
+ * detection also runs on animation frames through {@link useRafFn}, throttled
+ * by `fpsLimit` and never overlapping. Results are normalized into plain
+ * {@link DetectedBarcode} objects. The frame loop stops with the owning
+ * reactive scope; outside a scope call `stop()`.
+ *
+ * Server rendering: nothing is constructed or scheduled, `supported` is
+ * false and `barcodes` is empty.
+ * Inside a component `supported` turns true only after mounting, so
+ * hydration renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const video = useTemplateRef<HTMLVideoElement>("video");
+ * const { barcodes } = useBarcodeDetector({ source: video, formats: ["qr_code"] });
+ * ```
+ *
+ * @param options Constructor host, formats, and continuous-scan policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_RAF_INVALID_FPS_LIMIT` for an invalid `fpsLimit`.
+ * @returns Detector state and actions.
+ */
+declare function useBarcodeDetector(options?: UseBarcodeDetectorOptions): BarcodeDetectorControls;
+//#endregion
+export { BarcodeBoundingBox, BarcodeDetectorControls, BarcodeDetectorHost, BarcodeDetectorLike, BarcodeFormat, BarcodePoint, DetectedBarcode, DetectedBarcodeLike, UseBarcodeDetectorOptions, useBarcodeDetector };

package/dist/use-barcode-detector.mjs

@@ -0,0 +1,143 @@
+import { useRafFn } from "./use-raf-fn.mjs";
+import { computed, hasInjectionContext, readonly, shallowRef, toValue, unref, watchPostEffect } from "vue";
+//#region src/use-barcode-detector.ts
+const knownFormats = [
+	"aztec",
+	"code_128",
+	"code_39",
+	"code_93",
+	"codabar",
+	"data_matrix",
+	"ean_13",
+	"ean_8",
+	"itf",
+	"pdf417",
+	"qr_code",
+	"upc_a",
+	"upc_e",
+	"unknown"
+];
+function isBarcodeFormat(value) {
+	return knownFormats.includes(value);
+}
+function isDetectorHost(candidate) {
+	return typeof candidate === "function";
+}
+function browserDetector() {
+	if (typeof window === "undefined") return void 0;
+	const candidate = Reflect.get(window, "BarcodeDetector");
+	return isDetectorHost(candidate) ? candidate : void 0;
+}
+function isFrameReady(source) {
+	return !("readyState" in source) || typeof source.readyState !== "number" || source.readyState >= 2;
+}
+function normalize(barcode) {
+	const { x, y, width, height } = barcode.boundingBox;
+	return {
+		rawValue: barcode.rawValue,
+		format: isBarcodeFormat(barcode.format) ? barcode.format : "unknown",
+		boundingBox: {
+			x,
+			y,
+			width,
+			height
+		},
+		cornerPoints: barcode.cornerPoints.map((point) => ({
+			x: point.x,
+			y: point.y
+		}))
+	};
+}
+/**
+* Detect barcodes and QR codes with the Barcode Detection API.
+*
+* `detect(source)` scans once; with a `source` (typically a camera video),
+* detection also runs on animation frames through {@link useRafFn}, throttled
+* by `fpsLimit` and never overlapping. Results are normalized into plain
+* {@link DetectedBarcode} objects. The frame loop stops with the owning
+* reactive scope; outside a scope call `stop()`.
+*
+* Server rendering: nothing is constructed or scheduled, `supported` is
+* false and `barcodes` is empty.
+* Inside a component `supported` turns true only after mounting, so
+* hydration renders this server state first.
+*
+* @example
+* ```ts
+* const video = useTemplateRef<HTMLVideoElement>("video");
+* const { barcodes } = useBarcodeDetector({ source: video, formats: ["qr_code"] });
+* ```
+*
+* @param options Constructor host, formats, and continuous-scan policy.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_RAF_INVALID_FPS_LIMIT` for an invalid `fpsLimit`.
+* @returns Detector state and actions.
+*/
+function useBarcodeDetector(options = {}) {
+	const barcodes = shallowRef([]);
+	const error = shallowRef(void 0);
+	let cached;
+	let busy = false;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => options.BarcodeDetector === void 0 ? browserDetector() : unref(options.BarcodeDetector) ?? void 0;
+	const resolveDetector = (Host) => {
+		const formats = toValue(options.formats);
+		const key = formats?.join() ?? "*";
+		if (cached?.host !== Host || cached.key !== key) cached = {
+			host: Host,
+			key,
+			detector: new Host(formats ? { formats: [...formats] } : void 0)
+		};
+		return cached.detector;
+	};
+	const detect = async (source) => {
+		const host = resolveHost();
+		if (!host) return [];
+		try {
+			const found = (await resolveDetector(host).detect(source)).map(normalize);
+			barcodes.value = found;
+			error.value = void 0;
+			return found;
+		} catch (cause) {
+			error.value = cause;
+			return [];
+		}
+	};
+	const getSupportedFormats = async () => {
+		try {
+			return [...await resolveHost()?.getSupportedFormats?.() ?? []].filter(isBarcodeFormat);
+		} catch {
+			return [];
+		}
+	};
+	const loop = useRafFn(() => {
+		const source = toValue(options.source);
+		if (busy || !source || !isFrameReady(source)) return;
+		busy = true;
+		detect(source).finally(() => {
+			busy = false;
+		});
+	}, {
+		immediate: options.immediate ?? options.source !== void 0,
+		fpsLimit: () => toValue(options.fpsLimit) ?? 10,
+		...options.scheduler ? {
+			scheduler: options.scheduler,
+			runOnServer: true
+		} : {}
+	});
+	return {
+		supported: computed(() => hydrated.value && resolveHost() !== void 0),
+		barcodes: readonly(barcodes),
+		error: readonly(error),
+		isActive: loop.isActive,
+		detect,
+		getSupportedFormats,
+		start: loop.resume,
+		stop: loop.pause
+	};
+}
+//#endregion
+export { useBarcodeDetector };

package/dist/use-bluetooth.d.mts

@@ -0,0 +1,164 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-bluetooth.d.ts
+/** GATT service or characteristic UUID: a full UUID string, an alias name, or a 16/32-bit number. */
+type BluetoothUUIDLike = string | number;
+/** Scan filter for `requestDevice`. */
+interface BluetoothDeviceFilter {
+  /** Services the device must advertise. */
+  readonly services?: readonly BluetoothUUIDLike[];
+  /** Exact device name. */
+  readonly name?: string;
+  /** Device name prefix. */
+  readonly namePrefix?: string;
+}
+/** Options for `requestDevice`: explicit filters or every nearby device. */
+type BluetoothRequestOptions = {
+  /** Accepted device filters. */readonly filters: readonly BluetoothDeviceFilter[]; /** Extra services the page may access. */
+  readonly optionalServices?: readonly BluetoothUUIDLike[];
+} | {
+  /** Offer every nearby device. */readonly acceptAllDevices: true; /** Extra services the page may access. */
+  readonly optionalServices?: readonly BluetoothUUIDLike[];
+};
+/** Minimal `BluetoothRemoteGATTCharacteristic` used by {@link useBluetooth}. */
+interface BluetoothCharacteristicLike extends EventTarget {
+  /** Last read or notified value. */
+  readonly value?: DataView | null | undefined;
+  /** Read the value. */
+  readValue(): Promise<DataView>;
+  /** Write and wait for the device's acknowledgement. */
+  writeValueWithResponse(value: BufferSource): Promise<void>;
+  /** Write without acknowledgement. */
+  writeValueWithoutResponse(value: BufferSource): Promise<void>;
+  /** Start `characteristicvaluechanged` notifications. */
+  startNotifications(): Promise<unknown>;
+  /** Stop notifications. */
+  stopNotifications(): Promise<unknown>;
+}
+/** Minimal `BluetoothRemoteGATTService`. */
+interface BluetoothServiceLike {
+  /** Look up a characteristic. */
+  getCharacteristic(characteristic: BluetoothUUIDLike): Promise<BluetoothCharacteristicLike>;
+}
+/** Minimal `BluetoothRemoteGATTServer`. */
+interface BluetoothGATTServerLike {
+  /** Whether the server is connected. */
+  readonly connected: boolean;
+  /** Connect to the server. */
+  connect(): Promise<unknown>;
+  /** Disconnect from the server. */
+  disconnect(): void;
+  /** Look up a primary service. */
+  getPrimaryService(service: BluetoothUUIDLike): Promise<BluetoothServiceLike>;
+}
+/** Minimal `BluetoothDevice` used by {@link useBluetooth}. */
+interface BluetoothDeviceLike extends EventTarget {
+  /** Opaque device identifier. */
+  readonly id: string;
+  /** Advertised name. */
+  readonly name?: string | undefined;
+  /** GATT server, when the device supports GATT. */
+  readonly gatt?: BluetoothGATTServerLike | undefined;
+}
+/** `navigator.bluetooth`-like capability used by {@link useBluetooth}. */
+interface BluetoothHost extends EventTarget {
+  /** Whether a Bluetooth adapter is available. */
+  getAvailability(): Promise<boolean>;
+  /** Prompt the user for a device. */
+  requestDevice(options: BluetoothRequestOptions): Promise<BluetoothDeviceLike>;
+}
+/** Options for {@link useBluetooth}. */
+interface UseBluetoothOptions {
+  /**
+   * `navigator.bluetooth`-like capability.
+   *
+   * @default window.navigator.bluetooth when it exists
+   */
+  readonly host?: MaybeRefOrGetter<BluetoothHost | null | undefined>;
+  /**
+   * Default options for `requestDevice()`.
+   *
+   * @default { acceptAllDevices: true }
+   */
+  readonly requestOptions?: BluetoothRequestOptions;
+}
+/** Stops a notification subscription created by {@link BluetoothControls.notify}. */
+type BluetoothNotificationStop = () => Promise<void>;
+/** Reactive state and actions returned by {@link useBluetooth}. */
+interface BluetoothControls {
+  /** Whether Web Bluetooth is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether an adapter is available, following `availabilitychanged`. */
+  readonly available: Readonly<Ref<boolean>>;
+  /** Most recently chosen device. */
+  readonly device: Readonly<ShallowRef<BluetoothDeviceLike | undefined>>;
+  /** Whether the device's GATT server is connected. */
+  readonly connected: Readonly<Ref<boolean>>;
+  /** Most recent failure. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Prompt the user for a device (requires user activation). Disconnects
+   * the previous device.
+   *
+   * @returns The chosen device, or `undefined` when cancelled or failed.
+   */
+  readonly requestDevice: (options?: BluetoothRequestOptions) => Promise<BluetoothDeviceLike | undefined>;
+  /**
+   * Connect to the device's GATT server.
+   *
+   * @returns Whether the server is connected.
+   */
+  readonly connect: () => Promise<boolean>;
+  /** Stop notifications and disconnect the GATT server. Idempotent. */
+  readonly disconnect: () => void;
+  /**
+   * Read a characteristic.
+   *
+   * @returns The value, or `undefined` on failure.
+   */
+  readonly read: (service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike) => Promise<DataView | undefined>;
+  /**
+   * Write a characteristic, with a response unless `withoutResponse`.
+   *
+   * @returns Whether the write succeeded.
+   */
+  readonly write: (service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, value: BufferSource, options?: {
+    readonly withoutResponse?: boolean;
+  }) => Promise<boolean>;
+  /**
+   * Subscribe to characteristic notifications.
+   *
+   * @returns A stop function, or `undefined` on failure.
+   */
+  readonly notify: (service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, listener: (value: DataView) => void) => Promise<BluetoothNotificationStop | undefined>;
+}
+/**
+ * Connect to Bluetooth Low Energy devices with the Web Bluetooth API.
+ *
+ * `requestDevice()` prompts for a device, `connect()` connects its GATT
+ * server, and `read` / `write` / `notify` address characteristics by service
+ * and characteristic UUID. `connected` follows `gattserverdisconnected` and
+ * `available` follows `availabilitychanged`. Failures land in `error`.
+ * Notifications are stopped and the server disconnected when the owning
+ * reactive scope stops; outside a scope call `disconnect()`.
+ *
+ * Server rendering: `supported`, `available` and `connected` are false and
+ * nothing is queried.
+ * Inside a component the host is resolved after mounting, so hydration
+ * renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const ble = useBluetooth({ requestOptions: { filters: [{ services: ["heart_rate"] }] } });
+ * await ble.requestDevice();
+ * await ble.connect();
+ * await ble.notify("heart_rate", "heart_rate_measurement", (value) => show(value.getUint8(1)));
+ * ```
+ *
+ * @param options Host and default request options.
+ * @default options {}
+ * @returns Bluetooth state and actions.
+ */
+declare function useBluetooth(options?: UseBluetoothOptions): BluetoothControls;
+//#endregion
+export { BluetoothCharacteristicLike, BluetoothControls, BluetoothDeviceFilter, BluetoothDeviceLike, BluetoothGATTServerLike, BluetoothHost, BluetoothNotificationStop, BluetoothRequestOptions, BluetoothServiceLike, BluetoothUUIDLike, UseBluetoothOptions, useBluetooth };