@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/use-notification.ts

@@ -0,0 +1,285 @@
+import { computed, readonly, ref, shallowRef, toValue, unref } from "vue";
+import type { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Notification permission, plus `"unsupported"` when the API is missing. */
+export type NotificationPermissionState = "default" | "granted" | "denied" | "unsupported";
+
+/** Options accepted by the `Notification` constructor. */
+export interface NotificationOptionsLike<Data> {
+  /** Body text. */
+  readonly body?: string;
+
+  /** Icon URL. */
+  readonly icon?: string;
+
+  /** Monochrome badge URL for constrained surfaces. */
+  readonly badge?: string;
+
+  /** Grouping tag; a new notification with the same tag replaces the old one. */
+  readonly tag?: string;
+
+  /** BCP 47 language tag. */
+  readonly lang?: string;
+
+  /** Text direction. */
+  readonly dir?: "auto" | "ltr" | "rtl";
+
+  /** Keep the notification visible until the user interacts with it. */
+  readonly requireInteraction?: boolean;
+
+  /** Suppress sounds and vibration. */
+  readonly silent?: boolean | null;
+
+  /** Application data attached to the notification. */
+  readonly data?: Data;
+}
+
+/** Minimal `Notification` instance consumed by {@link useWebNotification}. */
+export interface NotificationLike extends EventTarget {
+  /** Dismiss the notification. */
+  close(): void;
+}
+
+/** Minimal `Notification` constructor (with its static members). */
+export interface NotificationHost {
+  /** Current permission. */
+  readonly permission: string;
+
+  /** Ask the user for permission. */
+  requestPermission(): Promise<string>;
+
+  /** Show a notification. */
+  new (title: string, options?: NotificationOptionsLike<unknown>): NotificationLike;
+}
+
+/** Default notification content for {@link useWebNotification}. */
+export interface WebNotificationDefaults<Data> extends NotificationOptionsLike<Data> {
+  /** Default title. */
+  readonly title?: string;
+}
+
+/** Options for {@link useWebNotification}. */
+export interface UseWebNotificationOptions<Data> {
+  /**
+   * Notification constructor for alternate runtimes and tests. A ref (not a
+   * getter) because the host itself is a constructor function.
+   *
+   * @default window.Notification when it exists
+   */
+  readonly host?: MaybeRef<NotificationHost | null | undefined>;
+
+  /**
+   * Reactive default title and options merged into every `show` call.
+   *
+   * @default {}
+   */
+  readonly defaults?: MaybeRefOrGetter<WebNotificationDefaults<Data>>;
+
+  /**
+   * Request permission from `show` when it has not been decided yet.
+   *
+   * @default true
+   */
+  readonly requestPermissionOnShow?: boolean;
+}
+
+/** Discriminated outcome of {@link WebNotificationControls.show}. */
+export type WebNotificationResult =
+  | {
+      /** The notification is showing. */
+      readonly status: "shown";
+      /** The shown notification. */
+      readonly notification: NotificationLike;
+    }
+  | {
+      /** Permission is not granted, the API is missing, or construction failed. */
+      readonly status: "denied" | "unsupported" | "failed";
+      /** Exact error thrown by the host, when one was thrown. */
+      readonly error: unknown;
+    };
+
+/** Notification lifecycle events exposed by {@link useWebNotification}. */
+export type WebNotificationEvent = "click" | "show" | "error" | "close";
+
+/** Reactive state and actions returned by {@link useWebNotification}. */
+export interface WebNotificationControls<Data> {
+  /** Whether the Notifications API is available. */
+  readonly supported: ComputedRef<boolean>;
+
+  /** Current permission state. */
+  readonly permission: Readonly<Ref<NotificationPermissionState>>;
+
+  /** Most recently shown notification, cleared when it closes. */
+  readonly notification: Readonly<ShallowRef<NotificationLike | undefined>>;
+
+  /** Data attached to the current notification. */
+  readonly data: Readonly<ShallowRef<Data | undefined>>;
+
+  /**
+   * Ask the user for permission.
+   *
+   * @returns The resulting permission state.
+   */
+  readonly requestPermission: () => Promise<NotificationPermissionState>;
+
+  /**
+   * Show a notification, replacing the current one.
+   *
+   * @param title Title overriding the default.
+   * @param options Options merged over the defaults.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly show: (
+    title?: string,
+    options?: NotificationOptionsLike<Data>,
+  ) => Promise<WebNotificationResult>;
+
+  /** Close the current notification. */
+  readonly close: () => void;
+
+  /**
+   * Subscribe to an event of every notification shown by this composable.
+   *
+   * @param event Lifecycle event.
+   * @param handler Called with the native event and its notification.
+   * @returns Unsubscribe function.
+   */
+  readonly on: (
+    event: WebNotificationEvent,
+    handler: (event: Event, notification: NotificationLike) => void,
+  ) => () => void;
+}
+
+function browserNotificationHost(): NotificationHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  return "Notification" in window ? window.Notification : undefined;
+}
+
+function normalizePermission(permission: string): NotificationPermissionState {
+  return permission === "granted" || permission === "denied" ? permission : "default";
+}
+
+const notificationEvents: readonly WebNotificationEvent[] = ["click", "show", "error", "close"];
+
+/**
+ * Show typed Web Notifications with permission handling.
+ *
+ * `show` merges reactive defaults with per-call options, asks for
+ * permission first when it is still undecided (configurable), and resolves
+ * to a discriminated {@link WebNotificationResult}. Handlers registered with
+ * `on` apply to every notification this composable shows. The current
+ * notification is closed when the owning reactive scope stops.
+ *
+ * Server rendering: the API is never touched; `permission` is
+ * `"unsupported"` and `supported` is false.
+ *
+ * @example
+ * ```ts
+ * const notify = useWebNotification<{ id: string }>({ defaults: { icon: "/icon.png" } });
+ * notify.on("click", () => window.focus());
+ * await notify.show("Build finished", { data: { id: "42" } });
+ * ```
+ *
+ * @typeParam Data Application data attached to notifications.
+ * @param options Capability, defaults, and permission policy.
+ * @default options {}
+ * @returns Notification state and actions.
+ */
+export function useWebNotification<Data = unknown>(
+  options: UseWebNotificationOptions<Data> = {},
+): WebNotificationControls<Data> {
+  const resolveHost = (): NotificationHost | undefined =>
+    options.host === undefined ? browserNotificationHost() : (unref(options.host) ?? undefined);
+  const readPermission = (): NotificationPermissionState => {
+    const host = resolveHost();
+    return host ? normalizePermission(host.permission) : "unsupported";
+  };
+  const permission = ref<NotificationPermissionState>(readPermission());
+  const notification = shallowRef<NotificationLike | undefined>(undefined);
+  const data = shallowRef<Data | undefined>(undefined);
+  const handlers = new Map<
+    WebNotificationEvent,
+    Set<(event: Event, notification: NotificationLike) => void>
+  >();
+
+  const requestPermission = async (): Promise<NotificationPermissionState> => {
+    const host = resolveHost();
+    if (!host) return (permission.value = "unsupported");
+    try {
+      permission.value = normalizePermission(await host.requestPermission());
+    } catch {
+      permission.value = readPermission();
+    }
+    return permission.value;
+  };
+
+  const close = (): void => {
+    notification.value?.close();
+    notification.value = undefined;
+    data.value = undefined;
+  };
+
+  const show = async (
+    title?: string,
+    overrides?: NotificationOptionsLike<Data>,
+  ): Promise<WebNotificationResult> => {
+    const host = resolveHost();
+    if (!host) return { status: "unsupported", error: undefined };
+    permission.value = readPermission();
+    if (permission.value === "default" && (options.requestPermissionOnShow ?? true)) {
+      await requestPermission();
+    }
+    if (permission.value !== "granted") return { status: "denied", error: undefined };
+    const { title: defaultTitle = "", ...defaults } = toValue(options.defaults) ?? {};
+    const merged: NotificationOptionsLike<Data> = { ...defaults, ...overrides };
+    let created: NotificationLike;
+    try {
+      created = new host(title ?? defaultTitle, merged);
+    } catch (error) {
+      return { status: "failed", error };
+    }
+    close();
+    notification.value = created;
+    data.value = merged.data;
+    for (const event of notificationEvents) {
+      created.addEventListener(event, (nativeEvent) => {
+        for (const handler of handlers.get(event) ?? []) handler(nativeEvent, created);
+        if (event === "close" && notification.value === created) {
+          notification.value = undefined;
+          data.value = undefined;
+        }
+      });
+    }
+    return { status: "shown", notification: created };
+  };
+
+  const on = (
+    event: WebNotificationEvent,
+    handler: (event: Event, notification: NotificationLike) => void,
+  ): (() => void) => {
+    let set = handlers.get(event);
+    if (!set) handlers.set(event, (set = new Set()));
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  };
+
+  tryOnScopeDispose(() => {
+    close();
+    handlers.clear();
+  });
+
+  return {
+    supported: computed(() => resolveHost() !== undefined),
+    permission: readonly(permission),
+    notification,
+    data,
+    requestPermission,
+    show,
+    close,
+    on,
+  };
+}

