@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/use-time-ago.ts

@@ -0,0 +1,276 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import type { IntervalScheduler, PausableControls } from "./use-interval.ts";
+import { useTimestamp } from "./use-now.ts";
+
+/** Calendar units {@link formatTimeAgo} can express a distance in. */
+export type TimeAgoUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+
+/** Date input accepted by the time formatting helpers. */
+export type TimeAgoInput = Date | number | string;
+
+/** Options for {@link formatTimeAgo}. */
+export interface FormatTimeAgoOptions {
+  /**
+   * BCP 47 locale(s) for `Intl.RelativeTimeFormat`. Defaults to a fixed
+   * locale (not the host default) so server and client output agree.
+   *
+   * @default "en"
+   */
+  readonly locale?: string | readonly string[];
+
+  /**
+   * `"auto"` allows phrases such as "yesterday" and "now"; `"always"` keeps
+   * numeric output such as "1 day ago".
+   *
+   * @default "auto"
+   */
+  readonly numeric?: "always" | "auto";
+
+  /**
+   * Length of the unit wording.
+   *
+   * @default "long"
+   */
+  readonly style?: "long" | "short" | "narrow";
+
+  /**
+   * Units allowed in the output, in any order. The largest allowed unit
+   * that fits the distance wins; smaller distances use the smallest unit.
+   *
+   * @default all units from second to year
+   */
+  readonly units?: readonly TimeAgoUnit[];
+
+  /**
+   * How a fractional unit count becomes an integer.
+   *
+   * @default "round"
+   */
+  readonly rounding?: "round" | "floor" | "ceil";
+
+  /**
+   * Distances below this many milliseconds are reported as zero of the
+   * smallest unit ("now" with `numeric: "auto"`).
+   *
+   * @default 0
+   */
+  readonly justNowMs?: number;
+
+  /**
+   * Distances of at least this many milliseconds are delegated to
+   * {@link FormatTimeAgoOptions.fullDateFormatter}.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly maxMs?: number;
+
+  /**
+   * Formats dates beyond {@link FormatTimeAgoOptions.maxMs}.
+   *
+   * @default medium date style in UTC for the configured locale
+   */
+  readonly fullDateFormatter?: (date: Date) => string;
+}
+
+/** Options for {@link useTimeAgo}. */
+export interface UseTimeAgoOptions<Controls extends boolean = false> extends Omit<
+  FormatTimeAgoOptions,
+  "locale"
+> {
+  /**
+   * Reactive BCP 47 locale(s). Pair with `useLocale()` to follow the user.
+   *
+   * @default "en"
+   */
+  readonly locale?: MaybeRefOrGetter<string | readonly string[]>;
+
+  /**
+   * How often the relative phrase is recomputed, in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly updateIntervalMs?: MaybeRefOrGetter<number>;
+
+  /**
+   * Clock source returning Unix epoch milliseconds.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+
+  /**
+   * Hydration-stable "now" used for the first render on server and client.
+   *
+   * @default undefined (read the clock immediately)
+   */
+  readonly initialNow?: number;
+
+  /**
+   * Starts host timers when no browser `window` is available.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Repeating timer host.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: IntervalScheduler;
+
+  /**
+   * Return the full control object instead of the bare phrase ref.
+   *
+   * @default false
+   */
+  readonly controls?: Controls;
+}
+
+/** Phrase and controls returned by `useTimeAgo(time, { controls: true })`. */
+export interface TimeAgoControls extends PausableControls {
+  /** Localized relative phrase such as "3 minutes ago". */
+  readonly timeAgo: ComputedRef<string>;
+
+  /** The reference "now" in Unix epoch milliseconds. */
+  readonly now: Readonly<ShallowRef<number>>;
+}
+
+const unitMs: Readonly<Record<TimeAgoUnit, number>> = {
+  second: 1_000,
+  minute: 60_000,
+  hour: 3_600_000,
+  day: 86_400_000,
+  week: 604_800_000,
+  month: 2_592_000_000,
+  year: 31_536_000_000,
+};
+
+const allUnits: readonly TimeAgoUnit[] = [
+  "second",
+  "minute",
+  "hour",
+  "day",
+  "week",
+  "month",
+  "year",
+];
+
+function toEpochMs(input: TimeAgoInput): number {
+  const value = input instanceof Date ? input.getTime() : new Date(input).getTime();
+  if (Number.isNaN(value)) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_TIME_AGO_INVALID_DATE] expected a valid date; received ${String(input)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Format the distance between two instants as a localized relative phrase.
+ *
+ * Pure and deterministic: the output depends only on the arguments (the
+ * locale defaults to `"en"`, never the host default), which makes it safe
+ * for server rendering and hydration.
+ *
+ * @example
+ * ```ts
+ * formatTimeAgo(Date.UTC(2026, 0, 1), Date.UTC(2026, 0, 2)); // "yesterday"
+ * formatTimeAgo(0, 90_000, { numeric: "always" }); // "2 minutes ago"
+ * ```
+ *
+ * @param time Instant being described.
+ * @param now Reference instant.
+ * @param options Locale, wording, unit, and threshold policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TIME_AGO_INVALID_DATE` when
+ * either input is not a valid date, and `RangeError` from `Intl` for invalid
+ * locales.
+ * @returns The localized phrase.
+ */
+export function formatTimeAgo(
+  time: TimeAgoInput,
+  now: TimeAgoInput,
+  options: FormatTimeAgoOptions = {},
+): string {
+  const target = toEpochMs(time);
+  const diff = target - toEpochMs(now);
+  const distance = Math.abs(diff);
+  const locales =
+    typeof options.locale === "string" ? options.locale : [...(options.locale ?? ["en"])];
+
+  if (distance >= (options.maxMs ?? Number.POSITIVE_INFINITY)) {
+    const date = new Date(target);
+    return options.fullDateFormatter === undefined
+      ? new Intl.DateTimeFormat(locales, { dateStyle: "medium", timeZone: "UTC" }).format(date)
+      : options.fullDateFormatter(date);
+  }
+
+  const allowed = allUnits.filter((unit) => (options.units ?? allUnits).includes(unit));
+  const smallest = allowed[0] ?? "second";
+  let unit = smallest;
+  for (const candidate of allowed) if (distance >= unitMs[candidate]) unit = candidate;
+
+  // Zero distance counts as past (`-0`), so "0 seconds ago" rather than "in 0 seconds".
+  const round = Math[options.rounding ?? "round"];
+  const magnitude = distance < (options.justNowMs ?? 0) ? 0 : round(distance / unitMs[unit]);
+  const formatter = new Intl.RelativeTimeFormat(locales, {
+    numeric: options.numeric ?? "auto",
+    style: options.style ?? "long",
+  });
+  return formatter.format(diff <= 0 ? -magnitude : magnitude, magnitude === 0 ? smallest : unit);
+}
+
+/**
+ * Reactive localized "time ago" phrase that refreshes on an interval.
+ *
+ * Combines {@link formatTimeAgo} with a pausable clock. For SSR, inject
+ * `initialNow` (the server render time) and a fixed `locale`: both sides
+ * then produce the same phrase and the client clock takes over on its first
+ * tick. No timer runs on the server; the timer stops with the owning scope.
+ *
+ * @example
+ * ```ts
+ * const phrase = useTimeAgo(() => post.value.createdAt, { locale: useLocale().locale });
+ * ```
+ *
+ * @param time Reactive instant being described.
+ * @param options Formatting, cadence, clock, and SSR policy.
+ * @default options {}
+ * @throws `RangeError` on read for invalid dates or locales, and for invalid
+ * update intervals at creation.
+ * @returns The phrase ref, or the full controls when `controls` is `true`.
+ */
+export function useTimeAgo(
+  time: MaybeRefOrGetter<TimeAgoInput>,
+  options?: UseTimeAgoOptions<false>,
+): ComputedRef<string>;
+export function useTimeAgo(
+  time: MaybeRefOrGetter<TimeAgoInput>,
+  options: UseTimeAgoOptions<true>,
+): TimeAgoControls;
+export function useTimeAgo(
+  time: MaybeRefOrGetter<TimeAgoInput>,
+  options: UseTimeAgoOptions<boolean> = {},
+): ComputedRef<string> | TimeAgoControls {
+  const { timestamp, pause, resume, isActive } = useTimestamp({
+    interval: options.updateIntervalMs ?? 30_000,
+    controls: true,
+    runOnServer: options.runOnServer ?? false,
+    ...(options.now === undefined ? {} : { now: options.now }),
+    ...(options.initialNow === undefined ? {} : { initial: options.initialNow }),
+    ...(options.scheduler === undefined ? {} : { scheduler: options.scheduler }),
+  });
+
+  const timeAgo = computed(() =>
+    formatTimeAgo(toValue(time), timestamp.value, {
+      ...options,
+      locale: toValue(options.locale) ?? "en",
+    }),
+  );
+
+  if (options.controls !== true) return timeAgo;
+  return { timeAgo, now: timestamp, pause, resume, isActive };
+}

package/registry/files/use-timeout.ts

@@ -0,0 +1,218 @@
+import { computed, shallowRef, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Options for {@link useTimeoutFn}. */
+export interface UseTimeoutFnOptions {
+  /**
+   * Start the timer as soon as the composable is created. Only available
+   * for callbacks without arguments; pass `false` to schedule a callback
+   * that takes arguments through {@link TimeoutFnControls.start}.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Starts host timers when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering: `isPending` then reports the
+   * requested state but no timer is created and the callback never runs.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Owns the single-shot timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+
+/** Controls returned by {@link useTimeoutFn}. */
+export interface TimeoutFnControls<Args extends readonly unknown[]> {
+  /** Whether a call is scheduled and has not fired or been stopped yet. */
+  readonly isPending: Readonly<ShallowRef<boolean>>;
+
+  /**
+   * (Re)start the timer. A pending call is replaced, and the callback later
+   * receives exactly these arguments.
+   */
+  readonly start: (...args: Args) => void;
+
+  /**
+   * Cancel the pending call.
+   *
+   * @returns Whether a pending call was cancelled.
+   */
+  readonly stop: () => boolean;
+}
+
+/** Options for {@link useTimeout}. */
+export interface UseTimeoutOptions<Controls extends boolean = false> extends UseTimeoutFnOptions {
+  /**
+   * Return the full control object instead of the bare readiness ref.
+   *
+   * @default false
+   */
+  readonly controls?: Controls;
+
+  /**
+   * Invoked when the timeout elapses.
+   *
+   * @default undefined
+   */
+  readonly callback?: () => void;
+}
+
+/** Readiness and controls returned by `useTimeout(ms, { controls: true })`. */
+export interface TimeoutControls extends TimeoutFnControls<[]> {
+  /** `true` once the timer elapsed or was stopped, `false` while pending. */
+  readonly ready: ComputedRef<boolean>;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+function resolveDelayMs(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_TIMEOUT_INVALID_DELAY] delayMs must be finite and at least zero; received ${String(value)}`,
+    );
+  }
+  return Math.trunc(value);
+}
+
+/**
+ * Call a function once after a delay, with restart and cancel controls.
+ *
+ * The typing is arity-aware: a zero-argument callback may start
+ * immediately, while a callback with parameters requires
+ * `{ immediate: false }` so it can only ever run with arguments supplied to
+ * `start(...)`. `delayMs` is reactive and read on every `start`.
+ *
+ * Server rendering is hydration-stable: without a browser `window` (and with
+ * {@link UseTimeoutFnOptions.runOnServer} disabled) `isPending` reports the
+ * requested state but no timer is created. A pending timer is cleared when
+ * the owning reactive scope stops.
+ *
+ * @example
+ * ```ts
+ * const { start, stop } = useTimeoutFn((id: string) => save(id), 500, { immediate: false });
+ * start("draft-1");
+ * ```
+ *
+ * @param callback Invoked once the delay elapses.
+ * @param delayMs Reactive delay in milliseconds; finite and at least zero.
+ * @param options Start, server, and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TIMEOUT_INVALID_DELAY` for invalid
+ * delays, synchronously at creation and on every `start`.
+ * @returns Pending flag and start/stop controls.
+ */
+export function useTimeoutFn(
+  callback: () => void,
+  delayMs: MaybeRefOrGetter<number>,
+  options?: UseTimeoutFnOptions,
+): TimeoutFnControls<[]>;
+export function useTimeoutFn<Args extends readonly unknown[]>(
+  callback: (...args: Args) => void,
+  delayMs: MaybeRefOrGetter<number>,
+  options: UseTimeoutFnOptions & { readonly immediate: false },
+): TimeoutFnControls<Args>;
+export function useTimeoutFn(
+  callback: (...args: readonly unknown[]) => void,
+  delayMs: MaybeRefOrGetter<number>,
+  options: UseTimeoutFnOptions = {},
+): TimeoutFnControls<readonly unknown[]> {
+  const scheduler = options.scheduler ?? defaultScheduler;
+  const isPending = shallowRef(false);
+  let handle: unknown;
+  let scheduled = false;
+
+  resolveDelayMs(toValue(delayMs));
+
+  const clear = (): void => {
+    if (!scheduled) return;
+    scheduled = false;
+    scheduler.clearTimeout(handle);
+    handle = undefined;
+  };
+
+  const stop = (): boolean => {
+    const wasPending = isPending.value;
+    isPending.value = false;
+    clear();
+    return wasPending;
+  };
+
+  const start = (...args: readonly unknown[]): void => {
+    const delay = resolveDelayMs(toValue(delayMs));
+    clear();
+    isPending.value = true;
+    if (typeof window === "undefined" && !(options.runOnServer ?? false)) return;
+    scheduled = true;
+    handle = scheduler.setTimeout(() => {
+      scheduled = false;
+      handle = undefined;
+      isPending.value = false;
+      callback(...args);
+    }, delay);
+  };
+
+  // Only the zero-argument overload may start immediately.
+  if (options.immediate ?? true) start();
+
+  tryOnScopeDispose(() => {
+    stop();
+  });
+
+  return { isPending, start, stop };
+}
+
+/**
+ * Reactive "has the delay elapsed yet?" flag.
+ *
+ * A wrapper over {@link useTimeoutFn}. Pass `{ controls: true }` to receive
+ * start/stop alongside the flag; the return type follows the literal flag.
+ * Stopping a pending timer marks it ready.
+ *
+ * @example
+ * ```ts
+ * const ready = useTimeout(300); // ComputedRef<boolean>
+ * const { ready: done, start } = useTimeout(300, { controls: true, immediate: false });
+ * ```
+ *
+ * @param delayMs Reactive delay in milliseconds.
+ * @param options Timeout options plus the `controls` flag.
+ * @default delayMs 1000
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TIMEOUT_INVALID_DELAY` for invalid
+ * delays (see {@link useTimeoutFn}).
+ * @returns The readiness ref, or the full controls when `controls` is `true`.
+ */
+export function useTimeout(
+  delayMs?: MaybeRefOrGetter<number>,
+  options?: UseTimeoutOptions<false>,
+): ComputedRef<boolean>;
+export function useTimeout(
+  delayMs: MaybeRefOrGetter<number>,
+  options: UseTimeoutOptions<true>,
+): TimeoutControls;
+export function useTimeout(
+  delayMs: MaybeRefOrGetter<number> = 1_000,
+  options: UseTimeoutOptions<boolean> = {},
+): ComputedRef<boolean> | TimeoutControls {
+  const controls = useTimeoutFn(() => options.callback?.(), delayMs, options);
+  const ready = computed(() => !controls.isPending.value);
+  if (options.controls !== true) return ready;
+  return { ...controls, ready };
+}

