@vizejs/composable 0.426.3 → 0.427.0

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

@@ -0,0 +1,281 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+/** Date input accepted by {@link formatDate} and {@link useDateFormat}. */
+export type DateFormatInput = Date | number | string;
+
+/**
+ * Tokens understood by the pattern form of {@link formatDate}.
+ *
+ * | Token | Output | Token | Output |
+ * | --- | --- | --- | --- |
+ * | `YYYY` | 2026 | `YY` | 26 |
+ * | `M` / `MM` | 1 / 01 | `MMM` / `MMMM` | Jan / January (localized) |
+ * | `D` / `DD` | 5 / 05 | `d` | 0–6, Sunday is 0 |
+ * | `dd` / `ddd` / `dddd` | S / Sun / Sunday (localized) | `H` / `HH` | 0–23 |
+ * | `h` / `hh` | 1–12 | `m` / `mm`, `s` / `ss` | minutes, seconds |
+ * | `SSS` | milliseconds | `A` / `a` | AM / am (localized) |
+ * | `Z` / `ZZ` | +09:00 / +0900 | `[text]` | literal text |
+ */
+export type DateFormatToken =
+  | "YYYY"
+  | "YY"
+  | "M"
+  | "MM"
+  | "MMM"
+  | "MMMM"
+  | "D"
+  | "DD"
+  | "d"
+  | "dd"
+  | "ddd"
+  | "dddd"
+  | "H"
+  | "HH"
+  | "h"
+  | "hh"
+  | "m"
+  | "mm"
+  | "s"
+  | "ss"
+  | "SSS"
+  | "A"
+  | "a"
+  | "Z"
+  | "ZZ";
+
+/** Options for {@link formatDate}. */
+export interface FormatDateOptions {
+  /**
+   * BCP 47 locale(s) for names and `Intl` option formats. Defaults to a fixed
+   * locale (not the host default) so server and client output agree.
+   *
+   * @default "en"
+   */
+  readonly locale?: string | readonly string[];
+
+  /**
+   * IANA time zone the date is rendered in. Defaults to UTC (not the host
+   * zone) for SSR determinism; pass the user's zone explicitly.
+   *
+   * @default "UTC"
+   */
+  readonly timeZone?: string;
+}
+
+/** Options for {@link useDateFormat}. */
+export interface UseDateFormatOptions {
+  /**
+   * Reactive BCP 47 locale(s).
+   *
+   * @default "en"
+   */
+  readonly locale?: MaybeRefOrGetter<string | readonly string[]>;
+
+  /**
+   * Reactive IANA time zone.
+   *
+   * @default "UTC"
+   */
+  readonly timeZone?: MaybeRefOrGetter<string>;
+}
+
+const tokenPattern =
+  /\[([^\]]*)]|YYYY|YY|MMMM|MMM|MM|M|DD|D|dddd|ddd|dd|d|HH|H|hh|h|mm|m|ss|s|SSS|A|a|ZZ|Z/g;
+
+const weekdayIndex: Readonly<Record<string, number>> = {
+  Sun: 0,
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6,
+};
+
+function toDate(input: DateFormatInput): Date {
+  const date = input instanceof Date ? new Date(input.getTime()) : new Date(input);
+  if (Number.isNaN(date.getTime())) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_DATE_FORMAT_INVALID_DATE] expected a valid date; received ${String(input)}`,
+    );
+  }
+  return date;
+}
+
+function pad(value: number, length: number): string {
+  return String(value).padStart(length, "0");
+}
+
+function partsOf(formatter: Intl.DateTimeFormat, date: Date): Map<string, string> {
+  return new Map(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+}
+
+/**
+ * Format a date with a token pattern or `Intl.DateTimeFormat` options.
+ *
+ * Pure and deterministic: locale and time zone default to fixed values
+ * (`"en"`, `"UTC"`) rather than host settings, so the same input renders
+ * identically on server and client. Calendar fields are computed in the
+ * requested time zone through `Intl`, so no host-zone arithmetic leaks in.
+ *
+ * @example
+ * ```ts
+ * formatDate(0, "YYYY-MM-DD HH:mm:ss"); // "1970-01-01 00:00:00"
+ * formatDate(0, "dddd, MMMM D [at] h:mm A", { locale: "en", timeZone: "Asia/Tokyo" });
+ * formatDate(0, { dateStyle: "long" }, { locale: "ja" }); // "1970年1月1日"
+ * ```
+ *
+ * @param input Date to format.
+ * @param format Token pattern (see {@link DateFormatToken}) or `Intl` options.
+ * @param options Locale and time zone.
+ * @default format "HH:mm:ss"
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_DATE_FORMAT_INVALID_DATE` for
+ * invalid dates, and `RangeError` from `Intl` for invalid locales or zones.
+ * @returns The formatted string.
+ */
+export function formatDate(
+  input: DateFormatInput,
+  format: string | Intl.DateTimeFormatOptions = "HH:mm:ss",
+  options: FormatDateOptions = {},
+): string {
+  const date = toDate(input);
+  const locales =
+    typeof options.locale === "string" ? options.locale : [...(options.locale ?? ["en"])];
+  const timeZone = options.timeZone ?? "UTC";
+
+  if (typeof format !== "string") {
+    return new Intl.DateTimeFormat(locales, { ...format, timeZone }).format(date);
+  }
+
+  const numeric = partsOf(
+    new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      second: "numeric",
+      weekday: "short",
+      timeZoneName: "longOffset",
+    }),
+    date,
+  );
+  const field = (type: string): number => Number(numeric.get(type) ?? "0");
+  const localized = (formatOptions: Intl.DateTimeFormatOptions): string =>
+    new Intl.DateTimeFormat(locales, { ...formatOptions, timeZone }).format(date);
+
+  const year = field("year");
+  const month = field("month");
+  const day = field("day");
+  const hour = field("hour") % 24;
+  const minute = field("minute");
+  const second = field("second");
+  const offset = (numeric.get("timeZoneName") ?? "GMT").replace("GMT", "") || "+00:00";
+
+  const meridiem = (): string =>
+    partsOf(
+      new Intl.DateTimeFormat(locales, { hour: "numeric", hourCycle: "h12", timeZone }),
+      date,
+    ).get("dayPeriod") ?? (hour < 12 ? "AM" : "PM");
+
+  const render = (token: string): string => {
+    switch (token) {
+      case "YYYY":
+        return pad(year, 4);
+      case "YY":
+        return pad(year % 100, 2);
+      case "M":
+        return String(month);
+      case "MM":
+        return pad(month, 2);
+      case "MMM":
+        return localized({ month: "short" });
+      case "MMMM":
+        return localized({ month: "long" });
+      case "D":
+        return String(day);
+      case "DD":
+        return pad(day, 2);
+      case "d":
+        return String(weekdayIndex[numeric.get("weekday") ?? "Sun"] ?? 0);
+      case "dd":
+        return localized({ weekday: "narrow" });
+      case "ddd":
+        return localized({ weekday: "short" });
+      case "dddd":
+        return localized({ weekday: "long" });
+      case "H":
+        return String(hour);
+      case "HH":
+        return pad(hour, 2);
+      case "h":
+        return String(hour % 12 || 12);
+      case "hh":
+        return pad(hour % 12 || 12, 2);
+      case "m":
+        return String(minute);
+      case "mm":
+        return pad(minute, 2);
+      case "s":
+        return String(second);
+      case "ss":
+        return pad(second, 2);
+      case "SSS":
+        return pad(date.getUTCMilliseconds(), 3);
+      case "A":
+        return meridiem();
+      case "a":
+        return meridiem().toLowerCase();
+      case "Z":
+        return offset;
+      default:
+        return offset.replace(":", "");
+    }
+  };
+
+  return format.replaceAll(
+    tokenPattern,
+    (match: string, literal: string | undefined) => literal ?? render(match),
+  );
+}
+
+/**
+ * Reactive formatted date.
+ *
+ * Wraps {@link formatDate} in a computed ref; the date, the format, the
+ * locale, and the time zone are all reactive. Deterministic defaults (`"en"`,
+ * `"UTC"`) keep server and client output identical. No timers, no globals,
+ * nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const label = useDateFormat(() => event.value.startsAt, "ddd, MMM D HH:mm", {
+ *   locale: () => locale.value,
+ *   timeZone: "Europe/Paris",
+ * });
+ * ```
+ *
+ * @param input Reactive date.
+ * @param format Reactive token pattern or `Intl` options.
+ * @param options Reactive locale and time zone.
+ * @default format "HH:mm:ss"
+ * @default options {}
+ * @throws `RangeError` on read for invalid dates, locales, or zones.
+ * @returns Computed formatted string.
+ */
+export function useDateFormat(
+  input: MaybeRefOrGetter<DateFormatInput>,
+  format: MaybeRefOrGetter<string | Intl.DateTimeFormatOptions> = "HH:mm:ss",
+  options: UseDateFormatOptions = {},
+): ComputedRef<string> {
+  return computed(() =>
+    formatDate(toValue(input), toValue(format), {
+      locale: toValue(options.locale) ?? "en",
+      timeZone: toValue(options.timeZone) ?? "UTC",
+    }),
+  );
+}

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

