@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/swipe.ts

@@ -0,0 +1,321 @@
+import { computed, readonly, ref, shallowReactive, shallowReadonly, watch } from "vue";
+import type { ComputedRef, Ref } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import type { Point } from "./mouse.ts";
+import type { PointerKind } from "./pointer.ts";
+import { toPointerKind } from "./pointer.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Dominant direction of a swipe gesture. `"none"` below the threshold. */
+export type SwipeDirection = "up" | "down" | "left" | "right" | "none";
+
+/** Callbacks shared by {@link useSwipe} and {@link usePointerSwipe}. */
+export interface SwipeCallbacks<GestureEvent extends Event> {
+  /**
+   * Called when a gesture starts.
+   *
+   * @default undefined
+   */
+  readonly onSwipeStart?: (event: GestureEvent) => void;
+
+  /**
+   * Called on every move after the threshold has been exceeded.
+   *
+   * @default undefined
+   */
+  readonly onSwipe?: (event: GestureEvent) => void;
+
+  /**
+   * Called when a gesture that exceeded the threshold ends.
+   *
+   * @default undefined
+   */
+  readonly onSwipeEnd?: (event: GestureEvent, direction: SwipeDirection) => void;
+}
+
+/** Options for {@link useSwipe}. */
+export interface UseSwipeOptions extends SwipeCallbacks<TouchEvent> {
+  /**
+   * Minimum travel in CSS pixels before a gesture counts as a swipe.
+   *
+   * @default 50
+   */
+  readonly threshold?: number;
+
+  /**
+   * Register passive touch listeners. Set to `false` to call
+   * `preventDefault()` on moves while swiping (for example to block
+   * pull-to-refresh).
+   *
+   * @default true
+   */
+  readonly passive?: boolean;
+}
+
+/** Reactive gesture state shared by the swipe composables. */
+export interface SwipeControls {
+  /** Whether a gesture past the threshold is in progress. */
+  readonly isSwiping: Readonly<Ref<boolean>>;
+  /** Dominant direction of the current (or last) gesture. */
+  readonly direction: ComputedRef<SwipeDirection>;
+  /** Gesture start coordinates. */
+  readonly coordsStart: Readonly<Point>;
+  /** Latest gesture coordinates. */
+  readonly coordsEnd: Readonly<Point>;
+  /** `start.x - end.x`: positive when moving left. */
+  readonly lengthX: ComputedRef<number>;
+  /** `start.y - end.y`: positive when moving up. */
+  readonly lengthY: ComputedRef<number>;
+  /** Remove listeners. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Classify a displacement into a {@link SwipeDirection}.
+ *
+ * Pure helper shared by the swipe composables and usable for custom gesture
+ * recognizers.
+ *
+ * @param lengthX `start.x - end.x`.
+ * @param lengthY `start.y - end.y`.
+ * @param threshold Minimum travel before a direction is reported.
+ * @returns The dominant axis direction, or `"none"`.
+ */
+export function swipeDirection(
+  lengthX: number,
+  lengthY: number,
+  threshold: number,
+): SwipeDirection {
+  if (Math.max(Math.abs(lengthX), Math.abs(lengthY)) < threshold) return "none";
+  if (Math.abs(lengthX) > Math.abs(lengthY)) return lengthX > 0 ? "left" : "right";
+  return lengthY > 0 ? "up" : "down";
+}
+
+interface GestureCore {
+  readonly controls: Omit<SwipeControls, "stop">;
+  readonly begin: (point: Point) => void;
+  readonly move: (point: Point) => boolean;
+  readonly reset: () => void;
+  readonly swiping: Ref<boolean>;
+}
+
+function createGesture(threshold: number): GestureCore {
+  const coordsStart = shallowReactive({ x: 0, y: 0 });
+  const coordsEnd = shallowReactive({ x: 0, y: 0 });
+  const swiping = ref(false);
+  const lengthX = computed(() => coordsStart.x - coordsEnd.x);
+  const lengthY = computed(() => coordsStart.y - coordsEnd.y);
+  const direction = computed(() => swipeDirection(lengthX.value, lengthY.value, threshold));
+  return {
+    controls: {
+      isSwiping: readonly(swiping),
+      direction,
+      coordsStart: shallowReadonly(coordsStart),
+      coordsEnd: shallowReadonly(coordsEnd),
+      lengthX,
+      lengthY,
+    },
+    begin: (point) => {
+      coordsStart.x = point.x;
+      coordsStart.y = point.y;
+      coordsEnd.x = point.x;
+      coordsEnd.y = point.y;
+    },
+    move: (point) => {
+      coordsEnd.x = point.x;
+      coordsEnd.y = point.y;
+      if (!swiping.value && direction.value !== "none") swiping.value = true;
+      return swiping.value;
+    },
+    reset: () => {
+      swiping.value = false;
+    },
+    swiping,
+  };
+}
+
+/**
+ * Detect touch swipes on an element.
+ *
+ * Tracks the first touch point from `touchstart` through `touchend`/
+ * `touchcancel`. Direction is derived from the dominant axis once the travel
+ * exceeds `threshold`. Server renders expose zeroed coordinates and
+ * `direction: "none"`; listeners are removed with the owning scope.
+ *
+ * @param target Reactive element target.
+ * @param options Threshold, passivity, and callbacks.
+ * @default options {}
+ * @returns Reactive gesture state and stop control.
+ */
+export function useSwipe(target: MaybeElementTarget, options: UseSwipeOptions = {}): SwipeControls {
+  const gesture = createGesture(options.threshold ?? 50);
+  const passive = options.passive ?? true;
+
+  const firstTouch = (event: TouchEvent): Point | null => {
+    const touch = event.touches[0] ?? event.changedTouches[0];
+    return touch ? { x: touch.clientX, y: touch.clientY } : null;
+  };
+  const onStart = (event: Event): void => {
+    if (!isTouchEvent(event)) return;
+    const point = firstTouch(event);
+    if (!point || event.touches.length > 1) return;
+    gesture.begin(point);
+    options.onSwipeStart?.(event);
+  };
+  const onMove = (event: Event): void => {
+    if (!isTouchEvent(event)) return;
+    const point = firstTouch(event);
+    if (!point) return;
+    if (!gesture.move(point)) return;
+    if (!passive && event.cancelable) event.preventDefault();
+    options.onSwipe?.(event);
+  };
+  const onEnd = (event: Event): void => {
+    if (!isTouchEvent(event)) return;
+    if (gesture.swiping.value) options.onSwipeEnd?.(event, gesture.controls.direction.value);
+    gesture.reset();
+  };
+
+  const stopWatch = watch(
+    () => resolveElement(target),
+    (element, _previous, onCleanup) => {
+      if (!element) return;
+      const listenerOptions: AddEventListenerOptions = { passive };
+      element.addEventListener("touchstart", onStart, { passive: true });
+      element.addEventListener("touchmove", onMove, listenerOptions);
+      element.addEventListener("touchend", onEnd, { passive: true });
+      element.addEventListener("touchcancel", onEnd, { passive: true });
+      onCleanup(() => {
+        element.removeEventListener("touchstart", onStart);
+        element.removeEventListener("touchmove", onMove);
+        element.removeEventListener("touchend", onEnd);
+        element.removeEventListener("touchcancel", onEnd);
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+  return { ...gesture.controls, stop };
+}
+
+/** Options for {@link usePointerSwipe}. */
+export interface UsePointerSwipeOptions extends SwipeCallbacks<PointerEvent> {
+  /**
+   * Minimum travel in CSS pixels before a gesture counts as a swipe.
+   *
+   * @default 50
+   */
+  readonly threshold?: number;
+
+  /**
+   * Device kinds that may start a gesture.
+   *
+   * @default ["mouse", "touch", "pen"]
+   */
+  readonly pointerTypes?: readonly PointerKind[];
+
+  /**
+   * Suppress text selection on the element while a gesture is active.
+   *
+   * @default false
+   */
+  readonly disableTextSelect?: boolean;
+}
+
+/**
+ * Detect swipes from any pointer device (mouse, touch, pen).
+ *
+ * Captures the pointer on `pointerdown` so moves outside the element still
+ * count, and ignores secondary pointers during a gesture. Shares the state
+ * shape and SSR defaults of {@link useSwipe}.
+ *
+ * @param target Reactive element target.
+ * @param options Threshold, device filter, selection handling, and callbacks.
+ * @default options {}
+ * @returns Reactive gesture state and stop control.
+ */
+export function usePointerSwipe(
+  target: MaybeElementTarget,
+  options: UsePointerSwipeOptions = {},
+): SwipeControls {
+  const gesture = createGesture(options.threshold ?? 50);
+  const pointerTypes = options.pointerTypes ?? ["mouse", "touch", "pen"];
+  let activePointer: number | null = null;
+
+  const accepts = (event: Event): event is PointerEvent => {
+    if (!isPointerEvent(event)) return false;
+    const kind = toPointerKind(event.pointerType);
+    return kind !== null && pointerTypes.includes(kind);
+  };
+  const setSelection = (element: Element, disabled: boolean): void => {
+    if (!options.disableTextSelect || !hasStyle(element)) return;
+    element.style.setProperty("user-select", disabled ? "none" : "");
+    element.style.setProperty("-webkit-user-select", disabled ? "none" : "");
+  };
+
+  const stopWatch = watch(
+    () => resolveElement(target),
+    (element, _previous, onCleanup) => {
+      if (!element) return;
+      const onDown = (event: Event): void => {
+        if (!accepts(event) || activePointer !== null) return;
+        if (event.pointerType === "mouse" && event.button !== 0) return;
+        activePointer = event.pointerId;
+        if (hasPointerCapture(element)) element.setPointerCapture(event.pointerId);
+        gesture.begin({ x: event.clientX, y: event.clientY });
+        setSelection(element, true);
+        options.onSwipeStart?.(event);
+      };
+      const onMove = (event: Event): void => {
+        if (!accepts(event) || event.pointerId !== activePointer) return;
+        if (gesture.move({ x: event.clientX, y: event.clientY })) options.onSwipe?.(event);
+      };
+      const onUp = (event: Event): void => {
+        if (!accepts(event) || event.pointerId !== activePointer) return;
+        activePointer = null;
+        if (hasPointerCapture(element)) element.releasePointerCapture(event.pointerId);
+        if (gesture.swiping.value) options.onSwipeEnd?.(event, gesture.controls.direction.value);
+        gesture.reset();
+        setSelection(element, false);
+      };
+      element.addEventListener("pointerdown", onDown, { passive: true });
+      element.addEventListener("pointermove", onMove, { passive: true });
+      element.addEventListener("pointerup", onUp, { passive: true });
+      element.addEventListener("pointercancel", onUp, { passive: true });
+      onCleanup(() => {
+        element.removeEventListener("pointerdown", onDown);
+        element.removeEventListener("pointermove", onMove);
+        element.removeEventListener("pointerup", onUp);
+        element.removeEventListener("pointercancel", onUp);
+        activePointer = null;
+        gesture.reset();
+        setSelection(element, false);
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+  return { ...gesture.controls, stop };
+}
+
+function isTouchEvent(event: Event): event is TouchEvent {
+  return "touches" in event && "changedTouches" in event;
+}
+
+function isPointerEvent(event: Event): event is PointerEvent {
+  return "pointerId" in event && "pointerType" in event;
+}
+
+function hasPointerCapture(
+  element: Element,
+): element is Element & Pick<HTMLElement, "setPointerCapture" | "releasePointerCapture"> {
+  return typeof element.setPointerCapture === "function";
+}
+
+function hasStyle(element: Element): element is Element & ElementCSSInlineStyle {
+  return "style" in element && typeof element.style === "object" && element.style !== null;
+}

package/registry/files/sync-ref.ts

@@ -0,0 +1,166 @@
+import { watch } from "vue";
+import type { Ref } from "vue";
+
+/** Which way {@link syncRef} copies values. */
+export type SyncRefDirection = "ltr" | "rtl" | "both";
+
+/** Converters required by {@link syncRef} for the chosen direction. */
+export type SyncRefTransform<
+  Left,
+  Right,
+  Direction extends SyncRefDirection,
+> = Direction extends "ltr"
+  ? { readonly ltr: (left: Left) => Right }
+  : Direction extends "rtl"
+    ? { readonly rtl: (right: Right) => Left }
+    : { readonly ltr: (left: Left) => Right; readonly rtl: (right: Right) => Left };
+
+/** Whether two types are mutually assignable (identical for syncing purposes). */
+type SameType<Left, Right> = [Left] extends [Right]
+  ? [Right] extends [Left]
+    ? true
+    : false
+  : false;
+
+/** Options for {@link syncRef}; `transform` is required when the ref types differ. */
+export type SyncRefOptions<
+  Left,
+  Right,
+  Direction extends SyncRefDirection = "both",
+> = SyncRefBaseOptions<Direction> &
+  (SameType<Left, Right> extends true
+    ? {
+        /**
+         * Converters between the two refs.
+         *
+         * @default identity
+         */
+        readonly transform?: Partial<SyncRefTransform<Left, Right, Direction>>;
+      }
+    : {
+        /** Converters between the two refs (required: the types differ). */
+        readonly transform: SyncRefTransform<Left, Right, Direction>;
+      });
+
+/** Direction and timing options shared by every {@link syncRef} call. */
+export interface SyncRefBaseOptions<Direction extends SyncRefDirection = "both"> {
+  /**
+   * `"ltr"` copies left to right, `"rtl"` right to left, `"both"` both ways.
+   *
+   * @default "both"
+   */
+  readonly direction?: Direction;
+
+  /**
+   * Watch flush timing.
+   *
+   * @default "sync"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+
+  /**
+   * Watch nested changes.
+   *
+   * @default false
+   */
+  readonly deep?: boolean;
+
+  /**
+   * Copy once right away (left wins for `"both"`/`"ltr"`, right for `"rtl"`).
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+}
+
+/**
+ * Keep two refs in sync, optionally converting between their types.
+ *
+ * The option type is computed from both ref types: converters may be
+ * omitted only when the types are identical, and exactly the converters the
+ * direction needs are required otherwise. A re-entrancy guard prevents
+ * ping-pong when converters are not exact inverses. Watchers follow the
+ * owning reactive scope; SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const celsius = ref(20);
+ * const label = ref("");
+ * syncRef(celsius, label, {
+ *   transform: { ltr: (c) => `${c}°C`, rtl: (text) => Number.parseFloat(text) },
+ * });
+ * ```
+ *
+ * @param left First ref.
+ * @param right Second ref.
+ * @param options Direction, timing, and converters.
+ * @returns Stops every sync watcher.
+ */
+export function syncRef<Left, Right = Left, const Direction extends SyncRefDirection = "both">(
+  left: Ref<Left>,
+  right: Ref<Right>,
+  ...options: SameType<Left, Right> extends true
+    ? [options?: SyncRefOptions<Left, Right, Direction>]
+    : [options: SyncRefOptions<Left, Right, Direction>]
+): () => void;
+export function syncRef(
+  left: Ref<unknown>,
+  right: Ref<unknown>,
+  options: SyncRefBaseOptions<SyncRefDirection> & {
+    readonly transform?: {
+      readonly ltr?: (left: unknown) => unknown;
+      readonly rtl?: (right: unknown) => unknown;
+    };
+  } = {},
+): () => void {
+  const direction = options.direction ?? "both";
+  const toRight = options.transform?.ltr ?? ((value: unknown) => value);
+  const toLeft = options.transform?.rtl ?? ((value: unknown) => value);
+  const watchOptions = {
+    flush: options.flush ?? "sync",
+    deep: options.deep ?? false,
+  } as const;
+  const stops: (() => void)[] = [];
+  let syncing = false;
+
+  const guarded = (copy: () => void): void => {
+    if (syncing) return;
+    syncing = true;
+    try {
+      copy();
+    } finally {
+      syncing = false;
+    }
+  };
+
+  if (direction !== "rtl") {
+    stops.push(
+      watch(
+        left,
+        (value) => {
+          guarded(() => {
+            right.value = toRight(value);
+          });
+        },
+        { ...watchOptions, immediate: options.immediate ?? true },
+      ),
+    );
+  }
+  if (direction !== "ltr") {
+    stops.push(
+      watch(
+        right,
+        (value) => {
+          guarded(() => {
+            left.value = toLeft(value);
+          });
+        },
+        { ...watchOptions, immediate: direction === "rtl" && (options.immediate ?? true) },
+      ),
+    );
+  }
+
+  return () => {
+    for (const stop of stops) stop();
+  };
+}

package/registry/files/temporal.ts

@@ -0,0 +1,182 @@
+import { computed, readonly, shallowRef, toValue, watchEffect } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+import { Intl as TemporalIntl, Temporal } from "temporal-polyfill-lite";
+
+/**
+ * Timer host used by {@link useTemporalNow}.
+ *
+ * Implement this interface to integrate a deterministic clock, a native
+ * runtime timer, or an application-owned scheduler.
+ */
+export interface TemporalScheduler {
+  /** Starts a repeating callback and returns its opaque cancellation handle. */
+  readonly setInterval: (callback: () => void, intervalMs: number) => unknown;
+
+  /** Cancels a handle previously returned by {@link TemporalScheduler.setInterval}. */
+  readonly clearInterval: (handle: unknown) => void;
+}
+
+/** Options for {@link useTemporalNow}. */
+export interface UseTemporalNowOptions {
+  /**
+   * Clock update interval in milliseconds.
+   *
+   * Reactive changes replace the active timer. Values must be finite and
+   * greater than zero.
+   *
+   * @default 1000
+   */
+  readonly intervalMs?: MaybeRefOrGetter<number>;
+
+  /**
+   * Pauses periodic updates while preserving the current instant.
+   * Manual calls to {@link TemporalClock.refresh} continue to work.
+   *
+   * @default false
+   */
+  readonly paused?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * Starts the timer when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering. Enable it for native,
+   * desktop, worker, and test runtimes whose scheduler is lifecycle-bound.
+   *
+   * @default false
+   */
+  readonly runOnServer?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * Produces the current instant.
+   *
+   * @default Temporal.Now.instant
+   */
+  readonly now?: () => Temporal.Instant;
+
+  /**
+   * Owns the repeating timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TemporalScheduler;
+}
+
+/** Reactive controls returned by {@link useTemporalNow}. */
+export interface TemporalClock {
+  /** The latest instant. This ref is readonly to consumers. */
+  readonly instant: Readonly<Ref<Temporal.Instant>>;
+
+  /** Reads the clock source immediately, stores the value, and returns it. */
+  readonly refresh: () => Temporal.Instant;
+}
+
+/** Options for {@link useTemporalZonedDateTime}. */
+export interface UseTemporalZonedDateTimeOptions extends UseTemporalNowOptions {
+  /**
+   * Time-zone identifier or zoned date-time accepted by Temporal.
+   *
+   * @default Temporal.Now.timeZoneId()
+   */
+  readonly timeZone?: MaybeRefOrGetter<Temporal.TimeZoneLike>;
+}
+
+const defaultScheduler: TemporalScheduler = {
+  setInterval: (callback, intervalMs) => globalThis.setInterval(callback, intervalMs),
+  clearInterval: (handle) => {
+    globalThis.clearInterval(handle as ReturnType<typeof setInterval>);
+  },
+};
+
+function resolveIntervalMs(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_TEMPORAL_INVALID_INTERVAL] intervalMs must be finite and greater than zero; received ${String(value)}`,
+    );
+  }
+
+  return Math.max(1, Math.trunc(value));
+}
+
+function shouldSchedule(options: UseTemporalNowOptions): boolean {
+  if (toValue(options.paused ?? false)) return false;
+  return typeof window !== "undefined" || toValue(options.runOnServer ?? false);
+}
+
+/**
+ * Creates a pauseable Temporal clock whose timer follows the current Vue
+ * effect scope.
+ *
+ * The timer is replaced when reactive options change and is always cancelled
+ * when the owning scope stops. Call inside an active effect scope; without
+ * one, there is no automatic timer cleanup. During
+ * server rendering, no timer starts unless
+ * {@link UseTemporalNowOptions.runOnServer} is explicitly enabled.
+ *
+ * @param options Clock scheduling, pause, and runtime overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TEMPORAL_INVALID_INTERVAL` when
+ * the resolved interval is not finite or not greater than zero, both
+ * synchronously at creation and on invalid reactive updates.
+ * @returns Reactive clock controls.
+ */
+export function useTemporalNow(options: UseTemporalNowOptions = {}): TemporalClock {
+  const readNow = options.now ?? Temporal.Now.instant;
+  const instant = shallowRef(readNow());
+
+  // Fail synchronously for invalid initial input. Reactive updates are still
+  // validated inside the watcher before a replacement timer is created.
+  if (shouldSchedule(options)) resolveIntervalMs(toValue(options.intervalMs ?? 1_000));
+
+  const refresh = (): Temporal.Instant => {
+    const nextInstant = readNow();
+    instant.value = nextInstant;
+    return nextInstant;
+  };
+
+  watchEffect((onCleanup) => {
+    if (!shouldSchedule(options)) return;
+
+    const intervalMs = resolveIntervalMs(toValue(options.intervalMs ?? 1_000));
+    const scheduler = options.scheduler ?? defaultScheduler;
+    const handle = scheduler.setInterval(refresh, intervalMs);
+
+    onCleanup(() => scheduler.clearInterval(handle));
+  });
+
+  return {
+    instant: readonly(instant),
+    refresh,
+  };
+}
+
+/**
+ * Creates a reactive zoned date-time derived from a scoped Temporal clock.
+ *
+ * Changes to {@link UseTemporalZonedDateTimeOptions.timeZone} are reflected
+ * without replacing the underlying timer. Scheduling, server rendering, and
+ * scope-cleanup rules are shared with {@link useTemporalNow}.
+ *
+ * @param options Clock scheduling plus the reactive time zone.
+ * @default options {}
+ * @throws `RangeError` for invalid intervals (see {@link useTemporalNow}),
+ * and on read when the reactive time zone cannot be resolved by Temporal.
+ * @returns Computed zoned date-time in the reactive time zone.
+ */
+export function useTemporalZonedDateTime(
+  options: UseTemporalZonedDateTimeOptions = {},
+): ComputedRef<Temporal.ZonedDateTime> {
+  const clock = useTemporalNow(options);
+
+  return computed(() => {
+    const timeZone =
+      options.timeZone === undefined ? Temporal.Now.timeZoneId() : toValue(options.timeZone);
+
+    return clock.instant.value.toZonedDateTimeISO(timeZone);
+  });
+}
+
+/**
+ * Temporal API namespaces re-exported from the underlying polyfill so hosts
+ * can construct instants and time zones without a direct dependency.
+ */
+export { Temporal, TemporalIntl };