@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/color-mode.ts

@@ -0,0 +1,274 @@
+import { computed, hasInjectionContext, onMounted, shallowRef, watch } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, WritableComputedRef } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { useMediaQuery } from "./media-query.ts";
+import type { MediaQueryHost } from "./media-query.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+import type { StorageLike } from "./use-storage.ts";
+
+/** Built-in color modes. */
+export type BasicColorMode = "light" | "dark";
+
+/** Selectable mode: a built-in mode, a custom mode, or `"auto"` (follow the system). */
+export type ColorModeValue<Custom extends string = never> = BasicColorMode | Custom | "auto";
+
+/**
+ * Synchronous key-value persistence used by {@link useColorMode}.
+ *
+ * The read/write subset of `StorageLike` from `./use-storage`, so
+ * `localStorage`, `sessionStorage`, and the same adapters work for both. For
+ * hydration-stable SSR pass a cookie-backed adapter that reads the request
+ * cookie on the server and `document.cookie` on the client.
+ */
+export type ColorModeStorage = Pick<StorageLike, "getItem" | "setItem">;
+
+/** Options for {@link useColorMode}. */
+export interface UseColorModeOptions<Custom extends string = never> {
+  /**
+   * Class name (or attribute value) written for each mode. Custom modes must
+   * be listed here.
+   *
+   * @default { light: "light", dark: "dark" }
+   */
+  readonly modes?: Readonly<Partial<Record<BasicColorMode, string>> & Record<Custom, string>>;
+
+  /**
+   * `"class"` toggles class names; any other value is used as an attribute
+   * name (e.g. `"data-theme"`).
+   *
+   * @default "class"
+   */
+  readonly attribute?: string;
+
+  /**
+   * Element that receives the class/attribute.
+   *
+   * @default document.documentElement when available
+   */
+  readonly target?: MaybeElementTarget;
+
+  /**
+   * Mode used when nothing is stored.
+   *
+   * @default "auto"
+   */
+  readonly initialValue?: ColorModeValue<Custom>;
+
+  /**
+   * Storage key. `null` disables persistence.
+   *
+   * @default "vize-color-mode"
+   */
+  readonly storageKey?: string | null;
+
+  /**
+   * Persistence adapter. `null` disables persistence.
+   *
+   * @default globalThis.window.localStorage when available
+   */
+  readonly storage?: ColorModeStorage | null;
+
+  /**
+   * System preference assumed while no media capability exists (server rendering).
+   *
+   * @default "light"
+   */
+  readonly ssrSystem?: BasicColorMode;
+
+  /**
+   * Suppress CSS transitions for one frame while switching modes.
+   *
+   * @default true
+   */
+  readonly disableTransition?: boolean;
+
+  /**
+   * Media capability used to read `prefers-color-scheme`.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<MediaQueryHost | null | undefined>;
+}
+
+/** Reactive color mode returned by {@link useColorMode}. */
+export interface ColorModeControls<Custom extends string> {
+  /** Selected mode, including `"auto"`. Assigning persists and applies it. */
+  readonly mode: WritableComputedRef<ColorModeValue<Custom>>;
+  /** System preference from `prefers-color-scheme`. */
+  readonly system: ComputedRef<BasicColorMode>;
+  /** Resolved mode (`"auto"` replaced by the system preference). */
+  readonly state: ComputedRef<BasicColorMode | Custom>;
+  /** Value read from storage at creation (or the initial value). */
+  readonly stored: ComputedRef<ColorModeValue<Custom>>;
+}
+
+/**
+ * Reactive color mode with persistence and DOM application.
+ *
+ * The stored mode is read synchronously during setup through the injected
+ * storage, so a cookie adapter yields identical server and client renders.
+ * On the client the resolved mode is written to the target's class list (or
+ * attribute) after each change, optionally with transitions suppressed.
+ * Nothing touches the DOM during server rendering.
+ *
+ * @param options Modes, target, persistence, SSR fallback, and capabilities.
+ * @default options {}
+ * @returns Writable mode plus system and resolved state.
+ */
+export function useColorMode<const Custom extends string = never>(
+  options: UseColorModeOptions<Custom> = {},
+): ColorModeControls<Custom> {
+  const modes: Readonly<Record<string, string>> = {
+    light: "light",
+    dark: "dark",
+    ...options.modes,
+  };
+  const attribute = options.attribute ?? "class";
+  const storageKey = options.storageKey === undefined ? "vize-color-mode" : options.storageKey;
+  const storage = options.storage === undefined ? browserStorage() : options.storage;
+  const initial = options.initialValue ?? "auto";
+  const isMode = (value: string | null): value is ColorModeValue<Custom> =>
+    value === "auto" || (value !== null && Object.hasOwn(modes, value));
+
+  const read = (): ColorModeValue<Custom> => {
+    if (!storage || storageKey === null) return initial;
+    try {
+      const value = storage.getItem(storageKey);
+      return isMode(value) ? value : initial;
+    } catch {
+      return initial;
+    }
+  };
+  // Inside a component the stored mode is read once it has mounted, so a
+  // hydrating client first renders `initialValue` exactly like the server.
+  const deferRead = hasInjectionContext();
+  const storedValue = shallowRef<ColorModeValue<Custom>>(deferRead ? initial : read());
+  const selectedRaw = shallowRef<string>(storedValue.value);
+  if (deferRead) {
+    onMounted(() => {
+      const value = read();
+      storedValue.value = value;
+      // Keep a mode the user picked before mounting.
+      if (selectedRaw.value === initial) selectedRaw.value = value;
+    });
+  }
+  const selected = computed<ColorModeValue<Custom>>(() =>
+    isMode(selectedRaw.value) ? selectedRaw.value : initial,
+  );
+  const prefersDark = useMediaQuery(
+    "(prefers-color-scheme: dark)",
+    options.host === undefined
+      ? { ssrValue: options.ssrSystem === "dark" }
+      : { ssrValue: options.ssrSystem === "dark", host: options.host },
+  );
+  const system = computed<BasicColorMode>(() => (prefersDark.value ? "dark" : "light"));
+  const state = computed<BasicColorMode | Custom>(() =>
+    selected.value === "auto" ? system.value : selected.value,
+  );
+
+  const target = (): Element | null =>
+    options.target === undefined
+      ? typeof document !== "undefined"
+        ? document.documentElement
+        : null
+      : resolveElement(options.target);
+
+  const stop = watch(
+    [state, target],
+    ([resolved, element]) => {
+      if (!element) return;
+      const restore =
+        options.disableTransition === false ? undefined : suppressTransitions(element);
+      const value = modes[resolved] ?? resolved;
+      if (attribute === "class") {
+        for (const name of Object.values(modes)) {
+          for (const token of name.split(/\s+/)) if (token) element.classList.remove(token);
+        }
+        for (const token of value.split(/\s+/)) if (token) element.classList.add(token);
+      } else {
+        element.setAttribute(attribute, value);
+      }
+      restore?.();
+    },
+    { immediate: true, flush: "post" },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  const mode = computed<ColorModeValue<Custom>>({
+    get: () => selected.value,
+    set: (next) => {
+      selectedRaw.value = next;
+      if (!storage || storageKey === null) return;
+      try {
+        storage.setItem(storageKey, next);
+      } catch {
+        // Persistence is best-effort (quota, privacy mode); the in-memory mode still applies.
+      }
+    },
+  });
+
+  return { mode, system, state, stored: computed(() => storedValue.value) };
+}
+
+/** Options for {@link useDark}. */
+export interface UseDarkOptions extends Omit<UseColorModeOptions, "modes"> {
+  /**
+   * Class/attribute value applied in dark mode.
+   *
+   * @default "dark"
+   */
+  readonly valueDark?: string;
+
+  /**
+   * Class/attribute value applied in light mode.
+   *
+   * @default ""
+   */
+  readonly valueLight?: string;
+}
+
+/**
+ * Boolean dark-mode switch built on {@link useColorMode}.
+ *
+ * Setting the ref to the current system preference stores `"auto"`, so the
+ * page keeps following the system until the user picks the opposite mode.
+ *
+ * @param options Dark/light values plus {@link useColorMode} options.
+ * @default options {}
+ * @returns Writable dark flag.
+ */
+export function useDark(options: UseDarkOptions = {}): WritableComputedRef<boolean> {
+  const { valueDark = "dark", valueLight = "", ...rest } = options;
+  const colorMode = useColorMode({ ...rest, modes: { dark: valueDark, light: valueLight } });
+  return computed({
+    get: () => colorMode.state.value === "dark",
+    set: (dark: boolean) => {
+      const preferred: BasicColorMode = dark ? "dark" : "light";
+      colorMode.mode.value = preferred === colorMode.system.value ? "auto" : preferred;
+    },
+  });
+}
+
+function suppressTransitions(element: Element): (() => void) | undefined {
+  const document = element.ownerDocument;
+  const head = document?.head;
+  if (!head || typeof document.createElement !== "function") return undefined;
+  const style = document.createElement("style");
+  style.textContent = "*,*::before,*::after{transition:none!important}";
+  head.appendChild(style);
+  return () => {
+    void document.defaultView?.getComputedStyle(style).opacity;
+    style.remove();
+  };
+}
+
+function browserStorage(): ColorModeStorage | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}

package/registry/files/computed-async.ts

@@ -0,0 +1,123 @@
+import { computed, shallowRef, watchEffect } from "vue";
+import type { Ref } from "vue";
+
+/** Registers a callback run when the current evaluation becomes stale. */
+export type ComputedAsyncCancel = (onCancel: () => void) => void;
+
+/** Context handed to a {@link computedAsync} evaluator. */
+export interface ComputedAsyncContext {
+  /** Aborted as soon as a newer evaluation starts or the scope stops. */
+  readonly signal: AbortSignal;
+
+  /** Register a callback for when this evaluation becomes stale. */
+  readonly onCancel: ComputedAsyncCancel;
+}
+
+/** Options for {@link computedAsync}. */
+export interface ComputedAsyncOptions {
+  /**
+   * Defer the first evaluation until the value is read.
+   *
+   * @default false
+   */
+  readonly lazy?: boolean;
+
+  /**
+   * Ref that is `true` while an evaluation is in flight.
+   *
+   * @default an internal ref
+   */
+  readonly evaluating?: Ref<boolean>;
+
+  /**
+   * Receives evaluator failures; the previous value is kept.
+   *
+   * @default undefined (failures are dropped)
+   */
+  readonly onError?: (error: unknown) => void;
+}
+
+/**
+ * Computed value backed by an async evaluator.
+ *
+ * Reactive dependencies read synchronously in the evaluator (before its
+ * first `await`) are tracked; when one changes, the previous evaluation is
+ * cancelled (its `signal` aborts and `onCancel` callbacks run) and a new one
+ * starts. Only the newest evaluation may write the result, so out-of-order
+ * responses can never win. The value holds `initial` until the first
+ * evaluation settles, which also keeps server and client markup identical
+ * during hydration (the server never waits for the promise). Results are
+ * stored shallowly: replace the value instead of mutating it.
+ *
+ * @example
+ * ```ts
+ * const user = computedAsync(
+ *   async ({ signal }) => (await fetch(`/users/${id.value}`, { signal })).json(),
+ *   null,
+ * );
+ * ```
+ *
+ * @param evaluator Async (or sync) producer of the value.
+ * @param initial Value before the first evaluation settles.
+ * @param options Laziness, evaluating flag, and error hook.
+ * @default options {}
+ * @returns Readonly ref holding the newest settled value.
+ */
+export function computedAsync<Value>(
+  evaluator: (context: ComputedAsyncContext) => Value | Promise<Value>,
+  initial: Value,
+  options?: ComputedAsyncOptions,
+): Readonly<Ref<Value>>;
+export function computedAsync<Value>(
+  evaluator: (context: ComputedAsyncContext) => Value | Promise<Value>,
+  initial?: undefined,
+  options?: ComputedAsyncOptions,
+): Readonly<Ref<Value | undefined>>;
+export function computedAsync<Value>(
+  evaluator: (context: ComputedAsyncContext) => Value | Promise<Value>,
+  initial?: Value,
+  options: ComputedAsyncOptions = {},
+): Readonly<Ref<Value | undefined>> {
+  const started = shallowRef(!(options.lazy ?? false));
+  const current = shallowRef<Value | undefined>(initial);
+  const evaluating = options.evaluating ?? shallowRef(false);
+  let generation = 0;
+
+  watchEffect(async (onCleanup) => {
+    if (!started.value) return;
+    generation += 1;
+    const own = generation;
+    const controller = new AbortController();
+    const cancelCallbacks: (() => void)[] = [];
+    let settled = false;
+    onCleanup(() => {
+      if (settled) return;
+      controller.abort();
+      for (const callback of cancelCallbacks) callback();
+    });
+
+    evaluating.value = true;
+    try {
+      const result = await evaluator({
+        signal: controller.signal,
+        onCancel: (callback) => {
+          cancelCallbacks.push(callback);
+        },
+      });
+      if (own === generation) current.value = result;
+    } catch (error) {
+      if (own === generation) options.onError?.(error);
+    } finally {
+      settled = true;
+      if (own === generation) evaluating.value = false;
+    }
+  });
+
+  if (options.lazy ?? false) {
+    return computed(() => {
+      started.value = true;
+      return current.value;
+    });
+  }
+  return current;
+}

package/registry/files/computed-with-control.ts

@@ -0,0 +1,80 @@
+import { customRef, watch } from "vue";
+import type { Ref, WatchSource } from "vue";
+
+/** Readonly cached value plus a manual invalidation trigger. */
+export interface ComputedWithControl<Value> extends Readonly<Ref<Value>> {
+  /** Mark the cached value stale; the next read recomputes it. */
+  readonly trigger: () => void;
+}
+
+/** Explicit dependency accepted by {@link computedWithControl}: anything Vue's `watch` accepts. */
+export type ComputedWithControlSource =
+  | WatchSource<unknown>
+  | object
+  | readonly (WatchSource<unknown> | object)[];
+
+/** Options for {@link computedWithControl}. */
+export interface ComputedWithControlOptions {
+  /**
+   * Invalidate on nested changes of the explicit sources.
+   *
+   * @default false
+   */
+  readonly deep?: boolean;
+}
+
+/**
+ * Computed value whose dependencies are declared explicitly.
+ *
+ * Only changes of `source` (or a manual {@link ComputedWithControl.trigger})
+ * invalidate the cache; reactive reads inside `getter` do not. Useful when
+ * the getter reads non-reactive data or should ignore some reactive reads.
+ * The getter receives the previous value and runs lazily on the next read.
+ * Pure derived state: SSR-safe; the invalidation watcher follows the owning
+ * reactive scope.
+ *
+ * @example
+ * ```ts
+ * const snapshot = computedWithControl(version, () => expensiveRead(store));
+ * snapshot.trigger(); // force a refresh
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param getter Produces the value from the previous one.
+ * @param options Depth of the source watch.
+ * @default options {}
+ * @returns The controlled computed ref.
+ */
+export function computedWithControl<Value>(
+  source: ComputedWithControlSource,
+  getter: (previous: Value | undefined) => Value,
+  options: ComputedWithControlOptions = {},
+): ComputedWithControl<Value> {
+  let dirty = true;
+  let cached: { readonly value: Value } | undefined;
+  let notify = (): void => undefined;
+
+  const invalidate = (): void => {
+    dirty = true;
+    notify();
+  };
+
+  watch(source, invalidate, { flush: "sync", deep: options.deep ?? false });
+
+  const value = customRef<Value>((track, trigger) => {
+    notify = trigger;
+    return {
+      get: () => {
+        track();
+        if (dirty || cached === undefined) {
+          cached = { value: getter(cached?.value) };
+          dirty = false;
+        }
+        return cached.value;
+      },
+      set: () => undefined,
+    };
+  });
+
+  return Object.assign(value, { trigger: invalidate });
+}

package/registry/files/create-event-hook.ts

@@ -0,0 +1,139 @@
+import { hasInjectionContext } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Listener registered on an {@link EventHook}. */
+export type EventHookListener<Arguments extends readonly unknown[]> = (
+  ...args: Arguments
+) => unknown;
+
+/** Registration handle returned by {@link EventHook.on}. */
+export interface EventHookSubscription {
+  /** Remove the listener. Idempotent. */
+  readonly off: () => void;
+}
+
+/** Options for {@link createEventHook}. */
+export interface CreateEventHookOptions {
+  /**
+   * What `on()` does when a hook created outside any component (a
+   * module-level hook shared by every request) is subscribed to from a
+   * component `setup` during server rendering. Vue never disposes server
+   * component scopes, so such listeners would accumulate across requests
+   * and keep every rendered component alive.
+   *
+   * - `"ignore"`: skip the registration (the returned `off` is a no-op) and
+   *   warn once in development.
+   * - `"register"`: register anyway; the caller must call `off()`.
+   *
+   * Hooks created inside a component (request-local hooks) are unaffected.
+   *
+   * @default "ignore"
+   */
+  readonly serverListeners?: "ignore" | "register";
+}
+
+/** Typed event emitter created by {@link createEventHook}. */
+export interface EventHook<Arguments extends readonly unknown[] = []> {
+  /**
+   * Add a listener. Inside an effect scope it is removed automatically when
+   * the scope stops. Adding the same function twice registers it once.
+   */
+  readonly on: (listener: EventHookListener<Arguments>) => EventHookSubscription;
+
+  /** Remove a listener. */
+  readonly off: (listener: EventHookListener<Arguments>) => void;
+
+  /**
+   * Call every listener with `args`, in registration order.
+   *
+   * @returns Settles with every listener's (awaited) result.
+   */
+  readonly trigger: (...args: Arguments) => Promise<unknown[]>;
+
+  /** Remove every listener. */
+  readonly clear: () => void;
+
+  /** Number of registered listeners. */
+  readonly size: () => number;
+}
+
+/**
+ * Create a small, strongly typed event emitter.
+ *
+ * The payload is a tuple type, so events can carry several named arguments
+ * (`createEventHook<[id: string, value: number]>()`) and `trigger` checks
+ * them. Listeners registered inside an effect scope unsubscribe themselves
+ * when it stops. Synchronous listener errors propagate from `trigger`;
+ * async rejections reject the returned promise.
+ *
+ * SSR: Vue does not dispose component scopes after a server render, so a
+ * listener that a server `setup` adds to a module-level hook would never be
+ * removed and would pile up once per request. By default such registrations
+ * are therefore skipped (with a one-time development warning); see
+ * {@link CreateEventHookOptions.serverListeners}. Hooks created inside a
+ * component, and every registration in the browser, behave normally.
+ *
+ * @example
+ * ```ts
+ * const saved = createEventHook<[id: string]>();
+ * saved.on((id) => toast(`Saved ${id}`));
+ * await saved.trigger("doc-1");
+ * ```
+ *
+ * @param options Server-side registration policy.
+ * @default options {}
+ * @returns The event hook.
+ */
+export function createEventHook<Arguments extends readonly unknown[] = []>(
+  options: CreateEventHookOptions = {},
+): EventHook<Arguments> {
+  const listeners = new Set<EventHookListener<Arguments>>();
+  // A hook created outside any component is shared by every server request.
+  // `hasInjectionContext()` also detects Vapor components, where the public
+  // current-instance getter returns `null`.
+  const shared = !hasInjectionContext();
+  let warned = false;
+
+  const off = (listener: EventHookListener<Arguments>): void => {
+    listeners.delete(listener);
+  };
+
+  const on = (listener: EventHookListener<Arguments>): EventHookSubscription => {
+    if (
+      shared &&
+      (options.serverListeners ?? "ignore") === "ignore" &&
+      typeof window === "undefined" &&
+      hasInjectionContext()
+    ) {
+      if (!warned && isDevelopment()) {
+        warned = true;
+        console.warn(
+          '[VIZE_COMPOSE_EVENT_HOOK_SERVER_LISTENER] a module-level event hook was subscribed to during server rendering; the listener was skipped because server component scopes are never disposed. Create the hook inside the component tree, or pass { serverListeners: "register" } and call off() yourself.',
+        );
+      }
+      return { off: () => undefined };
+    }
+    listeners.add(listener);
+    const subscription = { off: () => off(listener) };
+    tryOnScopeDispose(subscription.off);
+    return subscription;
+  };
+
+  const trigger = (...args: Arguments): Promise<unknown[]> =>
+    Promise.all([...listeners].map((listener) => listener(...args)));
+
+  return {
+    on,
+    off,
+    trigger,
+    clear: () => {
+      listeners.clear();
+    },
+    size: () => listeners.size,
+  };
+}
+
+function isDevelopment(): boolean {
+  return typeof process === "undefined" || process.env["NODE_ENV"] !== "production";
+}

package/registry/files/create-global-state.ts

@@ -0,0 +1,34 @@
+import { effectScope } from "vue";
+
+/**
+ * Lift a state factory into application-wide state shared by every caller.
+ *
+ * The factory runs once, lazily on the first call, inside a detached effect
+ * scope so its watchers and computeds outlive any component; every later
+ * call returns the same state. Because the state is module-level, it is
+ * shared across all server requests: on the server, keep per-request state
+ * in `provide`/`createInjectionState` instead, or reset it per request.
+ *
+ * @example
+ * ```ts
+ * const useSession = createGlobalState(() => ({ user: shallowRef<User | null>(null) }));
+ * useSession().user.value = currentUser;
+ * ```
+ *
+ * @param factory Creates the state; may use any composable.
+ * @throws `Error` tagged `VIZE_COMPOSE_GLOBAL_STATE_INACTIVE_SCOPE` if the
+ * private scope cannot run (never expected in practice).
+ * @returns Accessor returning the shared state.
+ */
+export function createGlobalState<State>(factory: () => State): () => State {
+  let created: { readonly state: State } | undefined;
+  return () => {
+    if (created === undefined) {
+      created = effectScope(true).run(() => ({ state: factory() }));
+      if (created === undefined) {
+        throw new Error("[VIZE_COMPOSE_GLOBAL_STATE_INACTIVE_SCOPE] the state scope did not run");
+      }
+    }
+    return created.state;
+  };
+}