@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/use-hid.ts

@@ -0,0 +1,359 @@
+import {
+  computed,
+  hasInjectionContext,
+  readonly,
+  shallowReadonly,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Device filter for `requestDevice`. */
+export interface HIDDeviceFilter {
+  /** USB vendor id. */
+  readonly vendorId?: number;
+  /** USB product id. */
+  readonly productId?: number;
+  /** HID usage page. */
+  readonly usagePage?: number;
+  /** HID usage. */
+  readonly usage?: number;
+}
+
+/** Minimal `HIDDevice` used by {@link useHID}. */
+export interface HIDDeviceLike extends EventTarget {
+  /** Whether the device is open. */
+  readonly opened: boolean;
+  /** USB vendor id. */
+  readonly vendorId: number;
+  /** USB product id. */
+  readonly productId: number;
+  /** Product name. */
+  readonly productName: string;
+  /** Open the device. */
+  open(): Promise<void>;
+  /** Close the device. */
+  close(): Promise<void>;
+  /** Send an output report. */
+  sendReport(reportId: number, data: BufferSource): Promise<void>;
+  /** Send a feature report. */
+  sendFeatureReport(reportId: number, data: BufferSource): Promise<void>;
+  /** Read a feature report. */
+  receiveFeatureReport(reportId: number): Promise<DataView>;
+}
+
+/** `navigator.hid`-like capability used by {@link useHID}. */
+export interface HIDHost extends EventTarget {
+  /** Devices the page already has access to. */
+  getDevices(): Promise<HIDDeviceLike[]>;
+  /** Prompt the user for devices. */
+  requestDevice(options: { readonly filters: HIDDeviceFilter[] }): Promise<HIDDeviceLike[]>;
+}
+
+/** Plain, reactive-friendly description of a granted device. */
+export interface HIDDeviceInfo {
+  /** The live device, for passing back to the actions. */
+  readonly device: HIDDeviceLike;
+  /** USB vendor id. */
+  readonly vendorId: number;
+  /** USB product id. */
+  readonly productId: number;
+  /** Product name. */
+  readonly productName: string;
+  /** Whether the device was open when the list was refreshed. */
+  readonly opened: boolean;
+}
+
+/** An input report received from an open device. */
+export interface HIDInputReport {
+  /** Device that sent the report. */
+  readonly device: HIDDeviceLike;
+  /** Report id (`0` when the device does not use report ids). */
+  readonly reportId: number;
+  /** Report payload. */
+  readonly data: DataView;
+}
+
+/** Options for {@link useHID}. */
+export interface UseHIDOptions {
+  /**
+   * `navigator.hid`-like capability.
+   *
+   * @default window.navigator.hid when it exists
+   */
+  readonly host?: MaybeRefOrGetter<HIDHost | null | undefined>;
+
+  /**
+   * Receives input reports from every device opened through {@link HIDControls.open}.
+   *
+   * @default undefined
+   */
+  readonly onInputReport?: (report: HIDInputReport) => void;
+}
+
+/** Reactive state and actions returned by {@link useHID}. */
+export interface HIDControls {
+  /** Whether WebHID is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Granted devices, refreshed on `connect` / `disconnect`, open and close. */
+  readonly devices: Readonly<ShallowRef<readonly HIDDeviceInfo[]>>;
+  /** Most recent failure. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Prompt the user for devices (requires user activation).
+   *
+   * @returns The chosen devices (empty when cancelled or failed).
+   */
+  readonly requestDevice: (filters?: HIDDeviceFilter[]) => Promise<readonly HIDDeviceLike[]>;
+  /**
+   * Refresh `devices`.
+   *
+   * @returns The granted devices.
+   */
+  readonly getDevices: () => Promise<readonly HIDDeviceInfo[]>;
+  /**
+   * Open a device and start forwarding its input reports.
+   *
+   * @returns Whether the device is open.
+   */
+  readonly open: (device: HIDDeviceLike) => Promise<boolean>;
+  /**
+   * Stop forwarding reports and close a device.
+   *
+   * @returns Whether the device closed.
+   */
+  readonly close: (device: HIDDeviceLike) => Promise<boolean>;
+  /**
+   * Send an output report.
+   *
+   * @returns Whether the report was sent.
+   */
+  readonly sendReport: (
+    device: HIDDeviceLike,
+    reportId: number,
+    data: BufferSource,
+  ) => Promise<boolean>;
+  /**
+   * Send a feature report.
+   *
+   * @returns Whether the report was sent.
+   */
+  readonly sendFeatureReport: (
+    device: HIDDeviceLike,
+    reportId: number,
+    data: BufferSource,
+  ) => Promise<boolean>;
+  /**
+   * Read a feature report.
+   *
+   * @returns The report, or `undefined` on failure.
+   */
+  readonly receiveFeatureReport: (
+    device: HIDDeviceLike,
+    reportId: number,
+  ) => Promise<DataView | undefined>;
+}
+
+function browserHIDHost(): HIDHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { navigator } = window;
+  // WebHID is not part of the DOM lib; read it through a structural guard.
+  const hid: unknown = "hid" in navigator ? navigator.hid : undefined;
+  return isHIDHost(hid) ? hid : undefined;
+}
+
+function isHIDHost(value: unknown): value is HIDHost {
+  return typeof value === "object" && value !== null && "getDevices" in value;
+}
+
+function isInputReport(event: Event): event is Event & {
+  readonly reportId: number;
+  readonly data: DataView;
+} {
+  return "reportId" in event && "data" in event;
+}
+
+function describe(device: HIDDeviceLike): HIDDeviceInfo {
+  return {
+    device,
+    vendorId: device.vendorId,
+    productId: device.productId,
+    productName: device.productName,
+    opened: device.opened,
+  };
+}
+
+/**
+ * Talk to human-interface devices with the WebHID API.
+ *
+ * `devices` lists granted devices as plain snapshots and follows the host's
+ * `connect` / `disconnect` events. Devices opened through `open()` forward
+ * `inputreport` events to `onInputReport`. Every action resolves to a
+ * boolean or value and records failures in `error`. Report listeners are
+ * removed and opened devices closed when the owning reactive scope stops;
+ * outside a scope call `close()` per device.
+ *
+ * Server rendering: `supported` is false and `devices` is empty.
+ * Inside a component the host is resolved after mounting, so hydration
+ * renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const hid = useHID({ onInputReport: ({ reportId, data }) => read(reportId, data) });
+ * const [device] = await hid.requestDevice([{ vendorId: 0x054c }]);
+ * if (device) await hid.open(device);
+ * ```
+ *
+ * @param options Host and input report callback.
+ * @default options {}
+ * @returns HID state and actions.
+ */
+export function useHID(options: UseHIDOptions = {}): HIDControls {
+  const devices = shallowRef<readonly HIDDeviceInfo[]>([]);
+  const error = shallowRef<unknown>(undefined);
+  const reportListeners = new Map<HIDDeviceLike, (event: Event) => void>();
+  const owned = new Set<HIDDeviceLike>();
+
+  // Inside a component the host is resolved only after mounting, so a
+  // hydrating client renders the server's unsupported state first. Outside
+  // components it resolves synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+
+  const resolveHost = (): HIDHost | undefined => {
+    if (!hydrated.value) return undefined;
+    return options.host === undefined ? browserHIDHost() : (toValue(options.host) ?? undefined);
+  };
+
+  const attempt = async <Value>(
+    action: () => Promise<Value>,
+    clearError = true,
+  ): Promise<Value | undefined> => {
+    try {
+      const value = await action();
+      if (clearError) error.value = undefined;
+      return value;
+    } catch (cause) {
+      error.value = cause;
+      return undefined;
+    }
+  };
+
+  const getDevices = async (): Promise<readonly HIDDeviceInfo[]> => {
+    const host = resolveHost();
+    const granted = host ? await attempt(() => host.getDevices(), false) : [];
+    if (granted) devices.value = granted.map(describe);
+    return devices.value;
+  };
+
+  const requestDevice = async (
+    filters: HIDDeviceFilter[] = [],
+  ): Promise<readonly HIDDeviceLike[]> => {
+    const host = resolveHost();
+    if (!host) return [];
+    const chosen = await attempt(() => host.requestDevice({ filters }));
+    await getDevices();
+    return chosen ?? [];
+  };
+
+  const unlisten = (device: HIDDeviceLike): void => {
+    const listener = reportListeners.get(device);
+    if (!listener) return;
+    device.removeEventListener("inputreport", listener);
+    reportListeners.delete(device);
+  };
+
+  const open = async (device: HIDDeviceLike): Promise<boolean> => {
+    if (!device.opened && (await attempt(() => device.open().then(() => true))) !== true) {
+      return false;
+    }
+    owned.add(device);
+    const onInputReport = options.onInputReport;
+    if (onInputReport && !reportListeners.has(device)) {
+      const listener = (event: Event): void => {
+        if (isInputReport(event)) {
+          onInputReport({ device, reportId: event.reportId, data: event.data });
+        }
+      };
+      reportListeners.set(device, listener);
+      device.addEventListener("inputreport", listener);
+    }
+    devices.value = devices.value.map((entry) => describe(entry.device));
+    return true;
+  };
+
+  const close = async (device: HIDDeviceLike): Promise<boolean> => {
+    unlisten(device);
+    owned.delete(device);
+    const closed =
+      !device.opened || (await attempt(() => device.close().then(() => true))) === true;
+    devices.value = devices.value.map((entry) => describe(entry.device));
+    return closed;
+  };
+
+  const sendReport = async (
+    device: HIDDeviceLike,
+    reportId: number,
+    data: BufferSource,
+  ): Promise<boolean> =>
+    (await attempt(() => device.sendReport(reportId, data).then(() => true))) === true;
+
+  const sendFeatureReport = async (
+    device: HIDDeviceLike,
+    reportId: number,
+    data: BufferSource,
+  ): Promise<boolean> =>
+    (await attempt(() => device.sendFeatureReport(reportId, data).then(() => true))) === true;
+
+  const receiveFeatureReport = (
+    device: HIDDeviceLike,
+    reportId: number,
+  ): Promise<DataView | undefined> => attempt(() => device.receiveFeatureReport(reportId));
+
+  const onConnectionChange = (): void => {
+    void 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);
+      });
+      void getDevices();
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  tryOnScopeDispose(() => {
+    for (const device of owned) void close(device);
+  });
+
+  return {
+    supported: computed(() => resolveHost() !== undefined),
+    devices: shallowReadonly(devices),
+    error: readonly(error),
+    requestDevice,
+    getDevices,
+    open,
+    close,
+    sendReport,
+    sendFeatureReport,
+    receiveFeatureReport,
+  };
+}