package/registry/files/use-now.ts

@@ -0,0 +1,194 @@
+import { computed, shallowRef } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { useIntervalFn } from "./use-interval.ts";
+import type { IntervalScheduler, PausableControls } from "./use-interval.ts";
+import { useRafFn } from "./use-raf-fn.ts";
+import type { FrameScheduler } from "./use-raf-fn.ts";
+
+/** Options for {@link useTimestamp}. */
+export interface UseTimestampOptions<Controls extends boolean = false> {
+  /**
+   * Update cadence: a period in milliseconds (reactive), or
+   * `"requestAnimationFrame"` to update on every animation frame.
+   *
+   * @default 1000
+   */
+  readonly interval?: MaybeRefOrGetter<number> | "requestAnimationFrame";
+
+  /**
+   * Milliseconds added to every reading, for example a server clock skew.
+   *
+   * @default 0
+   */
+  readonly offset?: number;
+
+  /**
+   * Clock source returning Unix epoch milliseconds.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+
+  /**
+   * Hydration-stable starting value. When set, the first reading is this
+   * value on both server and client instead of the live clock, and the live
+   * clock takes over on the first tick. Pass the server's render time here
+   * (for example through a payload) to avoid hydration mismatches.
+   *
+   * @default undefined (read the clock immediately)
+   */
+  readonly initial?: number;
+
+  /**
+   * Start updating as soon as the composable is created.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Starts host timers or frames when no browser `window` is available.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Repeating timer host for millisecond cadences.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: IntervalScheduler;
+
+  /**
+   * Frame host for the `"requestAnimationFrame"` cadence.
+   *
+   * @default globalThis animation-frame functions when available
+   */
+  readonly frameScheduler?: FrameScheduler;
+
+  /**
+   * Invoked after every update with the new timestamp.
+   *
+   * @default undefined
+   */
+  readonly callback?: (timestamp: number) => void;
+
+  /**
+   * Return the full control object instead of the bare ref.
+   *
+   * @default false
+   */
+  readonly controls?: Controls;
+}
+
+/** Options for {@link useNow}; identical to {@link UseTimestampOptions}. */
+export type UseNowOptions<Controls extends boolean = false> = UseTimestampOptions<Controls>;
+
+/** Timestamp and controls returned by `useTimestamp({ controls: true })`. */
+export interface TimestampControls extends PausableControls {
+  /** Latest reading in Unix epoch milliseconds. */
+  readonly timestamp: Readonly<ShallowRef<number>>;
+
+  /**
+   * Read the clock immediately, store the value, and return it.
+   *
+   * @returns The new timestamp.
+   */
+  readonly refresh: () => number;
+}
+
+/** Date and controls returned by `useNow({ controls: true })`. */
+export interface NowControls extends PausableControls {
+  /** Latest reading as a `Date`; a fresh instance per update. */
+  readonly now: ComputedRef<Date>;
+
+  /**
+   * Read the clock immediately, store the value, and return it.
+   *
+   * @returns The new date.
+   */
+  readonly refresh: () => Date;
+}
+
+function createTimestamp(options: UseTimestampOptions<boolean>): TimestampControls {
+  const offset = options.offset ?? 0;
+  const read = options.now ?? Date.now;
+  const timestamp = shallowRef(options.initial ?? read() + offset);
+
+  const refresh = (): number => {
+    timestamp.value = read() + offset;
+    options.callback?.(timestamp.value);
+    return timestamp.value;
+  };
+
+  const interval = options.interval ?? 1_000;
+  const controls =
+    interval === "requestAnimationFrame"
+      ? useRafFn(refresh, {
+          immediate: options.immediate ?? true,
+          runOnServer: options.runOnServer ?? false,
+          ...(options.frameScheduler === undefined ? {} : { scheduler: options.frameScheduler }),
+        })
+      : useIntervalFn(refresh, interval, {
+          immediate: options.immediate ?? true,
+          runOnServer: options.runOnServer ?? false,
+          ...(options.scheduler === undefined ? {} : { scheduler: options.scheduler }),
+        });
+
+  return { ...controls, timestamp, refresh };
+}
+
+/**
+ * Reactive Unix timestamp in milliseconds.
+ *
+ * Updates on a millisecond interval or every animation frame. For SSR,
+ * supply {@link UseTimestampOptions.initial} (or an injected `now`) so the
+ * server and the hydrating client render the same value; no timer runs on
+ * the server. Timers stop with the owning reactive scope.
+ *
+ * @example
+ * ```ts
+ * const timestamp = useTimestamp({ interval: 250 });
+ * const { timestamp: t, pause } = useTimestamp({ controls: true });
+ * ```
+ *
+ * @param options Cadence, clock, SSR, and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` for invalid millisecond cadences (see `useIntervalFn`).
+ * @returns The timestamp ref, or the full controls when `controls` is `true`.
+ */
+export function useTimestamp(options?: UseTimestampOptions<false>): Readonly<ShallowRef<number>>;
+export function useTimestamp(options: UseTimestampOptions<true>): TimestampControls;
+export function useTimestamp(
+  options: UseTimestampOptions<boolean> = {},
+): Readonly<ShallowRef<number>> | TimestampControls {
+  const controls = createTimestamp(options);
+  return options.controls === true ? controls : controls.timestamp;
+}
+
+/**
+ * Reactive current `Date`.
+ *
+ * Same cadence, SSR, and cleanup rules as {@link useTimestamp}; the value is
+ * a fresh `Date` derived from the latest timestamp.
+ *
+ * @example
+ * ```ts
+ * const now = useNow({ initial: serverRenderedAt });
+ * ```
+ *
+ * @param options Cadence, clock, SSR, and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` for invalid millisecond cadences (see `useIntervalFn`).
+ * @returns The date ref, or the full controls when `controls` is `true`.
+ */
+export function useNow(options?: UseNowOptions<false>): ComputedRef<Date>;
+export function useNow(options: UseNowOptions<true>): NowControls;
+export function useNow(options: UseNowOptions<boolean> = {}): ComputedRef<Date> | NowControls {
+  const { timestamp, refresh, ...pausable } = createTimestamp(options);
+  const now = computed(() => new Date(timestamp.value));
+  if (options.controls !== true) return now;
+  return { ...pausable, now, refresh: () => new Date(refresh()) };
+}

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

