@vizejs/composable 0.426.3 → 0.428.0

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

@@ -0,0 +1,333 @@
+import { computed, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Minimal `SpeechSynthesisVoice`. */
+export interface SpeechSynthesisVoiceLike {
+  /** Human-readable voice name. */
+  readonly name: string;
+
+  /** BCP 47 language tag. */
+  readonly lang: string;
+
+  /** Stable voice identifier. */
+  readonly voiceURI: string;
+
+  /** Whether synthesis runs locally. */
+  readonly localService: boolean;
+
+  /** Whether this is the platform default voice. */
+  readonly default: boolean;
+}
+
+/** Minimal `SpeechSynthesisUtterance`. */
+export interface SpeechSynthesisUtteranceLike extends EventTarget {
+  /** Text to speak. */
+  text: string;
+
+  /** BCP 47 language tag. */
+  lang: string;
+
+  /** Pitch from 0 to 2. */
+  pitch: number;
+
+  /** Rate from 0.1 to 10. */
+  rate: number;
+
+  /** Volume from 0 to 1. */
+  volume: number;
+
+  /** Voice, or `null` for the platform default. */
+  voice: SpeechSynthesisVoiceLike | null;
+}
+
+/** Minimal `speechSynthesis` controller. */
+export interface SpeechSynthesisLike extends EventTarget {
+  /** Queue an utterance. */
+  speak(utterance: SpeechSynthesisUtteranceLike): void;
+
+  /** Clear the queue and stop speaking. */
+  cancel(): void;
+
+  /** Pause speaking. */
+  pause(): void;
+
+  /** Resume speaking. */
+  resume(): void;
+
+  /** Voices available right now (may be empty until `voiceschanged`). */
+  getVoices(): readonly SpeechSynthesisVoiceLike[];
+}
+
+/** Capabilities used by {@link useSpeechSynthesis}. */
+export interface SpeechSynthesisHost {
+  /** Synthesis controller (`window.speechSynthesis`). */
+  readonly synthesis: SpeechSynthesisLike;
+
+  /** Utterance constructor (`window.SpeechSynthesisUtterance`). */
+  readonly Utterance: new (text?: string) => SpeechSynthesisUtteranceLike;
+}
+
+/** Playback state of {@link useSpeechSynthesis}. */
+export type SpeechSynthesisStatus = "idle" | "speaking" | "paused" | "ended" | "error";
+
+/** Error codes defined by the Web Speech API, plus `"unknown"` for future codes. */
+export type SpeechSynthesisErrorCode =
+  | "audio-busy"
+  | "audio-hardware"
+  | "invalid-argument"
+  | "language-unavailable"
+  | "network"
+  | "not-allowed"
+  | "synthesis-failed"
+  | "synthesis-unavailable"
+  | "text-too-long"
+  | "voice-unavailable"
+  | "unknown";
+
+/** Options for {@link useSpeechSynthesis}. */
+export interface UseSpeechSynthesisOptions {
+  /**
+   * BCP 47 language tag.
+   *
+   * @default "en-US"
+   */
+  readonly lang?: MaybeRefOrGetter<string>;
+
+  /**
+   * Pitch from 0 to 2.
+   *
+   * @default 1
+   */
+  readonly pitch?: MaybeRefOrGetter<number>;
+
+  /**
+   * Rate from 0.1 to 10.
+   *
+   * @default 1
+   */
+  readonly rate?: MaybeRefOrGetter<number>;
+
+  /**
+   * Volume from 0 to 1.
+   *
+   * @default 1
+   */
+  readonly volume?: MaybeRefOrGetter<number>;
+
+  /**
+   * Voice to use; `undefined` uses the platform default for `lang`.
+   *
+   * @default undefined
+   */
+  readonly voice?: MaybeRefOrGetter<SpeechSynthesisVoiceLike | undefined>;
+
+  /**
+   * Synthesis capabilities for alternate runtimes and tests.
+   *
+   * @default window.speechSynthesis and window.SpeechSynthesisUtterance
+   */
+  readonly host?: MaybeRefOrGetter<SpeechSynthesisHost | null | undefined>;
+}
+
+/** Reactive state and actions returned by {@link useSpeechSynthesis}. */
+export interface SpeechSynthesisControls {
+  /** Whether speech synthesis is available. */
+  readonly supported: ComputedRef<boolean>;
+
+  /** Playback state of the utterance spoken by this composable. */
+  readonly status: Readonly<Ref<SpeechSynthesisStatus>>;
+
+  /** Voices offered by the platform, updated on `voiceschanged`. */
+  readonly voices: Readonly<ShallowRef<readonly SpeechSynthesisVoiceLike[]>>;
+
+  /** Most recent synthesis error, cleared by the next `speak`. */
+  readonly error: Readonly<ShallowRef<SpeechSynthesisErrorCode | undefined>>;
+
+  /**
+   * Speak the current text, cancelling anything this composable is speaking.
+   *
+   * @returns Whether an utterance was queued.
+   * @throws {RangeError} `[VIZE_COMPOSE_SPEECH_SYNTHESIS_INVALID_OPTION]` when
+   * pitch, rate, or volume is out of range.
+   */
+  readonly speak: () => boolean;
+
+  /** Pause speaking. */
+  readonly pause: () => void;
+
+  /** Resume paused speech. */
+  readonly resume: () => void;
+
+  /** Stop speaking and clear the queue. */
+  readonly cancel: () => void;
+}
+
+const synthesisErrorCodes: ReadonlySet<string> = new Set<SpeechSynthesisErrorCode>([
+  "audio-busy",
+  "audio-hardware",
+  "invalid-argument",
+  "language-unavailable",
+  "network",
+  "not-allowed",
+  "synthesis-failed",
+  "synthesis-unavailable",
+  "text-too-long",
+  "voice-unavailable",
+]);
+
+function isSynthesisErrorCode(code: string): code is SpeechSynthesisErrorCode {
+  return synthesisErrorCodes.has(code);
+}
+
+function browserSynthesisHost(): SpeechSynthesisHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  if (!("speechSynthesis" in window) || !("SpeechSynthesisUtterance" in window)) return undefined;
+  return { synthesis: window.speechSynthesis, Utterance: window.SpeechSynthesisUtterance };
+}
+
+function checkedRange(name: string, value: number, minimum: number, maximum: number): number {
+  if (!Number.isFinite(value) || value < minimum || value > maximum) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_SPEECH_SYNTHESIS_INVALID_OPTION] ${name} must be between ${String(minimum)} and ${String(maximum)}; received ${String(value)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Speak text with the Web Speech API.
+ *
+ * Each `speak` creates a fresh utterance from the current reactive text,
+ * language, voice, pitch, rate, and volume (validated ranges), and cancels
+ * speech previously started by this composable. `status` follows the
+ * utterance lifecycle; interruptions caused by `cancel` return to `"idle"`
+ * instead of reporting an error. The available voices are kept current via
+ * `voiceschanged`. Speech started by this composable is cancelled and the
+ * listener removed when the owning reactive scope stops.
+ *
+ * Server rendering: nothing is spoken; `supported` is false, `status` is
+ * `"idle"`, and `voices` is empty.
+ *
+ * @example
+ * ```ts
+ * const text = ref("Hello, Vize");
+ * const { speak, status } = useSpeechSynthesis(text, { rate: 1.2 });
+ * speak();
+ * ```
+ *
+ * @param text Reactive text to speak.
+ * @param options Voice parameters and synthesis capabilities.
+ * @default options {}
+ * @returns Synthesis state and actions.
+ */
+export function useSpeechSynthesis(
+  text: MaybeRefOrGetter<string>,
+  options: UseSpeechSynthesisOptions = {},
+): SpeechSynthesisControls {
+  const status = ref<SpeechSynthesisStatus>("idle");
+  const voices = shallowRef<readonly SpeechSynthesisVoiceLike[]>([]);
+  const error = shallowRef<SpeechSynthesisErrorCode | undefined>(undefined);
+  let current: SpeechSynthesisUtteranceLike | undefined;
+
+  const resolveHost = (): SpeechSynthesisHost | undefined =>
+    options.host === undefined ? browserSynthesisHost() : (toValue(options.host) ?? undefined);
+
+  const readParameters = (): { pitch: number; rate: number; volume: number } => ({
+    pitch: checkedRange("pitch", toValue(options.pitch) ?? 1, 0, 2),
+    rate: checkedRange("rate", toValue(options.rate) ?? 1, 0.1, 10),
+    volume: checkedRange("volume", toValue(options.volume) ?? 1, 0, 1),
+  });
+  // Fail fast on statically invalid options.
+  readParameters();
+
+  watch(
+    () => resolveHost()?.synthesis,
+    (synthesis, _previous, onCleanup) => {
+      voices.value = [];
+      if (!synthesis) return;
+      const update = (): void => {
+        voices.value = [...synthesis.getVoices()];
+      };
+      update();
+      synthesis.addEventListener("voiceschanged", update);
+      onCleanup(() => synthesis.removeEventListener("voiceschanged", update));
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  const cancel = (): void => {
+    const host = resolveHost();
+    const active = current;
+    current = undefined;
+    if (host && active) host.synthesis.cancel();
+    status.value = "idle";
+  };
+
+  const speak = (): boolean => {
+    const host = resolveHost();
+    const parameters = readParameters();
+    if (!host) return false;
+    if (current) cancel();
+    const utterance = new host.Utterance(toValue(text));
+    utterance.lang = toValue(options.lang) ?? "en-US";
+    utterance.pitch = parameters.pitch;
+    utterance.rate = parameters.rate;
+    utterance.volume = parameters.volume;
+    utterance.voice = toValue(options.voice) ?? null;
+    const own = (): boolean => current === utterance;
+    utterance.addEventListener("start", () => {
+      if (own()) status.value = "speaking";
+    });
+    utterance.addEventListener("pause", () => {
+      if (own()) status.value = "paused";
+    });
+    utterance.addEventListener("resume", () => {
+      if (own()) status.value = "speaking";
+    });
+    utterance.addEventListener("end", () => {
+      if (!own()) return;
+      current = undefined;
+      status.value = "ended";
+    });
+    utterance.addEventListener("error", (event) => {
+      if (!own()) return;
+      current = undefined;
+      const code: unknown = "error" in event ? event.error : undefined;
+      if (code === "canceled" || code === "interrupted") {
+        status.value = "idle";
+        return;
+      }
+      error.value = typeof code === "string" && isSynthesisErrorCode(code) ? code : "unknown";
+      status.value = "error";
+    });
+    error.value = undefined;
+    current = utterance;
+    host.synthesis.speak(utterance);
+    return true;
+  };
+
+  const pause = (): void => {
+    if (current) resolveHost()?.synthesis.pause();
+  };
+
+  const resume = (): void => {
+    if (current) resolveHost()?.synthesis.resume();
+  };
+
+  tryOnScopeDispose(() => {
+    if (current) cancel();
+  });
+
+  return {
+    supported: computed(() => resolveHost() !== undefined),
+    status: readonly(status),
+    voices,
+    error,
+    speak,
+    pause,
+    resume,
+    cancel,
+  };
+}

package/registry/files/use-stack.ts

@@ -0,0 +1,164 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef } from "vue";
+
+/** What happens when an item is pushed while a bounded stack is full. */
+export type StackOverflowPolicy = "drop-oldest" | "reject";
+
+/** Options for {@link useStack}. */
+export interface UseStackOptions {
+  /**
+   * Maximum number of stacked items. A positive integer, or
+   * `Number.POSITIVE_INFINITY` for an unbounded stack.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly capacity?: number;
+
+  /**
+   * Policy applied when an item is pushed at capacity: `"drop-oldest"`
+   * discards the bottom item to make room, `"reject"` refuses the new item.
+   *
+   * @default "drop-oldest"
+   */
+  readonly overflow?: StackOverflowPolicy;
+}
+
+/** Reactive last-in, first-out stack returned by {@link useStack}. */
+export interface StackControls<Item> {
+  /** Snapshot of the stacked items, bottom first (the top is the last element). */
+  readonly items: ComputedRef<readonly Item[]>;
+
+  /** Number of stacked items. */
+  readonly size: ComputedRef<number>;
+
+  /** Whether the stack holds no items. */
+  readonly isEmpty: ComputedRef<boolean>;
+
+  /**
+   * Read the top without removing it. Reactive when read inside an effect.
+   *
+   * @returns The top item, or `undefined` when empty.
+   */
+  readonly peek: () => Item | undefined;
+
+  /**
+   * Push items in argument order (the last argument ends on top), applying
+   * the overflow policy.
+   *
+   * @param items Items to push.
+   * @returns How many of the given items were accepted.
+   */
+  readonly push: (...items: Item[]) => number;
+
+  /**
+   * Remove and return the top.
+   *
+   * @returns The removed item, or `undefined` when empty.
+   */
+  readonly pop: () => Item | undefined;
+
+  /** Remove every item. */
+  readonly clear: () => void;
+}
+
+function validateCapacity(capacity: number): number {
+  if (capacity === Number.POSITIVE_INFINITY) return capacity;
+  if (!Number.isSafeInteger(capacity) || capacity < 1) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_STACK_INVALID_CAPACITY] capacity must be a positive integer or Infinity; received ${String(capacity)}`,
+    );
+  }
+  return capacity;
+}
+
+/**
+ * Create a typed reactive LIFO stack.
+ *
+ * `push` and `pop` are O(1). A bounded stack either drops its bottom item
+ * or rejects new pushes when full. Reactivity is driven by a version
+ * counter, so `items`, `size`, `isEmpty`, and `peek` re-evaluate after
+ * every mutation.
+ *
+ * Purely synchronous state: safe during server rendering (no host globals,
+ * no timers) and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const breadcrumbs = useStack<string>(["home"]);
+ * breadcrumbs.push("settings");
+ * breadcrumbs.pop(); // "settings"
+ * ```
+ *
+ * @typeParam Item Stacked item type, inferred from `initial` when given.
+ * @param initial Items pushed at creation, bottom first (overflow applies).
+ * @param options Capacity and overflow policy.
+ * @default initial []
+ * @default options {}
+ * @throws {RangeError} `[VIZE_COMPOSE_STACK_INVALID_CAPACITY]` when `capacity`
+ * is not a positive integer or `Infinity`.
+ * @returns The reactive stack and its controls.
+ */
+export function useStack<Item>(
+  initial: Iterable<Item> = [],
+  options: UseStackOptions = {},
+): StackControls<Item> {
+  const capacity = validateCapacity(options.capacity ?? Number.POSITIVE_INFINITY);
+  const overflow = options.overflow ?? "drop-oldest";
+  let buffer: Item[] = [];
+  const version = shallowRef(0);
+  const touch = (): void => {
+    version.value += 1;
+  };
+
+  const append = (items: readonly Item[]): number => {
+    let accepted = 0;
+    let dropped = 0;
+    for (const item of items) {
+      if (buffer.length - dropped >= capacity) {
+        if (overflow === "reject") continue;
+        dropped += 1;
+      }
+      buffer.push(item);
+      accepted += 1;
+    }
+    if (dropped > 0) buffer = buffer.slice(dropped);
+    return accepted;
+  };
+
+  append([...initial]);
+
+  const items = computed<readonly Item[]>(() => {
+    void version.value;
+    return buffer.slice();
+  });
+  const size = computed(() => {
+    void version.value;
+    return buffer.length;
+  });
+
+  return {
+    items,
+    size,
+    isEmpty: computed(() => size.value === 0),
+    peek: () => {
+      void version.value;
+      return buffer.at(-1);
+    },
+    push: (...added) => {
+      const accepted = append(added);
+      if (accepted > 0) touch();
+      return accepted;
+    },
+    pop: () => {
+      if (buffer.length === 0) return undefined;
+      const item = buffer.pop();
+      touch();
+      return item;
+    },
+    clear: () => {
+      if (buffer.length === 0) return;
+      buffer = [];
+      touch();
+    },
+  };
+}

package/registry/files/use-stepper.ts

@@ -0,0 +1,166 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef, ShallowRef } from "vue";
+
+/** Step values keyed by step name. */
+export type StepValues<Name extends string> = { readonly [Step in Name]: unknown };
+
+/** Stepper state and navigation returned by {@link useStepper}. */
+export interface Stepper<Name extends string, Values extends StepValues<Name>> {
+  /** Step names in order. */
+  readonly stepNames: readonly Name[];
+
+  /** Zero-based index of the current step. */
+  readonly index: Readonly<ShallowRef<number>>;
+
+  /** Name of the current step. */
+  readonly current: ComputedRef<Name>;
+
+  /** Value of the current step (the name itself for array steps). */
+  readonly currentValue: ComputedRef<Values[Name]>;
+
+  /** Name of the next step, or `undefined` on the last. */
+  readonly next: ComputedRef<Name | undefined>;
+
+  /** Name of the previous step, or `undefined` on the first. */
+  readonly previous: ComputedRef<Name | undefined>;
+
+  /** Whether the current step is the first. */
+  readonly isFirst: ComputedRef<boolean>;
+
+  /** Whether the current step is the last. */
+  readonly isLast: ComputedRef<boolean>;
+
+  /** Step name at `index`, or `undefined`. */
+  readonly at: (index: number) => Name | undefined;
+
+  /** Value of a step. */
+  readonly get: <Step extends Name>(step: Step) => Values[Step];
+
+  /** Jump to a step. */
+  readonly goTo: (step: Name) => void;
+
+  /** Advance one step (no-op on the last). */
+  readonly goToNext: () => void;
+
+  /** Go back one step (no-op on the first). */
+  readonly goToPrevious: () => void;
+
+  /**
+   * Go back to an earlier step; later or current steps are ignored.
+   *
+   * @returns Whether the cursor moved.
+   */
+  readonly goBackTo: (step: Name) => boolean;
+
+  /** Whether `step` is the current step. */
+  readonly isCurrent: (step: Name) => boolean;
+
+  /** Whether `step` is the step right after the current one. */
+  readonly isNext: (step: Name) => boolean;
+
+  /** Whether `step` is the step right before the current one. */
+  readonly isPrevious: (step: Name) => boolean;
+
+  /** Whether `step` comes before the current step. */
+  readonly isBefore: (step: Name) => boolean;
+
+  /** Whether `step` comes after the current step. */
+  readonly isAfter: (step: Name) => boolean;
+}
+
+/**
+ * Linear multi-step flow (wizards, onboarding, checkout) with typed step
+ * names.
+ *
+ * Pass a tuple of names (`["account", "billing", "review"] as const`, or a
+ * plain array literal thanks to `const` inference) or an object whose keys
+ * are the names and whose values carry per-step data; every navigation
+ * method only accepts declared names. Synchronous state: SSR-safe and
+ * nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const wizard = useStepper(["account", "billing", "review"]);
+ * wizard.goTo("billing");
+ * wizard.goTo("shipping"); // type error
+ * ```
+ *
+ * @param steps Step names, or step values keyed by name.
+ * @param initial Step to start on.
+ * @default initial the first step
+ * @throws `RangeError` tagged `VIZE_COMPOSE_STEPPER_EMPTY` when there are no
+ * steps, and `RangeError` tagged `VIZE_COMPOSE_STEPPER_UNKNOWN_STEP` for an
+ * unknown step name at runtime.
+ * @returns Stepper state and navigation.
+ */
+export function useStepper<const Steps extends readonly string[]>(
+  steps: Steps,
+  initial?: NoInfer<Steps[number]>,
+): Stepper<Steps[number], { readonly [Step in Steps[number]]: Step }>;
+export function useStepper<Steps extends Readonly<Record<string, unknown>>>(
+  steps: Steps,
+  initial?: NoInfer<keyof Steps & string>,
+): Stepper<keyof Steps & string, Steps>;
+export function useStepper(
+  steps: readonly string[] | Readonly<Record<string, unknown>>,
+  initial?: string,
+): Stepper<string, Readonly<Record<string, unknown>>> {
+  const names: readonly string[] = isNameList(steps) ? [...steps] : Object.keys(steps);
+  const values: Readonly<Record<string, unknown>> = isNameList(steps)
+    ? Object.fromEntries(steps.map((name) => [name, name]))
+    : steps;
+  if (names.length === 0) {
+    throw new RangeError("[VIZE_COMPOSE_STEPPER_EMPTY] useStepper needs at least one step");
+  }
+
+  const indexOf = (step: string): number => {
+    const found = names.indexOf(step);
+    if (found === -1) {
+      throw new RangeError(`[VIZE_COMPOSE_STEPPER_UNKNOWN_STEP] unknown step "${step}"`);
+    }
+    return found;
+  };
+
+  const index = shallowRef(initial === undefined ? 0 : indexOf(initial));
+  const at = (position: number): string | undefined => names[position];
+  const current = computed(() => names[index.value] ?? "");
+
+  return {
+    stepNames: names,
+    index,
+    current,
+    currentValue: computed(() => values[current.value]),
+    next: computed(() => at(index.value + 1)),
+    previous: computed(() => at(index.value - 1)),
+    isFirst: computed(() => index.value === 0),
+    isLast: computed(() => index.value === names.length - 1),
+    at,
+    get: (step) => values[step],
+    goTo: (step) => {
+      index.value = indexOf(step);
+    },
+    goToNext: () => {
+      if (index.value < names.length - 1) index.value += 1;
+    },
+    goToPrevious: () => {
+      if (index.value > 0) index.value -= 1;
+    },
+    goBackTo: (step) => {
+      const target = indexOf(step);
+      if (target >= index.value) return false;
+      index.value = target;
+      return true;
+    },
+    isCurrent: (step) => indexOf(step) === index.value,
+    isNext: (step) => indexOf(step) === index.value + 1,
+    isPrevious: (step) => indexOf(step) === index.value - 1,
+    isBefore: (step) => indexOf(step) < index.value,
+    isAfter: (step) => indexOf(step) > index.value,
+  };
+}
+
+function isNameList(
+  steps: readonly string[] | Readonly<Record<string, unknown>>,
+): steps is readonly string[] {
+  return Array.isArray(steps);
+}