@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/disposal-scope.ts

@@ -0,0 +1,201 @@
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Stable error code reported when one or more owned cleanups fail. */
+export const DISPOSAL_ERROR_CODE = "VIZE_COMPOSE_DISPOSAL_FAILED" as const;
+
+/** Aggregate failure produced after every owned cleanup has been attempted. */
+export class DisposalError extends AggregateError {
+  /** Stable machine-readable error code. */
+  readonly code = DISPOSAL_ERROR_CODE;
+
+  /**
+   * Create an aggregate disposal failure.
+   *
+   * Nested {@link DisposalError} instances are flattened by the scope before
+   * construction, so `errors` contains the original cleanup failures in
+   * execution order.
+   *
+   * @param errors Cleanup failures in deterministic execution order.
+   */
+  constructor(errors: readonly unknown[]) {
+    super(errors, `[${DISPOSAL_ERROR_CODE}] ${String(errors.length)} cleanup operation(s) failed.`);
+    this.name = "DisposalError";
+  }
+}
+
+/** Handle for removing one cleanup from its owner before disposal. */
+export interface CleanupRegistration {
+  /** Whether this registration is still retained by its owner. */
+  readonly active: boolean;
+
+  /**
+   * Release the cleanup without running it.
+   *
+   * @returns Whether an active registration was removed.
+   */
+  readonly unregister: () => boolean;
+}
+
+/** Options for {@link createDisposalScope}. */
+export interface CreateDisposalScopeOptions {
+  /**
+   * Dispose the owner with the active Vue reactive scope when one exists.
+   * Outside a reactive scope, ownership remains entirely with the caller.
+   *
+   * @default true
+   */
+  readonly scope?: boolean;
+}
+
+/** Explicit owner for a deterministic group of cleanup operations. */
+export interface DisposalScope {
+  /** Whether disposal has started or completed. */
+  readonly disposed: boolean;
+
+  /** Number of active cleanup registrations currently retained. */
+  readonly size: number;
+
+  /**
+   * Register one cleanup.
+   *
+   * Active registrations run in last-in, first-out order. After disposal,
+   * registration runs the cleanup immediately and returns an inactive handle;
+   * a late failure is wrapped in {@link DisposalError}.
+   *
+   * @param cleanup Synchronous, idempotent resource cleanup.
+   * @returns A handle that can release the cleanup without running it.
+   * @throws {DisposalError} A late cleanup failed after the owner was disposed.
+   */
+  readonly add: <Cleanup extends () => unknown>(
+    cleanup: [ReturnType<Cleanup>] extends [never]
+      ? Cleanup
+      : ReturnType<Cleanup> extends PromiseLike<unknown>
+        ? never
+        : Cleanup,
+  ) => CleanupRegistration;
+
+  /**
+   * Create a child whose lifetime cannot outlive this owner.
+   *
+   * Disposing the child early unregisters it from the parent. Disposing the
+   * parent disposes the child in normal LIFO order.
+   *
+   * @returns A new child disposal scope.
+   */
+  readonly child: () => DisposalScope;
+
+  /**
+   * Run every active cleanup in last-in, first-out order exactly once.
+   *
+   * Reentrant and late registrations run immediately. All cleanups are
+   * attempted even when some fail. Repeated calls after successful or failed
+   * disposal do nothing.
+   *
+   * @throws {DisposalError} One or more cleanup operations failed.
+   */
+  readonly dispose: () => void;
+}
+
+interface CleanupRecord {
+  active: boolean;
+  readonly cleanup: () => unknown;
+}
+
+/**
+ * Create an explicit, deterministic cleanup owner.
+ *
+ * The owner is runtime-neutral and performs no browser-global access. By
+ * default it joins an active Vue reactive scope; when no scope exists, or
+ * `scope` is disabled, the caller must invoke `dispose()`. Cleanups are
+ * synchronous by contract so disposal completes before the owner releases
+ * its records.
+ *
+ * @param options Reactive-scope ownership behavior.
+ * @default options {}
+ * @returns A disposal owner with child-lifetime support.
+ */
+export function createDisposalScope(options: CreateDisposalScopeOptions = {}): DisposalScope {
+  const owner = createOwner();
+  if (options.scope ?? true) tryOnScopeDispose(owner.dispose);
+  return owner;
+}
+
+function createOwner(onDispose?: () => void): DisposalScope {
+  const records: CleanupRecord[] = [];
+  let disposed = false;
+  let size = 0;
+
+  const add = (cleanup: () => unknown): CleanupRegistration => {
+    if (disposed) {
+      try {
+        cleanup();
+      } catch (error) {
+        throw new DisposalError(flattenDisposalError(error));
+      }
+      return inactiveRegistration();
+    }
+
+    const record: CleanupRecord = { active: true, cleanup };
+    records.push(record);
+    size += 1;
+    return {
+      get active() {
+        return record.active;
+      },
+      unregister() {
+        if (!record.active) return false;
+        record.active = false;
+        size -= 1;
+        return true;
+      },
+    };
+  };
+
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    onDispose?.();
+
+    const errors: unknown[] = [];
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+      const record = records[index];
+      if (!record?.active) continue;
+      record.active = false;
+      size -= 1;
+      try {
+        record.cleanup();
+      } catch (error) {
+        errors.push(...flattenDisposalError(error));
+      }
+    }
+    records.length = 0;
+    if (errors.length > 0) throw new DisposalError(errors);
+  };
+
+  const child = () => {
+    let parentRegistration: CleanupRegistration | undefined;
+    const childOwner = createOwner(() => parentRegistration?.unregister());
+    parentRegistration = add(childOwner.dispose);
+    return childOwner;
+  };
+
+  return {
+    get disposed() {
+      return disposed;
+    },
+    get size() {
+      return size;
+    },
+    add,
+    child,
+    dispose,
+  };
+}
+
+function inactiveRegistration(): CleanupRegistration {
+  return { active: false, unregister: () => false };
+}
+
+function flattenDisposalError(error: unknown): readonly unknown[] {
+  return error instanceof DisposalError ? error.errors : [error];
+}

