@vizejs/composable 0.426.3 → 0.427.0

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

@@ -0,0 +1,75 @@
+import { inject, provide } from "vue";
+import type { InjectionKey } from "vue";
+
+/** Options for {@link createInjectionState}. */
+export interface CreateInjectionStateOptions<State> {
+  /**
+   * Key used for `provide`/`inject`.
+   *
+   * @default a fresh unique symbol
+   */
+  readonly injectionKey?: InjectionKey<State>;
+
+  /**
+   * Value injected when no ancestor provides the state; also narrows the
+   * injector's return type to `State`.
+   *
+   * @default undefined
+   */
+  readonly defaultValue?: State;
+}
+
+/** Provider, injector, and key returned by {@link createInjectionState}. */
+export type InjectionState<Arguments extends readonly unknown[], State, Injected> = readonly [
+  useProvidingState: (...args: Arguments) => State,
+  useInjectedState: () => Injected,
+  injectionKey: InjectionKey<State>,
+];
+
+/**
+ * Create a typed provide/inject pair around a composable, for component
+ * subtrees that share request-local state.
+ *
+ * The provider runs the composable with its arguments, provides the result
+ * under a typed `InjectionKey`, and returns it. The injector returns the
+ * nearest provided state, or `defaultValue`, or `undefined` (reflected in
+ * its return type). State lives in the component tree, so unlike module
+ * globals it is naturally per request during SSR. Both must be called
+ * during `setup` (or inside `app.runWithContext`).
+ *
+ * @example
+ * ```ts
+ * const [useProvideCounter, useCounter] = createInjectionState((initial: number) => {
+ *   const count = ref(initial);
+ *   return { count, increment: () => count.value++ };
+ * });
+ * ```
+ *
+ * @param composable Creates the state in the providing component.
+ * @param options Custom key and default value.
+ * @default options {}
+ * @returns `[useProvidingState, useInjectedState, injectionKey]`.
+ */
+export function createInjectionState<Arguments extends readonly unknown[], State>(
+  composable: (...args: Arguments) => State,
+  options: CreateInjectionStateOptions<State> & { readonly defaultValue: State },
+): InjectionState<Arguments, State, State>;
+export function createInjectionState<Arguments extends readonly unknown[], State>(
+  composable: (...args: Arguments) => State,
+  options?: CreateInjectionStateOptions<State>,
+): InjectionState<Arguments, State, State | undefined>;
+export function createInjectionState<Arguments extends readonly unknown[], State>(
+  composable: (...args: Arguments) => State,
+  options: CreateInjectionStateOptions<State> = {},
+): InjectionState<Arguments, State, State | undefined> {
+  const generatedKey: InjectionKey<State> = Symbol("InjectionState");
+  const key = options.injectionKey ?? generatedKey;
+  const useProvidingState = (...args: Arguments): State => {
+    const state = composable(...args);
+    provide(key, state);
+    return state;
+  };
+  const useInjectedState = (): State | undefined =>
+    options.defaultValue === undefined ? inject(key) : inject(key, options.defaultValue);
+  return [useProvidingState, useInjectedState, key];
+}

package/registry/files/create-shared-composable.ts