@@ -0,0 +1,120 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** Numeric values accepted by `Intl.NumberFormat`. */
+export type FormattableNumber = number | bigint;
+
+/** Options for {@link useNumberFormat}. */
+export interface UseNumberFormatOptions extends Intl.NumberFormatOptions {
+  /**
+   * Locale used for formatting. Pass it explicitly for server rendering:
+   * without it the server falls back to `"en"` while the browser detects
+   * `navigator.language`, which can make hydration mismatch.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+
+/** Reactive number formatting returned by {@link useNumberFormat}. */
+export interface NumberFormatControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Cached formatter for the current locale and options. */
+  readonly formatter: ComputedRef<Intl.NumberFormat>;
+
+  /** Formatted `value`, or `""` while the value is `null`/`undefined`. */
+  readonly formatted: ComputedRef<string>;
+
+  /**
+   * Format any number with the current formatter.
+   *
+   * @param value Number to format.
+   * @returns The formatted string.
+   */
+  readonly format: (value: FormattableNumber) => string;
+
+  /**
+   * Format any number into locale-aware parts.
+   *
+   * @param value Number to format.
+   * @returns The formatted parts.
+   */
+  readonly formatToParts: (value: FormattableNumber) => Intl.NumberFormatPart[];
+
+  /**
+   * Format a numeric range (for example `"3–5"`).
+   *
+   * @param start Range start.
+   * @param end Range end.
+   * @returns The formatted range.
+   */
+  readonly formatRange: (start: FormattableNumber, end: FormattableNumber) => string;
+}
+
+function formatRangeWith(
+  formatter: Intl.NumberFormat,
+  start: FormattableNumber,
+  end: FormattableNumber,
+): string {
+  // `formatRange` is ES2023; older engines fall back to joining both ends.
+  const native: unknown = Reflect.get(formatter, "formatRange");
+  if (typeof native === "function") {
+    const result: unknown = Reflect.apply(native, formatter, [start, end]);
+    if (typeof result === "string") return result;
+  }
+  return `${formatter.format(start)}\u2013${formatter.format(end)}`;
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+/**
+ * Format numbers reactively with `Intl.NumberFormat`.
+ *
+ * The formatter follows the reactive options (including `locale`) and is
+ * cached per locale and option set through {@link useLocale}. Without an
+ * explicit locale the browser language is used, falling back to `"en"`
+ * (always the case on the server). Invalid options surface as the
+ * platform's `RangeError`/`TypeError` on first read. No listeners or timers
+ * are created, so nothing needs cleanup.
+ *
+ * @example
+ * ```ts
+ * const price = ref(1234.5);
+ * const { formatted } = useNumberFormat(price, { locale: "de-DE", style: "currency", currency: "EUR" });
+ * formatted.value; // "1.234,50 €"
+ * ```
+ *
+ * @param value Reactive number; `null`/`undefined` format as `""`.
+ * @param options Reactive locale and `Intl.NumberFormat` options.
+ * @default value undefined
+ * @default options {}
+ * @returns Reactive formatted output and formatter helpers.
+ */
+export function useNumberFormat(
+  value?: MaybeRefOrGetter<FormattableNumber | null | undefined>,
+  options: MaybeRefOrGetter<UseNumberFormatOptions> = {},
+): NumberFormatControls {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const formatter = computed(() => {
+    const { locale: _locale, ...formatOptions } = toValue(options);
+    return localeControls.number(formatOptions);
+  });
+  const formatted = computed(() => {
+    const current = value === undefined ? undefined : toValue(value);
+    return current === null || current === undefined ? "" : 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) => formatRangeWith(formatter.value, start, end),
+  };
+}

package/registry/files/use-object-url.ts

@@ -0,0 +1,87 @@
+import { readonly, ref, toValue, unref, watch } from "vue";
+import type { MaybeRef, MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Objects accepted by `URL.createObjectURL`. */
+export type ObjectUrlSource = Blob | MediaSource;
+
+/** Minimal object-URL capability (the `URL` constructor's static methods). */
+export interface ObjectUrlHost {
+  /** Create a URL referencing `object`. */
+  createObjectURL(object: ObjectUrlSource): string;
+
+  /** Release a URL previously returned by `createObjectURL`. */
+  revokeObjectURL(url: string): void;
+}
+
+/** Options for {@link useObjectUrl}. */
+export interface UseObjectUrlOptions {
+  /**
+   * Object-URL capability for alternate runtimes and tests. A ref (not a
+   * getter) because the default host, `URL`, is itself a constructor.
+   *
+   * @default window.URL when a browser window exists
+   */
+  readonly host?: MaybeRef<ObjectUrlHost | null | undefined>;
+}
+
+function browserObjectUrlHost(): ObjectUrlHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { URL } = window;
+  return typeof URL.createObjectURL === "function" ? URL : undefined;
+}
+
+/**
+ * Create a reactive object URL for a `Blob`, `File`, or `MediaSource`.
+ *
+ * A new URL is created whenever the reactive object changes and the
+ * previous one is revoked immediately, so memory held by the old object is
+ * released. The last URL is revoked when the owning reactive scope stops.
+ * Outside a scope, the caller owns the last URL (it lives until unload).
+ *
+ * Server rendering: no URL is created and the ref stays `undefined`.
+ *
+ * @example
+ * ```ts
+ * const file = shallowRef<File>();
+ * const preview = useObjectUrl(file);
+ * // <img :src="preview">
+ * ```
+ *
+ * @param object Reactive object to reference; `null`/`undefined` clears the URL.
+ * @param options Object-URL capability.
+ * @default options {}
+ * @returns Readonly ref holding the current object URL.
+ */
+export function useObjectUrl(
+  object: MaybeRefOrGetter<ObjectUrlSource | null | undefined>,
+  options: UseObjectUrlOptions = {},
+): Readonly<Ref<string | undefined>> {
+  const url = ref<string | undefined>(undefined);
+  const resolveHost = (): ObjectUrlHost | undefined =>
+    options.host === undefined ? browserObjectUrlHost() : (unref(options.host) ?? undefined);
+
+  let revokeCurrent: (() => void) | undefined;
+  const release = (): void => {
+    revokeCurrent?.();
+    revokeCurrent = undefined;
+    url.value = undefined;
+  };
+
+  watch(
+    [() => toValue(object), resolveHost],
+    ([next, host]) => {
+      release();
+      if (!next || !host) return;
+      const created = host.createObjectURL(next);
+      url.value = created;
+      revokeCurrent = () => host.revokeObjectURL(created);
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  tryOnScopeDispose(release);
+
+  return readonly(url);
+}