@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/pointer-lock.ts

@@ -0,0 +1,232 @@
+import {
+  hasInjectionContext,
+  readonly,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Document-like capability used by {@link usePointerLock}. */
+export interface PointerLockHost extends EventTarget {
+  /** Element that currently holds the pointer lock. */
+  readonly pointerLockElement: Element | null;
+  /** Release the pointer lock. */
+  exitPointerLock(): void;
+}
+
+/** Stable error codes rejected by {@link PointerLockControls.lock} and `unlock`. */
+export type PointerLockErrorCode =
+  | "VIZE_COMPOSE_POINTER_LOCK_UNSUPPORTED"
+  | "VIZE_COMPOSE_POINTER_LOCK_NO_TARGET"
+  | "VIZE_COMPOSE_POINTER_LOCK_FAILED";
+
+/** Error thrown when pointer lock cannot be acquired or released. */
+export class PointerLockError extends Error {
+  /** Machine-readable failure code. */
+  readonly code: PointerLockErrorCode;
+
+  /**
+   * @param code Machine-readable failure code.
+   * @param message Human-readable explanation.
+   */
+  constructor(code: PointerLockErrorCode, message: string) {
+    super(message);
+    this.name = "PointerLockError";
+    this.code = code;
+  }
+}
+
+/** Options for {@link usePointerLock}. */
+export interface UsePointerLockOptions {
+  /**
+   * Request raw (unaccelerated) movement deltas where supported.
+   *
+   * @default false
+   */
+  readonly unadjustedMovement?: boolean;
+
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<PointerLockHost | null | undefined>;
+}
+
+/** Reactive state and actions returned by {@link usePointerLock}. */
+export interface PointerLockControls {
+  /** Whether the host supports pointer lock. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Element currently holding the lock (any element, not only the target). */
+  readonly element: Readonly<ShallowRef<Element | null>>;
+  /** Whether the composable's own target holds the lock. */
+  readonly isLocked: Readonly<Ref<boolean>>;
+  /**
+   * Lock the pointer to `target` (or the composable target).
+   *
+   * @returns The locked element once `pointerlockchange` confirms the lock.
+   */
+  readonly lock: (target?: MaybeElementTarget) => Promise<Element>;
+  /**
+   * Release the lock.
+   *
+   * @returns Whether a lock was held and released.
+   */
+  readonly unlock: () => Promise<boolean>;
+}
+
+/**
+ * Reactive wrapper around the Pointer Lock API.
+ *
+ * Tracks `pointerlockchange` on the document and exposes promise-based lock
+ * and unlock actions that settle on the platform confirmation events.
+ * Rejections are {@link PointerLockError}s with stable codes. Nothing runs
+ * during server rendering; listeners are removed with the owning scope.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param target Default reactive element to lock.
+ * @param options Movement mode and document capability.
+ * @default target undefined
+ * @default options {}
+ * @returns Support flag, lock state, and actions.
+ */
+export function usePointerLock(
+  target?: MaybeElementTarget,
+  options: UsePointerLockOptions = {},
+): PointerLockControls {
+  const isSupported = ref(false);
+  const element = shallowRef<Element | null>(null);
+  // Inside a component the host is attached by a post-flush job (after the
+  // component mounted), so a hydrating client first renders the same server
+  // fallback. Outside components it is attached synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+  const host = (): PointerLockHost | null | undefined =>
+    !hydrated.value
+      ? undefined
+      : options.host === undefined
+        ? browserPointerLockHost()
+        : toValue(options.host);
+
+  const stop = watch(
+    host,
+    (current, _previous, onCleanup) => {
+      isSupported.value = Boolean(current && "pointerLockElement" in current);
+      element.value = current?.pointerLockElement ?? null;
+      if (!current) return;
+      const onChange = (): void => {
+        element.value = current.pointerLockElement;
+      };
+      current.addEventListener("pointerlockchange", onChange);
+      onCleanup(() => current.removeEventListener("pointerlockchange", onChange));
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  const isLocked = ref(false);
+  watch(
+    [element, () => (target === undefined ? null : resolveElement(target))],
+    ([locked, own]) => {
+      isLocked.value = locked !== null && locked === own;
+    },
+    { immediate: true, flush: "sync" },
+  );
+
+  const lock = async (override?: MaybeElementTarget): Promise<Element> => {
+    const current = host();
+    if (!current || !isSupported.value) {
+      throw new PointerLockError(
+        "VIZE_COMPOSE_POINTER_LOCK_UNSUPPORTED",
+        "Pointer lock is not supported.",
+      );
+    }
+    const candidate = resolveElement(override ?? target);
+    if (!candidate || !isPointerLockable(candidate)) {
+      throw new PointerLockError(
+        "VIZE_COMPOSE_POINTER_LOCK_NO_TARGET",
+        "No lockable element resolved.",
+      );
+    }
+    const confirmed = waitFor(current, () => current.pointerLockElement === candidate);
+    try {
+      await candidate.requestPointerLock(
+        options.unadjustedMovement ? { unadjustedMovement: true } : undefined,
+      );
+    } catch (cause) {
+      confirmed.cancel();
+      throw new PointerLockError("VIZE_COMPOSE_POINTER_LOCK_FAILED", describe(cause));
+    }
+    await confirmed.promise;
+    return candidate;
+  };
+
+  const unlock = async (): Promise<boolean> => {
+    const current = host();
+    if (!current?.pointerLockElement) return false;
+    const confirmed = waitFor(current, () => current.pointerLockElement === null);
+    current.exitPointerLock();
+    await confirmed.promise;
+    return true;
+  };
+
+  return {
+    isSupported: readonly(isSupported),
+    element,
+    isLocked: readonly(isLocked),
+    lock,
+    unlock,
+  };
+}
+
+function waitFor(
+  host: PointerLockHost,
+  done: () => boolean,
+): { readonly promise: Promise<void>; readonly cancel: () => void } {
+  let cleanup = (): void => undefined;
+  const promise = new Promise<void>((resolve, reject) => {
+    const onChange = (): void => {
+      if (!done()) return;
+      cleanup();
+      resolve();
+    };
+    const onError = (): void => {
+      cleanup();
+      reject(
+        new PointerLockError("VIZE_COMPOSE_POINTER_LOCK_FAILED", "The pointer lock was refused."),
+      );
+    };
+    host.addEventListener("pointerlockchange", onChange);
+    host.addEventListener("pointerlockerror", onError);
+    cleanup = () => {
+      host.removeEventListener("pointerlockchange", onChange);
+      host.removeEventListener("pointerlockerror", onError);
+    };
+  });
+  return { promise, cancel: () => cleanup() };
+}
+
+function isPointerLockable(element: Element): boolean {
+  return typeof element.requestPointerLock === "function";
+}
+
+function describe(cause: unknown): string {
+  return cause instanceof Error ? cause.message : "The pointer lock request failed.";
+}
+
+function browserPointerLockHost(): PointerLockHost | undefined {
+  return typeof document !== "undefined" ? document : undefined;
+}

package/registry/files/pointer.ts

@@ -0,0 +1,153 @@
+import { readonly, ref, shallowReactive, shallowReadonly, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Pointer device kind reported by Pointer Events. */
+export type PointerKind = "mouse" | "touch" | "pen";
+
+/** Snapshot of the latest pointer event. */
+export interface PointerState {
+  /** Horizontal client coordinate. */
+  readonly x: number;
+  /** Vertical client coordinate. */
+  readonly y: number;
+  /** Normalized pressure in `[0, 1]`. */
+  readonly pressure: number;
+  /** Identifier of the pointer that produced the latest event. */
+  readonly pointerId: number;
+  /** Pen tilt around the Y axis in degrees. */
+  readonly tiltX: number;
+  /** Pen tilt around the X axis in degrees. */
+  readonly tiltY: number;
+  /** Contact geometry width in CSS pixels. */
+  readonly width: number;
+  /** Contact geometry height in CSS pixels. */
+  readonly height: number;
+  /** Pen rotation in degrees. */
+  readonly twist: number;
+  /** Device kind; `null` before the first event. */
+  readonly pointerType: PointerKind | null;
+}
+
+/** Options for {@link usePointer}. */
+export interface UsePointerOptions {
+  /**
+   * Device kinds to track.
+   *
+   * @default ["mouse", "touch", "pen"]
+   */
+  readonly pointerTypes?: readonly PointerKind[];
+
+  /**
+   * Event target to listen on.
+   *
+   * @default globalThis.window when available
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+
+  /**
+   * State exposed before any input and during server rendering.
+   *
+   * @default all numbers `0`, `pointerType: null`
+   */
+  readonly initialValue?: Partial<PointerState>;
+}
+
+/** Reactive pointer state returned by {@link usePointer}. */
+export interface PointerControls {
+  /** Latest pointer snapshot. */
+  readonly state: Readonly<PointerState>;
+  /** Whether the pointer is inside the target (between enter/move and leave). */
+  readonly isInside: Readonly<Ref<boolean>>;
+}
+
+/**
+ * Track the latest pointer (mouse, touch, or pen) state.
+ *
+ * Listens passively for `pointerdown`, `pointermove`, `pointerup`, and
+ * `pointerleave` on the reactive target and filters by device kind.
+ * Listeners are removed with the owning reactive scope; server renders expose
+ * the initial snapshot.
+ *
+ * @param options Device filter, target, and initial snapshot.
+ * @default options {}
+ * @returns Reactive snapshot and inside flag.
+ */
+export function usePointer(options: UsePointerOptions = {}): PointerControls {
+  const pointerTypes = options.pointerTypes ?? ["mouse", "touch", "pen"];
+  const state = shallowReactive<{ -readonly [Key in keyof PointerState]: PointerState[Key] }>({
+    x: 0,
+    y: 0,
+    pressure: 0,
+    pointerId: 0,
+    tiltX: 0,
+    tiltY: 0,
+    width: 0,
+    height: 0,
+    twist: 0,
+    pointerType: null,
+    ...options.initialValue,
+  });
+  const isInside = ref(false);
+
+  const onPointer = (event: Event): void => {
+    if (!isPointerEvent(event)) return;
+    const kind = toPointerKind(event.pointerType);
+    if (!kind || !pointerTypes.includes(kind)) return;
+    isInside.value = true;
+    state.x = event.clientX;
+    state.y = event.clientY;
+    state.pressure = event.pressure;
+    state.pointerId = event.pointerId;
+    state.tiltX = event.tiltX;
+    state.tiltY = event.tiltY;
+    state.width = event.width;
+    state.height = event.height;
+    state.twist = event.twist;
+    state.pointerType = kind;
+  };
+  const onLeave = (): void => {
+    isInside.value = false;
+  };
+
+  const stop = watch(
+    () => (options.target === undefined ? browserWindow() : toValue(options.target)),
+    (target, _previous, onCleanup) => {
+      if (!target) return;
+      const listenerOptions: AddEventListenerOptions = { passive: true };
+      for (const type of ["pointerdown", "pointermove", "pointerup"] as const) {
+        target.addEventListener(type, onPointer, listenerOptions);
+      }
+      target.addEventListener("pointerleave", onLeave, listenerOptions);
+      onCleanup(() => {
+        for (const type of ["pointerdown", "pointermove", "pointerup"] as const) {
+          target.removeEventListener(type, onPointer);
+        }
+        target.removeEventListener("pointerleave", onLeave);
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return { state: shallowReadonly(state), isInside: readonly(isInside) };
+}
+
+/**
+ * Narrow a platform `pointerType` string to the closed {@link PointerKind} union.
+ *
+ * @param value Raw `PointerEvent.pointerType`.
+ * @returns The matching kind, or `null` for unknown/future device kinds.
+ */
+export function toPointerKind(value: string): PointerKind | null {
+  return value === "mouse" || value === "touch" || value === "pen" ? value : null;
+}
+
+function isPointerEvent(event: Event): event is PointerEvent {
+  return "pointerId" in event && "pointerType" in event;
+}
+
+function browserWindow(): EventTarget | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/preferences.ts

@@ -0,0 +1,98 @@
+import { computed } from "vue";
+import type { ComputedRef, Ref } from "vue";
+
+import { useMediaQuery } from "./media-query.ts";
+import type { UseMediaQueryOptions } from "./media-query.ts";
+
+/** Color scheme preference exposed by {@link usePreferredColorScheme}. */
+export type ColorSchemePreference = "dark" | "light" | "no-preference";
+
+/** Contrast preference exposed by {@link usePreferredContrast}. */
+export type ContrastPreference = "more" | "less" | "custom" | "no-preference";
+
+/** Options for the multi-valued preference composables. */
+export interface UsePreferenceOptions<Preference extends string> extends Omit<
+  UseMediaQueryOptions,
+  "ssrValue"
+> {
+  /**
+   * Preference exposed during server rendering and whenever no media-query
+   * capability exists.
+   *
+   * @default "no-preference"
+   */
+  readonly ssrPreference?: Preference;
+}
+
+/**
+ * Whether the user prefers a dark color scheme.
+ *
+ * Shares {@link useMediaQuery} semantics: `ssrValue` (default `false`) during
+ * server rendering and subscription cleanup with the owning scope.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Readonly ref for `(prefers-color-scheme: dark)`.
+ */
+export function usePreferredDark(options: UseMediaQueryOptions = {}): Readonly<Ref<boolean>> {
+  return useMediaQuery("(prefers-color-scheme: dark)", options);
+}
+
+/**
+ * Reactive color scheme preference.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Computed closed preference.
+ */
+export function usePreferredColorScheme(
+  options: UsePreferenceOptions<ColorSchemePreference> = {},
+): ComputedRef<ColorSchemePreference> {
+  const fallback = options.ssrPreference ?? "no-preference";
+  const query = (value: "dark" | "light"): Readonly<Ref<boolean>> =>
+    useMediaQuery(`(prefers-color-scheme: ${value})`, withSsr(options, fallback === value));
+  const dark = query("dark");
+  const light = query("light");
+  return computed(() => (dark.value ? "dark" : light.value ? "light" : "no-preference"));
+}
+
+/**
+ * Reactive contrast preference.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Computed closed preference.
+ */
+export function usePreferredContrast(
+  options: UsePreferenceOptions<ContrastPreference> = {},
+): ComputedRef<ContrastPreference> {
+  const fallback = options.ssrPreference ?? "no-preference";
+  const query = (value: "more" | "less" | "custom"): Readonly<Ref<boolean>> =>
+    useMediaQuery(`(prefers-contrast: ${value})`, withSsr(options, fallback === value));
+  const more = query("more");
+  const less = query("less");
+  const custom = query("custom");
+  return computed(() =>
+    more.value ? "more" : less.value ? "less" : custom.value ? "custom" : "no-preference",
+  );
+}
+
+/**
+ * Whether the user prefers reduced transparency.
+ *
+ * @param options Runtime capability and server fallback.
+ * @default options {}
+ * @returns Readonly ref for `(prefers-reduced-transparency: reduce)`.
+ */
+export function usePreferredReducedTransparency(
+  options: UseMediaQueryOptions = {},
+): Readonly<Ref<boolean>> {
+  return useMediaQuery("(prefers-reduced-transparency: reduce)", options);
+}
+
+function withSsr<Preference extends string>(
+  options: UsePreferenceOptions<Preference>,
+  ssrValue: boolean,
+): UseMediaQueryOptions {
+  return options.host === undefined ? { ssrValue } : { ssrValue, host: options.host };
+}

package/registry/files/preferred-languages.ts

@@ -0,0 +1,88 @@
+import { hasInjectionContext, readonly, shallowRef, toValue, watch, watchPostEffect } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Window-like capability observed by {@link usePreferredLanguages}. */
+export interface PreferredLanguagesHost extends EventTarget {
+  /** Navigator exposing the user's languages. */
+  readonly navigator: { readonly languages: readonly string[]; readonly language?: string };
+}
+
+/** Options for {@link usePreferredLanguages}. */
+export interface UsePreferredLanguagesOptions {
+  /**
+   * Languages exposed during server rendering. Pass the request's
+   * `Accept-Language` list to keep hydration stable.
+   *
+   * @default ["en"]
+   */
+  readonly ssrLanguages?: readonly string[];
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<PreferredLanguagesHost | null | undefined>;
+}
+
+/**
+ * Track the user's preferred languages (`navigator.languages`).
+ *
+ * Updates on `languagechange`. The default host is gated on `window`, so
+ * Node's own `navigator` never leaks the server locale into the render;
+ * server renders expose `ssrLanguages`. Inside a component the languages are
+ * read after mounting, so hydration renders `ssrLanguages` first. The
+ * listener is removed with the owning reactive scope.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Readonly ref of BCP 47 language tags, most preferred first.
+ */
+export function usePreferredLanguages(
+  options: UsePreferredLanguagesOptions = {},
+): Readonly<Ref<readonly string[]>> {
+  const fallback = options.ssrLanguages ?? ["en"];
+  const languages = shallowRef<readonly string[]>(fallback);
+  // Inside a component the host is attached by a post-flush job (after the
+  // component mounted), so a hydrating client first renders the same server
+  // fallback. Outside components it is attached synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+
+  const stop = watch(
+    () =>
+      hydrated.value
+        ? options.host === undefined
+          ? browserLanguagesHost()
+          : toValue(options.host)
+        : undefined,
+    (host, _previous, onCleanup) => {
+      if (!host) {
+        languages.value = fallback;
+        return;
+      }
+      const update = (): void => {
+        const { languages: list, language } = host.navigator;
+        languages.value =
+          list.length > 0 ? [...list] : language !== undefined ? [language] : fallback;
+      };
+      update();
+      host.addEventListener("languagechange", update, { passive: true });
+      onCleanup(() => host.removeEventListener("languagechange", update));
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return readonly(languages);
+}
+
+function browserLanguagesHost(): PreferredLanguagesHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/reactify.ts

@@ -0,0 +1,39 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+/** Parameter list of a reactified function: every argument may be a ref or getter. */
+export type ReactifiedArguments<Arguments extends readonly unknown[]> = {
+  readonly [Index in keyof Arguments]: MaybeRefOrGetter<Arguments[Index]>;
+};
+
+/** Function returned by {@link reactify}. */
+export type Reactified<Arguments extends readonly unknown[], Result> = (
+  ...args: ReactifiedArguments<Arguments>
+) => ComputedRef<Result>;
+
+/**
+ * Turn a plain function into one that accepts refs/getters and returns a
+ * computed result.
+ *
+ * Arity and parameter names are preserved; each parameter additionally
+ * accepts `Ref<T>` or `() => T`. The computed re-runs the original function
+ * whenever a reactive argument changes. Pure derived state: SSR-safe and
+ * nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const add = reactify((left: number, right: number) => left + right);
+ * const sum = add(count, 1); // ComputedRef<number>
+ * ```
+ *
+ * @param fn Plain function to lift.
+ * @returns The reactified function.
+ */
+export function reactify<Arguments extends readonly unknown[], Result>(
+  fn: (...args: Arguments) => Result,
+): Reactified<Arguments, Result>;
+export function reactify(
+  fn: (...args: readonly unknown[]) => unknown,
+): (...args: readonly MaybeRefOrGetter<unknown>[]) => ComputedRef<unknown> {
+  return (...args) => computed(() => fn(...args.map((argument) => toValue(argument))));
+}