@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-plural-rules.ts

@@ -0,0 +1,134 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** CLDR plural categories. */
+export type PluralCategory = Intl.LDMLPluralRule;
+
+/**
+ * One plural message: a template where `{count}` and `#` are replaced by the
+ * locale-formatted count, or a function receiving the raw and formatted count.
+ */
+export type PluralMessage = string | ((count: number, formatted: string) => string);
+
+/**
+ * Messages per plural category. `other` is required because every locale
+ * falls back to it; exact-value overrides such as `"=0"` take precedence
+ * over categories.
+ */
+export type PluralMessages = {
+  readonly [Category in Exclude<PluralCategory, "other">]?: PluralMessage;
+} & {
+  /** Required fallback message. */
+  readonly other: PluralMessage;
+} & {
+  readonly [exact: `=${number}`]: PluralMessage | undefined;
+};
+
+/** Options for {@link usePluralRules}. */
+export interface UsePluralRulesOptions extends Intl.PluralRulesOptions {
+  /**
+   * Locale used for plural selection and count formatting. Pass it
+   * explicitly for hydration-stable server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+
+/** Reactive plural selection returned by {@link usePluralRules}. */
+export interface PluralRulesControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Plural rules for the current locale and options. */
+  readonly rules: ComputedRef<Intl.PluralRules>;
+
+  /** Category of the current count. */
+  readonly category: ComputedRef<PluralCategory>;
+
+  /** Message for the current count with `{count}` / `#` interpolated. */
+  readonly message: ComputedRef<string>;
+
+  /**
+   * Plural category of any count.
+   *
+   * @param count Count to classify.
+   * @returns The CLDR category.
+   */
+  readonly select: (count: number) => PluralCategory;
+
+  /**
+   * Message for any count.
+   *
+   * @param count Count to render.
+   * @returns The interpolated message.
+   */
+  readonly format: (count: number) => string;
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+function renderMessage(message: PluralMessage, count: number, formatted: string): string {
+  return typeof message === "function"
+    ? message(count, formatted)
+    : message.replaceAll("{count}", formatted).replaceAll("#", formatted);
+}
+
+/**
+ * Choose and render a message by CLDR plural category (`Intl.PluralRules`).
+ *
+ * Messages are typed per category with a mandatory `other`, plus optional
+ * exact overrides (`"=0": "No items"`). Cardinal (`1 item`) and ordinal
+ * (`1st`, `2nd`) rules are supported via `type`. The count is formatted
+ * with the same locale for interpolation. Everything is derived state:
+ * no listeners or timers, deterministic during server rendering when the
+ * locale is explicit. Invalid options surface as the platform `RangeError`.
+ *
+ * @example
+ * ```ts
+ * const { message } = usePluralRules(count, { "=0": "No files", one: "# file", other: "# files" }, { locale: "en" });
+ * ```
+ *
+ * @param count Reactive count.
+ * @param messages Reactive messages per category.
+ * @param options Reactive locale and `Intl.PluralRules` options.
+ * @default options {}
+ * @returns Reactive category, message, and selection helpers.
+ */
+export function usePluralRules(
+  count: MaybeRefOrGetter<number>,
+  messages: MaybeRefOrGetter<PluralMessages>,
+  options: MaybeRefOrGetter<UsePluralRulesOptions> = {},
+): PluralRulesControls {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const rules = computed(() => {
+    const { locale: _locale, ...ruleOptions } = toValue(options);
+    return new Intl.PluralRules(localeControls.locale.value, ruleOptions);
+  });
+  const numberFormat = computed(() => {
+    const { minimumFractionDigits, maximumFractionDigits } = toValue(options);
+    return localeControls.number({
+      ...(minimumFractionDigits === undefined ? {} : { minimumFractionDigits }),
+      ...(maximumFractionDigits === undefined ? {} : { maximumFractionDigits }),
+    });
+  });
+  const select = (value: number): PluralCategory => rules.value.select(value);
+  const format = (value: number): string => {
+    const table = toValue(messages);
+    const exact: `=${number}` = `=${value}`;
+    const message = table[exact] ?? table[select(value)] ?? table.other;
+    return renderMessage(message, value, numberFormat.value.format(value));
+  };
+  return {
+    locale: localeControls.locale,
+    rules,
+    category: computed(() => select(toValue(count))),
+    message: computed(() => format(toValue(count))),
+    select,
+    format,
+  };
+}

package/registry/files/use-previous.ts

@@ -0,0 +1,62 @@
+import { shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, ShallowRef } from "vue";
+
+/**
+ * Track the value a reactive source held before its latest change.
+ *
+ * The semantics are precise and arity-based:
+ *
+ * - Without an `initial` argument the ref holds `undefined` until the source
+ *   changes for the first time.
+ * - With an `initial` argument (including an explicit `undefined` when
+ *   `Value` allows it) the ref holds that value until the first change, and
+ *   the return type never widens with `undefined`.
+ * - Every synchronous write is observed (`flush: "sync"`), so a sequence of
+ *   writes in one tick shifts the previous value step by step instead of
+ *   collapsing into one batch.
+ * - Writes whose value is `Object.is`-equal to the current value do not
+ *   count as changes, matching Vue's own change detection.
+ * - Tracking is shallow: reassignments are observed, in-place mutations of
+ *   object values are not.
+ *
+ * Safe during server rendering: no browser globals are read and no timers
+ * start. The underlying watcher is bound to the current reactive scope and
+ * stops with it; call inside an active scope, or the watcher lives as long
+ * as the source. A plain non-reactive source never changes, so the ref stays
+ * at its initial value.
+ *
+ * @example
+ * ```ts
+ * const route = shallowRef("/home");
+ * const previousRoute = usePrevious(route, "/");
+ * route.value = "/settings";
+ * previousRoute.value; // "/home"
+ * ```
+ *
+ * @param source Reactive source to observe.
+ * @param initial Value reported before the first change.
+ * @returns Readonly shallow ref holding the previous source value.
+ */
+export function usePrevious<Value>(
+  source: MaybeRefOrGetter<Value>,
+): Readonly<ShallowRef<Value | undefined>>;
+export function usePrevious<Value>(
+  source: MaybeRefOrGetter<Value>,
+  initial: Value,
+): Readonly<ShallowRef<Value>>;
+export function usePrevious<Value>(
+  source: MaybeRefOrGetter<Value>,
+  ...initial: readonly [] | readonly [Value]
+): Readonly<ShallowRef<Value | undefined>> {
+  const previous = shallowRef<Value | undefined>(initial.length === 1 ? initial[0] : undefined);
+
+  watch(
+    () => toValue(source),
+    (_next, replaced) => {
+      previous.value = replaced;
+    },
+    { flush: "sync" },
+  );
+
+  return previous;
+}

package/registry/files/use-push-subscription.ts

@@ -0,0 +1,352 @@
+import {
+  computed,
+  hasInjectionContext,
+  readonly,
+  shallowReadonly,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Push permission states. */
+export type PushPermissionState = "granted" | "denied" | "prompt";
+
+/** JSON form of a push subscription (`PushSubscription.toJSON()`). */
+export interface PushSubscriptionJsonLike {
+  /** Push service endpoint. */
+  readonly endpoint?: string | undefined;
+
+  /** Expiration time in epoch milliseconds, if any. */
+  readonly expirationTime?: number | null | undefined;
+
+  /** Base64url-encoded keys (`p256dh`, `auth`). */
+  readonly keys?: Readonly<Record<string, string>> | undefined;
+}
+
+/** Minimal `PushSubscription` consumed by {@link usePushSubscription}. */
+export interface PushSubscriptionLike {
+  /** Push service endpoint. */
+  readonly endpoint: string;
+
+  /** Expiration time in epoch milliseconds, if any. */
+  readonly expirationTime: number | null;
+
+  /** Serialize for a server. */
+  toJSON(): PushSubscriptionJsonLike;
+
+  /** Cancel the subscription. */
+  unsubscribe(): Promise<boolean>;
+}
+
+/** Options forwarded to `PushManager.subscribe`. */
+export interface PushManagerSubscribeOptions {
+  /** VAPID public key bytes. */
+  readonly applicationServerKey: BufferSource;
+
+  /** Only user-visible notifications. */
+  readonly userVisibleOnly: boolean;
+}
+
+/** Minimal `PushManager` consumed by {@link usePushSubscription}. */
+export interface PushManagerLike {
+  /** Create (or return the existing) subscription. */
+  subscribe(options: PushManagerSubscribeOptions): Promise<PushSubscriptionLike>;
+
+  /** Current subscription, if any. */
+  getSubscription(): Promise<PushSubscriptionLike | null>;
+
+  /** Permission state for push. */
+  permissionState(options?: { readonly userVisibleOnly?: boolean }): Promise<PushPermissionState>;
+}
+
+/** Registration-like owner of a push manager. */
+export interface PushRegistrationLike {
+  /** The registration's push manager. */
+  readonly pushManager: PushManagerLike;
+}
+
+/** Options for {@link usePushSubscription}. */
+export interface UsePushSubscriptionOptions {
+  /**
+   * Service worker registration owning the push manager. `null` while it is
+   * not known yet.
+   *
+   * @default window.navigator.serviceWorker.ready when push is available
+   */
+  readonly registration?: MaybeRefOrGetter<PushRegistrationLike | null | undefined>;
+
+  /**
+   * Load the existing subscription as soon as a registration is known.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+}
+
+/** Arguments of {@link PushSubscriptionControls.subscribe}. */
+export interface PushSubscribeOptions {
+  /** VAPID public key as a base64url string or raw bytes. */
+  readonly applicationServerKey: string | BufferSource;
+
+  /**
+   * Only user-visible notifications (required by most browsers).
+   *
+   * @default true
+   */
+  readonly userVisibleOnly?: boolean;
+}
+
+/** Serializable snapshot of the current subscription. */
+export interface PushSubscriptionSnapshot {
+  /** Push service endpoint. */
+  readonly endpoint: string;
+
+  /** Expiration time in epoch milliseconds, or `null`. */
+  readonly expirationTime: number | null;
+
+  /** Base64url-encoded keys (`p256dh`, `auth`). */
+  readonly keys: Readonly<Record<string, string>>;
+}
+
+/** Reactive state and actions returned by {@link usePushSubscription}. */
+export interface PushSubscriptionControls {
+  /** Whether the Push API is available. */
+  readonly supported: ComputedRef<boolean>;
+
+  /** Current subscription, or `null`. */
+  readonly subscription: Readonly<ShallowRef<PushSubscriptionLike | null>>;
+
+  /** JSON snapshot of the current subscription, or `null`. */
+  readonly json: ComputedRef<PushSubscriptionSnapshot | null>;
+
+  /** Most recent failure, cleared by the next successful action. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+
+  /**
+   * Subscribe to push messages. Rejects with a tagged `TypeError` when the
+   * key string is not valid base64url.
+   *
+   * @param options VAPID key and visibility flag.
+   * @returns The subscription, or `null` when unsupported or on failure.
+   */
+  readonly subscribe: (options: PushSubscribeOptions) => Promise<PushSubscriptionLike | null>;
+
+  /**
+   * Cancel the current subscription.
+   *
+   * @returns Whether a subscription was cancelled.
+   */
+  readonly unsubscribe: () => Promise<boolean>;
+
+  /**
+   * Re-read the existing subscription.
+   *
+   * @returns The subscription, or `null`.
+   */
+  readonly refresh: () => Promise<PushSubscriptionLike | null>;
+
+  /**
+   * Query the push permission state.
+   *
+   * @param userVisibleOnly Query for user-visible pushes.
+   * @default userVisibleOnly true
+   * @returns The permission state, or `"unsupported"`.
+   */
+  readonly permissionState: (
+    userVisibleOnly?: boolean,
+  ) => Promise<PushPermissionState | "unsupported">;
+}
+
+const base64UrlAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+function decodeApplicationServerKey(text: string): Uint8Array<ArrayBuffer> {
+  const clean = text.trim().replace(/=+$/u, "").replaceAll("+", "-").replaceAll("/", "_");
+  const invalid = (): TypeError =>
+    new TypeError(
+      "[VIZE_COMPOSE_PUSH_INVALID_KEY] applicationServerKey must be a base64url string.",
+    );
+  if (clean.length % 4 === 1) throw invalid();
+  const bytes = new Uint8Array(Math.floor((clean.length * 3) / 4));
+  let buffer = 0;
+  let bits = 0;
+  let offset = 0;
+  for (const character of clean) {
+    const value = base64UrlAlphabet.indexOf(character);
+    if (value === -1) throw invalid();
+    buffer = ((buffer << 6) | value) & 0xffffff;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[offset] = (buffer >> bits) & 0xff;
+      offset += 1;
+    }
+  }
+  return bytes;
+}
+
+interface ReadyContainer {
+  readonly ready: Promise<PushRegistrationLike>;
+}
+
+function browserContainer(): ReadyContainer | undefined {
+  if (typeof window === "undefined" || !("PushManager" in window)) return undefined;
+  const { navigator } = window;
+  return "serviceWorker" in navigator && navigator.serviceWorker
+    ? navigator.serviceWorker
+    : undefined;
+}
+
+/**
+ * Manage a Web Push subscription.
+ *
+ * Uses the push manager of `options.registration`, or of
+ * `navigator.serviceWorker.ready` by default. The existing subscription is
+ * loaded when the registration becomes known; `subscribe` accepts the VAPID
+ * key as a base64url string. `json` is the snapshot to send to a push server.
+ * Nothing needs cleanup; pending results are ignored after the owning
+ * reactive scope stops.
+ *
+ * Server rendering: nothing is read, `supported` is false and the
+ * subscription is `null`.
+ * Inside a component the host is resolved after mounting, so hydration
+ * renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const push = usePushSubscription();
+ * const enable = async () => {
+ *   await push.subscribe({ applicationServerKey: VAPID_PUBLIC_KEY });
+ *   await fetch("/api/push", { method: "POST", body: JSON.stringify(push.json.value) });
+ * };
+ * ```
+ *
+ * @param options Registration override and initial read policy.
+ * @default options {}
+ * @returns Subscription state and actions.
+ */
+export function usePushSubscription(
+  options: UsePushSubscriptionOptions = {},
+): PushSubscriptionControls {
+  const subscription = shallowRef<PushSubscriptionLike | null>(null);
+  const error = shallowRef<unknown>(undefined);
+  let active = true;
+
+  // Inside a component the host is resolved only after mounting, so a
+  // hydrating client renders the server's unsupported state first. Outside
+  // components it resolves synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+
+  const source = (): PushRegistrationLike | ReadyContainer | undefined => {
+    if (!hydrated.value) return undefined;
+    return options.registration === undefined
+      ? browserContainer()
+      : (toValue(options.registration) ?? undefined);
+  };
+
+  const resolveManager = async (): Promise<PushManagerLike | undefined> => {
+    const current = source();
+    if (!current) return undefined;
+    return "pushManager" in current ? current.pushManager : (await current.ready).pushManager;
+  };
+
+  const attempt = async <Value>(
+    fallback: Value,
+    action: (manager: PushManagerLike) => Promise<Value>,
+  ): Promise<Value> => {
+    try {
+      const manager = await resolveManager();
+      if (!manager) return fallback;
+      const value = await action(manager);
+      if (active) error.value = undefined;
+      return value;
+    } catch (cause) {
+      if (active) error.value = cause;
+      return fallback;
+    }
+  };
+
+  const refresh = (): Promise<PushSubscriptionLike | null> =>
+    attempt(null, async (manager) => {
+      const current = await manager.getSubscription();
+      if (active) subscription.value = current;
+      return current;
+    });
+
+  const subscribe = async ({
+    applicationServerKey,
+    userVisibleOnly = true,
+  }: PushSubscribeOptions): Promise<PushSubscriptionLike | null> => {
+    const key =
+      typeof applicationServerKey === "string"
+        ? decodeApplicationServerKey(applicationServerKey)
+        : applicationServerKey;
+    return attempt(null, async (manager) => {
+      const next = await manager.subscribe({ applicationServerKey: key, userVisibleOnly });
+      if (active) subscription.value = next;
+      return next;
+    });
+  };
+
+  const unsubscribe = async (): Promise<boolean> => {
+    const current = subscription.value;
+    if (!current) return false;
+    try {
+      const removed = await current.unsubscribe();
+      if (active && removed && subscription.value === current) subscription.value = null;
+      if (active) error.value = undefined;
+      return removed;
+    } catch (cause) {
+      if (active) error.value = cause;
+      return false;
+    }
+  };
+
+  const permissionState = (userVisibleOnly = true): Promise<PushPermissionState | "unsupported"> =>
+    attempt<PushPermissionState | "unsupported">("unsupported", (manager) =>
+      manager.permissionState({ userVisibleOnly }),
+    );
+
+  if (options.immediate ?? true) {
+    watch(
+      source,
+      (current) => {
+        if (current) void refresh();
+        else subscription.value = null;
+      },
+      { immediate: true },
+    );
+  }
+
+  tryOnScopeDispose(() => {
+    active = false;
+  });
+
+  return {
+    supported: computed(() => source() !== undefined),
+    subscription: shallowReadonly(subscription),
+    json: computed(() => {
+      const current = subscription.value;
+      if (!current) return null;
+      const serialized = current.toJSON();
+      return {
+        endpoint: serialized.endpoint ?? current.endpoint,
+        expirationTime: serialized.expirationTime ?? current.expirationTime,
+        keys: serialized.keys ?? {},
+      };
+    }),
+    error: readonly(error),
+    subscribe,
+    unsubscribe,
+    refresh,
+    permissionState,
+  };
+}