@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-bluetooth.mjs

@@ -0,0 +1,183 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowReadonly, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-bluetooth.ts
+function browserBluetoothHost() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator } = window;
+	const bluetooth = "bluetooth" in navigator ? navigator.bluetooth : void 0;
+	return isBluetoothHost(bluetooth) ? bluetooth : void 0;
+}
+function isBluetoothHost(value) {
+	return typeof value === "object" && value !== null && "requestDevice" in value;
+}
+function availabilityOf(event) {
+	return "value" in event && typeof event.value === "boolean" ? event.value : void 0;
+}
+/**
+* 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.
+*/
+function useBluetooth(options = {}) {
+	const available = ref(false);
+	const device = shallowRef(void 0);
+	const connected = ref(false);
+	const error = shallowRef(void 0);
+	const notifications = /* @__PURE__ */ new Set();
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => {
+		if (!hydrated.value) return void 0;
+		return options.host === void 0 ? browserBluetoothHost() : toValue(options.host) ?? void 0;
+	};
+	const onDisconnected = () => {
+		connected.value = false;
+		for (const stop of notifications) stop();
+	};
+	const disconnect = () => {
+		for (const stop of notifications) stop();
+		notifications.clear();
+		device.value?.gatt?.disconnect();
+		connected.value = false;
+	};
+	const requestDevice = async (requestOptions = options.requestOptions ?? { acceptAllDevices: true }) => {
+		const host = resolveHost();
+		if (!host) return void 0;
+		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 = void 0;
+			return chosen;
+		} catch (cause) {
+			error.value = cause;
+			return;
+		}
+	};
+	const connect = async () => {
+		const server = device.value?.gatt;
+		if (!server) return false;
+		try {
+			await server.connect();
+			connected.value = server.connected;
+			error.value = void 0;
+		} catch (cause) {
+			error.value = cause;
+			connected.value = false;
+		}
+		return connected.value;
+	};
+	const characteristicOf = async (service, characteristic) => {
+		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 (action) => {
+		try {
+			const value = await action();
+			error.value = void 0;
+			return value;
+		} catch (cause) {
+			error.value = cause;
+			return;
+		}
+	};
+	const read = (service, characteristic) => attempt(async () => (await characteristicOf(service, characteristic)).readValue());
+	const write = async (service, characteristic, value, writeOptions = {}) => 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, characteristic, listener) => attempt(async () => {
+		const target = await characteristicOf(service, characteristic);
+		const onChange = () => {
+			if (target.value) listener(target.value);
+		};
+		target.addEventListener("characteristicvaluechanged", onChange);
+		try {
+			await target.startNotifications();
+		} catch (cause) {
+			target.removeEventListener("characteristicvaluechanged", onChange);
+			throw cause;
+		}
+		const stop = 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) => {
+			const value = availabilityOf(event);
+			if (value !== void 0) available.value = value;
+		};
+		host.addEventListener("availabilitychanged", onAvailability);
+		onCleanup(() => {
+			active = false;
+			host.removeEventListener("availabilitychanged", onAvailability);
+		});
+		host.getAvailability().then((value) => {
+			if (active) available.value = value;
+		}, (cause) => {
+			if (active) error.value = cause;
+		});
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	tryOnScopeDispose(() => {
+		disconnect();
+		device.value?.removeEventListener("gattserverdisconnected", onDisconnected);
+	});
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		available: readonly(available),
+		device: shallowReadonly(device),
+		connected: readonly(connected),
+		error: readonly(error),
+		requestDevice,
+		connect,
+		disconnect,
+		read,
+		write,
+		notify
+	};
+}
+//#endregion
+export { useBluetooth };

package/dist/use-broadcast-channel.d.mts

@@ -0,0 +1,115 @@
+import { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-broadcast-channel.d.ts
+/** Minimal structural view of a `BroadcastChannel` instance. */
+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`. */
+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.
+ */
+interface BroadcastChannelHost {
+  /** Channel constructor. */
+  readonly BroadcastChannel: BroadcastChannelConstructor;
+}
+/** Stable failure codes reported by {@link useBroadcastChannel}. */
+type BroadcastChannelErrorCode = "open-failed" | "post-failed" | "message-error" | "invalid-message";
+/** Failure observed while using a broadcast channel. */
+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}. */
+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}. */
+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;
+}
+/**
+ * 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.
+ */
+declare function useBroadcastChannel<Message>(name: MaybeRefOrGetter<string>, options?: UseBroadcastChannelOptions<Message>): BroadcastChannelControls<Message>;
+//#endregion
+export { BroadcastChannelConstructor, BroadcastChannelControls, BroadcastChannelErrorCode, BroadcastChannelFailure, BroadcastChannelHost, BroadcastChannelLike, UseBroadcastChannelOptions, useBroadcastChannel };

package/dist/use-broadcast-channel.mjs

@@ -0,0 +1,121 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-broadcast-channel.ts
+function browserBroadcastChannelHost() {
+	return typeof window !== "undefined" && typeof window.BroadcastChannel === "function" ? window : void 0;
+}
+/**
+* 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.
+*/
+function useBroadcastChannel(name, options = {}) {
+	const data = shallowRef(void 0);
+	const error = shallowRef(void 0);
+	const supported = ref(false);
+	const closed = ref(true);
+	let channel;
+	let stopped = false;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const fail = (code, cause) => {
+		const failure = {
+			code,
+			name: toValue(name),
+			cause
+		};
+		error.value = failure;
+		options.onError?.(failure);
+	};
+	const resolveHost = () => (options.host === void 0 ? browserBroadcastChannelHost() : toValue(options.host))?.BroadcastChannel;
+	const onMessage = (event) => {
+		const payload = event instanceof MessageEvent ? event.data : void 0;
+		if (options.validate !== void 0 && !options.validate(payload)) {
+			fail("invalid-message", payload);
+			return;
+		}
+		const message = payload;
+		error.value = void 0;
+		data.value = message;
+		options.onMessage?.(message);
+	};
+	const onMessageError = (event) => fail("message-error", event);
+	const stopWatch = watch([() => toValue(name), () => hydrated.value ? resolveHost() : void 0], ([channelName, Host], _previous, onCleanup) => {
+		supported.value = Host !== void 0;
+		if (Host === void 0 || stopped) return;
+		let opened;
+		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 = void 0;
+			closed.value = true;
+		});
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const post = (message) => {
+		if (channel === void 0) return false;
+		try {
+			channel.postMessage(message);
+		} catch (cause) {
+			fail("post-failed", cause);
+			return false;
+		}
+		error.value = void 0;
+		return true;
+	};
+	const close = () => {
+		stopped = true;
+		stopWatch();
+	};
+	tryOnScopeDispose(close);
+	return {
+		data,
+		supported: readonly(supported),
+		closed: readonly(closed),
+		error,
+		post,
+		close
+	};
+}
+//#endregion
+export { useBroadcastChannel };