package/registry/files/document-visibility.ts

@@ -0,0 +1,152 @@
+import {
+  computed,
+  hasInjectionContext,
+  onMounted,
+  readonly,
+  ref,
+  shallowRef,
+  toValue,
+  watchEffect,
+} from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+/** Page visibility state exposed by {@link useDocumentVisibility}. */
+export type PageVisibilityState = "hidden" | "visible";
+
+/** Capability required to observe document visibility. */
+export interface DocumentVisibilityHost {
+  /** Current browser visibility state. Unknown states are treated as hidden. */
+  readonly visibilityState?: string;
+
+  /** Legacy visibility flag used when `visibilityState` is absent. */
+  readonly hidden?: boolean;
+
+  /** Subscribe to `visibilitychange`. */
+  readonly addEventListener: (
+    event: "visibilitychange",
+    listener: EventListener,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+
+  /** Remove a previous `visibilitychange` listener. */
+  readonly removeEventListener: (
+    event: "visibilitychange",
+    listener: EventListener,
+    options?: boolean | EventListenerOptions,
+  ) => void;
+}
+
+/** Options for {@link useDocumentVisibility}. */
+export interface UseDocumentVisibilityOptions {
+  /**
+   * State exposed while no document capability is available.
+   *
+   * @default "visible"
+   */
+  readonly ssrState?: PageVisibilityState;
+
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<DocumentVisibilityHost | null | undefined>;
+
+  /**
+   * Reactive subscription update timing.
+   *
+   * @default "pre"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+
+/** Reactive state returned by {@link useDocumentVisibility}. */
+export interface DocumentVisibilityControls {
+  /** Current visibility state, using the configured SSR fallback while unsupported. */
+  readonly state: Readonly<Ref<PageVisibilityState>>;
+
+  /** Whether a concrete document capability is currently attached. */
+  readonly supported: Readonly<Ref<boolean>>;
+
+  /** Whether `state` is `"visible"`. */
+  readonly visible: ComputedRef<boolean>;
+
+  /** Whether `state` is `"hidden"`. */
+  readonly hidden: ComputedRef<boolean>;
+}
+
+/**
+ * Observe document visibility without touching browser globals during module evaluation.
+ *
+ * The composable is safe during server rendering: when no host resolves, it exposes
+ * `ssrState` and marks `supported` false. During hydration or tests, passing a
+ * host attaches exactly one `visibilitychange` listener and removes it when the
+ * reactive host changes or the owning scope stops. Unsupported or future
+ * visibility states normalize to `"hidden"` so consumers fail closed instead of
+ * accidentally treating a prerendered or unloaded page as visible.
+ *
+ * @param options Runtime capability, server fallback, and watcher timing.
+ * @default options {}
+ * @returns Reactive visibility state plus derived booleans.
+ */
+export function useDocumentVisibility(
+  options: UseDocumentVisibilityOptions = {},
+): DocumentVisibilityControls {
+  const fallback = options.ssrState ?? "visible";
+  const state = ref<PageVisibilityState>(fallback);
+  const supported = 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;
+    });
+  }
+
+  watchEffect(
+    (onCleanup) => {
+      const host = !mounted.value
+        ? undefined
+        : options.host === undefined
+          ? browserDocumentVisibilityHost()
+          : toValue(options.host);
+      if (!host) {
+        supported.value = false;
+        state.value = fallback;
+        return;
+      }
+
+      const update = (): void => {
+        state.value = readVisibilityState(host);
+      };
+      supported.value = true;
+      update();
+      host.addEventListener("visibilitychange", update);
+      onCleanup(() => {
+        host.removeEventListener("visibilitychange", update);
+        supported.value = false;
+      });
+    },
+    { flush: options.flush ?? "pre" },
+  );
+
+  return {
+    state: readonly(state),
+    supported: readonly(supported),
+    visible: computed(() => state.value === "visible"),
+    hidden: computed(() => state.value === "hidden"),
+  };
+}
+
+function readVisibilityState(host: DocumentVisibilityHost): PageVisibilityState {
+  if (host.visibilityState === "visible") return "visible";
+  if (host.visibilityState === "hidden") return "hidden";
+  if (host.visibilityState !== undefined) return "hidden";
+  return host.hidden === false ? "visible" : "hidden";
+}
+
+function browserDocumentVisibilityHost(): DocumentVisibilityHost | undefined {
+  return typeof document !== "undefined" ? document : undefined;
+}