@@ -0,0 +1,74 @@
+import { effectScope } from "vue";
+import type { EffectScope } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Options for {@link createSharedComposable}. */
+export interface CreateSharedComposableOptions {
+  /**
+   * Share one instance across callers on the server too. Disabled by
+   * default because module-level sharing leaks state between requests;
+   * without a browser `window` every call then gets its own instance.
+   *
+   * @default false
+   */
+  readonly shareOnServer?: boolean;
+}
+
+/**
+ * Share one instance of a composable between all simultaneously mounted
+ * callers, reference-counted by their effect scopes.
+ *
+ * The first caller creates the instance inside a detached scope using its
+ * arguments (later callers' arguments are ignored while it lives). When the
+ * last subscribing scope stops, the instance's scope is stopped and the next
+ * call starts fresh. Calls outside any effect scope subscribe permanently.
+ * On the server every call gets its own instance unless `shareOnServer` is
+ * set, so request state never leaks.
+ *
+ * @example
+ * ```ts
+ * const useSharedMouse = createSharedComposable(useMouse);
+ * ```
+ *
+ * @param composable Composable to share.
+ * @param options Server sharing policy.
+ * @default options {}
+ * @throws `Error` tagged `VIZE_COMPOSE_SHARED_COMPOSABLE_INACTIVE_SCOPE` if
+ * the private scope cannot run (never expected in practice).
+ * @returns A composable with the same signature that shares its result.
+ */
+export function createSharedComposable<Arguments extends readonly unknown[], Result>(
+  composable: (...args: Arguments) => Result,
+  options: CreateSharedComposableOptions = {},
+): (...args: Arguments) => Result {
+  let subscribers = 0;
+  let shared: { readonly result: Result; readonly scope: EffectScope } | undefined;
+
+  const release = (): void => {
+    subscribers -= 1;
+    if (subscribers > 0 || shared === undefined) return;
+    shared.scope.stop();
+    shared = undefined;
+  };
+
+  return (...args) => {
+    if (typeof window === "undefined" && !(options.shareOnServer ?? false)) {
+      return composable(...args);
+    }
+    subscribers += 1;
+    if (shared === undefined) {
+      const scope = effectScope(true);
+      const result = scope.run(() => ({ value: composable(...args) }));
+      if (result === undefined) {
+        throw new Error(
+          "[VIZE_COMPOSE_SHARED_COMPOSABLE_INACTIVE_SCOPE] the shared scope did not run",
+        );
+      }
+      shared = { result: result.value, scope };
+    }
+    const { result } = shared;
+    tryOnScopeDispose(release);
+    return result;
+  };
+}

package/registry/files/device-motion.ts

