@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/use-interval.ts

@@ -0,0 +1,253 @@
+import { shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/**
+ * Repeating timer host used by {@link useIntervalFn} and the clocks built
+ * on it.
+ *
+ * Implement this interface to integrate a deterministic test clock, a native
+ * runtime timer, or an application-owned scheduler. Handles are opaque: they
+ * are only handed back to {@link IntervalScheduler.clearInterval}.
+ */
+export interface IntervalScheduler {
+  /** Starts a repeating callback and returns its opaque cancellation handle. */
+  readonly setInterval: (callback: () => void, intervalMs: number) => unknown;
+
+  /** Cancels a handle previously returned by {@link IntervalScheduler.setInterval}. */
+  readonly clearInterval: (handle: unknown) => void;
+}
+
+/** Pause/resume controls shared by the repeating timing composables. */
+export interface PausableControls {
+  /**
+   * Whether the timer is logically running.
+   *
+   * On the server (without `runOnServer`) this reflects the requested state
+   * without starting a host timer, so server and client render the same
+   * initial value.
+   */
+  readonly isActive: Readonly<ShallowRef<boolean>>;
+
+  /** Stop ticking. Idempotent. */
+  readonly pause: () => void;
+
+  /** Start (or keep) ticking. Idempotent. */
+  readonly resume: () => void;
+}
+
+/** Options for {@link useIntervalFn}. */
+export interface UseIntervalFnOptions {
+  /**
+   * Start ticking as soon as the composable is created.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Invoke the callback synchronously whenever the timer (re)starts, in
+   * addition to every tick.
+   *
+   * @default false
+   */
+  readonly immediateCallback?: boolean;
+
+  /**
+   * Starts host timers when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering: the controls then track the
+   * requested state but never schedule work. Enable it for native, desktop,
+   * worker, and test runtimes whose scheduler is lifecycle-bound.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Owns the repeating timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: IntervalScheduler;
+}
+
+/** Options for {@link useInterval}. */
+export interface UseIntervalOptions<Controls extends boolean = false> extends UseIntervalFnOptions {
+  /**
+   * Return the full control object instead of the bare counter ref.
+   *
+   * @default false
+   */
+  readonly controls?: Controls;
+
+  /**
+   * Invoked after every increment with the new count.
+   *
+   * @default undefined
+   */
+  readonly callback?: (count: number) => void;
+}
+
+/** Counter and controls returned by `useInterval(ms, { controls: true })`. */
+export interface IntervalControls extends PausableControls {
+  /** Number of ticks since creation or the last {@link IntervalControls.reset}. */
+  readonly counter: Readonly<ShallowRef<number>>;
+
+  /** Reset the counter to zero without touching the timer. */
+  readonly reset: () => void;
+}
+
+const defaultScheduler: IntervalScheduler = {
+  setInterval: (callback, intervalMs) => globalThis.setInterval(callback, intervalMs),
+  clearInterval: (handle) => {
+    globalThis.clearInterval(handle as ReturnType<typeof setInterval>);
+  },
+};
+
+function resolveIntervalMs(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_INTERVAL_INVALID_DELAY] intervalMs must be finite and greater than zero; received ${String(value)}`,
+    );
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+/**
+ * Call a function on a fixed, pausable interval.
+ *
+ * `intervalMs` is reactive: while active, a change replaces the running timer
+ * with one using the new period. The timer is cleared when the owning
+ * reactive scope stops; call inside an active scope, or call `pause()`
+ * yourself.
+ *
+ * Server rendering is hydration-stable: without a browser `window` (and
+ * with {@link UseIntervalFnOptions.runOnServer} disabled) `isActive` reports
+ * the requested state but no host timer is created, so nothing leaks and
+ * the server snapshot matches the client's initial render.
+ *
+ * @example
+ * ```ts
+ * const { pause, resume, isActive } = useIntervalFn(() => poll(), 5_000);
+ * ```
+ *
+ * @param callback Invoked on every tick.
+ * @param intervalMs Reactive period in milliseconds; must be finite and
+ * greater than zero. Fractions are truncated.
+ * @param options Start, server, and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_INTERVAL_INVALID_DELAY` when the
+ * resolved period is invalid, synchronously at creation and whenever a timer
+ * would start.
+ * @returns Pause/resume controls.
+ */
+export function useIntervalFn(
+  callback: () => void,
+  intervalMs: MaybeRefOrGetter<number>,
+  options: UseIntervalFnOptions = {},
+): PausableControls {
+  const scheduler = options.scheduler ?? defaultScheduler;
+  const isActive = shallowRef(false);
+  let handle: unknown;
+  let running = false;
+
+  resolveIntervalMs(toValue(intervalMs));
+
+  const canSchedule = (): boolean =>
+    typeof window !== "undefined" || (options.runOnServer ?? false);
+
+  const clear = (): void => {
+    if (!running) return;
+    running = false;
+    scheduler.clearInterval(handle);
+    handle = undefined;
+  };
+
+  const start = (): void => {
+    const period = resolveIntervalMs(toValue(intervalMs));
+    clear();
+    if (!canSchedule()) return;
+    if (options.immediateCallback ?? false) callback();
+    if (!isActive.value) return;
+    running = true;
+    handle = scheduler.setInterval(callback, period);
+  };
+
+  const pause = (): void => {
+    isActive.value = false;
+    clear();
+  };
+
+  const resume = (): void => {
+    if (isActive.value) return;
+    isActive.value = true;
+    start();
+  };
+
+  watch(
+    () => toValue(intervalMs),
+    () => {
+      if (isActive.value) start();
+    },
+  );
+
+  if (options.immediate ?? true) resume();
+
+  tryOnScopeDispose(pause);
+
+  return { isActive, pause, resume };
+}
+
+/**
+ * Count interval ticks reactively.
+ *
+ * A thin wrapper over {@link useIntervalFn} whose state is a counter. Pass
+ * `{ controls: true }` to receive pause/resume/reset alongside the counter;
+ * the return type follows the literal flag.
+ *
+ * @example
+ * ```ts
+ * const ticks = useInterval(1_000); // Readonly<ShallowRef<number>>
+ * const { counter, pause, reset } = useInterval(1_000, { controls: true });
+ * ```
+ *
+ * @param intervalMs Reactive period in milliseconds.
+ * @param options Interval options plus the `controls` flag.
+ * @default intervalMs 1000
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_INTERVAL_INVALID_DELAY` for
+ * invalid periods (see {@link useIntervalFn}).
+ * @returns The counter ref, or the full controls when `controls` is `true`.
+ */
+export function useInterval(
+  intervalMs?: MaybeRefOrGetter<number>,
+  options?: UseIntervalOptions<false>,
+): Readonly<ShallowRef<number>>;
+export function useInterval(
+  intervalMs: MaybeRefOrGetter<number>,
+  options: UseIntervalOptions<true>,
+): IntervalControls;
+export function useInterval(
+  intervalMs: MaybeRefOrGetter<number> = 1_000,
+  options: UseIntervalOptions<boolean> = {},
+): Readonly<ShallowRef<number>> | IntervalControls {
+  const counter = shallowRef(0);
+  const controls = useIntervalFn(
+    () => {
+      counter.value += 1;
+      options.callback?.(counter.value);
+    },
+    intervalMs,
+    options,
+  );
+  if (options.controls !== true) return counter;
+  return {
+    ...controls,
+    counter,
+    reset: () => {
+      counter.value = 0;
+    },
+  };
+}

package/registry/files/use-list-format.ts

@@ -0,0 +1,85 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** Options for {@link useListFormat}. */
+export interface UseListFormatOptions extends Intl.ListFormatOptions {
+  /**
+   * Locale used for formatting. Pass it explicitly for hydration-stable
+   * server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+
+/** Reactive list formatting returned by {@link useListFormat}. */
+export interface ListFormatControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Cached formatter for the current locale and options. */
+  readonly formatter: ComputedRef<Intl.ListFormat>;
+
+  /** Formatted list, for example `"apples, pears, and plums"`. */
+  readonly formatted: ComputedRef<string>;
+
+  /**
+   * Format any list with the current formatter.
+   *
+   * @param items Items to join.
+   * @returns The formatted list.
+   */
+  readonly format: (items: Iterable<string>) => string;
+
+  /**
+   * Format any list into element and literal parts (for rich rendering).
+   *
+   * @param items Items to join.
+   * @returns The formatted parts.
+   */
+  readonly formatToParts: (
+    items: Iterable<string>,
+  ) => { type: "element" | "literal"; value: string }[];
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+/**
+ * Join strings into a locale-aware list with `Intl.ListFormat`
+ * (`"a, b, and c"`, `"a、b、c"`, `"a, b or c"`).
+ *
+ * Follows reactive items and options; formatters are cached per locale and
+ * option set through {@link useLocale}. Invalid options surface as the
+ * platform's `RangeError`. No listeners or timers are created.
+ *
+ * @example
+ * ```ts
+ * const { formatted } = useListFormat(names, { locale: "en", type: "disjunction" });
+ * ```
+ *
+ * @param items Reactive list of strings.
+ * @param options Reactive locale and `Intl.ListFormat` options.
+ * @default options {}
+ * @returns Reactive formatted output and formatting helpers.
+ */
+export function useListFormat(
+  items: MaybeRefOrGetter<readonly string[]>,
+  options: MaybeRefOrGetter<UseListFormatOptions> = {},
+): ListFormatControls {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const formatter = computed(() => {
+    const { locale: _locale, ...formatOptions } = toValue(options);
+    return localeControls.list(formatOptions);
+  });
+  return {
+    locale: localeControls.locale,
+    formatter,
+    formatted: computed(() => formatter.value.format(toValue(items))),
+    format: (list) => formatter.value.format(list),
+    formatToParts: (list) => formatter.value.formatToParts(list),
+  };
+}

package/registry/files/use-machine.ts

@@ -0,0 +1,171 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef, ShallowRef } from "vue";
+
+/** Guarded, effectful transition to `target`. */
+export interface MachineTransition<State extends string, Context> {
+  /** State entered when the transition is taken. */
+  readonly target: State;
+
+  /** Take the transition only when this returns `true`. */
+  readonly guard?: (context: Context) => boolean;
+
+  /** Produce the next context while transitioning. */
+  readonly action?: (context: Context) => Context;
+}
+
+/** One state of a {@link MachineConfig}. */
+export interface MachineStateNode<State extends string, Event extends string, Context> {
+  /**
+   * Transitions keyed by event: a target state name, one transition object,
+   * or a list of guarded transitions where the first passing guard wins.
+   */
+  readonly on?: {
+    readonly [Name in Event]?:
+      | State
+      | MachineTransition<State, Context>
+      | readonly MachineTransition<State, Context>[];
+  };
+
+  /** Called with the context after the machine enters this state. */
+  readonly entry?: (context: Context) => void;
+
+  /** Called with the context before the machine leaves this state. */
+  readonly exit?: (context: Context) => void;
+}
+
+/** Definition consumed by {@link useMachine}. */
+export interface MachineConfig<State extends string, Event extends string, Context> {
+  /** State the machine starts (and resets) in. */
+  readonly initial: NoInfer<State>;
+
+  /** Initial extended state. */
+  readonly context: Context;
+
+  /** Every state, keyed by name. */
+  readonly states: { readonly [Name in State]: MachineStateNode<NoInfer<State>, Event, Context> };
+}
+
+/** Reactive machine returned by {@link useMachine}. */
+export interface Machine<State extends string, Event extends string, Context> {
+  /** Current state name. */
+  readonly state: Readonly<ShallowRef<State>>;
+
+  /** Current extended state. */
+  readonly context: Readonly<ShallowRef<Context>>;
+
+  /** Events that would cause a transition from the current state right now. */
+  readonly nextEvents: ComputedRef<Event[]>;
+
+  /**
+   * Deliver an event.
+   *
+   * @returns Whether a transition was taken.
+   */
+  readonly send: (event: Event) => boolean;
+
+  /** Whether `event` would cause a transition right now (guards included). */
+  readonly can: (event: Event) => boolean;
+
+  /** Whether the current state is one of `states`. */
+  readonly matches: (...states: readonly State[]) => boolean;
+
+  /** Return to the initial state and context without running hooks. */
+  readonly reset: () => void;
+}
+
+/** Shallow ref typed through an unconstrained parameter, so literal unions stay intact. */
+function ownedRef<Value>(value: Value): ShallowRef<Value> {
+  return shallowRef(value);
+}
+
+/**
+ * Finite state machine with typed states, events, and targets.
+ *
+ * State names are inferred from the keys of `states`, event names from the
+ * keys of every `on` map, and every `target` (and `initial`) must name a
+ * declared state, so typos fail to compile. Transitions may carry guards
+ * (first passing guard wins) and actions that return the next context;
+ * `exit` runs on the old state before `entry` runs on the new one, and a
+ * self-transition runs both. Synchronous and free of globals: identical on
+ * server and client, nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const fetcher = useMachine({
+ *   initial: "idle",
+ *   context: { retries: 0 },
+ *   states: {
+ *     idle: { on: { FETCH: "loading" } },
+ *     loading: { on: { RESOLVE: "success", REJECT: "failure" } },
+ *     failure: {
+ *       on: {
+ *         RETRY: { target: "loading", guard: (c) => c.retries < 3, action: (c) => ({ retries: c.retries + 1 }) },
+ *       },
+ *     },
+ *     success: {},
+ *   },
+ * });
+ * fetcher.send("FETCH");
+ * ```
+ *
+ * @param config States, events, context, and hooks.
+ * @returns The reactive machine.
+ */
+export function useMachine<State extends string, Event extends string = never, Context = undefined>(
+  config: MachineConfig<State, Event, Context>,
+): Machine<State, Event, Context> {
+  const state = ownedRef<State>(config.initial);
+  const context = ownedRef<Context>(config.context);
+
+  const isTarget = (
+    option:
+      | State
+      | MachineTransition<State, Context>
+      | readonly MachineTransition<State, Context>[],
+  ): option is State => typeof option === "string";
+
+  const resolve = (event: Event): MachineTransition<State, Context> | undefined => {
+    const node: MachineStateNode<State, Event, Context> = config.states[state.value];
+    const option = node.on?.[event];
+    if (option === undefined) return undefined;
+    if (isTarget(option)) return { target: option };
+    const candidates: readonly MachineTransition<State, Context>[] = Array.isArray(option)
+      ? option
+      : [option];
+    return candidates.find((candidate) => candidate.guard?.(context.value) ?? true);
+  };
+
+  const send = (event: Event): boolean => {
+    const transition = resolve(event);
+    if (transition === undefined) return false;
+    const leaving: MachineStateNode<State, Event, Context> = config.states[state.value];
+    leaving.exit?.(context.value);
+    if (transition.action !== undefined) context.value = transition.action(context.value);
+    state.value = transition.target;
+    const entering: MachineStateNode<State, Event, Context> = config.states[transition.target];
+    entering.entry?.(context.value);
+    return true;
+  };
+
+  const can = (event: Event): boolean => resolve(event) !== undefined;
+
+  const nextEvents = computed(() => {
+    const node: MachineStateNode<State, Event, Context> = config.states[state.value];
+    const on = node.on ?? {};
+    const isEvent = (name: string): name is Event => name in on;
+    return Object.keys(on).filter(isEvent).filter(can);
+  });
+
+  return {
+    state,
+    context,
+    nextEvents,
+    send,
+    can,
+    matches: (...states) => states.some((candidate) => candidate === state.value),
+    reset: () => {
+      state.value = config.initial;
+      context.value = config.context;
+    },
+  };
+}

package/registry/files/use-map.ts

@@ -0,0 +1,145 @@
+import { computed, shallowReactive, shallowReadonly } from "vue";
+import type { ComputedRef } from "vue";
+
+/** Reactive map wrapper returned by {@link useMap}. */
+export interface MapControls<Key, Value> {
+  /**
+   * Read-only reactive view of the map. `get`, `has`, iteration, and `size`
+   * on this view are tracked per key. Values are stored shallowly.
+   */
+  readonly map: ReadonlyMap<Key, Value>;
+
+  /** Number of entries. */
+  readonly size: ComputedRef<number>;
+
+  /** Snapshot of the entries in insertion order. */
+  readonly entries: ComputedRef<readonly (readonly [Key, Value])[]>;
+
+  /**
+   * Read the value for `key`. Reactive when read inside an effect.
+   *
+   * @param key Key to read.
+   * @returns The value, or `undefined` when absent.
+   */
+  readonly get: (key: Key) => Value | undefined;
+
+  /**
+   * Whether `key` is present. Reactive when read inside an effect.
+   *
+   * @param key Key to test.
+   * @returns Whether the key exists.
+   */
+  readonly has: (key: Key) => boolean;
+
+  /**
+   * Store `value` under `key`.
+   *
+   * @param key Key to write.
+   * @param value Value to store.
+   */
+  readonly set: (key: Key, value: Value) => void;
+
+  /**
+   * Remove `key`.
+   *
+   * @param key Key to remove.
+   * @returns Whether an entry was removed.
+   */
+  readonly delete: (key: Key) => boolean;
+
+  /** Remove every entry. */
+  readonly clear: () => void;
+
+  /**
+   * Replace the value under `key` with the result of `updater`.
+   *
+   * @param key Key to update.
+   * @param updater Receives the current value (`undefined` when absent).
+   * @returns The stored value.
+   */
+  readonly update: (key: Key, updater: (previous: Value | undefined) => Value) => Value;
+
+  /**
+   * Return the value under `key`, inserting `create(key)` first when absent.
+   *
+   * @param key Key to read or insert.
+   * @param create Factory for a missing value.
+   * @returns The existing or inserted value.
+   */
+  readonly getOrInsert: (key: Key, create: (key: Key) => Value) => Value;
+
+  /** Restore the creation-time entries. */
+  readonly reset: () => void;
+}
+
+/**
+ * Narrow a `get` result using the matching `has` answer: when the key is
+ * present the result is a stored `Value`, even if that value is `undefined`.
+ */
+function isStored<Value>(value: Value | undefined, present: boolean): value is Value {
+  return present;
+}
+
+/**
+ * Create a reactive `Map` with typed helpers.
+ *
+ * Key and value types are inferred from the initial entries
+ * (`useMap([["a", 1]])` is a `Map<string, number>`); pass type arguments
+ * for an initially empty map. Reads through `get`, `has`, and `map` are
+ * tracked per key, so an effect reading one key does not re-run when an
+ * unrelated key changes. Values are stored as-is (not deeply reactive).
+ *
+ * Purely synchronous state: safe during server rendering (no host globals,
+ * no timers) and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const counts = useMap<string, number>();
+ * counts.update("clicks", (previous = 0) => previous + 1);
+ * ```
+ *
+ * @typeParam Key Key type, inferred from `initial`.
+ * @typeParam Value Value type, inferred from `initial`.
+ * @param initial Entries inserted at creation and restored by `reset`.
+ * @default initial []
+ * @returns The reactive map and its helpers.
+ */
+export function useMap<Key = unknown, Value = unknown>(
+  initial: Iterable<readonly [Key, Value]> = [],
+): MapControls<Key, Value> {
+  const baseline: readonly (readonly [Key, Value])[] = [...initial];
+  const map = shallowReactive(new Map<Key, Value>(baseline));
+
+  const reset = (): void => {
+    map.clear();
+    for (const [key, value] of baseline) map.set(key, value);
+  };
+
+  return {
+    map: shallowReadonly(map),
+    size: computed(() => map.size),
+    entries: computed(() => [...map.entries()]),
+    get: (key) => map.get(key),
+    has: (key) => map.has(key),
+    set: (key, value) => {
+      map.set(key, value);
+    },
+    delete: (key) => map.delete(key),
+    clear: () => {
+      map.clear();
+    },
+    update: (key, updater) => {
+      const next = updater(map.get(key));
+      map.set(key, next);
+      return next;
+    },
+    getOrInsert: (key, create) => {
+      const existing = map.get(key);
+      if (isStored(existing, map.has(key))) return existing;
+      const created = create(key);
+      map.set(key, created);
+      return created;
+    },
+    reset,
+  };
+}