@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-compression-stream.mjs

@@ -0,0 +1,166 @@
+import { computed, hasInjectionContext, readonly, ref, shallowRef, unref, watchPostEffect } from "vue";
+//#region src/use-compression-stream.ts
+const formats = [
+	"gzip",
+	"deflate",
+	"deflate-raw"
+];
+function isConstructor(candidate) {
+	return typeof candidate === "function";
+}
+function browserConstructor(name) {
+	if (typeof window === "undefined") return void 0;
+	const candidate = Reflect.get(window, name);
+	return isConstructor(candidate) ? candidate : void 0;
+}
+function toReadable(data) {
+	if (data instanceof ReadableStream) return data;
+	if (data instanceof Blob) return data.stream();
+	const bytes = typeof data === "string" ? new TextEncoder().encode(data) : ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice() : new Uint8Array(data);
+	return new ReadableStream({ start(controller) {
+		controller.enqueue(bytes);
+		controller.close();
+	} });
+}
+async function transform(data, format, Stream, name) {
+	if (!formats.includes(format)) throw new TypeError(`[VIZE_COMPOSE_COMPRESSION_INVALID_FORMAT] Unsupported format "${String(format)}".`);
+	if (!Stream) throw new TypeError(`[VIZE_COMPOSE_COMPRESSION_UNSUPPORTED] ${name} is not available.`);
+	const reader = toReadable(data).pipeThrough(new Stream(format)).getReader();
+	const chunks = [];
+	let length = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		chunks.push(value);
+		length += value.byteLength;
+	}
+	const output = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		output.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return output;
+}
+/**
+* Compress data with the Compression Streams API.
+*
+* Strings are UTF-8 encoded first. Rejects with a tagged `TypeError` for an
+* unknown format or when no `CompressionStream` is available (always on the
+* server unless one is injected).
+*
+* @example
+* ```ts
+* const gzipped = await compress(JSON.stringify(state), "gzip");
+* ```
+*
+* @param data Input data.
+* @param format Compression format.
+* @param options Constructor override.
+* @default format "gzip"
+* @default options {}
+* @returns Compressed bytes.
+*/
+function compress(data, format = "gzip", options = {}) {
+	return transform(data, format, options.CompressionStream === void 0 ? browserConstructor("CompressionStream") : options.CompressionStream, "CompressionStream");
+}
+/**
+* Decompress data with the Compression Streams API.
+*
+* Rejects with a tagged `TypeError` for an unknown format or when no
+* `DecompressionStream` is available, and with the stream's error for
+* corrupt input.
+*
+* @example
+* ```ts
+* const bytes = await decompress(await response.blob(), "gzip");
+* ```
+*
+* @param data Compressed data.
+* @param format Compression format.
+* @param options Constructor override.
+* @default format "gzip"
+* @default options {}
+* @returns Decompressed bytes.
+*/
+function decompress(data, format = "gzip", options = {}) {
+	return transform(data, format, options.DecompressionStream === void 0 ? browserConstructor("DecompressionStream") : options.DecompressionStream, "DecompressionStream");
+}
+/**
+* Decompress data and decode the result as UTF-8 text.
+*
+* Rejects exactly like {@link decompress}.
+*
+* @example
+* ```ts
+* const json = JSON.parse(await decompressText(bytes, "deflate"));
+* ```
+*
+* @param data Compressed data.
+* @param format Compression format.
+* @param options Constructor override.
+* @default format "gzip"
+* @default options {}
+* @returns Decompressed text.
+*/
+async function decompressText(data, format = "gzip", options = {}) {
+	return new TextDecoder().decode(await decompress(data, format, options));
+}
+/**
+* Reactive wrapper around {@link compress}, {@link decompress} and
+* {@link decompressText}.
+*
+* Tracks whether an action is in flight and records the last failure in
+* `error`; actions still reject so callers can handle failures inline.
+* Nothing needs cleanup.
+*
+* Server rendering: `supported` is false and actions reject with the tagged
+* unsupported error unless constructors are injected.
+* Inside a component `supported` turns true only after mounting, so
+* hydration renders this server state first.
+*
+* @example
+* ```ts
+* const { compress, decompressText, pending } = useCompressionStream({ format: "deflate" });
+* const packed = await compress(draft.value);
+* ```
+*
+* @param options Constructor overrides and default format.
+* @default options {}
+* @returns Compression state and bound actions.
+*/
+function useCompressionStream(options = {}) {
+	const defaultFormat = options.format ?? "gzip";
+	const inFlight = ref(0);
+	const error = shallowRef(void 0);
+	const resolve = (source, name) => source === void 0 ? browserConstructor(name) : unref(source) ?? void 0;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveCompression = () => resolve(options.CompressionStream, "CompressionStream");
+	const resolveDecompression = () => resolve(options.DecompressionStream, "DecompressionStream");
+	const track = async (action) => {
+		inFlight.value += 1;
+		try {
+			const value = await action();
+			error.value = void 0;
+			return value;
+		} catch (cause) {
+			error.value = cause;
+			throw cause;
+		} finally {
+			inFlight.value -= 1;
+		}
+	};
+	return {
+		supported: computed(() => hydrated.value && resolveCompression() !== void 0 && resolveDecompression() !== void 0),
+		pending: computed(() => inFlight.value > 0),
+		error: readonly(error),
+		compress: (data, format = defaultFormat) => track(() => compress(data, format, { CompressionStream: resolveCompression() ?? null })),
+		decompress: (data, format = defaultFormat) => track(() => decompress(data, format, { DecompressionStream: resolveDecompression() ?? null })),
+		decompressText: (data, format = defaultFormat) => track(() => decompressText(data, format, { DecompressionStream: resolveDecompression() ?? null }))
+	};
+}
+//#endregion
+export { compress, decompress, decompressText, useCompressionStream };