package/registry/files/use-history.ts

@@ -0,0 +1,231 @@
+import { computed, shallowRef, watch } from "vue";
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Options for {@link useHistory}. */
+export interface UseHistoryOptions<Value> {
+  /**
+   * Maximum number of undo entries retained; recording a change beyond it
+   * drops the oldest entry. The redo stack is bounded by construction, since
+   * redo entries only ever come from undone changes. Must be an integer
+   * greater than zero and is fixed at creation.
+   *
+   * @default 100
+   */
+  readonly capacity?: number;
+
+  /**
+   * Clone applied to every value captured into history and to every value
+   * restored out of it, isolating snapshots from later in-place mutation.
+   *
+   * @default identity — values are stored and restored by reference
+   */
+  readonly clone?: (value: Value) => Value;
+}
+
+/** Reactive undo/redo controls returned by {@link useHistory}. */
+export interface HistoryControls {
+  /** Whether {@link HistoryControls.undo} currently has an entry to restore. */
+  readonly canUndo: ComputedRef<boolean>;
+
+  /** Whether {@link HistoryControls.redo} currently has an entry to restore. */
+  readonly canRedo: ComputedRef<boolean>;
+
+  /** Number of retained undo entries. */
+  readonly undoCount: ComputedRef<number>;
+
+  /** Number of retained redo entries. */
+  readonly redoCount: ComputedRef<number>;
+
+  /**
+   * Restore the newest undo entry and move the current value onto the redo
+   * stack. The restoring write is not recorded.
+   *
+   * @returns Whether an entry was restored.
+   */
+  readonly undo: () => boolean;
+
+  /**
+   * Restore the newest redo entry and move the current value back onto the
+   * undo stack. The restoring write is not recorded.
+   *
+   * @returns Whether an entry was restored.
+   */
+  readonly redo: () => boolean;
+
+  /**
+   * Group every source write inside `run` into at most one undo entry.
+   *
+   * The entry restores the value from just before the batch. It is committed
+   * only when the final value differs (`Object.is`) from the starting value,
+   * and it is committed even when `run` throws, so a partially applied batch
+   * stays undoable as one step. Nested calls collapse into the outermost
+   * batch. The callback's return value is passed through.
+   */
+  readonly batch: <Result>(run: () => Result) => Result;
+
+  /** Drop every undo and redo entry while keeping the current value. */
+  readonly clear: () => void;
+}
+
+interface HistoryEntry<Value> {
+  readonly value: Value;
+}
+
+/**
+ * Record bounded undo/redo history over the writes of a ref.
+ *
+ * Recording is shallow and identity-based, matching Vue's own change
+ * detection: assignments to `source.value` are recorded (observed with
+ * `flush: "sync"`, so every synchronous write counts), writes that are
+ * `Object.is`-equal to the current value are not changes, and in-place
+ * mutations of object values are invisible — pair mutable values with
+ * {@link UseHistoryOptions.clone} and reassign. Undoing and redoing restore
+ * values through `clone` as well, so snapshots never share identity with the
+ * live value unless the default identity clone is kept. When a
+ * user-provided `clone` throws, the failed operation leaves history
+ * unchanged and the error propagates.
+ *
+ * Safe during server rendering: no browser globals are read and no timers
+ * start. Cleanup rule: when the owning reactive scope stops, recording stops
+ * and every retained snapshot is released, so `undo`/`redo` return `false`
+ * afterwards; call inside an active scope, or the watcher lives as long as
+ * the source.
+ *
+ * @example
+ * ```ts
+ * const text = shallowRef("");
+ * const { undo, redo, batch } = useHistory(text);
+ * text.value = "a";
+ * batch(() => {
+ *   text.value = "ab";
+ *   text.value = "abc";
+ * });
+ * undo(); // text.value === "a" (the batch is one step)
+ * redo(); // text.value === "abc"
+ * ```
+ *
+ * @param source Ref whose writes are recorded.
+ * @param options Retention bound and snapshot cloning.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_HISTORY_INVALID_CAPACITY` when
+ * the capacity is not an integer greater than zero.
+ * @throws `Error` tagged `VIZE_COMPOSE_HISTORY_IN_BATCH` when `undo`,
+ * `redo`, or `clear` is called inside {@link HistoryControls.batch}, where
+ * stack movement would corrupt the pending group.
+ * @returns Reactive undo/redo state and controls.
+ */
+export function useHistory<Value>(
+  source: Ref<Value>,
+  options: UseHistoryOptions<Value> = {},
+): HistoryControls {
+  const capacity = options.capacity ?? 100;
+  if (!Number.isInteger(capacity) || capacity < 1) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_HISTORY_INVALID_CAPACITY] capacity must be an integer greater than zero; received ${String(capacity)}`,
+    );
+  }
+  const clone = options.clone ?? ((value: Value) => value);
+  const undoStack: ShallowRef<readonly HistoryEntry<Value>[]> = shallowRef([]);
+  const redoStack: ShallowRef<readonly HistoryEntry<Value>[]> = shallowRef([]);
+  let restoring = false;
+  let batchDepth = 0;
+  let activeBatch: { readonly raw: Value; readonly entry: HistoryEntry<Value> } | undefined;
+
+  const pushUndo = (entry: HistoryEntry<Value>): void => {
+    const next = [...undoStack.value, entry];
+    undoStack.value = next.length > capacity ? next.slice(next.length - capacity) : next;
+    redoStack.value = [];
+  };
+
+  const writeSilently = (value: Value): void => {
+    restoring = true;
+    try {
+      source.value = value;
+    } finally {
+      restoring = false;
+    }
+  };
+
+  const requireOutsideBatch = (operation: string): void => {
+    if (batchDepth > 0) {
+      throw new Error(
+        `[VIZE_COMPOSE_HISTORY_IN_BATCH] ${operation}() is not available inside batch()`,
+      );
+    }
+  };
+
+  const undo = (): boolean => {
+    requireOutsideBatch("undo");
+    const entry = undoStack.value.at(-1);
+    if (entry === undefined) return false;
+    const restored = clone(entry.value);
+    const recorded: HistoryEntry<Value> = { value: clone(source.value) };
+    undoStack.value = undoStack.value.slice(0, -1);
+    redoStack.value = [...redoStack.value, recorded];
+    writeSilently(restored);
+    return true;
+  };
+
+  const redo = (): boolean => {
+    requireOutsideBatch("redo");
+    const entry = redoStack.value.at(-1);
+    if (entry === undefined) return false;
+    const restored = clone(entry.value);
+    const recorded: HistoryEntry<Value> = { value: clone(source.value) };
+    redoStack.value = redoStack.value.slice(0, -1);
+    undoStack.value = [...undoStack.value, recorded];
+    writeSilently(restored);
+    return true;
+  };
+
+  const batch = <Result>(run: () => Result): Result => {
+    if (batchDepth === 0) {
+      activeBatch = { raw: source.value, entry: { value: clone(source.value) } };
+    }
+    batchDepth += 1;
+    try {
+      return run();
+    } finally {
+      batchDepth -= 1;
+      if (batchDepth === 0 && activeBatch !== undefined) {
+        const finished = activeBatch;
+        activeBatch = undefined;
+        if (!Object.is(finished.raw, source.value)) pushUndo(finished.entry);
+      }
+    }
+  };
+
+  const clear = (): void => {
+    requireOutsideBatch("clear");
+    undoStack.value = [];
+    redoStack.value = [];
+  };
+
+  const handle = watch(
+    source,
+    (_next, replaced) => {
+      if (restoring || batchDepth > 0) return;
+      pushUndo({ value: clone(replaced) });
+    },
+    { flush: "sync" },
+  );
+
+  tryOnScopeDispose(() => {
+    handle.stop();
+    undoStack.value = [];
+    redoStack.value = [];
+  });
+
+  return {
+    canUndo: computed(() => undoStack.value.length > 0),
+    canRedo: computed(() => redoStack.value.length > 0),
+    undoCount: computed(() => undoStack.value.length),
+    redoCount: computed(() => redoStack.value.length),
+    undo,
+    redo,
+    batch,
+    clear,
+  };
+}

package/registry/files/use-id-generator.ts

@@ -0,0 +1,61 @@
+import { hasInjectionContext, useId } from "vue";
+
+/** Options for {@link useIdGenerator}. */
+export interface UseIdGeneratorOptions {
+  /**
+   * Namespace placed in front of every id.
+   *
+   * @default "vize"
+   */
+  readonly prefix?: string;
+
+  /**
+   * Stable seed identifying this generator. Defaults to Vue's `useId()`
+   * inside a component (identical on server and hydrating client), or to
+   * `"root"` outside one.
+   *
+   * @default useId() or "root"
+   */
+  readonly seed?: string;
+}
+
+/** Id factory returned by {@link useIdGenerator}. */
+export type IdGenerator = (hint?: string) => string;
+
+function sanitize(part: string): string {
+  return part.replaceAll(/[^\w-]/g, "-");
+}
+
+/**
+ * Create an SSR-stable id factory for one component.
+ *
+ * Each call to the returned function yields
+ * `<prefix>-<seed>-<hint>-<n>` with a per-generator counter, so as long as
+ * ids are generated in the same order on the server and the client (for
+ * example during `setup`), the markup hydrates without mismatches. The seed
+ * comes from Vue's `useId()` inside components, which is itself stable across
+ * SSR and hydration; outside components pass an explicit `seed`. Characters
+ * outside `[A-Za-z0-9_-]` are replaced so ids are valid in selectors.
+ *
+ * @example
+ * ```ts
+ * const nextId = useIdGenerator({ prefix: "field" });
+ * const inputId = nextId("input"); // "field-v-0-input-0"
+ * ```
+ *
+ * @param options Prefix and seed.
+ * @default options {}
+ * @returns The id factory.
+ */
+export function useIdGenerator(options: UseIdGeneratorOptions = {}): IdGenerator {
+  // `hasInjectionContext()` (unlike `getCurrentInstance()`) also detects
+  // Vapor components, whose `useId()` is hydration-stable as well.
+  const seed = options.seed ?? (hasInjectionContext() ? useId() : "root");
+  const base = `${sanitize(options.prefix ?? "vize")}-${sanitize(seed)}`;
+  let counter = 0;
+  return (hint = "id") => {
+    const id = `${base}-${sanitize(hint)}-${counter}`;
+    counter += 1;
+    return id;
+  };
+}