@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-queue.ts

@@ -0,0 +1,197 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef } from "vue";
+
+/** What happens when an item arrives while a bounded queue is full. */
+export type QueueOverflowPolicy = "drop-oldest" | "reject";
+
+/** Options for {@link useQueue}. */
+export interface UseQueueOptions {
+  /**
+   * Maximum number of queued items. A positive integer, or
+   * `Number.POSITIVE_INFINITY` for an unbounded queue.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly capacity?: number;
+
+  /**
+   * Policy applied when an item arrives at capacity: `"drop-oldest"` evicts
+   * the head to make room, `"reject"` refuses the new item.
+   *
+   * @default "drop-oldest"
+   */
+  readonly overflow?: QueueOverflowPolicy;
+}
+
+/** Reactive first-in, first-out queue returned by {@link useQueue}. */
+export interface QueueControls<Item> {
+  /** Snapshot of the queued items, head first. Recomputed after every change. */
+  readonly items: ComputedRef<readonly Item[]>;
+
+  /** Number of queued items. */
+  readonly size: ComputedRef<number>;
+
+  /** Whether the queue holds no items. */
+  readonly isEmpty: ComputedRef<boolean>;
+
+  /**
+   * Read the head without removing it. Reactive when read inside an effect.
+   *
+   * @returns The head item, or `undefined` when empty.
+   */
+  readonly peek: () => Item | undefined;
+
+  /**
+   * Append items at the tail in argument order, applying the overflow policy.
+   *
+   * @param items Items to append.
+   * @returns How many of the given items were accepted.
+   */
+  readonly enqueue: (...items: Item[]) => number;
+
+  /**
+   * Remove and return the head.
+   *
+   * @returns The removed item, or `undefined` when empty.
+   */
+  readonly dequeue: () => Item | undefined;
+
+  /**
+   * Remove and return every queued item, head first.
+   *
+   * @returns The removed items.
+   */
+  readonly drain: () => Item[];
+
+  /** Remove every item. */
+  readonly clear: () => void;
+}
+
+/** Compact the backing buffer once this many dequeued slots accumulate. */
+const COMPACT_THRESHOLD = 32;
+
+function validateCapacity(capacity: number): number {
+  if (capacity === Number.POSITIVE_INFINITY) return capacity;
+  if (!Number.isSafeInteger(capacity) || capacity < 1) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_QUEUE_INVALID_CAPACITY] capacity must be a positive integer or Infinity; received ${String(capacity)}`,
+    );
+  }
+  return capacity;
+}
+
+/**
+ * Create a typed reactive FIFO queue.
+ *
+ * Dequeueing is amortized O(1): the head advances through a backing buffer
+ * that is compacted only after enough slots have been consumed, so large
+ * queues never pay for `Array.prototype.shift`. Reactivity is driven by a
+ * single version counter; `items`, `size`, `isEmpty`, and `peek` all
+ * re-evaluate after each mutation.
+ *
+ * Purely synchronous state: safe during server rendering (no host globals,
+ * no timers) and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const jobs = useQueue<string>([], { capacity: 100, overflow: "reject" });
+ * jobs.enqueue("a", "b");
+ * jobs.dequeue(); // "a"
+ * ```
+ *
+ * @typeParam Item Queued item type, inferred from `initial` when given.
+ * @param initial Items enqueued at creation, head first (overflow applies).
+ * @param options Capacity and overflow policy.
+ * @default initial []
+ * @default options {}
+ * @throws {RangeError} `[VIZE_COMPOSE_QUEUE_INVALID_CAPACITY]` when `capacity`
+ * is not a positive integer or `Infinity`.
+ * @returns The reactive queue and its controls.
+ */
+export function useQueue<Item>(
+  initial: Iterable<Item> = [],
+  options: UseQueueOptions = {},
+): QueueControls<Item> {
+  const capacity = validateCapacity(options.capacity ?? Number.POSITIVE_INFINITY);
+  const overflow = options.overflow ?? "drop-oldest";
+  let buffer: Item[] = [];
+  let head = 0;
+  const version = shallowRef(0);
+  const touch = (): void => {
+    version.value += 1;
+  };
+  const length = (): number => buffer.length - head;
+
+  const compact = (): void => {
+    if (head >= COMPACT_THRESHOLD && head * 2 >= buffer.length) {
+      buffer = buffer.slice(head);
+      head = 0;
+    }
+  };
+
+  const append = (items: readonly Item[]): number => {
+    let accepted = 0;
+    for (const item of items) {
+      if (length() >= capacity) {
+        if (overflow === "reject") continue;
+        head += 1;
+      }
+      buffer.push(item);
+      accepted += 1;
+    }
+    compact();
+    return accepted;
+  };
+
+  append([...initial]);
+
+  const items = computed<readonly Item[]>(() => {
+    void version.value;
+    return buffer.slice(head);
+  });
+  const size = computed(() => {
+    void version.value;
+    return length();
+  });
+
+  return {
+    items,
+    size,
+    isEmpty: computed(() => size.value === 0),
+    peek: () => {
+      void version.value;
+      return length() > 0 ? buffer[head] : undefined;
+    },
+    enqueue: (...added) => {
+      const accepted = append(added);
+      if (accepted > 0) touch();
+      return accepted;
+    },
+    dequeue: () => {
+      if (length() === 0) return undefined;
+      const item = buffer[head];
+      head += 1;
+      if (head === buffer.length) {
+        buffer = [];
+        head = 0;
+      } else {
+        compact();
+      }
+      touch();
+      return item;
+    },
+    drain: () => {
+      const drained = buffer.slice(head);
+      buffer = [];
+      head = 0;
+      if (drained.length > 0) touch();
+      return drained;
+    },
+    clear: () => {
+      if (length() === 0) return;
+      buffer = [];
+      head = 0;
+      touch();
+    },
+  };
+}

