@vizejs/composable 0.426.3 → 0.428.0

package/dist/retry-delay.d.mts

@@ -1,73 +1,2 @@
-//#region src/retry-delay.d.ts
-/** Options for {@link calculateRetryDelay}. */
-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.
- */
-declare function calculateRetryDelay(retryAttempt: number, options?: RetryDelayOptions): number;
-//#endregion
+import { n as calculateRetryDelay, t as RetryDelayOptions } from "./retry-delay-DYsdq4SE.mjs";
 export { RetryDelayOptions, calculateRetryDelay };

package/dist/screen-orientation.d.mts

@@ -0,0 +1,77 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/screen-orientation.d.ts
+/** Lock targets accepted by `ScreenOrientation.lock()`. */
+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. */
+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}. */
+interface ScreenOrientationHost {
+  /** Screen exposing the orientation object. */
+  readonly screen: {
+    readonly orientation?: ScreenOrientationLike;
+  };
+}
+/** Options for {@link useScreenOrientation}. */
+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}. */
+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.
+ */
+declare function useScreenOrientation(options?: UseScreenOrientationOptions): ScreenOrientationControls;
+//#endregion
+export { ScreenOrientationControls, ScreenOrientationHost, ScreenOrientationLike, ScreenOrientationLockType, UseScreenOrientationOptions, useScreenOrientation };

package/dist/screen-orientation.mjs