package/dist/use-confirm-dialog.d.mts

@@ -0,0 +1,70 @@
+import { EventHookListener, EventHookSubscription } from "./create-event-hook.mjs";
+import { ShallowRef } from "vue";
+
+//#region src/use-confirm-dialog.d.ts
+/** States of the {@link useConfirmDialog} machine. */
+type ConfirmDialogState = "idle" | "revealed";
+/** Outcome a {@link ConfirmDialog.reveal} promise resolves with. */
+type ConfirmDialogResult<ConfirmData, CancelData> = {
+  readonly isCanceled: false;
+  readonly data: ConfirmData;
+} | {
+  readonly isCanceled: true;
+  readonly data: CancelData;
+};
+/** Arguments of a payload: none for `void`, one otherwise. */
+type ConfirmDialogPayload<Data> = [Data] extends [void] ? [] : [data: Data];
+/** Dialog state machine returned by {@link useConfirmDialog}. */
+interface ConfirmDialog<RevealData, ConfirmData, CancelData> {
+  /** `"revealed"` between `reveal()` and `confirm()`/`cancel()`. */
+  readonly state: Readonly<ShallowRef<ConfirmDialogState>>;
+  /** Shorthand for `state === "revealed"`. */
+  readonly isRevealed: Readonly<ShallowRef<boolean>>;
+  /**
+   * Open the dialog. While already revealed, returns the pending promise
+   * without re-firing `onReveal`.
+   *
+   * @returns Resolves when the dialog is confirmed or cancelled.
+   */
+  readonly reveal: (...payload: ConfirmDialogPayload<RevealData>) => Promise<ConfirmDialogResult<ConfirmData, CancelData>>;
+  /**
+   * Confirm the revealed dialog.
+   *
+   * @returns Whether the dialog was revealed.
+   */
+  readonly confirm: (...payload: ConfirmDialogPayload<ConfirmData>) => boolean;
+  /**
+   * Cancel the revealed dialog.
+   *
+   * @returns Whether the dialog was revealed.
+   */
+  readonly cancel: (...payload: ConfirmDialogPayload<CancelData>) => boolean;
+  /** Listen for reveals. */
+  readonly onReveal: (listener: EventHookListener<ConfirmDialogPayload<RevealData>>) => EventHookSubscription;
+  /** Listen for confirmations. */
+  readonly onConfirm: (listener: EventHookListener<ConfirmDialogPayload<ConfirmData>>) => EventHookSubscription;
+  /** Listen for cancellations. */
+  readonly onCancel: (listener: EventHookListener<ConfirmDialogPayload<CancelData>>) => EventHookSubscription;
+}
+/**
+ * Promise-based confirm dialog state machine (`idle` → `revealed` →
+ * `idle`), independent of any dialog markup.
+ *
+ * `reveal()` resolves with a discriminated result, so `if (!result.isCanceled)`
+ * narrows `data` to the confirm payload. Payload types are declared as type
+ * parameters; `void` payloads take no argument. Pair it with a native
+ * `<dialog>` or any headless dialog. Synchronous state: SSR-safe; listeners
+ * registered inside a scope are removed with it.
+ *
+ * @example
+ * ```ts
+ * const dialog = useConfirmDialog<{ name: string }, "keep" | "delete">();
+ * const result = await dialog.reveal({ name: file.name });
+ * if (!result.isCanceled && result.data === "delete") remove(file);
+ * ```
+ *
+ * @returns The dialog machine.
+ */
+declare function useConfirmDialog<RevealData = void, ConfirmData = void, CancelData = void>(): ConfirmDialog<RevealData, ConfirmData, CancelData>;
+//#endregion
+export { ConfirmDialog, ConfirmDialogPayload, ConfirmDialogResult, ConfirmDialogState, useConfirmDialog };