package/registry/files/draggable.ts

@@ -0,0 +1,273 @@
+import { computed, readonly, ref, toValue, watch } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+import { isElementNode, resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import type { Point } from "./mouse.ts";
+import { toPointerKind } from "./pointer.ts";
+import type { PointerKind } from "./pointer.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Axis constraint for {@link useDraggable}. */
+export type DragAxis = "x" | "y" | "both";
+
+/** Rectangle (in the same coordinate space as the position) that bounds dragging. */
+export interface DragBounds {
+  /** Minimum x. */
+  readonly left: number;
+  /** Minimum y. */
+  readonly top: number;
+  /** Maximum x of the dragged element's right edge. */
+  readonly right: number;
+  /** Maximum y of the dragged element's bottom edge. */
+  readonly bottom: number;
+}
+
+/** Options for {@link useDraggable}. */
+export interface UseDraggableOptions {
+  /**
+   * Element that starts the drag. Defaults to the dragged element itself.
+   *
+   * @default undefined (the target)
+   */
+  readonly handle?: MaybeElementTarget;
+
+  /**
+   * Restrict movement to one axis.
+   *
+   * @default "both"
+   */
+  readonly axis?: MaybeRefOrGetter<DragAxis>;
+
+  /**
+   * Keep the element inside these bounds, or inside a container element's
+   * client rectangle.
+   *
+   * @default undefined (unbounded)
+   */
+  readonly bounds?: MaybeRefOrGetter<DragBounds | null | undefined> | MaybeElementTarget;
+
+  /**
+   * Position before the first drag and during server rendering.
+   *
+   * @default { x: 0, y: 0 }
+   */
+  readonly initialValue?: Point;
+
+  /**
+   * Device kinds that may start a drag.
+   *
+   * @default ["mouse", "touch", "pen"]
+   */
+  readonly pointerTypes?: readonly PointerKind[];
+
+  /**
+   * Only start when the pointer goes down on the handle itself, not a descendant.
+   *
+   * @default false
+   */
+  readonly exact?: boolean;
+
+  /**
+   * Call `preventDefault()` on pointer events while dragging.
+   *
+   * @default false
+   */
+  readonly preventDefault?: boolean;
+
+  /**
+   * Temporarily disable dragging.
+   *
+   * @default false
+   */
+  readonly disabled?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * Called before a drag starts. Return `false` to cancel it.
+   *
+   * @default undefined
+   */
+  readonly onStart?: (position: Point, event: PointerEvent) => boolean | void;
+
+  /**
+   * Called after every position update.
+   *
+   * @default undefined
+   */
+  readonly onMove?: (position: Point, event: PointerEvent) => void;
+
+  /**
+   * Called when the drag ends.
+   *
+   * @default undefined
+   */
+  readonly onEnd?: (position: Point, event: PointerEvent) => void;
+}
+
+/** Reactive drag state returned by {@link useDraggable}. */
+export interface DraggableControls {
+  /** Horizontal position (the element's left edge in client coordinates). */
+  readonly x: Ref<number>;
+  /** Vertical position (the element's top edge in client coordinates). */
+  readonly y: Ref<number>;
+  /** Current position snapshot. */
+  readonly position: ComputedRef<Point>;
+  /** Whether a drag is in progress. */
+  readonly isDragging: Readonly<Ref<boolean>>;
+  /** `left`/`top` declaration for `position: fixed` or `absolute` placement. */
+  readonly style: ComputedRef<string>;
+  /** Remove listeners. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Make an element draggable with Pointer Events.
+ *
+ * `pointerdown` on the handle records the offset between the pointer and the
+ * element; moves are tracked on the owner document (so fast drags that leave
+ * the element keep working) and constrained by `axis` and `bounds`. `x`/`y`
+ * are writable for programmatic placement. Server renders expose
+ * `initialValue`; listeners are removed with the owning reactive scope.
+ *
+ * @param target Reactive element being dragged.
+ * @param options Handle, axis, bounds, device filter, and lifecycle callbacks.
+ * @default options {}
+ * @returns Writable position, drag flag, inline style, and stop control.
+ */
+export function useDraggable(
+  target: MaybeElementTarget,
+  options: UseDraggableOptions = {},
+): DraggableControls {
+  const initial = options.initialValue ?? { x: 0, y: 0 };
+  const x = ref(initial.x);
+  const y = ref(initial.y);
+  const isDragging = ref(false);
+  const pointerTypes = options.pointerTypes ?? ["mouse", "touch", "pen"];
+  const position = computed<Point>(() => ({ x: x.value, y: y.value }));
+  let offset: Point | null = null;
+  let activePointer: number | null = null;
+
+  const constrain = (element: Element, next: Point): Point => {
+    const bounds = readBounds(options.bounds);
+    if (!bounds) return next;
+    const rect = element.getBoundingClientRect();
+    return {
+      x: clamp(next.x, bounds.left, Math.max(bounds.left, bounds.right - rect.width)),
+      y: clamp(next.y, bounds.top, Math.max(bounds.top, bounds.bottom - rect.height)),
+    };
+  };
+  const accepts = (event: Event): event is PointerEvent => {
+    if (!isPointerEvent(event)) return false;
+    const kind = toPointerKind(event.pointerType);
+    return kind !== null && pointerTypes.includes(kind);
+  };
+  const handleEvent = (event: PointerEvent): void => {
+    if (options.preventDefault && event.cancelable) event.preventDefault();
+  };
+
+  const stopWatch = watch(
+    () =>
+      [
+        resolveElement(target),
+        options.handle === undefined ? undefined : resolveElement(options.handle),
+      ] as const,
+    ([element, handleOverride], _previous, onCleanup) => {
+      const handle = handleOverride === undefined ? element : handleOverride;
+      if (!element || !handle) return;
+      const document = element.ownerDocument;
+
+      const onMove = (event: Event): void => {
+        if (!accepts(event) || event.pointerId !== activePointer || !offset) return;
+        const axis = toValue(options.axis) ?? "both";
+        const next = constrain(element, {
+          x: axis === "y" ? x.value : event.clientX - offset.x,
+          y: axis === "x" ? y.value : event.clientY - offset.y,
+        });
+        x.value = next.x;
+        y.value = next.y;
+        handleEvent(event);
+        options.onMove?.(next, event);
+      };
+      const onUp = (event: Event): void => {
+        if (!accepts(event) || event.pointerId !== activePointer) return;
+        activePointer = null;
+        offset = null;
+        isDragging.value = false;
+        document.removeEventListener("pointermove", onMove);
+        document.removeEventListener("pointerup", onUp);
+        document.removeEventListener("pointercancel", onUp);
+        handleEvent(event);
+        options.onEnd?.(position.value, event);
+      };
+      const onDown = (event: Event): void => {
+        if (!accepts(event) || toValue(options.disabled) || activePointer !== null) return;
+        if (event.pointerType === "mouse" && event.button !== 0) return;
+        if (options.exact && event.target !== handle) return;
+        const rect = element.getBoundingClientRect();
+        const start = { x: rect.left, y: rect.top };
+        if (options.onStart?.(start, event) === false) return;
+        activePointer = event.pointerId;
+        offset = { x: event.clientX - rect.left, y: event.clientY - rect.top };
+        isDragging.value = true;
+        document.addEventListener("pointermove", onMove);
+        document.addEventListener("pointerup", onUp);
+        document.addEventListener("pointercancel", onUp);
+        handleEvent(event);
+      };
+
+      handle.addEventListener("pointerdown", onDown);
+      onCleanup(() => {
+        handle.removeEventListener("pointerdown", onDown);
+        document.removeEventListener("pointermove", onMove);
+        document.removeEventListener("pointerup", onUp);
+        document.removeEventListener("pointercancel", onUp);
+        activePointer = null;
+        offset = null;
+        isDragging.value = false;
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+
+  return {
+    x,
+    y,
+    position,
+    isDragging: readonly(isDragging),
+    style: computed(() => `left:${x.value}px;top:${y.value}px;`),
+    stop,
+  };
+}
+
+function readBounds(source: UseDraggableOptions["bounds"]): DragBounds | null {
+  if (source === undefined) return null;
+  const value: unknown = toValue(source);
+  if (isDragBounds(value)) return value;
+  const root: unknown =
+    typeof value === "object" && value !== null && "$el" in value ? value.$el : value;
+  if (!isElementNode(root)) return null;
+  const element = root;
+  const rect = element.getBoundingClientRect();
+  return { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom };
+}
+
+function isDragBounds(value: unknown): value is DragBounds {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !("nodeType" in value) &&
+    !("$el" in value) &&
+    "left" in value &&
+    "right" in value
+  );
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(Math.max(value, minimum), maximum);
+}
+
+function isPointerEvent(event: Event): event is PointerEvent {
+  return "pointerId" in event && "pointerType" in event;
+}