package/registry/files/use-raf-fn.ts

@@ -0,0 +1,176 @@
+import { shallowRef, toValue } from "vue";
+import type { MaybeRefOrGetter } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { PausableControls } from "./use-interval.ts";
+
+/**
+ * Animation-frame host used by {@link useRafFn}.
+ *
+ * Implement this interface to drive frames from a deterministic test clock,
+ * a native display link, or an offscreen renderer.
+ */
+export interface FrameScheduler {
+  /** Requests one frame callback and returns its opaque cancellation handle. */
+  readonly requestAnimationFrame: (callback: (timestamp: number) => void) => unknown;
+
+  /** Cancels a handle previously returned by {@link FrameScheduler.requestAnimationFrame}. */
+  readonly cancelAnimationFrame: (handle: unknown) => void;
+}
+
+/** Timing information passed to every {@link useRafFn} callback. */
+export interface RafFrame {
+  /** Milliseconds since the previous delivered frame (`0` for the first). */
+  readonly delta: number;
+
+  /** High-resolution frame timestamp supplied by the host. */
+  readonly timestamp: number;
+}
+
+/** Options for {@link useRafFn}. */
+export interface UseRafFnOptions {
+  /**
+   * Start the frame loop as soon as the composable is created.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Maximum callback rate in frames per second. Frames arriving sooner than
+   * `1000 / fpsLimit` ms after the last delivered frame are skipped.
+   * `undefined` delivers every frame. Reactive.
+   *
+   * @default undefined
+   */
+  readonly fpsLimit?: MaybeRefOrGetter<number | undefined>;
+
+  /**
+   * Deliver a single frame and then pause.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+
+  /**
+   * Requests frames when no browser `window` is available, for example from
+   * a native or offscreen frame host passed as `scheduler`.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Frame host. When omitted, `globalThis.requestAnimationFrame` is used if
+   * it exists; without one (server rendering, workers without frames) the
+   * loop only tracks its requested state.
+   *
+   * @default globalThis animation-frame functions when available
+   */
+  readonly scheduler?: FrameScheduler;
+}
+
+function resolveHost(scheduler: FrameScheduler | undefined): FrameScheduler | undefined {
+  if (scheduler !== undefined) return scheduler;
+  if (typeof globalThis.requestAnimationFrame !== "function") return undefined;
+  return {
+    requestAnimationFrame: (callback) => globalThis.requestAnimationFrame(callback),
+    cancelAnimationFrame: (handle) => {
+      globalThis.cancelAnimationFrame(handle as number);
+    },
+  };
+}
+
+/**
+ * Run a callback on every animation frame, with pause/resume controls and an
+ * optional frame-rate cap.
+ *
+ * The host is resolved lazily on `resume()`, so importing and calling this
+ * during server rendering is safe: without a browser `window` (and without
+ * {@link UseRafFnOptions.runOnServer}), or without any frame host,
+ * `isActive` reports the requested state and no callbacks run, matching the
+ * client's initial render. The pending frame is cancelled when the owning reactive scope
+ * stops.
+ *
+ * @example
+ * ```ts
+ * const { pause } = useRafFn(({ delta }) => step(delta), { fpsLimit: 30 });
+ * ```
+ *
+ * @param callback Invoked with frame timing for every delivered frame.
+ * @param options Start, rate-limit, and host policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_RAF_INVALID_FPS_LIMIT` when a
+ * resolved `fpsLimit` is not finite and greater than zero.
+ * @returns Pause/resume controls.
+ */
+export function useRafFn(
+  callback: (frame: RafFrame) => void,
+  options: UseRafFnOptions = {},
+): PausableControls {
+  const isActive = shallowRef(false);
+  let host: FrameScheduler | undefined;
+  let handle: unknown;
+  let requested = false;
+  let previous: number | undefined;
+
+  const readInterval = (): number => {
+    const limit = toValue(options.fpsLimit);
+    if (limit === undefined) return 0;
+    if (!Number.isFinite(limit) || limit <= 0) {
+      throw new RangeError(
+        `[VIZE_COMPOSE_RAF_INVALID_FPS_LIMIT] fpsLimit must be finite and greater than zero; received ${String(limit)}`,
+      );
+    }
+    return 1_000 / limit;
+  };
+
+  readInterval();
+
+  const request = (): void => {
+    if (host === undefined) return;
+    requested = true;
+    handle = host.requestAnimationFrame(loop);
+  };
+
+  function loop(timestamp: number): void {
+    requested = false;
+    if (!isActive.value) return;
+    previous ??= timestamp;
+    const delta = timestamp - previous;
+    const interval = readInterval();
+    if (interval > 0 && delta > 0 && delta < interval) {
+      request();
+      return;
+    }
+    previous = timestamp;
+    callback({ delta, timestamp });
+    if (options.once ?? false) {
+      pause();
+      return;
+    }
+    request();
+  }
+
+  const pause = (): void => {
+    isActive.value = false;
+    if (requested && host !== undefined) host.cancelAnimationFrame(handle);
+    requested = false;
+    handle = undefined;
+  };
+
+  const resume = (): void => {
+    if (isActive.value) return;
+    isActive.value = true;
+    previous = undefined;
+    if (typeof window === "undefined" && !(options.runOnServer ?? false)) return;
+    host ??= resolveHost(options.scheduler);
+    request();
+  };
+
+  if (options.immediate ?? true) resume();
+
+  tryOnScopeDispose(pause);
+
+  return { isActive, pause, resume };
+}