@@ -0,0 +1,113 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** Values accepted by `Intl.DateTimeFormat`: a `Date` or Unix milliseconds. */
+export type FormattableDate = Date | number;
+
+/** Options for {@link useDateTimeFormat}. */
+export interface UseDateTimeFormatOptions extends Intl.DateTimeFormatOptions {
+  /**
+   * Locale used for formatting. Pass it explicitly (and a `timeZone`) for
+   * server rendering: the server falls back to `"en"` and its own time zone.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+
+/** Reactive date formatting returned by {@link useDateTimeFormat}. */
+export interface DateTimeFormatControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Cached formatter for the current locale and options. */
+  readonly formatter: ComputedRef<Intl.DateTimeFormat>;
+
+  /**
+   * Formatted `value`, or `""` while the value is `null`/`undefined` or an
+   * invalid date.
+   */
+  readonly formatted: ComputedRef<string>;
+
+  /**
+   * Format any date with the current formatter.
+   *
+   * @param value Date or Unix milliseconds.
+   * @returns The formatted string.
+   * @throws {RangeError} For an invalid date, as `Intl.DateTimeFormat` does.
+   */
+  readonly format: (value: FormattableDate) => string;
+
+  /**
+   * Format any date into locale-aware parts.
+   *
+   * @param value Date or Unix milliseconds.
+   * @returns The formatted parts.
+   */
+  readonly formatToParts: (value: FormattableDate) => Intl.DateTimeFormatPart[];
+
+  /**
+   * Format a date range, collapsing shared fields (for example `"Jan 3 – 5, 2026"`).
+   *
+   * @param start Range start.
+   * @param end Range end.
+   * @returns The formatted range.
+   */
+  readonly formatRange: (start: FormattableDate, end: FormattableDate) => string;
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+function isValidDate(value: FormattableDate): boolean {
+  return !Number.isNaN(value instanceof Date ? value.getTime() : value);
+}
+
+/**
+ * Format dates and times reactively with `Intl.DateTimeFormat`.
+ *
+ * The formatter follows the reactive options (including `locale`) and is
+ * cached per locale and option set through {@link useLocale}. For
+ * hydration-stable output pass both `locale` and `timeZone`: otherwise the
+ * server uses `"en"` and its own zone. Invalid options surface as the
+ * platform's `RangeError` on first read; invalid dates render as `""`.
+ * No listeners or timers are created — combine with a clock composable for
+ * live-updating output.
+ *
+ * @example
+ * ```ts
+ * const { formatted } = useDateTimeFormat(date, { locale: "en-GB", dateStyle: "long", timeZone: "UTC" });
+ * ```
+ *
+ * @param value Reactive date; `null`/`undefined` format as `""`.
+ * @param options Reactive locale and `Intl.DateTimeFormat` options.
+ * @default value undefined
+ * @default options {}
+ * @returns Reactive formatted output and formatter helpers.
+ */
+export function useDateTimeFormat(
+  value?: MaybeRefOrGetter<FormattableDate | null | undefined>,
+  options: MaybeRefOrGetter<UseDateTimeFormatOptions> = {},
+): DateTimeFormatControls {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const formatter = computed(() => {
+    const { locale: _locale, ...formatOptions } = toValue(options);
+    return localeControls.dateTime(formatOptions);
+  });
+  const formatted = computed(() => {
+    const current = value === undefined ? undefined : toValue(value);
+    if (current === null || current === undefined || !isValidDate(current)) return "";
+    return formatter.value.format(current);
+  });
+  return {
+    locale: localeControls.locale,
+    formatter,
+    formatted,
+    format: (input) => formatter.value.format(input),
+    formatToParts: (input) => formatter.value.formatToParts(input),
+    formatRange: (start, end) => formatter.value.formatRange(start, end),
+  };
+}

package/registry/files/use-debounced.ts

@@ -0,0 +1,163 @@
+import { shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Options for {@link useDebounced}. */
+export interface UseDebouncedOptions {
+  /**
+   * Applies the timing policy when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering, where the debounced view
+   * mirrors the source synchronously instead of starting timers. Enable it
+   * for native, desktop, worker, and test runtimes whose scheduler is
+   * lifecycle-bound.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Owns the single-shot timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+
+/** Reactive debounced view and controls returned by {@link useDebounced}. */
+export interface DebouncedControls<Value> {
+  /** Readonly view of the source that settles `waitMs` after the last change. */
+  readonly debounced: Readonly<ShallowRef<Value>>;
+
+  /** Whether a trailing update is currently scheduled. */
+  readonly pending: Readonly<ShallowRef<boolean>>;
+
+  /**
+   * Discard the scheduled trailing update and keep the last settled value.
+   * Later source changes debounce again as usual.
+   *
+   * @returns Whether a scheduled update was discarded.
+   */
+  readonly cancel: () => boolean;
+
+  /**
+   * Apply the current source value immediately instead of waiting out the
+   * delay.
+   *
+   * @returns Whether a scheduled update was applied.
+   */
+  readonly flush: () => boolean;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+/**
+ * Create a readonly debounced view of a reactive source.
+ *
+ * The view starts at the current source value. Each source change (observed
+ * with `flush: "sync"`, so every synchronous write counts) restarts a
+ * single-shot timer of `waitMs` milliseconds; when it fires, the view takes
+ * the source value current at that moment. `waitMs` is reactive and is read
+ * when a timer is scheduled; changing it does not restart an already-pending
+ * timer. A wait of `0` still defers to the next scheduler tick.
+ *
+ * Server rendering is explicit: without a browser `window` (and with
+ * {@link UseDebouncedOptions.runOnServer} disabled) no timer ever starts and
+ * the view mirrors the source synchronously, so server-rendered output shows
+ * current values and nothing leaks. `pending` stays `false` and the controls
+ * report `false` in that mode.
+ *
+ * Cleanup rule: the watcher and any pending timer are released when the
+ * owning reactive scope stops; call inside an active scope. Outside one, the
+ * watcher lives as long as the source and `cancel()` only clears the pending
+ * timer.
+ *
+ * @example
+ * ```ts
+ * const query = shallowRef("");
+ * const { debounced, flush } = useDebounced(query, 300);
+ * query.value = "vize"; // debounced.value still "" for 300ms
+ * flush(); // debounced.value === "vize" immediately
+ * ```
+ *
+ * @param source Reactive source to debounce.
+ * @param waitMs Reactive delay in milliseconds; must be finite and at least
+ * zero. Fractions are truncated.
+ * @param options Runtime scheduling overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` when the
+ * resolved wait is not finite or is negative, both synchronously at creation
+ * (even in mirror mode) and again for every scheduled delay.
+ * @returns Readonly debounced view, pending flag, and cancel/flush controls.
+ */
+export function useDebounced<Value>(
+  source: MaybeRefOrGetter<Value>,
+  waitMs: MaybeRefOrGetter<number>,
+  options: UseDebouncedOptions = {},
+): DebouncedControls<Value> {
+  const scheduler = options.scheduler ?? defaultScheduler;
+  const debounced = shallowRef(toValue(source));
+  const pending = shallowRef(false);
+  let handle: unknown;
+
+  // Fail synchronously for invalid initial input, even in mirror mode.
+  resolveWaitMs(toValue(waitMs));
+
+  const apply = (): void => {
+    handle = undefined;
+    pending.value = false;
+    debounced.value = toValue(source);
+  };
+
+  const cancel = (): boolean => {
+    if (!pending.value) return false;
+    scheduler.clearTimeout(handle);
+    handle = undefined;
+    pending.value = false;
+    return true;
+  };
+
+  const flush = (): boolean => {
+    if (!pending.value) return false;
+    scheduler.clearTimeout(handle);
+    apply();
+    return true;
+  };
+
+  watch(
+    () => toValue(source),
+    (next) => {
+      if (typeof window === "undefined" && !(options.runOnServer ?? false)) {
+        debounced.value = next;
+        return;
+      }
+      const delayMs = resolveWaitMs(toValue(waitMs));
+      if (pending.value) scheduler.clearTimeout(handle);
+      pending.value = true;
+      handle = scheduler.setTimeout(apply, delayMs);
+    },
+    { flush: "sync" },
+  );
+
+  tryOnScopeDispose(() => {
+    cancel();
+  });
+
+  return { debounced, pending, cancel, flush };
+}
+
+function resolveWaitMs(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT] waitMs must be finite and at least zero; received ${String(value)}`,
+    );
+  }
+  return Math.trunc(value);
+}

package/registry/files/use-display-media.ts

@@ -0,0 +1,89 @@
+import { toValue } from "vue";
+import type { MaybeRefOrGetter } from "vue";
+
+import { useMediaStream } from "./use-user-media.ts";
+import type { MediaStreamControls, MediaStreamLike } from "./use-user-media.ts";
+
+/** Minimal `MediaDevices` consumed by {@link useDisplayMedia}. */
+export interface DisplayMediaHost {
+  /** Ask the user to pick a screen, window, or tab to capture. */
+  getDisplayMedia(options?: DisplayMediaStreamOptions): Promise<MediaStreamLike>;
+}
+
+/** Options for {@link useDisplayMedia}. */
+export interface UseDisplayMediaOptions {
+  /**
+   * Video capture constraints.
+   *
+   * @default true
+   */
+  readonly video?: MaybeRefOrGetter<boolean | MediaTrackConstraints>;
+
+  /**
+   * Audio capture constraints (tab or system audio where supported).
+   *
+   * @default false
+   */
+  readonly audio?: MaybeRefOrGetter<boolean | MediaTrackConstraints>;
+
+  /**
+   * Start while `true`, stop while `false`. Browsers require a user gesture
+   * for screen capture, so prefer calling `start` from an event handler.
+   *
+   * @default false
+   */
+  readonly enabled?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * `MediaDevices` capability for alternate runtimes and tests.
+   *
+   * @default window.navigator.mediaDevices when it implements `getDisplayMedia`
+   */
+  readonly host?: MaybeRefOrGetter<DisplayMediaHost | null | undefined>;
+}
+
+function browserDisplayMediaHost(): DisplayMediaHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  // `mediaDevices` is undefined in insecure contexts despite its DOM typing.
+  const devices: MediaDevices | undefined = window.navigator.mediaDevices;
+  return devices && typeof devices.getDisplayMedia === "function" ? devices : undefined;
+}
+
+/**
+ * Capture a screen, window, or tab with `getDisplayMedia`.
+ *
+ * Shares the stream lifecycle of `useMediaStream` (from `use-user-media`):
+ * classified failures (`"permission-denied"` when the user dismisses the
+ * picker), latest-wins requests, and automatic return to `"idle"` when the
+ * user ends sharing from the browser UI (every track `ended`). Tracks are
+ * stopped when the owning reactive scope stops.
+ *
+ * Server rendering: nothing is captured; `status` is `"idle"` and
+ * `supported` is false.
+ *
+ * @example
+ * ```ts
+ * const screen = useDisplayMedia({ audio: true });
+ * const share = () => screen.start();
+ * ```
+ *
+ * @param options Capture constraints, activation, and capability.
+ * @default options {}
+ * @returns Stream state and actions.
+ */
+export function useDisplayMedia(options: UseDisplayMediaOptions = {}): MediaStreamControls {
+  const resolveHost = (): DisplayMediaHost | undefined =>
+    options.host === undefined ? browserDisplayMediaHost() : (toValue(options.host) ?? undefined);
+
+  return useMediaStream<DisplayMediaStreamOptions>({
+    source: () => {
+      const host = resolveHost();
+      return host ? { request: (constraints) => host.getDisplayMedia(constraints) } : undefined;
+    },
+    constraints: () => ({
+      video: toValue(options.video) ?? true,
+      audio: toValue(options.audio) ?? false,
+    }),
+    enabled: () => toValue(options.enabled) ?? false,
+  });
+}