@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/retry-delay.ts

@@ -0,0 +1,132 @@
+/** Options for {@link calculateRetryDelay}. */
+export interface RetryDelayOptions {
+  /**
+   * Delay before the first retry, in milliseconds.
+   *
+   * @default 100
+   */
+  readonly initialDelayMs?: number;
+
+  /**
+   * Exponential multiplier applied for each subsequent retry.
+   *
+   * Values may be fractional but must be finite and at least one. The
+   * calculated delay is rounded up so a retry never starts earlier than the
+   * requested backoff.
+   *
+   * @default 2
+   */
+  readonly multiplier?: number;
+
+  /**
+   * Inclusive ceiling for the calculated delay, in milliseconds.
+   *
+   * The ceiling may be lower than {@link RetryDelayOptions.initialDelayMs};
+   * in that case it also caps the first retry.
+   *
+   * @default 30000
+   */
+  readonly maximumDelayMs?: number;
+
+  /**
+   * Fraction of the capped delay eligible for downward jitter.
+   *
+   * `0` is deterministic exponential backoff, `0.5` samples from the upper
+   * half of the range, and `1` applies full jitter from zero through the
+   * capped delay. Jitter never exceeds the unjittered delay.
+   *
+   * @default 0
+   */
+  readonly jitterRatio?: number;
+
+  /**
+   * Entropy source returning a number in the half-open interval `[0, 1)`.
+   * It is called exactly once when the selected jitter range contains more
+   * than one integer millisecond, and is otherwise not read.
+   *
+   * @default Math.random
+   */
+  readonly random?: () => number;
+}
+
+/**
+ * Calculate a bounded exponential-backoff delay for a one-based retry.
+ *
+ * The first retry is `retryAttempt = 1`. The result is always an integer from
+ * zero through `2_147_483_647`, making it safe to pass to common host timer
+ * APIs without implementation-specific clamping. The calculation is pure
+ * unless jitter requires the supplied entropy source, and it performs no work
+ * when the module is imported.
+ *
+ * Jitter samples uniformly from the inclusive integer range
+ * `ceil(cappedDelay * (1 - jitterRatio))...cappedDelay`. Capping occurs before
+ * jitter, so neither floating-point overflow nor entropy can exceed the
+ * configured maximum.
+ *
+ * @param retryAttempt One-based retry number after a failed initial attempt.
+ * @param options Backoff, cap, jitter, and entropy configuration.
+ * @default options {}
+ * @throws {RangeError} A tagged error when the retry number, delay options, or
+ * entropy value is outside its documented range.
+ * @throws {TypeError} A tagged error when `options` is not an object or
+ * `random` is not callable.
+ * @returns An integer delay in milliseconds.
+ */
+export function calculateRetryDelay(retryAttempt: number, options: RetryDelayOptions = {}): number {
+  if (!Number.isSafeInteger(retryAttempt) || retryAttempt < 1) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_ATTEMPT] retryAttempt must be a positive safe integer; received ${String(retryAttempt)}`,
+    );
+  }
+  if (options === null || typeof options !== "object") {
+    throw new TypeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_OPTIONS] options must be an object; received ${options === null ? "null" : typeof options}`,
+    );
+  }
+
+  const initialDelayMs = options.initialDelayMs === undefined ? 100 : options.initialDelayMs;
+  const multiplier = options.multiplier === undefined ? 2 : options.multiplier;
+  const maximumDelayMs = options.maximumDelayMs === undefined ? 30_000 : options.maximumDelayMs;
+  const jitterRatio = options.jitterRatio === undefined ? 0 : options.jitterRatio;
+  if (
+    !isPortableDelay(initialDelayMs) ||
+    !isPortableDelay(maximumDelayMs) ||
+    !Number.isFinite(multiplier) ||
+    multiplier < 1 ||
+    !Number.isFinite(jitterRatio) ||
+    jitterRatio < 0 ||
+    jitterRatio > 1
+  ) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_OPTIONS] initialDelayMs and maximumDelayMs must be integers from 0 through ${String(maximumPortableTimeoutMs)}, multiplier must be finite and at least 1, and jitterRatio must be from 0 through 1; received initialDelayMs=${String(initialDelayMs)}, maximumDelayMs=${String(maximumDelayMs)}, multiplier=${String(multiplier)}, jitterRatio=${String(jitterRatio)}`,
+    );
+  }
+  if (initialDelayMs === 0 || maximumDelayMs === 0) return 0;
+
+  const scaledDelay = initialDelayMs * multiplier ** (retryAttempt - 1);
+  const cappedDelay = Math.min(maximumDelayMs, Math.ceil(scaledDelay));
+  const minimumDelay = Math.ceil(cappedDelay * (1 - jitterRatio));
+  const integerRange = cappedDelay - minimumDelay;
+  if (integerRange === 0) return cappedDelay;
+
+  const random = options.random === undefined ? Math.random : options.random;
+  if (typeof random !== "function") {
+    throw new TypeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_RANDOM] random must be a function; received ${typeof random}`,
+    );
+  }
+  const sample = random();
+  if (!Number.isFinite(sample) || sample < 0 || sample >= 1) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_RANDOM] random must return a finite number from 0 up to but excluding 1; received ${String(sample)}`,
+    );
+  }
+
+  return minimumDelay + Math.floor(sample * (integerRange + 1));
+}
+
+function isPortableDelay(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0 && value <= maximumPortableTimeoutMs;
+}
+
+const maximumPortableTimeoutMs = 2_147_483_647;

package/registry/files/scope.ts

@@ -0,0 +1,21 @@
+import { getCurrentScope, onScopeDispose } from "vue";
+
+/**
+ * Register cleanup in the active reactive scope when one exists.
+ *
+ * This is the shared lifecycle primitive of the package: composables hand
+ * their teardown here so owned resources are released when the surrounding
+ * scope stops.
+ *
+ * Never throws and is safe during server rendering; no browser globals are
+ * read. When no scope is active the cleanup is not registered and disposal
+ * ownership stays with the caller.
+ *
+ * @param cleanup Cleanup invoked exactly once when the scope is disposed.
+ * @returns Whether the cleanup was registered.
+ */
+export function tryOnScopeDispose(cleanup: () => void): boolean {
+  if (!getCurrentScope()) return false;
+  onScopeDispose(cleanup);
+  return true;
+}

package/registry/files/screen-orientation.ts

@@ -0,0 +1,165 @@
+import {
+  hasInjectionContext,
+  readonly,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Lock targets accepted by `ScreenOrientation.lock()`. */
+export type ScreenOrientationLockType =
+  | "any"
+  | "natural"
+  | "landscape"
+  | "portrait"
+  | "portrait-primary"
+  | "portrait-secondary"
+  | "landscape-primary"
+  | "landscape-secondary";
+
+/** Subset of `ScreenOrientation`, including the lock methods absent from some DOM typings. */
+export interface ScreenOrientationLike extends EventTarget {
+  /** Current orientation type. */
+  readonly type: OrientationType;
+  /** Current orientation angle in degrees. */
+  readonly angle: number;
+  /** Lock the orientation (fullscreen or installed apps only in most browsers). */
+  readonly lock?: (orientation: ScreenOrientationLockType) => Promise<void>;
+  /** Release an orientation lock. */
+  readonly unlock?: () => void;
+}
+
+/** Window-like capability observed by {@link useScreenOrientation}. */
+export interface ScreenOrientationHost {
+  /** Screen exposing the orientation object. */
+  readonly screen: { readonly orientation?: ScreenOrientationLike };
+}
+
+/** Options for {@link useScreenOrientation}. */
+export interface UseScreenOrientationOptions {
+  /**
+   * Orientation exposed during server rendering.
+   *
+   * @default "portrait-primary"
+   */
+  readonly ssrOrientation?: OrientationType;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<ScreenOrientationHost | null | undefined>;
+}
+
+/** Reactive orientation state returned by {@link useScreenOrientation}. */
+export interface ScreenOrientationControls {
+  /** Whether the host exposes `screen.orientation`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Current orientation type. */
+  readonly orientation: Readonly<Ref<OrientationType>>;
+  /** Current angle in degrees. */
+  readonly angle: Readonly<Ref<number>>;
+  /**
+   * Lock the orientation.
+   *
+   * @returns Whether a lock was requested and accepted.
+   */
+  readonly lockOrientation: (type: ScreenOrientationLockType) => Promise<boolean>;
+  /**
+   * Release a lock.
+   *
+   * @returns Whether an unlock method was available.
+   */
+  readonly unlockOrientation: () => boolean;
+}
+
+/**
+ * Track the screen orientation.
+ *
+ * Server renders expose `ssrOrientation` with angle `0`. The `change`
+ * listener follows the reactive host and is removed with the owning scope.
+ * Lock failures (not fullscreen, unsupported) resolve `false` instead of
+ * throwing.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Reactive orientation plus lock actions.
+ */
+export function useScreenOrientation(
+  options: UseScreenOrientationOptions = {},
+): ScreenOrientationControls {
+  const fallback = options.ssrOrientation ?? "portrait-primary";
+  const isSupported = ref(false);
+  const orientation = ref<OrientationType>(fallback);
+  const angle = ref(0);
+  // 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 target = (): ScreenOrientationLike | undefined => {
+    if (!hydrated.value) return undefined;
+    const host = options.host === undefined ? browserScreenHost() : toValue(options.host);
+    return host?.screen.orientation;
+  };
+
+  const stop = watch(
+    target,
+    (current, _previous, onCleanup) => {
+      isSupported.value = current !== undefined;
+      if (!current) {
+        orientation.value = fallback;
+        angle.value = 0;
+        return;
+      }
+      const update = (): void => {
+        orientation.value = current.type;
+        angle.value = current.angle;
+      };
+      update();
+      current.addEventListener("change", update, { passive: true });
+      onCleanup(() => current.removeEventListener("change", update));
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return {
+    isSupported: readonly(isSupported),
+    orientation: readonly(orientation),
+    angle: readonly(angle),
+    lockOrientation: async (type) => {
+      const current = target();
+      if (typeof current?.lock !== "function") return false;
+      try {
+        await current.lock(type);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    unlockOrientation: () => {
+      const current = target();
+      if (typeof current?.unlock !== "function") return false;
+      current.unlock();
+      return true;
+    },
+  };
+}
+
+function browserScreenHost(): ScreenOrientationHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/scroll-lock.ts

@@ -0,0 +1,80 @@
+import { computed, ref, watch } from "vue";
+import type { WritableComputedRef } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Options for {@link useScrollLock}. */
+export interface UseScrollLockOptions {
+  /**
+   * Lock as soon as the element resolves.
+   *
+   * @default false
+   */
+  readonly initialValue?: boolean;
+
+  /**
+   * Also cancel `touchmove` on the element while locked (iOS Safari ignores
+   * `overflow: hidden` for touch scrolling).
+   *
+   * @default true
+   */
+  readonly preventTouchMove?: boolean;
+}
+
+interface StyledElement extends Element {
+  readonly style: Pick<CSSStyleDeclaration, "overflow" | "setProperty" | "getPropertyValue">;
+}
+
+/**
+ * Lock scrolling of a single element by toggling `overflow: hidden`.
+ *
+ * The element's previous inline `overflow` is restored on unlock, target
+ * change, and scope disposal. This is intentionally element-scoped: for the
+ * document viewport (nested lock stacking, scrollbar-gap compensation,
+ * scroll restoration) use `createScrollLock` from `@vizejs/ui/scroll-lock`.
+ * Server renders never touch styles and report the requested initial value.
+ *
+ * @param target Reactive element target.
+ * @param options Initial state and touch handling.
+ * @default options {}
+ * @returns Writable locked flag.
+ */
+export function useScrollLock(
+  target: MaybeElementTarget,
+  options: UseScrollLockOptions = {},
+): WritableComputedRef<boolean> {
+  const locked = ref(options.initialValue ?? false);
+  const preventTouchMove = options.preventTouchMove ?? true;
+  const onTouchMove = (event: Event): void => {
+    if (event.cancelable) event.preventDefault();
+  };
+
+  const stop = watch(
+    [() => resolveElement(target), locked],
+    ([element, isLocked], _previous, onCleanup) => {
+      if (!element || !isLocked || !isStyled(element)) return;
+      const previous = element.style.overflow;
+      element.style.setProperty("overflow", "hidden");
+      if (preventTouchMove) element.addEventListener("touchmove", onTouchMove, { passive: false });
+      onCleanup(() => {
+        element.style.setProperty("overflow", previous);
+        element.removeEventListener("touchmove", onTouchMove);
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return computed({
+    get: () => locked.value,
+    set: (next: boolean) => {
+      locked.value = next;
+    },
+  });
+}
+
+function isStyled(element: Element): element is StyledElement {
+  return "style" in element && typeof element.style === "object" && element.style !== null;
+}