package/dist/use-confirm-dialog.mjs

@@ -0,0 +1,57 @@
+import { createEventHook } from "./create-event-hook.mjs";
+import { shallowRef } from "vue";
+//#region src/use-confirm-dialog.ts
+function useConfirmDialog() {
+	const state = shallowRef("idle");
+	const isRevealed = shallowRef(false);
+	const revealHook = createEventHook();
+	const confirmHook = createEventHook();
+	const cancelHook = createEventHook();
+	let pending;
+	let settle;
+	const close = (result) => {
+		const resolve = settle;
+		if (resolve === void 0) return false;
+		settle = void 0;
+		pending = void 0;
+		state.value = "idle";
+		isRevealed.value = false;
+		resolve(result);
+		return true;
+	};
+	return {
+		state,
+		isRevealed,
+		reveal: (...payload) => {
+			if (pending !== void 0) return pending;
+			pending = new Promise((resolve) => {
+				settle = resolve;
+			});
+			state.value = "revealed";
+			isRevealed.value = true;
+			revealHook.trigger(...payload);
+			return pending;
+		},
+		confirm: (...payload) => {
+			if (settle === void 0) return false;
+			confirmHook.trigger(...payload);
+			return close({
+				isCanceled: false,
+				data: payload[0]
+			});
+		},
+		cancel: (...payload) => {
+			if (settle === void 0) return false;
+			cancelHook.trigger(...payload);
+			return close({
+				isCanceled: true,
+				data: payload[0]
+			});
+		},
+		onReveal: revealHook.on,
+		onConfirm: confirmHook.on,
+		onCancel: cancelHook.on
+	};
+}
+//#endregion
+export { useConfirmDialog };

package/dist/use-contact-picker.d.mts

