@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/use-vibrate.ts

@@ -0,0 +1,174 @@
+import { computed, readonly, ref, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** A single duration or an alternating vibrate/pause pattern in milliseconds. */
+export type VibrationPattern = number | readonly number[];
+
+/** Minimal Vibration API (`navigator`). */
+export interface VibrationHost {
+  /** Start (or with `0`/`[]`, cancel) a vibration. Returns whether it was accepted. */
+  vibrate(pattern: VibrationPattern): boolean;
+}
+
+/** Options for {@link useVibrate}. */
+export interface UseVibrateOptions {
+  /**
+   * Default pattern used by `vibrate()`.
+   *
+   * @default []
+   */
+  readonly pattern?: MaybeRefOrGetter<VibrationPattern>;
+
+  /**
+   * Repeat the pattern every `interval` milliseconds until `stop`; `0`
+   * vibrates once.
+   *
+   * @default 0
+   */
+  readonly interval?: number;
+
+  /**
+   * Vibration capability for alternate runtimes and tests.
+   *
+   * @default window.navigator when it implements `vibrate`
+   */
+  readonly host?: MaybeRefOrGetter<VibrationHost | null | undefined>;
+
+  /**
+   * Timer host used for repetition.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+
+/** Reactive state and actions returned by {@link useVibrate}. */
+export interface VibrateControls {
+  /** Whether the Vibration API is available. */
+  readonly supported: ComputedRef<boolean>;
+
+  /** Whether a (possibly repeating) vibration started by this composable is active. */
+  readonly vibrating: Readonly<Ref<boolean>>;
+
+  /**
+   * Vibrate with `pattern` or the default pattern.
+   *
+   * @param pattern Pattern overriding the default.
+   * @returns Whether the platform accepted the pattern.
+   * @throws {RangeError} `[VIZE_COMPOSE_VIBRATE_INVALID_PATTERN]` for negative,
+   * fractional, or non-finite durations.
+   */
+  readonly vibrate: (pattern?: VibrationPattern) => boolean;
+
+  /** Cancel the vibration and any repetition. */
+  readonly stop: () => void;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+function browserVibrationHost(): VibrationHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { navigator } = window;
+  return typeof navigator.vibrate === "function" ? navigator : undefined;
+}
+
+function validatePattern(pattern: VibrationPattern): readonly number[] {
+  const durations = typeof pattern === "number" ? [pattern] : pattern;
+  for (const duration of durations) {
+    if (!Number.isSafeInteger(duration) || duration < 0) {
+      throw new RangeError(
+        `[VIZE_COMPOSE_VIBRATE_INVALID_PATTERN] vibration durations must be non-negative integers; received ${String(duration)}`,
+      );
+    }
+  }
+  return durations;
+}
+
+/**
+ * Drive the Vibration API with validated, optionally repeating patterns.
+ *
+ * Patterns alternate vibration and pause durations. With `interval > 0`
+ * the pattern repeats until `stop` is called or the owning reactive scope
+ * stops, which also cancels an ongoing vibration.
+ *
+ * Server rendering: nothing vibrates and no timer starts; `supported` is false.
+ *
+ * @example
+ * ```ts
+ * const { vibrate, stop } = useVibrate({ pattern: [200, 100, 200] });
+ * vibrate();
+ * ```
+ *
+ * @param options Default pattern, repetition, and capability.
+ * @default options {}
+ * @returns Vibration state and actions.
+ * @throws {RangeError} `[VIZE_COMPOSE_VIBRATE_INVALID_INTERVAL]` for a negative
+ * or non-finite interval.
+ */
+export function useVibrate(options: UseVibrateOptions = {}): VibrateControls {
+  const interval = options.interval ?? 0;
+  if (!Number.isFinite(interval) || interval < 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_VIBRATE_INVALID_INTERVAL] interval must be a non-negative finite number; received ${String(interval)}`,
+    );
+  }
+  const scheduler = options.scheduler ?? defaultScheduler;
+  const vibrating = ref(false);
+  let handle: unknown;
+  let scheduled = false;
+
+  const resolveHost = (): VibrationHost | undefined =>
+    options.host === undefined ? browserVibrationHost() : (toValue(options.host) ?? undefined);
+
+  const clearRepeat = (): void => {
+    if (scheduled) scheduler.clearTimeout(handle);
+    scheduled = false;
+  };
+
+  const stop = (): void => {
+    clearRepeat();
+    if (vibrating.value) resolveHost()?.vibrate(0);
+    vibrating.value = false;
+  };
+
+  const vibrate = (pattern?: VibrationPattern): boolean => {
+    const durations = validatePattern(pattern ?? toValue(options.pattern) ?? []);
+    const host = resolveHost();
+    clearRepeat();
+    if (!host) return false;
+    const accepted = host.vibrate(durations);
+    const total = durations.reduce((sum, duration) => sum + duration, 0);
+    vibrating.value = accepted && total > 0;
+    if (vibrating.value && interval > 0) {
+      const repeat = (): void => {
+        scheduled = false;
+        if (!vibrating.value) return;
+        vibrating.value = host.vibrate(durations);
+        if (vibrating.value) {
+          scheduled = true;
+          handle = scheduler.setTimeout(repeat, interval);
+        }
+      };
+      scheduled = true;
+      handle = scheduler.setTimeout(repeat, interval);
+    }
+    return accepted;
+  };
+
+  tryOnScopeDispose(stop);
+
+  return {
+    supported: computed(() => resolveHost() !== undefined),
+    vibrating: readonly(vibrating),
+    vibrate,
+    stop,
+  };
+}

package/registry/files/use-view-transition.ts

@@ -0,0 +1,229 @@
+import { computed, hasInjectionContext, readonly, shallowRef, toValue, watchPostEffect } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { useReducedMotion } from "./media-query.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Minimal `ViewTransition`. */
+export interface ViewTransitionLike {
+  /** Settles when the transition animation finished (or was skipped). */
+  readonly finished: Promise<void>;
+  /** Resolves when the animation is about to start; rejects when skipped. */
+  readonly ready: Promise<void>;
+  /** Settles when the update callback settled. */
+  readonly updateCallbackDone: Promise<void>;
+  /** Skip the animation; the update still runs. */
+  skipTransition(): void;
+}
+
+/** Argument accepted by `document.startViewTransition`. */
+export type StartViewTransitionArgument =
+  | (() => unknown)
+  | {
+      /** DOM update callback. */
+      readonly update?: () => unknown;
+      /** Active transition types (`:active-view-transition-type()`). */
+      readonly types?: string[];
+    };
+
+/** Minimal document consumed by {@link useViewTransition}. */
+export interface ViewTransitionDocumentHost {
+  /** Start a same-document view transition. */
+  startViewTransition(update?: StartViewTransitionArgument): ViewTransitionLike;
+}
+
+/** Options for {@link useViewTransition}. */
+export interface UseViewTransitionOptions {
+  /**
+   * Document for alternate runtimes and tests.
+   *
+   * @default window.document when it implements startViewTransition
+   */
+  readonly document?: MaybeRefOrGetter<ViewTransitionDocumentHost | null | undefined>;
+
+  /**
+   * Run updates without a transition while reduced motion is preferred.
+   *
+   * @default true
+   */
+  readonly respectReducedMotion?: boolean;
+
+  /**
+   * Whether reduced motion is preferred.
+   *
+   * @default useReducedMotion() === "reduce"
+   */
+  readonly reducedMotion?: MaybeRefOrGetter<boolean>;
+}
+
+/** Per-call options of {@link ViewTransitionControls.start}. */
+export interface ViewTransitionStartOptions {
+  /**
+   * Transition types. Runtimes without typed transitions fall back to an
+   * untyped transition.
+   *
+   * @default []
+   */
+  readonly types?: readonly string[];
+}
+
+/** Reactive state and actions returned by {@link useViewTransition}. */
+export interface ViewTransitionControls {
+  /** Whether `document.startViewTransition` is available. */
+  readonly supported: ComputedRef<boolean>;
+
+  /**
+   * The running transition (the host object itself, not a readonly proxy, so
+   * native methods keep working), cleared once it finished.
+   */
+  readonly transition: ComputedRef<ViewTransitionLike | null>;
+
+  /** Whether a transition started by this composable is running. */
+  readonly isTransitioning: Readonly<ShallowRef<boolean>>;
+
+  /**
+   * Run `update` inside a view transition, or directly when unsupported or
+   * reduced motion is preferred.
+   *
+   * @param update DOM update; may return a value or a promise.
+   * @param options Transition types.
+   * @default options {}
+   * @returns Resolves with the update result once the DOM was updated (the
+   * animation may still run; await `transition.value?.finished` for it);
+   * rejects with the update error.
+   */
+  readonly start: <Result>(
+    update: () => Result | PromiseLike<Result>,
+    options?: ViewTransitionStartOptions,
+  ) => Promise<Result>;
+
+  /** Skip the running transition's animation. */
+  readonly skip: () => void;
+}
+
+function browserDocument(): ViewTransitionDocumentHost | undefined {
+  return typeof window !== "undefined" && typeof window.document.startViewTransition === "function"
+    ? window.document
+    : undefined;
+}
+
+function ignore(): void {
+  // Settlement is observed elsewhere.
+}
+
+/**
+ * Animate DOM updates with the View Transition API.
+ *
+ * Starting a new transition skips the running one (browser behavior). The
+ * running transition is skipped when the owning reactive scope stops.
+ *
+ * Server rendering: `start` runs the update directly; `supported` and
+ * `isTransitioning` are false.
+ *
+ * @example
+ * ```ts
+ * const { start } = useViewTransition();
+ * await start(async () => {
+ *   page.value = next;
+ *   await nextTick();
+ * }, { types: ["forward"] });
+ * ```
+ *
+ * @param options Document host and reduced-motion policy.
+ * @default options {}
+ * @returns Transition state and actions.
+ */
+export function useViewTransition(options: UseViewTransitionOptions = {}): ViewTransitionControls {
+  const transition = shallowRef<ViewTransitionLike | null>(null);
+  const isTransitioning = shallowRef(false);
+  const respect = options.respectReducedMotion ?? true;
+  const preference =
+    respect && options.reducedMotion === undefined ? useReducedMotion() : undefined;
+
+  // Inside a component the host resolves only after mount (a post-flush
+  // job), so a hydrating client first renders the same unsupported state as
+  // the server. Outside components it resolves immediately.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+  const resolveDocument = (): ViewTransitionDocumentHost | undefined =>
+    !hydrated.value
+      ? undefined
+      : options.document === undefined
+        ? browserDocument()
+        : (toValue(options.document) ?? undefined);
+
+  const prefersReducedMotion = (): boolean => {
+    if (!respect) return false;
+    return preference ? preference.value === "reduce" : toValue(options.reducedMotion) === true;
+  };
+
+  const begin = (
+    host: ViewTransitionDocumentHost,
+    run: () => Promise<void>,
+    types: readonly string[],
+  ): ViewTransitionLike => {
+    if (types.length === 0) return host.startViewTransition(run);
+    try {
+      return host.startViewTransition({ update: run, types: [...types] });
+    } catch {
+      // Runtimes without typed transitions reject the options object.
+      return host.startViewTransition(run);
+    }
+  };
+
+  const start = async <Result>(
+    update: () => Result | PromiseLike<Result>,
+    startOptions: ViewTransitionStartOptions = {},
+  ): Promise<Result> => {
+    const host = resolveDocument();
+    if (!host || prefersReducedMotion()) return update();
+
+    let run: () => Promise<void> = async () => undefined;
+    const outcome = new Promise<Result>((resolve, reject) => {
+      run = async () => {
+        try {
+          resolve(await update());
+        } catch (cause) {
+          reject(cause);
+          throw cause;
+        }
+      };
+    });
+
+    let current: ViewTransitionLike;
+    try {
+      current = begin(host, run, startOptions.types ?? []);
+    } catch {
+      return update();
+    }
+    transition.value = current;
+    isTransitioning.value = true;
+    const clear = (): void => {
+      if (transition.value !== current) return;
+      transition.value = null;
+      isTransitioning.value = false;
+    };
+    current.ready.catch(ignore);
+    current.updateCallbackDone.catch(ignore);
+    current.finished.then(clear, clear);
+    return outcome;
+  };
+
+  const skip = (): void => {
+    transition.value?.skipTransition();
+  };
+
+  tryOnScopeDispose(skip);
+
+  return {
+    supported: computed(() => resolveDocument() !== undefined),
+    transition: computed(() => transition.value),
+    isTransitioning: readonly(isTransitioning),
+    start,
+    skip,
+  };
+}

package/registry/files/use-visual-viewport.ts

@@ -0,0 +1,228 @@
+import {
+  computed,
+  hasInjectionContext,
+  readonly,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Structural `VisualViewport` observed by {@link useVisualViewport}. */
+export interface VisualViewportHost extends EventTarget {
+  /** Visible width in CSS pixels. */
+  readonly width: number;
+  /** Visible height in CSS pixels (shrinks when an on-screen keyboard overlays the page). */
+  readonly height: number;
+  /** Offset of the visual viewport from the layout viewport's top edge. */
+  readonly offsetTop: number;
+  /** Offset of the visual viewport from the layout viewport's left edge. */
+  readonly offsetLeft: number;
+  /** Pinch-zoom scale factor. */
+  readonly scale: number;
+}
+
+/** Structural VirtualKeyboard API (`navigator.virtualKeyboard`). */
+export interface VirtualKeyboardHost extends EventTarget {
+  /** Whether the keyboard overlays content instead of resizing the viewport. */
+  overlaysContent: boolean;
+  /** Keyboard rectangle in CSS pixels. */
+  readonly boundingRect: { readonly height: number };
+}
+
+/** Window-like capability read by {@link useVisualViewport}. */
+export interface VisualViewportWindowHost {
+  /** Layout viewport height. */
+  readonly innerHeight: number;
+  /** Visual viewport, when the engine supports it. */
+  readonly visualViewport?: VisualViewportHost | null;
+  /** Navigator that may expose the VirtualKeyboard API as `virtualKeyboard`. */
+  readonly navigator?: object;
+}
+
+/** Options for {@link useVisualViewport}. */
+export interface UseVisualViewportOptions {
+  /**
+   * Minimum occluded height (CSS px) reported as an open keyboard, filtering
+   * browser toolbars that collapse while scrolling.
+   *
+   * @default 120
+   */
+  readonly keyboardThreshold?: number;
+
+  /**
+   * Opt in to `navigator.virtualKeyboard.overlaysContent = true` (Chromium) so
+   * the keyboard height comes from the VirtualKeyboard API and the layout
+   * viewport no longer resizes. The previous value is restored on cleanup.
+   *
+   * @default false
+   */
+  readonly overlaysContent?: boolean;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<VisualViewportWindowHost | null | undefined>;
+}
+
+/** Reactive viewport geometry returned by {@link useVisualViewport}. */
+export interface VisualViewportControls {
+  /** Visual viewport width (0 on the server). */
+  readonly width: Readonly<Ref<number>>;
+  /** Visual viewport height (0 on the server). */
+  readonly height: Readonly<Ref<number>>;
+  /** Visual viewport top offset within the layout viewport. */
+  readonly offsetTop: Readonly<Ref<number>>;
+  /** Visual viewport left offset within the layout viewport. */
+  readonly offsetLeft: Readonly<Ref<number>>;
+  /** Pinch-zoom scale (1 on the server). */
+  readonly scale: Readonly<Ref<number>>;
+  /** Height of the bottom area hidden by an on-screen keyboard, in CSS px. */
+  readonly keyboardHeight: Readonly<Ref<number>>;
+  /** Whether `keyboardHeight` exceeds `keyboardThreshold`. */
+  readonly keyboardOpen: ComputedRef<boolean>;
+  /** Whether a VisualViewport (or VirtualKeyboard) capability is attached. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+}
+
+/**
+ * Track the visual viewport and on-screen keyboard.
+ *
+ * On mobile browsers the visual viewport shrinks (or scrolls) when a virtual
+ * keyboard opens while the layout viewport stays put; `keyboardHeight` is the
+ * occluded bottom area (`innerHeight - height - offsetTop`), or the
+ * VirtualKeyboard API rectangle when `overlaysContent` is enabled. Pin
+ * toolbars above the keyboard with `bottom: calc(var(--kb, 0px))` bound to it.
+ *
+ * Server rendering reports zeros (scale 1) and attaches nothing; inside a
+ * component the host attaches after mount, so hydration renders the same
+ * zeros first. Listeners
+ * (`resize`, `scroll`, `geometrychange`) are passive and removed with the
+ * owning reactive scope.
+ *
+ * @example
+ * ```ts
+ * const { keyboardHeight, keyboardOpen } = useVisualViewport();
+ * const toolbarStyle = computed(() => ({ bottom: `${keyboardHeight.value}px` }));
+ * ```
+ *
+ * @param options Keyboard threshold, VirtualKeyboard opt-in, and capability.
+ * @default options {}
+ * @returns Reactive viewport geometry and keyboard state.
+ */
+export function useVisualViewport(options: UseVisualViewportOptions = {}): VisualViewportControls {
+  const threshold =
+    typeof options.keyboardThreshold === "number" && Number.isFinite(options.keyboardThreshold)
+      ? Math.max(options.keyboardThreshold, 0)
+      : 120;
+  const width = ref(0);
+  const height = ref(0);
+  const offsetTop = ref(0);
+  const offsetLeft = ref(0);
+  const scale = ref(1);
+  const keyboardHeight = ref(0);
+  const isSupported = ref(false);
+
+  // Inside a component the host is attached after mount (a post-flush
+  // job), so a hydrating client first renders the same zeroed geometry as
+  // the server. Outside components it attaches immediately.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+  const stopWatch = watch(
+    () =>
+      !hydrated.value
+        ? undefined
+        : options.host === undefined
+          ? browserViewportHost()
+          : toValue(options.host),
+    (host, _previous, onCleanup) => {
+      const viewport = host?.visualViewport ?? undefined;
+      const keyboard =
+        options.overlaysContent === true ? virtualKeyboardOf(host?.navigator) : undefined;
+      isSupported.value = viewport !== undefined || keyboard !== undefined;
+      if (host === null || host === undefined || !isSupported.value) {
+        width.value = 0;
+        height.value = 0;
+        offsetTop.value = 0;
+        offsetLeft.value = 0;
+        scale.value = 1;
+        keyboardHeight.value = 0;
+        return;
+      }
+      const previousOverlay = keyboard?.overlaysContent;
+      if (keyboard !== undefined) keyboard.overlaysContent = true;
+      const update = (): void => {
+        if (viewport !== undefined) {
+          width.value = viewport.width;
+          height.value = viewport.height;
+          offsetTop.value = viewport.offsetTop;
+          offsetLeft.value = viewport.offsetLeft;
+          scale.value = viewport.scale;
+        }
+        const occluded =
+          keyboard !== undefined
+            ? keyboard.boundingRect.height
+            : viewport === undefined
+              ? 0
+              : host.innerHeight - viewport.height - viewport.offsetTop;
+        keyboardHeight.value = Math.max(Math.round(occluded), 0);
+      };
+      update();
+      const passive: AddEventListenerOptions = { passive: true };
+      viewport?.addEventListener("resize", update, passive);
+      viewport?.addEventListener("scroll", update, passive);
+      keyboard?.addEventListener("geometrychange", update, passive);
+      onCleanup(() => {
+        viewport?.removeEventListener("resize", update);
+        viewport?.removeEventListener("scroll", update);
+        keyboard?.removeEventListener("geometrychange", update);
+        if (keyboard !== undefined && previousOverlay !== undefined) {
+          keyboard.overlaysContent = previousOverlay;
+        }
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stopWatch.stop());
+
+  return {
+    width: readonly(width),
+    height: readonly(height),
+    offsetTop: readonly(offsetTop),
+    offsetLeft: readonly(offsetLeft),
+    scale: readonly(scale),
+    keyboardHeight: readonly(keyboardHeight),
+    keyboardOpen: computed(() => keyboardHeight.value > threshold),
+    isSupported: readonly(isSupported),
+  };
+}
+
+function browserViewportHost(): VisualViewportWindowHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}
+
+function isVirtualKeyboard(value: unknown): value is VirtualKeyboardHost {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "overlaysContent" in value &&
+    "boundingRect" in value &&
+    typeof Reflect.get(value, "addEventListener") === "function"
+  );
+}
+
+function virtualKeyboardOf(navigator: object | undefined): VirtualKeyboardHost | undefined {
+  if (navigator === undefined || !("virtualKeyboard" in navigator)) return undefined;
+  const keyboard: unknown = navigator.virtualKeyboard;
+  return isVirtualKeyboard(keyboard) ? keyboard : undefined;
+}