@@ -0,0 +1,152 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { requestMotionPermission } from "./device-orientation.ts";
+import type { MotionPermissionConstructor, MotionPermissionState } from "./device-orientation.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Window-like capability observed by {@link useDeviceMotion}. */
+export interface DeviceMotionHost extends EventTarget {
+  /** Constructor used to detect support and request permission. */
+  readonly DeviceMotionEvent?: MotionPermissionConstructor;
+}
+
+/** Acceleration along the device axes in m/s². */
+export interface MotionVector {
+  /** X axis (left to right). */
+  readonly x: number | null;
+  /** Y axis (bottom to top). */
+  readonly y: number | null;
+  /** Z axis (back to front). */
+  readonly z: number | null;
+}
+
+/** Rotation rate around the device axes in degrees per second. */
+export interface MotionRotationRate {
+  /** Around the Z axis. */
+  readonly alpha: number | null;
+  /** Around the X axis. */
+  readonly beta: number | null;
+  /** Around the Y axis. */
+  readonly gamma: number | null;
+}
+
+/** Options for {@link useDeviceMotion}. */
+export interface UseDeviceMotionOptions {
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<DeviceMotionHost | null | undefined>;
+}
+
+/** Reactive motion state returned by {@link useDeviceMotion}. */
+export interface DeviceMotionControls {
+  /** Whether the host exposes `DeviceMotionEvent`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Acceleration without gravity; `null` before the first reading. */
+  readonly acceleration: Readonly<ShallowRef<MotionVector | null>>;
+  /** Acceleration including gravity; `null` before the first reading. */
+  readonly accelerationIncludingGravity: Readonly<ShallowRef<MotionVector | null>>;
+  /** Rotation rate; `null` before the first reading. */
+  readonly rotationRate: Readonly<ShallowRef<MotionRotationRate | null>>;
+  /** Sampling interval in milliseconds. */
+  readonly interval: Readonly<Ref<number>>;
+  /** Latest permission outcome; `"granted"` where no prompt exists. */
+  readonly permission: Readonly<Ref<MotionPermissionState>>;
+  /**
+   * Request sensor permission where the platform requires it.
+   *
+   * @returns The resulting permission state.
+   */
+  readonly requestPermission: () => Promise<MotionPermissionState>;
+}
+
+/**
+ * Track device acceleration and rotation rate.
+ *
+ * Readings are copied into plain snapshots. Server renders expose `null`
+ * readings and `isSupported: false`; the listener is removed with the owning
+ * reactive scope. Shares the permission model of `useDeviceOrientation`.
+ *
+ * @param options Window capability.
+ * @default options {}
+ * @returns Reactive readings, support/permission state, and a permission action.
+ */
+export function useDeviceMotion(options: UseDeviceMotionOptions = {}): DeviceMotionControls {
+  const isSupported = ref(false);
+  const acceleration = shallowRef<MotionVector | null>(null);
+  const accelerationIncludingGravity = shallowRef<MotionVector | null>(null);
+  const rotationRate = shallowRef<MotionRotationRate | null>(null);
+  const interval = ref(0);
+  const permission = ref<MotionPermissionState>("prompt");
+  // Inside a component the host is read once it has mounted, so a hydrating
+  // client first renders the same fallback as the server. `hasInjectionContext`
+  // also detects Vapor components (unlike `getCurrentInstance`).
+  const mounted = shallowRef(!hasInjectionContext());
+  if (!mounted.value) {
+    onMounted(() => {
+      mounted.value = true;
+    });
+  }
+  const host = (): DeviceMotionHost | null | undefined =>
+    !mounted.value
+      ? undefined
+      : options.host === undefined
+        ? browserMotionHost()
+        : toValue(options.host);
+
+  const onMotion = (event: Event): void => {
+    if (!isMotionEvent(event)) return;
+    acceleration.value = vector(event.acceleration);
+    accelerationIncludingGravity.value = vector(event.accelerationIncludingGravity);
+    rotationRate.value = event.rotationRate
+      ? {
+          alpha: event.rotationRate.alpha,
+          beta: event.rotationRate.beta,
+          gamma: event.rotationRate.gamma,
+        }
+      : null;
+    interval.value = event.interval;
+  };
+
+  const stop = watch(
+    host,
+    (current, _previous, onCleanup) => {
+      const constructor = current?.DeviceMotionEvent;
+      isSupported.value = constructor !== undefined;
+      if (!current || !constructor) return;
+      if (typeof constructor.requestPermission !== "function") permission.value = "granted";
+      current.addEventListener("devicemotion", onMotion, { passive: true });
+      onCleanup(() => current.removeEventListener("devicemotion", onMotion));
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return {
+    isSupported: readonly(isSupported),
+    acceleration,
+    accelerationIncludingGravity,
+    rotationRate,
+    interval: readonly(interval),
+    permission: readonly(permission),
+    requestPermission: async () => {
+      permission.value = await requestMotionPermission(host()?.DeviceMotionEvent);
+      return permission.value;
+    },
+  };
+}
+
+function vector(value: DeviceMotionEventAcceleration | null): MotionVector | null {
+  return value ? { x: value.x, y: value.y, z: value.z } : null;
+}
+
+function isMotionEvent(event: Event): event is DeviceMotionEvent {
+  return "accelerationIncludingGravity" in event && "interval" in event;
+}
+
+function browserMotionHost(): DeviceMotionHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/device-orientation.ts

@@ -0,0 +1,168 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Permission outcome of the iOS-style motion/orientation permission prompt. */
+export type MotionPermissionState = "granted" | "denied" | "prompt";
+
+/** Event constructor that may expose the iOS `requestPermission` static. */
+export interface MotionPermissionConstructor {
+  /** Constructor prototype; present on every platform event constructor. */
+  readonly prototype: object;
+  /** Ask the user for sensor access (Safari on iOS/iPadOS 13+). */
+  readonly requestPermission?: () => Promise<string>;
+}
+
+/** Window-like capability observed by {@link useDeviceOrientation}. */
+export interface DeviceOrientationHost extends EventTarget {
+  /** Constructor used to detect support and request permission. */
+  readonly DeviceOrientationEvent?: MotionPermissionConstructor;
+}
+
+/** Options for {@link useDeviceOrientation}. */
+export interface UseDeviceOrientationOptions {
+  /**
+   * Listen to `deviceorientationabsolute` (earth-frame) instead of
+   * `deviceorientation`.
+   *
+   * @default false
+   */
+  readonly absolute?: boolean;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<DeviceOrientationHost | null | undefined>;
+}
+
+/** Reactive orientation state returned by {@link useDeviceOrientation}. */
+export interface DeviceOrientationControls {
+  /** Whether the host exposes `DeviceOrientationEvent`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Whether the latest reading is relative to the earth frame. */
+  readonly isAbsolute: Readonly<Ref<boolean>>;
+  /** Rotation around the Z axis in degrees `[0, 360)`. */
+  readonly alpha: Readonly<Ref<number | null>>;
+  /** Rotation around the X axis in degrees `[-180, 180)`. */
+  readonly beta: Readonly<Ref<number | null>>;
+  /** Rotation around the Y axis in degrees `[-90, 90)`. */
+  readonly gamma: Readonly<Ref<number | null>>;
+  /** Latest permission outcome; `"granted"` where no prompt exists. */
+  readonly permission: Readonly<Ref<MotionPermissionState>>;
+  /**
+   * Request sensor permission where the platform requires it. Must be called
+   * from a user gesture on iOS.
+   *
+   * @returns The resulting permission state.
+   */
+  readonly requestPermission: () => Promise<MotionPermissionState>;
+}
+
+/**
+ * Track device orientation angles.
+ *
+ * Server renders expose `null` angles and `isSupported: false`. The listener
+ * follows the reactive host and is removed with the owning reactive scope.
+ * On platforms with a permission prompt, `permission` starts as `"prompt"`
+ * and readings arrive only after `requestPermission` resolves `"granted"`.
+ *
+ * @param options Frame selection and window capability.
+ * @default options {}
+ * @returns Reactive angles, support/permission state, and a permission action.
+ */
+export function useDeviceOrientation(
+  options: UseDeviceOrientationOptions = {},
+): DeviceOrientationControls {
+  const isSupported = ref(false);
+  const isAbsolute = ref(false);
+  const alpha = ref<number | null>(null);
+  const beta = ref<number | null>(null);
+  const gamma = ref<number | null>(null);
+  const permission = ref<MotionPermissionState>("prompt");
+  // Inside a component the host is read once it has mounted, so a hydrating
+  // client first renders the same fallback as the server. `hasInjectionContext`
+  // also detects Vapor components (unlike `getCurrentInstance`).
+  const mounted = shallowRef(!hasInjectionContext());
+  if (!mounted.value) {
+    onMounted(() => {
+      mounted.value = true;
+    });
+  }
+  const host = (): DeviceOrientationHost | null | undefined =>
+    !mounted.value
+      ? undefined
+      : options.host === undefined
+        ? browserOrientationHost()
+        : toValue(options.host);
+  const eventName = options.absolute ? "deviceorientationabsolute" : "deviceorientation";
+
+  const onOrientation = (event: Event): void => {
+    if (!isOrientationEvent(event)) return;
+    isAbsolute.value = event.absolute;
+    alpha.value = event.alpha;
+    beta.value = event.beta;
+    gamma.value = event.gamma;
+  };
+
+  const stop = watch(
+    host,
+    (current, _previous, onCleanup) => {
+      const constructor = current?.DeviceOrientationEvent;
+      isSupported.value = constructor !== undefined;
+      if (!current || !constructor) return;
+      if (typeof constructor.requestPermission !== "function") permission.value = "granted";
+      current.addEventListener(eventName, onOrientation, { passive: true });
+      onCleanup(() => current.removeEventListener(eventName, onOrientation));
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return {
+    isSupported: readonly(isSupported),
+    isAbsolute: readonly(isAbsolute),
+    alpha: readonly(alpha),
+    beta: readonly(beta),
+    gamma: readonly(gamma),
+    permission: readonly(permission),
+    requestPermission: async () => {
+      permission.value = await requestMotionPermission(host()?.DeviceOrientationEvent);
+      return permission.value;
+    },
+  };
+}
+
+/**
+ * Request motion/orientation sensor permission from an event constructor.
+ *
+ * Normalizes the platform result to {@link MotionPermissionState}. Missing
+ * constructors resolve `"denied"`; constructors without a prompt resolve
+ * `"granted"`; unknown results resolve `"prompt"`. Rejections (for example
+ * when not called from a user gesture) resolve `"denied"` instead of throwing.
+ *
+ * @param constructor `DeviceOrientationEvent` or `DeviceMotionEvent`.
+ * @returns The normalized permission state.
+ */
+export async function requestMotionPermission(
+  constructor: MotionPermissionConstructor | undefined,
+): Promise<MotionPermissionState> {
+  if (!constructor) return "denied";
+  if (typeof constructor.requestPermission !== "function") return "granted";
+  try {
+    const result = await constructor.requestPermission();
+    return result === "granted" || result === "denied" ? result : "prompt";
+  } catch {
+    return "denied";
+  }
+}
+
+function isOrientationEvent(event: Event): event is DeviceOrientationEvent {
+  return "alpha" in event && "beta" in event && "gamma" in event;
+}
+
+function browserOrientationHost(): DeviceOrientationHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/device-pixel-ratio.ts

@@ -0,0 +1,100 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import type { MediaQueryHost } from "./media-query.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Window-like capability observed by {@link useDevicePixelRatio}. */
+export interface DevicePixelRatioHost extends MediaQueryHost {
+  /** Ratio of physical to CSS pixels. */
+  readonly devicePixelRatio: number;
+}
+
+/** Options for {@link useDevicePixelRatio}. */
+export interface UseDevicePixelRatioOptions {
+  /**
+   * Ratio exposed during server rendering.
+   *
+   * @default 1
+   */
+  readonly ssrPixelRatio?: number;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<DevicePixelRatioHost | null | undefined>;
+}
+
+/** Reactive ratio returned by {@link useDevicePixelRatio}. */
+export interface DevicePixelRatioControls {
+  /** Current device pixel ratio. */
+  readonly pixelRatio: Readonly<Ref<number>>;
+  /** Whether a window capability is attached. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+}
+
+/**
+ * Track `window.devicePixelRatio` (zoom and moving between displays).
+ *
+ * Subscribes to a `(resolution: <ratio>dppx)` media query and re-subscribes
+ * with the new ratio after each change, which is the only change signal the
+ * platform offers. Server renders expose `ssrPixelRatio`.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Reactive ratio and support flag.
+ */
+export function useDevicePixelRatio(
+  options: UseDevicePixelRatioOptions = {},
+): DevicePixelRatioControls {
+  const fallback = options.ssrPixelRatio ?? 1;
+  const pixelRatio = ref(fallback);
+  const isSupported = ref(false);
+  // Inside a component the host is read once it has mounted, so a hydrating
+  // client first renders the same fallback as the server. `hasInjectionContext`
+  // also detects Vapor components (unlike `getCurrentInstance`).
+  const mounted = shallowRef(!hasInjectionContext());
+  if (!mounted.value) {
+    onMounted(() => {
+      mounted.value = true;
+    });
+  }
+
+  const stop = watch(
+    () =>
+      !mounted.value
+        ? undefined
+        : options.host === undefined
+          ? browserPixelRatioHost()
+          : toValue(options.host),
+    (host, _previous, onCleanup) => {
+      isSupported.value = Boolean(host);
+      if (!host) {
+        pixelRatio.value = fallback;
+        return;
+      }
+      let release = (): void => undefined;
+      const subscribe = (): void => {
+        release();
+        pixelRatio.value = host.devicePixelRatio;
+        const media = host.matchMedia(`(resolution: ${host.devicePixelRatio}dppx)`);
+        media.addEventListener("change", subscribe, { once: true });
+        release = () => media.removeEventListener("change", subscribe);
+      };
+      subscribe();
+      onCleanup(() => release());
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return { pixelRatio: readonly(pixelRatio), isSupported: readonly(isSupported) };
+}
+
+function browserPixelRatioHost(): DevicePixelRatioHost | undefined {
+  return typeof window !== "undefined" && typeof window.matchMedia === "function"
+    ? window
+    : undefined;
+}