@@ -0,0 +1,117 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-contact-picker.d.ts
+/** Contact property that can be requested from the picker. */
+type ContactProperty = "address" | "email" | "icon" | "name" | "tel";
+/** Postal address returned for the `address` property. */
+interface ContactAddressLike {
+  /** Street address lines. */
+  readonly addressLine?: readonly string[];
+  /** City. */
+  readonly city?: string;
+  /** Region or state. */
+  readonly region?: string;
+  /** Postal code. */
+  readonly postalCode?: string;
+  /** ISO 3166 country code. */
+  readonly country?: string;
+}
+/** Every value the picker can return, keyed by property. */
+interface ContactInfo {
+  /** Postal addresses. */
+  readonly address: readonly ContactAddressLike[];
+  /** Email addresses. */
+  readonly email: readonly string[];
+  /** Avatar images. */
+  readonly icon: readonly Blob[];
+  /** Names. */
+  readonly name: readonly string[];
+  /** Phone numbers. */
+  readonly tel: readonly string[];
+}
+/** Contact typed with exactly the requested properties. */
+type SelectedContact<Property extends ContactProperty> = Pick<ContactInfo, Property>;
+/** Minimal `navigator.contacts` (`ContactsManager`). */
+interface ContactsManagerLike {
+  /** Properties this platform supports. */
+  getProperties(): Promise<readonly string[]>;
+  /** Open the picker (needs user activation). */
+  select(properties: ContactProperty[], options?: {
+    multiple?: boolean;
+  }): Promise<readonly Partial<ContactInfo>[]>;
+}
+/** Options for {@link useContactPicker}. */
+interface UseContactPickerOptions {
+  /**
+   * Contacts manager for alternate runtimes and tests.
+   *
+   * @default window.navigator.contacts when it exists
+   */
+  readonly contacts?: MaybeRefOrGetter<ContactsManagerLike | null | undefined>;
+}
+/** Options of {@link ContactPickerControls.select}. */
+interface ContactSelectOptions {
+  /**
+   * Allow picking several contacts.
+   *
+   * @default false
+   */
+  readonly multiple?: boolean;
+}
+/** Discriminated outcome of {@link ContactPickerControls.select}. */
+type ContactPickerResult<Property extends ContactProperty> = {
+  /** The picker closed; `contacts` is empty when the user dismissed it. */readonly status: "selected"; /** Picked contacts with exactly the requested keys. */
+  readonly contacts: SelectedContact<Property>[];
+} | {
+  /** `unsupported`: no API; `failed`: the host rejected. */readonly status: "unsupported" | "failed"; /** Error thrown by the host, when one was thrown. */
+  readonly error: unknown;
+};
+/** Reactive state and actions returned by {@link useContactPicker}. */
+interface ContactPickerControls {
+  /** Whether the Contact Picker API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether the picker is open. */
+  readonly pending: Readonly<Ref<boolean>>;
+  /** Most recent failure, cleared on success. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Properties the platform supports.
+   *
+   * @returns Known supported properties; empty when unsupported or failing.
+   */
+  readonly getProperties: () => Promise<ContactProperty[]>;
+  /**
+   * Open the contact picker.
+   *
+   * @param properties Properties to request; the result is typed from them.
+   * @param options Selection options.
+   * @throws `TypeError` tagged `VIZE_COMPOSE_CONTACT_PICKER_NO_PROPERTIES` when `properties` is empty.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly select: <const Property extends ContactProperty>(properties: readonly Property[], options?: ContactSelectOptions) => Promise<ContactPickerResult<Property>>;
+}
+/**
+ * Let the user share contacts with the Contact Picker API.
+ *
+ * `select(["name", "email"])` resolves to contacts typed with exactly those
+ * keys (missing values become empty arrays). Dismissing the picker resolves
+ * with an empty list. The composable holds no resources, so nothing needs
+ * cleanup.
+ *
+ * Server rendering: nothing is requested, `supported` and `pending` are false.
+ * Inside a component `supported` turns true only after mounting, so
+ * hydration renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const picker = useContactPicker();
+ * const result = await picker.select(["name", "tel"], { multiple: true });
+ * ```
+ *
+ * @param options Capability host.
+ * @default options {}
+ * @returns Picker state and actions.
+ */
+declare function useContactPicker(options?: UseContactPickerOptions): ContactPickerControls;
+//#endregion
+export { ContactAddressLike, ContactInfo, ContactPickerControls, ContactPickerResult, ContactProperty, ContactSelectOptions, ContactsManagerLike, SelectedContact, UseContactPickerOptions, useContactPicker };

package/dist/use-contact-picker.mjs

@@ -0,0 +1,103 @@
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, watchPostEffect } from "vue";
+//#region src/use-contact-picker.ts
+const knownProperties = [
+	"address",
+	"email",
+	"icon",
+	"name",
+	"tel"
+];
+function isContactProperty(value) {
+	return knownProperties.includes(value);
+}
+function isContactsManager(candidate) {
+	return typeof candidate === "object" && candidate !== null && "select" in candidate && "getProperties" in candidate && typeof candidate.select === "function" && typeof candidate.getProperties === "function";
+}
+function browserContacts() {
+	if (typeof window === "undefined") return void 0;
+	const candidate = Reflect.get(window.navigator, "contacts");
+	return isContactsManager(candidate) ? candidate : void 0;
+}
+function pickContact(contact, properties) {
+	const full = {
+		address: contact.address ?? [],
+		email: contact.email ?? [],
+		icon: contact.icon ?? [],
+		name: contact.name ?? [],
+		tel: contact.tel ?? []
+	};
+	const picked = {};
+	for (const property of properties) picked[property] = full[property];
+	return picked;
+}
+/**
+* Let the user share contacts with the Contact Picker API.
+*
+* `select(["name", "email"])` resolves to contacts typed with exactly those
+* keys (missing values become empty arrays). Dismissing the picker resolves
+* with an empty list. The composable holds no resources, so nothing needs
+* cleanup.
+*
+* Server rendering: nothing is requested, `supported` and `pending` are false.
+* Inside a component `supported` turns true only after mounting, so
+* hydration renders this server state first.
+*
+* @example
+* ```ts
+* const picker = useContactPicker();
+* const result = await picker.select(["name", "tel"], { multiple: true });
+* ```
+*
+* @param options Capability host.
+* @default options {}
+* @returns Picker state and actions.
+*/
+function useContactPicker(options = {}) {
+	const pending = ref(false);
+	const error = shallowRef(void 0);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => options.contacts === void 0 ? browserContacts() : toValue(options.contacts) ?? void 0;
+	const getProperties = async () => {
+		try {
+			return [...await resolveHost()?.getProperties() ?? []].filter(isContactProperty);
+		} catch {
+			return [];
+		}
+	};
+	const select = (properties, selectOptions = {}) => {
+		if (properties.length === 0) throw new TypeError("[VIZE_COMPOSE_CONTACT_PICKER_NO_PROPERTIES] select() needs at least one property");
+		const host = resolveHost();
+		if (!host) return Promise.resolve({
+			status: "unsupported",
+			error: void 0
+		});
+		pending.value = true;
+		return host.select([...properties], { multiple: selectOptions.multiple ?? false }).then((contacts) => {
+			error.value = void 0;
+			return {
+				status: "selected",
+				contacts: contacts.map((contact) => pickContact(contact, properties))
+			};
+		}, (cause) => {
+			error.value = cause;
+			return {
+				status: "failed",
+				error: cause
+			};
+		}).finally(() => {
+			pending.value = false;
+		});
+	};
+	return {
+		supported: computed(() => hydrated.value && resolveHost() !== void 0),
+		pending: readonly(pending),
+		error: readonly(error),
+		getProperties,
+		select
+	};
+}
+//#endregion
+export { useContactPicker };