@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/use-share.ts

@@ -0,0 +1,168 @@
+import { computed, readonly, ref, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+/** Data shared through the Web Share API. */
+export interface ShareDataLike {
+  /** Title of the shared content. */
+  readonly title?: string;
+
+  /** Body text of the shared content. */
+  readonly text?: string;
+
+  /** URL of the shared content. */
+  readonly url?: string;
+
+  /** Files to share (Level 2 of the Web Share API). */
+  readonly files?: File[];
+}
+
+/** Minimal Web Share capability (`navigator`). */
+export interface ShareHost {
+  /** Open the platform share sheet. */
+  share(data: ShareDataLike): Promise<void>;
+
+  /** Whether the platform can share `data`. Absent in older engines. */
+  canShare?(data?: ShareDataLike): boolean;
+}
+
+/** Discriminated outcome of {@link ShareControls.share}. */
+export type ShareResult =
+  | {
+      /** The share sheet completed. */
+      readonly status: "shared";
+      /** Data that was shared. */
+      readonly data: ShareDataLike;
+    }
+  | {
+      /**
+       * `"cancelled"`: the user dismissed the sheet (AbortError).
+       * `"unsupported"`: no Web Share capability.
+       * `"invalid"`: the platform cannot share this data (canShare / TypeError).
+       * `"not-allowed"`: no transient user activation or blocked by policy.
+       * `"failed"`: any other failure.
+       */
+      readonly status: "cancelled" | "unsupported" | "invalid" | "not-allowed" | "failed";
+      /** Exact error thrown by the host, when one was thrown. */
+      readonly error: unknown;
+    };
+
+/** Options for {@link useShare}. */
+export interface UseShareOptions {
+  /**
+   * Web Share capability for alternate runtimes and tests.
+   *
+   * @default window.navigator when it implements `share`
+   */
+  readonly host?: MaybeRefOrGetter<ShareHost | null | undefined>;
+}
+
+/** Reactive state and actions returned by {@link useShare}. */
+export interface ShareControls {
+  /** Whether the Web Share API is available. */
+  readonly supported: ComputedRef<boolean>;
+
+  /** Whether a share sheet opened by this composable is currently open. */
+  readonly sharing: Readonly<Ref<boolean>>;
+
+  /**
+   * Whether the platform can share the given (or default) data.
+   *
+   * @param data Data merged over the defaults.
+   * @returns `false` when unsupported.
+   */
+  readonly canShare: (data?: ShareDataLike) => boolean;
+
+  /**
+   * Open the share sheet. Must run inside a user gesture in browsers.
+   *
+   * @param overrides Data merged over the defaults.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly share: (overrides?: ShareDataLike) => Promise<ShareResult>;
+}
+
+function browserShareHost(): ShareHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { navigator } = window;
+  return typeof navigator.share === "function" ? navigator : undefined;
+}
+
+function errorName(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "name" in error
+    ? String(error.name)
+    : undefined;
+}
+
+/**
+ * Share text, links, and files through the platform share sheet.
+ *
+ * Reactive defaults are merged with per-call overrides. Outcomes are
+ * reported as a discriminated {@link ShareResult}, so a user dismissing the
+ * sheet (`"cancelled"`) is distinguishable from missing support or invalid
+ * data without try/catch.
+ *
+ * Server rendering: no capability is resolved, `supported` is false, and
+ * nothing is shared. No resources are retained, so nothing needs cleanup.
+ *
+ * @example
+ * ```ts
+ * const { share, supported } = useShare(() => ({ title: document.title, url: location.href }));
+ * const onClick = () => share();
+ * ```
+ *
+ * @param defaults Reactive default share data.
+ * @param options Web Share capability.
+ * @default defaults {}
+ * @default options {}
+ * @returns Share state and actions.
+ */
+export function useShare(
+  defaults: MaybeRefOrGetter<ShareDataLike> = {},
+  options: UseShareOptions = {},
+): ShareControls {
+  const sharing = ref(false);
+  const resolveHost = (): ShareHost | undefined =>
+    options.host === undefined ? browserShareHost() : (toValue(options.host) ?? undefined);
+  const merge = (data: ShareDataLike | undefined): ShareDataLike => ({
+    ...toValue(defaults),
+    ...data,
+  });
+
+  const canShare = (data?: ShareDataLike): boolean => {
+    const host = resolveHost();
+    if (!host) return false;
+    if (!host.canShare) return true;
+    try {
+      return host.canShare(merge(data));
+    } catch {
+      return false;
+    }
+  };
+
+  const share = async (overrides?: ShareDataLike): Promise<ShareResult> => {
+    const host = resolveHost();
+    if (!host) return { status: "unsupported", error: undefined };
+    const data = merge(overrides);
+    if (host.canShare && !canShare(overrides)) return { status: "invalid", error: undefined };
+    sharing.value = true;
+    try {
+      await host.share(data);
+      return { status: "shared", data };
+    } catch (error) {
+      const name = errorName(error);
+      if (name === "AbortError") return { status: "cancelled", error };
+      if (name === "NotAllowedError") return { status: "not-allowed", error };
+      if (name === "TypeError" || name === "DataError") return { status: "invalid", error };
+      return { status: "failed", error };
+    } finally {
+      sharing.value = false;
+    }
+  };
+
+  return {
+    supported: computed(() => resolveHost() !== undefined),
+    sharing: readonly(sharing),
+    canShare,
+    share,
+  };
+}

package/registry/files/use-sorted-locale.ts

@@ -0,0 +1,130 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** Options for {@link useSortedLocale}. */
+export interface UseSortedLocaleOptions<Item> extends Intl.CollatorOptions {
+  /**
+   * Locale whose collation order is used. Pass it explicitly for
+   * hydration-stable server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+
+  /**
+   * Sort from Z to A.
+   *
+   * @default false
+   */
+  readonly descending?: boolean;
+
+  /**
+   * Text to compare for each item. Required for non-string items.
+   *
+   * @default String(item)
+   */
+  readonly key?: (item: Item) => string;
+}
+
+/** Reactive locale-aware sorting returned by {@link useSortedLocale}. */
+export interface SortedLocaleControls<Item> {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Collator for the current locale and options. */
+  readonly collator: ComputedRef<Intl.Collator>;
+
+  /** New array sorted by locale collation; the source is never mutated. */
+  readonly sorted: ComputedRef<readonly Item[]>;
+
+  /**
+   * Compare two strings with the current collator (ignores `descending`).
+   *
+   * @param left First string.
+   * @param right Second string.
+   * @returns Negative, zero, or positive.
+   */
+  readonly compare: (left: string, right: string) => number;
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+/**
+ * Sort strings locale-aware with `Intl.Collator`.
+ *
+ * @param items Reactive strings.
+ * @param options Reactive locale, collation, and direction options.
+ * @returns Reactive sorted copy and collation helpers.
+ */
+export function useSortedLocale(
+  items: MaybeRefOrGetter<readonly string[]>,
+  options?: MaybeRefOrGetter<UseSortedLocaleOptions<string>>,
+): SortedLocaleControls<string>;
+
+/**
+ * Sort any items locale-aware by a string key with `Intl.Collator`.
+ *
+ * @param items Reactive items.
+ * @param options Reactive locale, collation, direction, and required key.
+ * @returns Reactive sorted copy and collation helpers.
+ */
+export function useSortedLocale<Item>(
+  items: MaybeRefOrGetter<readonly Item[]>,
+  options: MaybeRefOrGetter<
+    UseSortedLocaleOptions<Item> & { readonly key: (item: Item) => string }
+  >,
+): SortedLocaleControls<Item>;
+
+/**
+ * Sort items with locale-aware collation (`Intl.Collator`): `"ä"` sorts
+ * next to `"a"` in German but after `"z"` in Swedish, and `numeric: true`
+ * orders `"item 10"` after `"item 9"`.
+ *
+ * The result is a new, stable-sorted array recomputed when the items,
+ * options, or locale change; the source array is never mutated. Invalid
+ * options surface as the platform `RangeError`. Derived state only: safe
+ * and deterministic on the server when the locale is explicit.
+ *
+ * @example
+ * ```ts
+ * const { sorted } = useSortedLocale(users, { key: (user) => user.name, locale: "de", sensitivity: "base" });
+ * ```
+ *
+ * @param items Reactive items.
+ * @param options Reactive locale, collation, direction, and key.
+ * @default options {}
+ * @returns Reactive sorted copy and collation helpers.
+ */
+export function useSortedLocale<Item>(
+  items: MaybeRefOrGetter<readonly Item[]>,
+  options: MaybeRefOrGetter<UseSortedLocaleOptions<Item>> = {},
+): SortedLocaleControls<Item> {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const collator = computed(() => {
+    const {
+      locale: _locale,
+      descending: _descending,
+      key: _key,
+      ...collatorOptions
+    } = toValue(options);
+    return new Intl.Collator(localeControls.locale.value, collatorOptions);
+  });
+  const sorted = computed(() => {
+    const { key = String, descending = false } = toValue(options);
+    const active = collator.value;
+    const direction = descending ? -1 : 1;
+    const keyed = toValue(items).map((item) => ({ item, text: key(item) }));
+    keyed.sort((left, right) => direction * active.compare(left.text, right.text));
+    return keyed.map(({ item }) => item);
+  });
+  return {
+    locale: localeControls.locale,
+    collator,
+    sorted,
+    compare: (left, right) => collator.value.compare(left, right),
+  };
+}

package/registry/files/use-sorted.ts

@@ -0,0 +1,49 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+/** Comparator with `Array.prototype.sort` semantics. */
+export type SortComparator<Item> = (left: Item, right: Item) => number;
+
+/** Values with a natural order used by the default comparator. */
+export type NaturallyOrdered = number | bigint | string | Date;
+
+function naturalOrder(left: NaturallyOrdered, right: NaturallyOrdered): number {
+  const a = left instanceof Date ? left.getTime() : left;
+  const b = right instanceof Date ? right.getTime() : right;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * Sorted copy of a reactive array; the source is never mutated.
+ *
+ * Numbers, bigints, strings, and dates sort in natural ascending order by
+ * default (numerically, unlike `Array.prototype.sort`); any other item type
+ * requires a comparator. The sort is stable. Pure derived state: SSR-safe
+ * and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const ranked = useSorted(players, (a, b) => b.score - a.score);
+ * const ascending = useSorted([10, 9, 100]); // [9, 10, 100]
+ * ```
+ *
+ * @param source Reactive array.
+ * @param compare Comparator; optional for naturally ordered items.
+ * @returns Computed sorted copy.
+ */
+export function useSorted<Item extends NaturallyOrdered>(
+  source: MaybeRefOrGetter<readonly Item[]>,
+  compare?: SortComparator<Item>,
+): ComputedRef<Item[]>;
+export function useSorted<Item>(
+  source: MaybeRefOrGetter<readonly Item[]>,
+  compare: SortComparator<Item>,
+): ComputedRef<Item[]>;
+export function useSorted(
+  source: MaybeRefOrGetter<readonly NaturallyOrdered[]>,
+  compare: SortComparator<NaturallyOrdered> = naturalOrder,
+): ComputedRef<NaturallyOrdered[]> {
+  return computed(() => [...toValue(source)].sort(compare));
+}

package/registry/files/use-speech-recognition.ts

@@ -0,0 +1,357 @@
+import { computed, readonly, ref, shallowRef, toValue, unref, watch } from "vue";
+import type { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+/** One recognition hypothesis. */
+export interface SpeechRecognitionAlternativeLike {
+  /** Recognized text. */
+  readonly transcript: string;
+
+  /** Confidence between 0 and 1. */
+  readonly confidence: number;
+}
+
+/** One recognition result: an array-like list of alternatives. */
+export interface SpeechRecognitionResultLike {
+  /** Number of alternatives. */
+  readonly length: number;
+
+  /** Whether the result is final (no longer interim). */
+  readonly isFinal: boolean;
+
+  /** Alternative at `index`, most likely first. */
+  readonly [index: number]: SpeechRecognitionAlternativeLike;
+}
+
+/** Array-like list of every result of the current session. */
+export interface SpeechRecognitionResultListLike {
+  /** Number of results. */
+  readonly length: number;
+
+  /** Result at `index`. */
+  readonly [index: number]: SpeechRecognitionResultLike;
+}
+
+/** Minimal `SpeechRecognition` instance consumed by {@link useSpeechRecognition}. */
+export interface SpeechRecognitionLike extends EventTarget {
+  /** BCP 47 language tag. */
+  lang: string;
+
+  /** Keep listening after the first final result. */
+  continuous: boolean;
+
+  /** Report interim (non-final) results. */
+  interimResults: boolean;
+
+  /** Maximum alternatives per result. */
+  maxAlternatives: number;
+
+  /** Start listening. Throws `InvalidStateError` when already started. */
+  start(): void;
+
+  /** Stop listening and deliver a final result. */
+  stop(): void;
+
+  /** Stop listening without delivering a result. */
+  abort(): void;
+}
+
+/** Minimal `SpeechRecognition` constructor. */
+export interface SpeechRecognitionHost {
+  /** Create a recognizer. */
+  new (): SpeechRecognitionLike;
+}
+
+/** Error codes defined by the Web Speech API, plus `"unknown"` for future codes. */
+export type SpeechRecognitionErrorCode =
+  | "aborted"
+  | "audio-capture"
+  | "bad-grammar"
+  | "language-not-supported"
+  | "network"
+  | "no-speech"
+  | "not-allowed"
+  | "phrases-not-supported"
+  | "service-not-allowed"
+  | "unknown";
+
+/** Recognition failure reported by {@link useSpeechRecognition}. */
+export interface SpeechRecognitionFailure {
+  /** Normalized error code. */
+  readonly code: SpeechRecognitionErrorCode;
+
+  /** Implementation-provided message, possibly empty. */
+  readonly message: string;
+}
+
+/** Options for {@link useSpeechRecognition}. */
+export interface UseSpeechRecognitionOptions {
+  /**
+   * Recognition language, applied when listening starts.
+   *
+   * @default "en-US"
+   */
+  readonly lang?: MaybeRefOrGetter<string>;
+
+  /**
+   * Keep listening after the first final result.
+   *
+   * @default true
+   */
+  readonly continuous?: boolean;
+
+  /**
+   * Report interim results through `interimResult`.
+   *
+   * @default true
+   */
+  readonly interimResults?: boolean;
+
+  /**
+   * Maximum alternatives per result.
+   *
+   * @default 1
+   */
+  readonly maxAlternatives?: number;
+
+  /**
+   * Recognizer constructor for alternate runtimes and tests. A ref (not a
+   * getter) because the host itself is a constructor function.
+   *
+   * @default window.SpeechRecognition ?? window.webkitSpeechRecognition
+   */
+  readonly host?: MaybeRef<SpeechRecognitionHost | null | undefined>;
+}
+
+/** Reactive state and actions returned by {@link useSpeechRecognition}. */
+export interface SpeechRecognitionControls {
+  /** Whether a speech recognizer is available. */
+  readonly supported: ComputedRef<boolean>;
+
+  /** Whether the recognizer is listening. */
+  readonly listening: Readonly<Ref<boolean>>;
+
+  /** Concatenated final transcript of the current session. */
+  readonly result: Readonly<Ref<string>>;
+
+  /** Concatenated interim transcript not yet final. */
+  readonly interimResult: Readonly<Ref<string>>;
+
+  /** Alternatives of the most recent result. */
+  readonly alternatives: Readonly<ShallowRef<readonly SpeechRecognitionAlternativeLike[]>>;
+
+  /** Most recent recognition failure, cleared when listening starts. */
+  readonly error: Readonly<ShallowRef<SpeechRecognitionFailure | undefined>>;
+
+  /**
+   * Start listening with the current options, clearing previous results.
+   *
+   * @returns Whether listening started.
+   */
+  readonly start: () => boolean;
+
+  /** Stop listening and keep the final result. */
+  readonly stop: () => void;
+
+  /** Stop listening immediately without a final result. */
+  readonly abort: () => void;
+
+  /**
+   * Start or stop listening.
+   *
+   * @param value Force listening on or off.
+   * @default value !listening
+   */
+  readonly toggle: (value?: boolean) => void;
+}
+
+const errorCodes: ReadonlySet<string> = new Set<SpeechRecognitionErrorCode>([
+  "aborted",
+  "audio-capture",
+  "bad-grammar",
+  "language-not-supported",
+  "network",
+  "no-speech",
+  "not-allowed",
+  "phrases-not-supported",
+  "service-not-allowed",
+]);
+
+function isErrorCode(code: string): code is SpeechRecognitionErrorCode {
+  return errorCodes.has(code);
+}
+
+function isRecognitionConstructor(candidate: unknown): candidate is SpeechRecognitionHost {
+  return typeof candidate === "function";
+}
+
+function browserRecognitionHost(): SpeechRecognitionHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const candidate: unknown =
+    Reflect.get(window, "SpeechRecognition") ?? Reflect.get(window, "webkitSpeechRecognition");
+  return isRecognitionConstructor(candidate) ? candidate : undefined;
+}
+
+interface ResultEventLike extends Event {
+  readonly results: SpeechRecognitionResultListLike;
+}
+
+function isResultEvent(event: Event): event is ResultEventLike {
+  if (!("results" in event)) return false;
+  const { results } = event;
+  return typeof results === "object" && results !== null && "length" in results;
+}
+
+function readString(event: Event, key: "error" | "message"): string {
+  const value: unknown = key in event ? Reflect.get(event, key) : undefined;
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Transcribe speech with the Web Speech API.
+ *
+ * `result` accumulates the final transcript of the current session and
+ * `interimResult` the text still being recognized. Options are applied each
+ * time listening starts, so a reactive `lang` takes effect on the next
+ * `start`. Errors are normalized to a closed {@link SpeechRecognitionErrorCode}
+ * union and exposed through `error` rather than thrown. The recognizer is
+ * aborted and its listeners removed when the owning reactive scope stops.
+ *
+ * Server rendering: no recognizer is created; `supported` and `listening`
+ * are false and the transcripts are empty.
+ *
+ * @example
+ * ```ts
+ * const speech = useSpeechRecognition({ lang: "ja-JP" });
+ * speech.start();
+ * watch(speech.result, (text) => console.log(text));
+ * ```
+ *
+ * @param options Recognition settings and recognizer constructor.
+ * @default options {}
+ * @returns Recognition state and actions.
+ */
+export function useSpeechRecognition(
+  options: UseSpeechRecognitionOptions = {},
+): SpeechRecognitionControls {
+  const listening = ref(false);
+  const result = ref("");
+  const interimResult = ref("");
+  const alternatives = shallowRef<readonly SpeechRecognitionAlternativeLike[]>([]);
+  const error = shallowRef<SpeechRecognitionFailure | undefined>(undefined);
+  let recognition: SpeechRecognitionLike | undefined;
+
+  const resolveHost = (): SpeechRecognitionHost | undefined =>
+    options.host === undefined ? browserRecognitionHost() : (unref(options.host) ?? undefined);
+
+  const onResult = (event: Event): void => {
+    if (!isResultEvent(event)) return;
+    const finals: string[] = [];
+    const interim: string[] = [];
+    let last: SpeechRecognitionResultLike | undefined;
+    for (let index = 0; index < event.results.length; index += 1) {
+      const entry = event.results[index];
+      if (!entry) continue;
+      last = entry;
+      const best = entry[0];
+      if (best) (entry.isFinal ? finals : interim).push(best.transcript);
+    }
+    result.value = finals.join("");
+    interimResult.value = interim.join("");
+    const collected: SpeechRecognitionAlternativeLike[] = [];
+    for (let index = 0; last && index < last.length; index += 1) {
+      const alternative = last[index];
+      if (alternative) collected.push(alternative);
+    }
+    alternatives.value = collected;
+  };
+
+  const onError = (event: Event): void => {
+    const code = readString(event, "error");
+    error.value = {
+      code: isErrorCode(code) ? code : "unknown",
+      message: readString(event, "message"),
+    };
+  };
+
+  const onStart = (): void => {
+    listening.value = true;
+  };
+
+  const onEnd = (): void => {
+    listening.value = false;
+    interimResult.value = "";
+  };
+
+  watch(
+    resolveHost,
+    (Host, _previous, onCleanup) => {
+      listening.value = false;
+      recognition = undefined;
+      if (!Host) return;
+      const instance = new Host();
+      instance.addEventListener("result", onResult);
+      instance.addEventListener("error", onError);
+      instance.addEventListener("start", onStart);
+      instance.addEventListener("end", onEnd);
+      recognition = instance;
+      onCleanup(() => {
+        instance.removeEventListener("result", onResult);
+        instance.removeEventListener("error", onError);
+        instance.removeEventListener("start", onStart);
+        instance.removeEventListener("end", onEnd);
+        if (listening.value) instance.abort();
+        listening.value = false;
+        if (recognition === instance) recognition = undefined;
+      });
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  const start = (): boolean => {
+    const instance = recognition;
+    if (!instance || listening.value) return listening.value;
+    instance.lang = toValue(options.lang) ?? "en-US";
+    instance.continuous = options.continuous ?? true;
+    instance.interimResults = options.interimResults ?? true;
+    instance.maxAlternatives = options.maxAlternatives ?? 1;
+    result.value = "";
+    interimResult.value = "";
+    alternatives.value = [];
+    error.value = undefined;
+    try {
+      instance.start();
+    } catch {
+      // InvalidStateError: the recognizer is already running.
+      return false;
+    }
+    listening.value = true;
+    return true;
+  };
+
+  const stop = (): void => {
+    recognition?.stop();
+  };
+
+  const abort = (): void => {
+    recognition?.abort();
+    listening.value = false;
+  };
+
+  const toggle = (value: boolean = !listening.value): void => {
+    if (value) start();
+    else stop();
+  };
+
+  return {
+    supported: computed(() => resolveHost() !== undefined),
+    listening: readonly(listening),
+    result: readonly(result),
+    interimResult: readonly(interimResult),
+    alternatives,
+    error,
+    start,
+    stop,
+    abort,
+    toggle,
+  };
+}