@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/text-selection.ts

@@ -0,0 +1,110 @@
+import { computed, hasInjectionContext, shallowRef, toValue, watch, watchPostEffect } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Document-like capability observed by {@link useTextSelection}. */
+export interface TextSelectionHost extends EventTarget {
+  /** Current selection. */
+  getSelection(): Selection | null;
+}
+
+/** Options for {@link useTextSelection}. */
+export interface UseTextSelectionOptions {
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<TextSelectionHost | null | undefined>;
+}
+
+/** Reactive selection state returned by {@link useTextSelection}. */
+export interface TextSelectionControls {
+  /** Current `Selection` object; `null` during server rendering. */
+  readonly selection: Readonly<ShallowRef<Selection | null>>;
+  /** Selected text. Empty during server rendering. */
+  readonly text: ComputedRef<string>;
+  /** Selected ranges. */
+  readonly ranges: ComputedRef<readonly Range[]>;
+  /** Client rectangles of each selected range. */
+  readonly rects: ComputedRef<readonly DOMRect[]>;
+}
+
+/**
+ * Track the document text selection.
+ *
+ * Re-reads the selection on every `selectionchange`. Because the platform
+ * mutates the same `Selection` object in place, a revision counter is used to
+ * invalidate the derived `text`, `ranges`, and `rects`. Server renders expose
+ * an empty selection; the listener is removed with the owning scope.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param options Document capability.
+ * @default options {}
+ * @returns Reactive selection, text, ranges, and rectangles.
+ */
+export function useTextSelection(options: UseTextSelectionOptions = {}): TextSelectionControls {
+  const selection = shallowRef<Selection | null>(null);
+  const revision = shallowRef(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 stop = watch(
+    () =>
+      hydrated.value
+        ? options.host === undefined
+          ? browserSelectionHost()
+          : toValue(options.host)
+        : undefined,
+    (host, _previous, onCleanup) => {
+      if (!host) {
+        selection.value = null;
+        return;
+      }
+      const update = (): void => {
+        selection.value = host.getSelection();
+        revision.value += 1;
+      };
+      update();
+      host.addEventListener("selectionchange", update, { passive: true });
+      onCleanup(() => host.removeEventListener("selectionchange", update));
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  const ranges = computed<readonly Range[]>(() => {
+    void revision.value;
+    const current = selection.value;
+    if (!current) return [];
+    const list: Range[] = [];
+    for (let index = 0; index < current.rangeCount; index += 1) {
+      list.push(current.getRangeAt(index));
+    }
+    return list;
+  });
+
+  return {
+    selection,
+    text: computed(() => {
+      void revision.value;
+      return selection.value?.toString() ?? "";
+    }),
+    ranges,
+    rects: computed(() => ranges.value.map((range) => range.getBoundingClientRect())),
+  };
+}
+
+function browserSelectionHost(): TextSelectionHost | undefined {
+  return typeof document !== "undefined" ? document : undefined;
+}

package/registry/files/textarea-autosize.ts

@@ -0,0 +1,114 @@
+import { ref, watch } from "vue";
+import type { Ref } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { useResizeObserver } from "./resize-observer.ts";
+import type { ResizeObserverHost } from "./resize-observer.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+import type { MaybeRefOrGetter } from "vue";
+
+/** Style property that receives the measured height. */
+export type TextareaAutosizeStyleProperty = "height" | "min-height";
+
+/** Options for {@link useTextareaAutosize}. */
+export interface UseTextareaAutosizeOptions {
+  /**
+   * Text bound to the textarea. Changes trigger a resize. A fresh ref is
+   * created when omitted.
+   *
+   * @default ref("")
+   */
+  readonly input?: Ref<string>;
+
+  /**
+   * Style property written with the measured height.
+   *
+   * @default "height"
+   */
+  readonly styleProp?: TextareaAutosizeStyleProperty;
+
+  /**
+   * Called after each resize with the new height.
+   *
+   * @default undefined
+   */
+  readonly onResize?: (height: number) => void;
+
+  /**
+   * Resize-observer capability used to re-measure when the width changes.
+   *
+   * @default globalThis when it provides `ResizeObserver`
+   */
+  readonly host?: MaybeRefOrGetter<ResizeObserverHost | null | undefined>;
+}
+
+/** Textarea-like element measured by {@link useTextareaAutosize}. */
+interface AutosizeElement extends Element {
+  readonly scrollHeight: number;
+  readonly style: Pick<CSSStyleDeclaration, "setProperty" | "removeProperty">;
+}
+
+/** State returned by {@link useTextareaAutosize}. */
+export interface TextareaAutosizeControls {
+  /** Text bound to the textarea (use with `v-model`). */
+  readonly input: Ref<string>;
+  /** Re-measure immediately. */
+  readonly triggerResize: () => void;
+}
+
+/**
+ * Grow a textarea to fit its content.
+ *
+ * On each input change (and when the element width changes), the style
+ * property is reset to `auto`, `scrollHeight` is read, and the height is
+ * written back in pixels. Nothing is measured during server rendering, so the
+ * markup keeps its declared `rows`.
+ *
+ * @param target Reactive textarea target.
+ * @param options Bound input, style property, callback, and observer capability.
+ * @default options {}
+ * @returns Bound input and a manual resize trigger.
+ */
+export function useTextareaAutosize(
+  target: MaybeElementTarget,
+  options: UseTextareaAutosizeOptions = {},
+): TextareaAutosizeControls {
+  const input = options.input ?? ref("");
+  const styleProp = options.styleProp ?? "height";
+  let lastWidth = -1;
+
+  const triggerResize = (): void => {
+    const element = resolveElement(target);
+    if (!element || !isAutosizeElement(element)) return;
+    element.style.setProperty(styleProp, "auto");
+    const height = element.scrollHeight;
+    element.style.setProperty(styleProp, `${height}px`);
+    options.onResize?.(height);
+  };
+
+  const stop = watch([input, () => resolveElement(target)], triggerResize, {
+    immediate: true,
+    flush: "post",
+  });
+  const observer = useResizeObserver(
+    target,
+    (entries) => {
+      const width = entries.at(-1)?.contentRect.width ?? -1;
+      if (width === lastWidth) return;
+      lastWidth = width;
+      triggerResize();
+    },
+    options.host === undefined ? {} : { host: options.host },
+  );
+  tryOnScopeDispose(() => {
+    stop.stop();
+    observer.stop();
+  });
+
+  return { input, triggerResize };
+}
+
+function isAutosizeElement(element: Element): element is AutosizeElement {
+  return "style" in element && typeof element.scrollHeight === "number";
+}

package/registry/files/timeout-scheduler.ts

@@ -0,0 +1,16 @@
+/**
+ * Single-shot timer host used by the debounced and throttled state
+ * utilities.
+ *
+ * Implement this interface to integrate a deterministic test clock, a native
+ * runtime timer, or an application-owned scheduler. Handles are opaque: the
+ * utilities only hand them back to {@link TimeoutScheduler.clearTimeout}.
+ * This module declares types only and contributes no runtime code.
+ */
+export interface TimeoutScheduler {
+  /** Starts a single-shot callback and returns its opaque cancellation handle. */
+  readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
+
+  /** Cancels a handle previously returned by {@link TimeoutScheduler.setTimeout}. */
+  readonly clearTimeout: (handle: unknown) => void;
+}

package/registry/files/to-reactive.ts

@@ -0,0 +1,44 @@
+import { isRef, reactive, unref } from "vue";
+import type { MaybeRef, Reactive } from "vue";
+
+/**
+ * Reactive object view over a ref that holds an object.
+ *
+ * Property reads and writes go to the ref's current object, so replacing the
+ * ref's value swaps the whole object behind a stable reactive proxy (handy
+ * for `v-bind="state"` or destructuring-free templates). Nested refs are
+ * unwrapped on read and written through on assignment. A non-ref object is
+ * simply passed to `reactive`. SSR-safe and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const state = ref({ name: "a" });
+ * const view = toReactive(state);
+ * state.value = { name: "b" };
+ * view.name; // "b"
+ * ```
+ *
+ * @param objectRef Ref (or plain object) holding the object.
+ * @returns A reactive proxy following the ref.
+ */
+export function toReactive<Value extends object>(objectRef: MaybeRef<Value>): Reactive<Value> {
+  if (!isRef(objectRef)) return reactive(objectRef);
+
+  const proxy = new Proxy<Value>(objectRef.value, {
+    get: (_target, property, receiver) => unref(Reflect.get(objectRef.value, property, receiver)),
+    set: (_target, property, value) => {
+      const current: unknown = Reflect.get(objectRef.value, property);
+      if (isRef(current) && !isRef(value)) current.value = value;
+      else Reflect.set(objectRef.value, property, value);
+      return true;
+    },
+    deleteProperty: (_target, property) => Reflect.deleteProperty(objectRef.value, property),
+    has: (_target, property) => Reflect.has(objectRef.value, property),
+    ownKeys: () => Reflect.ownKeys(objectRef.value),
+    getOwnPropertyDescriptor: (_target, property) => {
+      const descriptor = Reflect.getOwnPropertyDescriptor(objectRef.value, property);
+      return descriptor === undefined ? undefined : { ...descriptor, configurable: true };
+    },
+  });
+  return reactive(proxy);
+}

package/registry/files/transition.ts

@@ -0,0 +1,271 @@
+import { shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Cubic Bézier control points `[x1, y1, x2, y2]`. */
+export type CubicBezierPoints = readonly [number, number, number, number];
+
+/** Easing: a preset name, cubic Bézier control points, or a function on `[0, 1]`. */
+export type TransitionEasing =
+  | TransitionPresetName
+  | CubicBezierPoints
+  | ((progress: number) => number);
+
+/** Named cubic Bézier easing presets (the classic easings.net set). */
+export const TransitionPresets = {
+  linear: [0, 0, 1, 1],
+  easeInSine: [0.12, 0, 0.39, 0],
+  easeOutSine: [0.61, 1, 0.88, 1],
+  easeInOutSine: [0.37, 0, 0.63, 1],
+  easeInQuad: [0.11, 0, 0.5, 0],
+  easeOutQuad: [0.5, 1, 0.89, 1],
+  easeInOutQuad: [0.45, 0, 0.55, 1],
+  easeInCubic: [0.32, 0, 0.67, 0],
+  easeOutCubic: [0.33, 1, 0.68, 1],
+  easeInOutCubic: [0.65, 0, 0.35, 1],
+  easeInQuart: [0.5, 0, 0.75, 0],
+  easeOutQuart: [0.25, 1, 0.5, 1],
+  easeInOutQuart: [0.76, 0, 0.24, 1],
+  easeInQuint: [0.64, 0, 0.78, 0],
+  easeOutQuint: [0.22, 1, 0.36, 1],
+  easeInOutQuint: [0.83, 0, 0.17, 1],
+  easeInExpo: [0.7, 0, 0.84, 0],
+  easeOutExpo: [0.16, 1, 0.3, 1],
+  easeInOutExpo: [0.87, 0, 0.13, 1],
+  easeInCirc: [0.55, 0, 1, 0.45],
+  easeOutCirc: [0, 0.55, 0.45, 1],
+  easeInOutCirc: [0.85, 0, 0.15, 1],
+  easeInBack: [0.36, 0, 0.66, -0.56],
+  easeOutBack: [0.34, 1.56, 0.64, 1],
+  easeInOutBack: [0.68, -0.6, 0.32, 1.6],
+} as const satisfies Readonly<Record<string, CubicBezierPoints>>;
+
+/** Names of {@link TransitionPresets}. */
+export type TransitionPresetName = keyof typeof TransitionPresets;
+
+/** Numeric value tweened by {@link useTransition}: a number or a fixed-length tuple. */
+export type TransitionValue = number | readonly number[];
+
+/** Mutable tuple output matching a tuple source. */
+export type TransitionTupleOutput<Source extends readonly number[]> = {
+  -readonly [Index in keyof Source]: number;
+};
+
+/** Frame scheduler used by {@link useTransition}. */
+export interface TransitionFrameHost {
+  /** Schedule a callback before the next repaint. */
+  readonly requestAnimationFrame: (callback: FrameRequestCallback) => number;
+  /** Cancel a scheduled frame. */
+  readonly cancelAnimationFrame: (handle: number) => void;
+}
+
+/** Options for {@link useTransition}. */
+export interface UseTransitionOptions {
+  /**
+   * Duration in milliseconds.
+   *
+   * @default 1000
+   */
+  readonly duration?: MaybeRefOrGetter<number>;
+
+  /**
+   * Delay before each transition starts, in milliseconds.
+   *
+   * @default 0
+   */
+  readonly delay?: MaybeRefOrGetter<number>;
+
+  /**
+   * Easing function, preset name, or cubic Bézier points.
+   *
+   * @default "linear"
+   */
+  readonly easing?: MaybeRefOrGetter<TransitionEasing>;
+
+  /**
+   * Jump to the source value without animating.
+   *
+   * @default false
+   */
+  readonly disabled?: MaybeRefOrGetter<boolean>;
+
+  /**
+   * Called when a transition starts.
+   *
+   * @default undefined
+   */
+  readonly onStarted?: () => void;
+
+  /**
+   * Called when a transition reaches its target.
+   *
+   * @default undefined
+   */
+  readonly onFinished?: () => void;
+
+  /**
+   * Frame scheduler. Without one (server rendering) the output mirrors the
+   * source immediately.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<TransitionFrameHost | null | undefined>;
+}
+
+/**
+ * Tween a number toward its reactive source.
+ *
+ * Each source change starts a new transition from the current output, so
+ * interrupted transitions stay continuous. Easing presets and Bézier points
+ * are solved with Newton–Raphson plus bisection. Without a frame scheduler
+ * (server rendering, tests) the output equals the source, which keeps SSR
+ * deterministic. Pending frames are cancelled with the owning scope.
+ *
+ * @param source Reactive number.
+ * @param options Duration, delay, easing, callbacks, and frame capability.
+ * @returns Readonly tweened number.
+ */
+export function useTransition(
+  source: MaybeRefOrGetter<number>,
+  options?: UseTransitionOptions,
+): Readonly<Ref<number>>;
+/**
+ * Tween each element of a fixed-length numeric tuple.
+ *
+ * @param source Reactive tuple; its length must stay constant.
+ * @param options Duration, delay, easing, callbacks, and frame capability.
+ * @returns Readonly tweened tuple with the same length.
+ */
+export function useTransition<const Source extends readonly number[]>(
+  source: MaybeRefOrGetter<Source>,
+  options?: UseTransitionOptions,
+): Readonly<Ref<TransitionTupleOutput<Source>>>;
+export function useTransition(
+  source: MaybeRefOrGetter<TransitionValue>,
+  options: UseTransitionOptions = {},
+): Readonly<Ref<number | number[]>> {
+  const initial = toValue(source);
+  const output = shallowRef<number | number[]>(copy(initial));
+  let cancel = (): void => undefined;
+
+  const stop = watch(
+    () => copy(toValue(source)),
+    (target) => {
+      cancel();
+      const host = options.host === undefined ? browserFrameHost() : toValue(options.host);
+      const duration = Math.max(0, toValue(options.duration) ?? 1000);
+      if (!host || toValue(options.disabled) || duration === 0) {
+        output.value = target;
+        return;
+      }
+      const from = output.value;
+      const ease = toEasingFunction(toValue(options.easing) ?? "linear");
+      const delay = Math.max(0, toValue(options.delay) ?? 0);
+      let startedAt: number | undefined;
+      let started = false;
+      let handle = 0;
+      const frame = (time: number): void => {
+        startedAt ??= time + delay;
+        const elapsed = time - startedAt;
+        if (elapsed < 0) {
+          handle = host.requestAnimationFrame(frame);
+          return;
+        }
+        if (!started) {
+          started = true;
+          options.onStarted?.();
+        }
+        const progress = Math.min(1, elapsed / duration);
+        output.value = interpolate(from, target, ease(progress));
+        if (progress < 1) {
+          handle = host.requestAnimationFrame(frame);
+          return;
+        }
+        cancel = () => undefined;
+        options.onFinished?.();
+      };
+      handle = host.requestAnimationFrame(frame);
+      cancel = () => {
+        host.cancelAnimationFrame(handle);
+        cancel = () => undefined;
+      };
+    },
+  );
+  tryOnScopeDispose(() => {
+    stop.stop();
+    cancel();
+  });
+
+  return output;
+}
+
+/**
+ * Build an easing function from cubic Bézier control points.
+ *
+ * @param points `[x1, y1, x2, y2]` with `x1`/`x2` in `[0, 1]`.
+ * @returns Easing function mapping progress to eased progress.
+ */
+export function cubicBezier(points: CubicBezierPoints): (progress: number) => number {
+  const [x1, y1, x2, y2] = points;
+  const a = (p1: number, p2: number): number => 1 - 3 * p2 + 3 * p1;
+  const b = (p1: number, p2: number): number => 3 * p2 - 6 * p1;
+  const c = (p1: number): number => 3 * p1;
+  const at = (t: number, p1: number, p2: number): number =>
+    ((a(p1, p2) * t + b(p1, p2)) * t + c(p1)) * t;
+  const slope = (t: number, p1: number, p2: number): number =>
+    3 * a(p1, p2) * t * t + 2 * b(p1, p2) * t + c(p1);
+  const solve = (x: number): number => {
+    let t = x;
+    for (let iteration = 0; iteration < 8; iteration += 1) {
+      const error = at(t, x1, x2) - x;
+      if (Math.abs(error) < 1e-7) return t;
+      const derivative = slope(t, x1, x2);
+      if (Math.abs(derivative) < 1e-6) break;
+      t -= error / derivative;
+    }
+    let low = 0;
+    let high = 1;
+    t = x;
+    while (high - low > 1e-7) {
+      if (at(t, x1, x2) < x) low = t;
+      else high = t;
+      t = (low + high) / 2;
+    }
+    return t;
+  };
+  return (progress) => {
+    if (progress <= 0) return 0;
+    if (progress >= 1) return 1;
+    if (x1 === y1 && x2 === y2) return progress;
+    return at(solve(progress), y1, y2);
+  };
+}
+
+function toEasingFunction(easing: TransitionEasing): (progress: number) => number {
+  if (typeof easing === "function") return easing;
+  return cubicBezier(typeof easing === "string" ? TransitionPresets[easing] : easing);
+}
+
+function copy(value: TransitionValue): number | number[] {
+  return typeof value === "number" ? value : [...value];
+}
+
+function interpolate(
+  from: number | number[],
+  to: number | number[],
+  progress: number,
+): number | number[] {
+  if (typeof to === "number") {
+    const start = typeof from === "number" ? from : to;
+    return start + (to - start) * progress;
+  }
+  return to.map((target, index) => {
+    const start = typeof from === "number" ? target : (from[index] ?? target);
+    return start + (target - start) * progress;
+  });
+}
+
+function browserFrameHost(): TransitionFrameHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}