@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-bluetooth.ts

@@ -0,0 +1,409 @@
+import {
+  computed,
+  hasInjectionContext,
+  readonly,
+  ref,
+  shallowReadonly,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** GATT service or characteristic UUID: a full UUID string, an alias name, or a 16/32-bit number. */
+export type BluetoothUUIDLike = string | number;
+
+/** Scan filter for `requestDevice`. */
+export 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. */
+export 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}. */
+export 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`. */
+export interface BluetoothServiceLike {
+  /** Look up a characteristic. */
+  getCharacteristic(characteristic: BluetoothUUIDLike): Promise<BluetoothCharacteristicLike>;
+}
+
+/** Minimal `BluetoothRemoteGATTServer`. */
+export 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}. */
+export 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}. */
+export 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}. */
+export 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}. */
+export type BluetoothNotificationStop = () => Promise<void>;
+
+/** Reactive state and actions returned by {@link useBluetooth}. */
+export 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>;
+}
+
+function browserBluetoothHost(): BluetoothHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { navigator } = window;
+  // Web Bluetooth is not part of the DOM lib; read it through a structural guard.
+  const bluetooth: unknown = "bluetooth" in navigator ? navigator.bluetooth : undefined;
+  return isBluetoothHost(bluetooth) ? bluetooth : undefined;
+}
+
+function isBluetoothHost(value: unknown): value is BluetoothHost {
+  return typeof value === "object" && value !== null && "requestDevice" in value;
+}
+
+function availabilityOf(event: Event): boolean | undefined {
+  return "value" in event && typeof event.value === "boolean" ? event.value : 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.
+ */
+export function useBluetooth(options: UseBluetoothOptions = {}): BluetoothControls {
+  const available = ref(false);
+  const device = shallowRef<BluetoothDeviceLike | undefined>(undefined);
+  const connected = ref(false);
+  const error = shallowRef<unknown>(undefined);
+  const notifications = new Set<BluetoothNotificationStop>();
+
+  // 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 = (): BluetoothHost | undefined => {
+    if (!hydrated.value) return undefined;
+    return options.host === undefined
+      ? browserBluetoothHost()
+      : (toValue(options.host) ?? undefined);
+  };
+
+  const onDisconnected = (): void => {
+    connected.value = false;
+    for (const stop of notifications) void stop();
+  };
+
+  const disconnect = (): void => {
+    for (const stop of notifications) void stop();
+    notifications.clear();
+    device.value?.gatt?.disconnect();
+    connected.value = false;
+  };
+
+  const requestDevice = async (
+    requestOptions: BluetoothRequestOptions = options.requestOptions ?? { acceptAllDevices: true },
+  ): Promise<BluetoothDeviceLike | undefined> => {
+    const host = resolveHost();
+    if (!host) return undefined;
+    try {
+      const chosen = await host.requestDevice(requestOptions);
+      disconnect();
+      device.value?.removeEventListener("gattserverdisconnected", onDisconnected);
+      chosen.addEventListener("gattserverdisconnected", onDisconnected);
+      device.value = chosen;
+      connected.value = chosen.gatt?.connected ?? false;
+      error.value = undefined;
+      return chosen;
+    } catch (cause) {
+      error.value = cause;
+      return undefined;
+    }
+  };
+
+  const connect = async (): Promise<boolean> => {
+    const server = device.value?.gatt;
+    if (!server) return false;
+    try {
+      await server.connect();
+      connected.value = server.connected;
+      error.value = undefined;
+    } catch (cause) {
+      error.value = cause;
+      connected.value = false;
+    }
+    return connected.value;
+  };
+
+  const characteristicOf = async (
+    service: BluetoothUUIDLike,
+    characteristic: BluetoothUUIDLike,
+  ): Promise<BluetoothCharacteristicLike> => {
+    const server = device.value?.gatt;
+    if (!server?.connected) {
+      throw new Error(
+        "[VIZE_COMPOSE_BLUETOOTH_NOT_CONNECTED] connect() to a device before accessing characteristics",
+      );
+    }
+    return (await server.getPrimaryService(service)).getCharacteristic(characteristic);
+  };
+
+  const attempt = async <Value>(action: () => Promise<Value>): Promise<Value | undefined> => {
+    try {
+      const value = await action();
+      error.value = undefined;
+      return value;
+    } catch (cause) {
+      error.value = cause;
+      return undefined;
+    }
+  };
+
+  const read = (
+    service: BluetoothUUIDLike,
+    characteristic: BluetoothUUIDLike,
+  ): Promise<DataView | undefined> =>
+    attempt(async () => (await characteristicOf(service, characteristic)).readValue());
+
+  const write = async (
+    service: BluetoothUUIDLike,
+    characteristic: BluetoothUUIDLike,
+    value: BufferSource,
+    writeOptions: { readonly withoutResponse?: boolean } = {},
+  ): Promise<boolean> =>
+    (await attempt(async () => {
+      const target = await characteristicOf(service, characteristic);
+      await ((writeOptions.withoutResponse ?? false)
+        ? target.writeValueWithoutResponse(value)
+        : target.writeValueWithResponse(value));
+      return true;
+    })) === true;
+
+  const notify = (
+    service: BluetoothUUIDLike,
+    characteristic: BluetoothUUIDLike,
+    listener: (value: DataView) => void,
+  ): Promise<BluetoothNotificationStop | undefined> =>
+    attempt(async () => {
+      const target = await characteristicOf(service, characteristic);
+      const onChange = (): void => {
+        if (target.value) listener(target.value);
+      };
+      target.addEventListener("characteristicvaluechanged", onChange);
+      try {
+        await target.startNotifications();
+      } catch (cause) {
+        target.removeEventListener("characteristicvaluechanged", onChange);
+        throw cause;
+      }
+      const stop: BluetoothNotificationStop = async () => {
+        if (!notifications.delete(stop)) return;
+        target.removeEventListener("characteristicvaluechanged", onChange);
+        try {
+          await target.stopNotifications();
+        } catch (cause) {
+          error.value = cause;
+        }
+      };
+      notifications.add(stop);
+      return stop;
+    });
+
+  watch(
+    resolveHost,
+    (host, _previous, onCleanup) => {
+      available.value = false;
+      if (!host) return;
+      let active = true;
+      const onAvailability = (event: Event): void => {
+        const value = availabilityOf(event);
+        if (value !== undefined) available.value = value;
+      };
+      host.addEventListener("availabilitychanged", onAvailability);
+      onCleanup(() => {
+        active = false;
+        host.removeEventListener("availabilitychanged", onAvailability);
+      });
+      host.getAvailability().then(
+        (value) => {
+          if (active) available.value = value;
+        },
+        (cause: unknown) => {
+          if (active) error.value = cause;
+        },
+      );
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  tryOnScopeDispose(() => {
+    disconnect();
+    device.value?.removeEventListener("gattserverdisconnected", onDisconnected);
+  });
+
+  return {
+    supported: computed(() => resolveHost() !== undefined),
+    available: readonly(available),
+    device: shallowReadonly(device),
+    connected: readonly(connected),
+    error: readonly(error),
+    requestDevice,
+    connect,
+    disconnect,
+    read,
+    write,
+    notify,
+  };
+}

package/registry/files/use-broadcast-channel.ts

@@ -0,0 +1,250 @@
+import {
+  hasInjectionContext,
+  readonly,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Minimal structural view of a `BroadcastChannel` instance. */
+export interface BroadcastChannelLike extends EventTarget {
+  /** Post a structured-cloneable message to every other channel with the same name. */
+  readonly postMessage: (message: unknown) => void;
+
+  /** Close the channel; no further messages are delivered. */
+  readonly close: () => void;
+}
+
+/** Constructor creating channels, compatible with `window.BroadcastChannel`. */
+export type BroadcastChannelConstructor = new (name: string) => BroadcastChannelLike;
+
+/**
+ * Capability host exposing a channel constructor; `window` satisfies it.
+ *
+ * The constructor is wrapped in an object because a bare class would be
+ * mistaken for a getter by `MaybeRefOrGetter` resolution.
+ */
+export interface BroadcastChannelHost {
+  /** Channel constructor. */
+  readonly BroadcastChannel: BroadcastChannelConstructor;
+}
+
+/** Stable failure codes reported by {@link useBroadcastChannel}. */
+export type BroadcastChannelErrorCode =
+  | "open-failed"
+  | "post-failed"
+  | "message-error"
+  | "invalid-message";
+
+/** Failure observed while using a broadcast channel. */
+export interface BroadcastChannelFailure {
+  /** Which step failed. */
+  readonly code: BroadcastChannelErrorCode;
+
+  /** Channel name involved in the failure. */
+  readonly name: string;
+
+  /** Exact thrown value, event, or rejected payload. */
+  readonly cause: unknown;
+}
+
+/** Options for {@link useBroadcastChannel}. */
+export interface UseBroadcastChannelOptions<Message> {
+  /**
+   * Host exposing the channel constructor. `null`/`undefined` keeps the
+   * composable closed, which is also what happens during server rendering.
+   *
+   * @default window when it exposes `BroadcastChannel`
+   */
+  readonly host?: MaybeRefOrGetter<BroadcastChannelHost | null | undefined>;
+
+  /**
+   * Validate incoming payloads. Rejected payloads leave `data` untouched and
+   * report an `"invalid-message"` failure.
+   *
+   * @default every payload is accepted
+   */
+  readonly validate?: (data: unknown) => data is Message;
+
+  /**
+   * Observe every accepted message.
+   *
+   * @default undefined
+   */
+  readonly onMessage?: (message: Message) => void;
+
+  /**
+   * Observe failures. Failures never throw out of the composable.
+   *
+   * @default undefined
+   */
+  readonly onError?: (failure: BroadcastChannelFailure) => void;
+}
+
+/** Reactive state and controls returned by {@link useBroadcastChannel}. */
+export interface BroadcastChannelControls<Message> {
+  /** Most recent accepted message received from another context. */
+  readonly data: Readonly<ShallowRef<Message | undefined>>;
+
+  /** Whether a channel constructor is available. */
+  readonly supported: Readonly<Ref<boolean>>;
+
+  /** Whether no channel is currently open. */
+  readonly closed: Readonly<Ref<boolean>>;
+
+  /** Most recent failure, cleared by the next successful post or message. */
+  readonly error: Readonly<ShallowRef<BroadcastChannelFailure | undefined>>;
+
+  /**
+   * Post a typed message.
+   *
+   * @param message Structured-cloneable payload.
+   * @returns Whether the message was handed to an open channel.
+   */
+  readonly post: (message: Message) => boolean;
+
+  /** Close the channel and stop following the reactive name. Idempotent. */
+  readonly close: () => void;
+}
+
+function browserBroadcastChannelHost(): BroadcastChannelHost | undefined {
+  return typeof window !== "undefined" && typeof window.BroadcastChannel === "function"
+    ? window
+    : undefined;
+}
+
+/**
+ * Exchange typed messages with other tabs, windows, and workers of the same
+ * origin through the Broadcast Channel API.
+ *
+ * The channel follows the reactive `name`: changing it closes the old channel
+ * and opens a new one. The channel closes when the owning reactive scope
+ * stops or when `close()` is called; outside a scope the caller owns
+ * `close()`. Incoming payloads pass the `validate` type guard before they
+ * reach `data`, so foreign messages cannot widen the declared type.
+ *
+ * Server rendering: without a browser `window` no channel is opened (Node's
+ * global `BroadcastChannel` is ignored), `supported` is `false`, and `post`
+ * returns `false`.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @example
+ * ```ts
+ * type Sync = { readonly type: "logout" };
+ * const { data, post } = useBroadcastChannel<Sync>("auth");
+ * post({ type: "logout" });
+ * ```
+ *
+ * @typeParam Message Payload type exchanged over the channel.
+ * @param name Reactive channel name.
+ * @param options Host, validation, and observation hooks.
+ * @default options {}
+ * @returns Reactive channel state and controls.
+ */
+export function useBroadcastChannel<Message>(
+  name: MaybeRefOrGetter<string>,
+  options: UseBroadcastChannelOptions<Message> = {},
+): BroadcastChannelControls<Message> {
+  const data = shallowRef<Message | undefined>(undefined);
+  const error = shallowRef<BroadcastChannelFailure | undefined>(undefined);
+  const supported = ref(false);
+  const closed = ref(true);
+  let channel: BroadcastChannelLike | undefined;
+  let stopped = false;
+  // Inside a component the host is attached by a post-flush job (after the
+  // component mounted), so a hydrating client first renders the same server
+  // fallback. Outside components it is attached synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+
+  const fail = (code: BroadcastChannelErrorCode, cause: unknown): void => {
+    const failure: BroadcastChannelFailure = { code, name: toValue(name), cause };
+    error.value = failure;
+    options.onError?.(failure);
+  };
+
+  const resolveHost = (): BroadcastChannelConstructor | undefined =>
+    (options.host === undefined ? browserBroadcastChannelHost() : toValue(options.host))
+      ?.BroadcastChannel;
+
+  const onMessage = (event: Event): void => {
+    const payload: unknown = event instanceof MessageEvent ? event.data : undefined;
+    if (options.validate !== undefined && !options.validate(payload)) {
+      fail("invalid-message", payload);
+      return;
+    }
+    // Without a validator the declared message type is trusted, as for
+    // `postMessage` peers of the same application.
+    const message = payload as Message;
+    error.value = undefined;
+    data.value = message;
+    options.onMessage?.(message);
+  };
+  const onMessageError = (event: Event): void => fail("message-error", event);
+
+  const stopWatch = watch(
+    [() => toValue(name), () => (hydrated.value ? resolveHost() : undefined)],
+    ([channelName, Host], _previous, onCleanup) => {
+      supported.value = Host !== undefined;
+      if (Host === undefined || stopped) return;
+      let opened: BroadcastChannelLike;
+      try {
+        opened = new Host(channelName);
+      } catch (cause) {
+        fail("open-failed", cause);
+        return;
+      }
+      channel = opened;
+      closed.value = false;
+      opened.addEventListener("message", onMessage);
+      opened.addEventListener("messageerror", onMessageError);
+      onCleanup(() => {
+        opened.removeEventListener("message", onMessage);
+        opened.removeEventListener("messageerror", onMessageError);
+        opened.close();
+        if (channel === opened) channel = undefined;
+        closed.value = true;
+      });
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  const post = (message: Message): boolean => {
+    if (channel === undefined) return false;
+    try {
+      channel.postMessage(message);
+    } catch (cause) {
+      fail("post-failed", cause);
+      return false;
+    }
+    error.value = undefined;
+    return true;
+  };
+
+  const close = (): void => {
+    stopped = true;
+    stopWatch();
+  };
+
+  tryOnScopeDispose(close);
+
+  return {
+    data,
+    supported: readonly(supported),
+    closed: readonly(closed),
+    error,
+    post,
+    close,
+  };
+}