package/registry/files/use-relative-time-format.ts

@@ -0,0 +1,201 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** Units selected by {@link selectRelativeTimeUnit}. */
+export type RelativeTimeUnitSelection =
+  | "second"
+  | "minute"
+  | "hour"
+  | "day"
+  | "week"
+  | "month"
+  | "year";
+
+/** A signed amount in one relative-time unit. */
+export interface RelativeTimeValue {
+  /** Signed, rounded amount; negative values are in the past. */
+  readonly value: number;
+
+  /** Unit the amount is expressed in. */
+  readonly unit: RelativeTimeUnitSelection;
+}
+
+/** Options for {@link useRelativeTimeFormat}. */
+export interface UseRelativeTimeFormatOptions extends Intl.RelativeTimeFormatOptions {
+  /**
+   * Locale used for formatting. Pass it explicitly for hydration-stable
+   * server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+
+/** Options for {@link RelativeTimeFormatControls.formatFrom}. */
+export interface RelativeTimeFromOptions {
+  /**
+   * Reference time in Unix milliseconds. Pass it explicitly to keep server
+   * and client output identical.
+   *
+   * @default Date.now()
+   */
+  readonly now?: number;
+}
+
+/** Reactive relative-time formatting returned by {@link useRelativeTimeFormat}. */
+export interface RelativeTimeFormatControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Cached formatter for the current locale and options. */
+  readonly formatter: ComputedRef<Intl.RelativeTimeFormat>;
+
+  /** Formatted `value` in `unit`, or `""` while either is missing. */
+  readonly formatted: ComputedRef<string>;
+
+  /**
+   * Format an amount in a unit.
+   *
+   * @param value Signed amount; negative is in the past.
+   * @param unit Relative-time unit.
+   * @returns The formatted string.
+   */
+  readonly format: (value: number, unit: Intl.RelativeTimeFormatUnit) => string;
+
+  /**
+   * Format an amount in a unit into parts.
+   *
+   * @param value Signed amount.
+   * @param unit Relative-time unit.
+   * @returns The formatted parts.
+   */
+  readonly formatToParts: (
+    value: number,
+    unit: Intl.RelativeTimeFormatUnit,
+  ) => Intl.RelativeTimeFormatPart[];
+
+  /**
+   * Format a signed millisecond difference using the best-fitting unit
+   * (see {@link selectRelativeTimeUnit}).
+   *
+   * @param diffMs Signed difference; negative is in the past.
+   * @returns The formatted string.
+   */
+  readonly formatDiff: (diffMs: number) => string;
+
+  /**
+   * Format a date relative to a reference time using the best-fitting unit.
+   *
+   * @param date Date or Unix milliseconds.
+   * @param options Reference time.
+   * @default options {}
+   * @returns The formatted string.
+   */
+  readonly formatFrom: (date: Date | number, options?: RelativeTimeFromOptions) => string;
+}
+
+// Literal millisecond values keep module evaluation free of computation, so
+// bundlers can drop this module entirely when it is unused.
+const SECOND = 1000;
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+const WEEK = 604_800_000;
+/** Gregorian average month: 30.436875 days. */
+const MONTH = 2_629_746_000;
+/** Gregorian average year: 365.2425 days. */
+const YEAR = 31_556_952_000;
+
+const thresholds: readonly (readonly [number, number, RelativeTimeUnitSelection])[] = [
+  [MINUTE, SECOND, "second"],
+  [HOUR, MINUTE, "minute"],
+  [DAY, HOUR, "hour"],
+  [WEEK, DAY, "day"],
+  [MONTH, WEEK, "week"],
+  [YEAR, MONTH, "month"],
+];
+
+/**
+ * Pick the largest unit that expresses a millisecond difference as a
+ * non-zero rounded amount: seconds below a minute, minutes below an hour,
+ * hours below a day, days below a week, weeks below a month, months below
+ * a year, and years otherwise (Gregorian average month/year lengths).
+ *
+ * @param diffMs Signed difference; negative is in the past.
+ * @returns The rounded amount and its unit.
+ * @throws {RangeError} `[VIZE_COMPOSE_RELATIVE_TIME_INVALID_DIFF]` for a
+ * non-finite difference.
+ */
+export function selectRelativeTimeUnit(diffMs: number): RelativeTimeValue {
+  if (!Number.isFinite(diffMs)) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_RELATIVE_TIME_INVALID_DIFF] the difference must be finite; received ${String(diffMs)}`,
+    );
+  }
+  const magnitude = Math.abs(diffMs);
+  for (const [limit, size, unit] of thresholds) {
+    if (magnitude < limit) return { value: Math.round(diffMs / size) + 0, unit };
+  }
+  return { value: Math.round(diffMs / YEAR) + 0, unit: "year" };
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+/**
+ * Format relative times ("in 3 days", "yesterday") with `Intl.RelativeTimeFormat`.
+ *
+ * A pure formatting wrapper: it owns no clock or timer, so it never
+ * re-renders on its own and stays deterministic during server rendering
+ * (pair it with a clock composable for live "time ago" labels). The
+ * formatter follows the reactive options and is cached per locale and
+ * option set through {@link useLocale}; invalid options surface as the
+ * platform's `RangeError`.
+ *
+ * @example
+ * ```ts
+ * const { formatted } = useRelativeTimeFormat(-1, "day", { locale: "en", numeric: "auto" });
+ * formatted.value; // "yesterday"
+ * ```
+ *
+ * @param value Reactive signed amount; `null`/`undefined` format as `""`.
+ * @param unit Reactive unit.
+ * @param options Reactive locale and `Intl.RelativeTimeFormat` options.
+ * @default options {}
+ * @returns Reactive formatted output and formatting helpers.
+ */
+export function useRelativeTimeFormat(
+  value: MaybeRefOrGetter<number | null | undefined>,
+  unit: MaybeRefOrGetter<Intl.RelativeTimeFormatUnit>,
+  options: MaybeRefOrGetter<UseRelativeTimeFormatOptions> = {},
+): RelativeTimeFormatControls {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const formatter = computed(() => {
+    const { locale: _locale, ...formatOptions } = toValue(options);
+    return localeControls.relativeTime(formatOptions);
+  });
+  const formatDiff = (diffMs: number): string => {
+    const selected = selectRelativeTimeUnit(diffMs);
+    return formatter.value.format(selected.value, selected.unit);
+  };
+  return {
+    locale: localeControls.locale,
+    formatter,
+    formatted: computed(() => {
+      const current = toValue(value);
+      return current === null || current === undefined
+        ? ""
+        : formatter.value.format(current, toValue(unit));
+    }),
+    format: (amount, amountUnit) => formatter.value.format(amount, amountUnit),
+    formatToParts: (amount, amountUnit) => formatter.value.formatToParts(amount, amountUnit),
+    formatDiff,
+    formatFrom: (date, fromOptions = {}) => {
+      const time = date instanceof Date ? date.getTime() : date;
+      return formatDiff(time - (fromOptions.now ?? Date.now()));
+    },
+  };
+}