@@ -0,0 +1,74 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/screen-orientation.ts
+/**
+* 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.
+*/
+function useScreenOrientation(options = {}) {
+	const fallback = options.ssrOrientation ?? "portrait-primary";
+	const isSupported = ref(false);
+	const orientation = ref(fallback);
+	const angle = ref(0);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const target = () => {
+		if (!hydrated.value) return void 0;
+		return (options.host === void 0 ? browserScreenHost() : toValue(options.host))?.screen.orientation;
+	};
+	const stop = watch(target, (current, _previous, onCleanup) => {
+		isSupported.value = current !== void 0;
+		if (!current) {
+			orientation.value = fallback;
+			angle.value = 0;
+			return;
+		}
+		const update = () => {
+			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() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { useScreenOrientation };

package/dist/scroll-lock.d.mts

@@ -0,0 +1,37 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { WritableComputedRef } from "vue";
+
+//#region src/scroll-lock.d.ts
+/** Options for {@link useScrollLock}. */
+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;
+}
+/**
+ * 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.
+ */
+declare function useScrollLock(target: MaybeElementTarget, options?: UseScrollLockOptions): WritableComputedRef<boolean>;
+//#endregion
+export { UseScrollLockOptions, useScrollLock };

package/dist/scroll-lock.mjs

@@ -0,0 +1,50 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { computed, ref, watch } from "vue";
+//#region src/scroll-lock.ts
+/**
+* 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.
+*/
+function useScrollLock(target, options = {}) {
+	const locked = ref(options.initialValue ?? false);
+	const preventTouchMove = options.preventTouchMove ?? true;
+	const onTouchMove = (event) => {
+		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) => {
+			locked.value = next;
+		}
+	});
+}
+function isStyled(element) {
+	return "style" in element && typeof element.style === "object" && element.style !== null;
+}
+//#endregion
+export { useScrollLock };

package/dist/scroll.d.mts

@@ -0,0 +1,158 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { ComponentPublicInstance, MaybeRefOrGetter, Ref, WritableComputedRef } from "vue";
+
+//#region src/scroll.d.ts
+/** Scroll extents shared by elements and the document root element. */
+interface ScrollMetrics {
+  /** Total scrollable width. */
+  readonly scrollWidth: number;
+  /** Total scrollable height. */
+  readonly scrollHeight: number;
+  /** Visible width without scrollbars. */
+  readonly clientWidth: number;
+  /** Visible height without scrollbars. */
+  readonly clientHeight: number;
+}
+/** Window-like scroll container accepted by {@link useScroll}. */
+interface ScrollWindowHost extends EventTarget {
+  /** Horizontal document scroll offset. */
+  readonly scrollX: number;
+  /** Vertical document scroll offset. */
+  readonly scrollY: number;
+  /** Scroll the document. */
+  scrollTo(options: ScrollToOptions): void;
+  /** Document whose root element reports the scroll extents. */
+  readonly document: {
+    readonly documentElement: ScrollMetrics;
+  };
+}
+/** Value accepted as a scroll container. */
+type ScrollTargetValue = Element | ComponentPublicInstance | ScrollWindowHost | null | undefined;
+/** Per-edge boolean state. */
+interface ScrollEdges {
+  /** Left edge (or inline start in LTR). */
+  readonly left: boolean;
+  /** Right edge. */
+  readonly right: boolean;
+  /** Top edge. */
+  readonly top: boolean;
+  /** Bottom edge. */
+  readonly bottom: boolean;
+}
+/** Per-edge distance thresholds in CSS pixels. */
+interface ScrollOffset {
+  /** Distance from the left edge that still counts as arrived. */
+  readonly left?: number;
+  /** Distance from the right edge that still counts as arrived. */
+  readonly right?: number;
+  /** Distance from the top edge that still counts as arrived. */
+  readonly top?: number;
+  /** Distance from the bottom edge that still counts as arrived. */
+  readonly bottom?: number;
+}
+/** Options for {@link useScroll}. */
+interface UseScrollOptions {
+  /**
+   * Edge tolerances used to compute `arrivedState`.
+   *
+   * @default { left: 0, right: 0, top: 0, bottom: 0 }
+   */
+  readonly offset?: ScrollOffset;
+  /**
+   * Milliseconds without scroll events before `isScrolling` becomes `false`
+   * (used when the engine does not fire `scrollend`).
+   *
+   * @default 200
+   */
+  readonly idle?: number;
+  /**
+   * Scroll behavior used by `scrollTo` and the writable `x`/`y` refs.
+   *
+   * @default "auto"
+   */
+  readonly behavior?: MaybeRefOrGetter<ScrollBehavior>;
+  /**
+   * Called for every scroll event after the state has been updated.
+   *
+   * @default undefined
+   */
+  readonly onScroll?: (event: Event) => void;
+  /**
+   * Called once scrolling settles.
+   *
+   * @default undefined
+   */
+  readonly onStop?: (event: Event) => void;
+  /**
+   * Owns the idle timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+  /**
+   * Target resolution timing. `"post"` observes template refs after mount.
+   *
+   * @default "post"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+/** Reactive scroll state returned by {@link useScroll}. */
+interface ScrollControls {
+  /** Horizontal offset. Assigning scrolls the target with the configured behavior. */
+  readonly x: WritableComputedRef<number>;
+  /** Vertical offset. Assigning scrolls the target with the configured behavior. */
+  readonly y: WritableComputedRef<number>;
+  /** Whether scroll events arrived within the idle window. */
+  readonly isScrolling: Readonly<Ref<boolean>>;
+  /** Whether each edge has been reached (within `offset`). */
+  readonly arrivedState: Readonly<ScrollEdges>;
+  /** Direction of the most recent scroll movement; reset when scrolling stops. */
+  readonly directions: Readonly<ScrollEdges>;
+  /** Re-read offsets and edges without waiting for a scroll event. */
+  readonly measure: () => void;
+  /** Scroll the target. Missing axes keep their current offset. */
+  readonly scrollTo: (options: {
+    readonly left?: number;
+    readonly top?: number;
+  }) => void;
+}
+/**
+ * Track the scroll offset, edges, and direction of an element or window.
+ *
+ * During server rendering (or while the target is unresolved) offsets are `0`,
+ * the top/left edges report arrived, and the bottom/right edges do not —
+ * matching an unscrolled page, so hydration is stable. The scroll listener is
+ * passive and removed together with the idle timer when the owning reactive
+ * scope stops.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param target Reactive element, component, or window-like target.
+ * @param options Edge offsets, idle timing, behavior, and callbacks.
+ * @default options {}
+ * @returns Writable offsets, activity, edges, directions, and controls.
+ */
+declare function useScroll(target: MaybeRefOrGetter<ScrollTargetValue>, options?: UseScrollOptions): ScrollControls;
+/** Options for {@link useWindowScroll}. */
+interface UseWindowScrollOptions extends UseScrollOptions {
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<ScrollWindowHost | null | undefined>;
+}
+/**
+ * Track the document scroll position.
+ *
+ * Equivalent to {@link useScroll} with the window as target, so it shares its
+ * SSR-stable defaults and scope-bound cleanup.
+ *
+ * @param options Window capability plus every {@link useScroll} option.
+ * @default options {}
+ * @returns The same controls as {@link useScroll}.
+ */
+declare function useWindowScroll(options?: UseWindowScrollOptions): ScrollControls;
+//#endregion
+export { ScrollControls, ScrollEdges, ScrollMetrics, ScrollOffset, ScrollTargetValue, ScrollWindowHost, UseScrollOptions, UseWindowScrollOptions, useScroll, useWindowScroll };

package/dist/scroll.mjs

@@ -0,0 +1,172 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { isElementNode, resolveElement } from "./element-target.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowReactive, shallowReadonly, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/scroll.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* Track the scroll offset, edges, and direction of an element or window.
+*
+* During server rendering (or while the target is unresolved) offsets are `0`,
+* the top/left edges report arrived, and the bottom/right edges do not —
+* matching an unscrolled page, so hydration is stable. The scroll listener is
+* passive and removed together with the idle timer when the owning reactive
+* scope stops.
+*
+* Inside a component the host is read after mounting, so hydration renders
+* the server fallback first and never mismatches.
+*
+* @param target Reactive element, component, or window-like target.
+* @param options Edge offsets, idle timing, behavior, and callbacks.
+* @default options {}
+* @returns Writable offsets, activity, edges, directions, and controls.
+*/
+function useScroll(target, options = {}) {
+	const offset = options.offset ?? {};
+	const idle = options.idle ?? 200;
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const internalX = ref(0);
+	const internalY = ref(0);
+	const isScrolling = ref(false);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const arrivedState = shallowReactive({
+		left: true,
+		right: false,
+		top: true,
+		bottom: false
+	});
+	const directions = shallowReactive({
+		left: false,
+		right: false,
+		top: false,
+		bottom: false
+	});
+	let idleHandle;
+	let hasIdleTimer = false;
+	const resolveContainer = () => {
+		if (!hydrated.value) return null;
+		const value = toValue(target);
+		if (isScrollWindow(value)) return value;
+		return resolveElement(value);
+	};
+	const measure = () => {
+		const container = resolveContainer();
+		if (!container) return;
+		const metrics = isScrollWindow(container) ? container.document.documentElement : container;
+		const x = isScrollWindow(container) ? container.scrollX : container.scrollLeft;
+		const y = isScrollWindow(container) ? container.scrollY : container.scrollTop;
+		directions.left = x < internalX.value;
+		directions.right = x > internalX.value;
+		directions.top = y < internalY.value;
+		directions.bottom = y > internalY.value;
+		internalX.value = x;
+		internalY.value = y;
+		const left = Math.abs(x) <= (offset.left ?? 0);
+		const top = Math.abs(y) <= (offset.top ?? 0);
+		arrivedState.left = left;
+		arrivedState.top = top;
+		arrivedState.right = Math.abs(x) + metrics.clientWidth >= metrics.scrollWidth - (offset.right ?? 0) - 1;
+		arrivedState.bottom = Math.abs(y) + metrics.clientHeight >= metrics.scrollHeight - (offset.bottom ?? 0) - 1;
+	};
+	const settle = (event) => {
+		if (!isScrolling.value) return;
+		isScrolling.value = false;
+		directions.left = false;
+		directions.right = false;
+		directions.top = false;
+		directions.bottom = false;
+		options.onStop?.(event);
+	};
+	const clearIdle = () => {
+		if (!hasIdleTimer) return;
+		scheduler.clearTimeout(idleHandle);
+		hasIdleTimer = false;
+	};
+	const onScroll = (event) => {
+		measure();
+		isScrolling.value = true;
+		clearIdle();
+		idleHandle = scheduler.setTimeout(() => {
+			hasIdleTimer = false;
+			settle(event);
+		}, idle);
+		hasIdleTimer = true;
+		options.onScroll?.(event);
+	};
+	const onScrollEnd = (event) => {
+		clearIdle();
+		settle(event);
+	};
+	const stopWatch = watch(resolveContainer, (container, _previous, onCleanup) => {
+		if (!container) return;
+		measure();
+		const listenerOptions = { passive: true };
+		container.addEventListener("scroll", onScroll, listenerOptions);
+		container.addEventListener("scrollend", onScrollEnd, listenerOptions);
+		onCleanup(() => {
+			container.removeEventListener("scroll", onScroll);
+			container.removeEventListener("scrollend", onScrollEnd);
+			clearIdle();
+		});
+	}, {
+		immediate: true,
+		flush: options.flush ?? "post"
+	});
+	tryOnScopeDispose(() => {
+		stopWatch.stop();
+		clearIdle();
+	});
+	const scrollTo = (next) => {
+		const container = resolveContainer();
+		if (!container) return;
+		container.scrollTo({
+			left: next.left ?? internalX.value,
+			top: next.top ?? internalY.value,
+			behavior: toValue(options.behavior) ?? "auto"
+		});
+	};
+	return {
+		x: computed({
+			get: () => internalX.value,
+			set: (left) => scrollTo({ left })
+		}),
+		y: computed({
+			get: () => internalY.value,
+			set: (top) => scrollTo({ top })
+		}),
+		isScrolling: readonly(isScrolling),
+		arrivedState: shallowReadonly(arrivedState),
+		directions: shallowReadonly(directions),
+		measure,
+		scrollTo
+	};
+}
+/**
+* Track the document scroll position.
+*
+* Equivalent to {@link useScroll} with the window as target, so it shares its
+* SSR-stable defaults and scope-bound cleanup.
+*
+* @param options Window capability plus every {@link useScroll} option.
+* @default options {}
+* @returns The same controls as {@link useScroll}.
+*/
+function useWindowScroll(options = {}) {
+	const { host, ...scrollOptions } = options;
+	return useScroll(() => host === void 0 ? browserScrollWindow() : toValue(host), scrollOptions);
+}
+function isScrollWindow(value) {
+	return typeof value === "object" && value !== null && !isElementNode(value) && "scrollX" in value && "document" in value;
+}
+function browserScrollWindow() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { useScroll, useWindowScroll };