package/registry/files/use-toggle.ts

@@ -0,0 +1,54 @@
+import { shallowRef } from "vue";
+import type { Ref } from "vue";
+
+/** Reactive controls returned by {@link useToggle}. */
+export interface ToggleControls {
+  /**
+   * Owned boolean state.
+   *
+   * Deliberately writable: unlike the derived views elsewhere in this
+   * package, the toggle owns its state, so assigning the ref directly (for
+   * example through `v-model`) is equivalent to calling
+   * {@link ToggleControls.toggle} with a forced value.
+   */
+  readonly state: Ref<boolean>;
+
+  /**
+   * Invert the state, or force it to `force` when the argument is given.
+   * Passing an explicit `undefined` behaves like passing no argument.
+   *
+   * @param force Value assigned instead of inverting.
+   * @returns The state after the change.
+   */
+  readonly toggle: (force?: boolean) => boolean;
+}
+
+/**
+ * Create owned boolean state with an inverting control.
+ *
+ * Purely synchronous state: safe during server rendering (no browser
+ * globals, no timers) and nothing to dispose, so it works inside and
+ * outside reactive scopes alike.
+ *
+ * @example
+ * ```ts
+ * const { state: open, toggle } = useToggle();
+ * toggle(); // true
+ * toggle(false); // false
+ * open.value; // false
+ * ```
+ *
+ * @param initial State before the first toggle.
+ * @default initial false
+ * @returns The writable state and its toggle control.
+ */
+export function useToggle(initial = false): ToggleControls {
+  const state = shallowRef(initial);
+
+  const toggle = (force?: boolean): boolean => {
+    state.value = force ?? !state.value;
+    return state.value;
+  };
+
+  return { state, toggle };
+}