@lab206/animate 0.1.0

package/src/animate.ts

@@ -0,0 +1,256 @@
+import type { Signal } from "@lab206/core";
+import { driver } from "./driver.js";
+import { resolveEase } from "./easings.js";
+import { createPlayback } from "./playback.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+import { clearActive, getActive, setActive } from "./registry.js";
+import type {
+  AnimateOptions,
+  AnimationPlayback,
+  SpringOptions,
+  TweenOptions,
+} from "./types.js";
+
+const DEFAULT_DURATION = 300;
+const DEFAULT_STIFFNESS = 170;
+const DEFAULT_DAMPING = 26;
+const DEFAULT_MASS = 1;
+const DEFAULT_REST_DELTA = 0.1;
+const DEFAULT_REST_SPEED = 0.01;
+
+/**
+ * Create spring options for `animate()`.
+ *
+ * @example
+ * ```ts
+ * animate(x, 100, spring({ stiffness: 200, damping: 20 }));
+ * ```
+ */
+export function spring(
+  options: Omit<SpringOptions, "type"> = {},
+): SpringOptions {
+  return { type: "spring", ...options };
+}
+
+/**
+ * Animate a number `signal` to a target value.
+ *
+ * - **Tween (default):** duration + easing
+ * - **Spring:** pass `spring({ ... })` or `{ type: "spring", ... }`
+ * - **Interruptible:** calling `animate` again on the same signal cancels the prior run
+ * - **A11y:** honors `prefers-reduced-motion` (jumps to end) unless opted out
+ *
+ * @example
+ * ```ts
+ * const x = signal(0);
+ * const anim = animate(x, 100, { duration: 300, ease: "easeOut" });
+ * await anim.finished;
+ * ```
+ */
+export function animate(
+  target: Signal<number>,
+  to: number,
+  options: AnimateOptions = {},
+): AnimationPlayback {
+  // Interrupt any prior animation on this signal.
+  getActive(target)?.cancel();
+
+  const isSpring = options.type === "spring";
+  const respect =
+    options.respectReducedMotion !== false && prefersReducedMotion();
+  const from =
+    options.from !== undefined ? options.from : target.peek();
+
+  let frameId: number | null = null;
+
+  const stopFrames = () => {
+    if (frameId !== null) {
+      driver.caf(frameId);
+      frameId = null;
+    }
+  };
+
+  const apply = (value: number) => {
+    target.set(value);
+    options.onUpdate?.(value);
+  };
+
+  let finishedCleanup = false;
+  const finishClean = () => {
+    if (finishedCleanup) return;
+    finishedCleanup = true;
+    stopFrames();
+    clearActive(target, playback);
+  };
+
+  const playback = createPlayback({
+    onCancel: () => {
+      finishClean();
+      options.onCancel?.();
+    },
+    onComplete: () => {
+      apply(to);
+      finishClean();
+      options.onComplete?.();
+    },
+  });
+
+  setActive(target, playback);
+
+  // Already there, or reduced motion → snap finish.
+  if (respect || Object.is(from, to)) {
+    apply(to);
+    finishClean();
+    options.onComplete?.();
+    playback._resolveFinished();
+    return playback;
+  }
+
+  const delay = options.delay ?? 0;
+  const startAt = driver.now() + delay;
+
+  const schedule = (cb: () => void) => {
+    frameId = driver.raf(() => {
+      frameId = null;
+      if (playback.playState !== "running") return;
+      cb();
+    });
+  };
+
+  const begin = () => {
+    if (playback.playState !== "running") return;
+    if (isSpring) {
+      startSpring(
+        from,
+        to,
+        options as SpringOptions,
+        playback,
+        apply,
+        schedule,
+        () => {
+          finishClean();
+          options.onComplete?.();
+          playback._resolveFinished();
+        },
+      );
+    } else {
+      startTween(
+        from,
+        to,
+        options as TweenOptions,
+        playback,
+        apply,
+        schedule,
+        () => {
+          finishClean();
+          options.onComplete?.();
+          playback._resolveFinished();
+        },
+      );
+    }
+  };
+
+  if (delay > 0) {
+    const wait = () => {
+      if (playback.playState !== "running") return;
+      if (driver.now() < startAt) {
+        schedule(wait);
+        return;
+      }
+      begin();
+    };
+    schedule(wait);
+  } else {
+    begin();
+  }
+
+  return playback;
+}
+
+function startTween(
+  from: number,
+  to: number,
+  options: TweenOptions,
+  playback: AnimationPlayback,
+  apply: (v: number) => void,
+  schedule: (cb: () => void) => void,
+  onDone: () => void,
+): void {
+  const duration = Math.max(0, options.duration ?? DEFAULT_DURATION);
+  const ease = resolveEase(options.ease ?? "easeOut");
+  const start = driver.now();
+
+  if (duration === 0) {
+    apply(to);
+    onDone();
+    return;
+  }
+
+  const tick = () => {
+    if (playback.playState !== "running") return;
+
+    const elapsed = driver.now() - start;
+    const t = Math.min(1, elapsed / duration);
+    apply(from + (to - from) * ease(t));
+
+    if (t >= 1) {
+      apply(to);
+      onDone();
+      return;
+    }
+    schedule(tick);
+  };
+
+  schedule(tick);
+}
+
+function startSpring(
+  from: number,
+  to: number,
+  options: SpringOptions,
+  playback: AnimationPlayback,
+  apply: (v: number) => void,
+  schedule: (cb: () => void) => void,
+  onDone: () => void,
+): void {
+  const stiffness = options.stiffness ?? DEFAULT_STIFFNESS;
+  const damping = options.damping ?? DEFAULT_DAMPING;
+  const mass = options.mass ?? DEFAULT_MASS;
+  const restDelta = options.restDelta ?? DEFAULT_REST_DELTA;
+  const restSpeed = options.restSpeed ?? DEFAULT_REST_SPEED;
+
+  let current = from;
+  let velocity = options.velocity ?? 0;
+  let last = driver.now();
+
+  apply(current);
+
+  const tick = () => {
+    if (playback.playState !== "running") return;
+
+    const now = driver.now();
+    const dt = Math.min(0.064, Math.max(0.001, (now - last) / 1000));
+    last = now;
+
+    const springForce = -stiffness * (current - to);
+    const damperForce = -damping * velocity;
+    const acceleration = (springForce + damperForce) / mass;
+    velocity += acceleration * dt;
+    current += velocity * dt;
+
+    apply(current);
+
+    if (
+      Math.abs(velocity) <= restSpeed &&
+      Math.abs(current - to) <= restDelta
+    ) {
+      apply(to);
+      onDone();
+      return;
+    }
+
+    schedule(tick);
+  };
+
+  schedule(tick);
+}

package/src/driver.ts

@@ -0,0 +1,100 @@
+import type { FrameDriver } from "./types.js";
+
+function defaultNow(): number {
+  return typeof performance !== "undefined" && performance.now
+    ? performance.now()
+    : Date.now();
+}
+
+function defaultRaf(cb: (time: number) => void): number {
+  if (typeof requestAnimationFrame === "function") {
+    return requestAnimationFrame(cb);
+  }
+  // Node / SSR fallback ~60fps
+  return setTimeout(() => cb(defaultNow()), 1000 / 60) as unknown as number;
+}
+
+function defaultCaf(id: number): void {
+  if (typeof cancelAnimationFrame === "function") {
+    cancelAnimationFrame(id);
+    return;
+  }
+  clearTimeout(id);
+}
+
+/** Active frame driver — replace in tests via `installDriver`. */
+export let driver: FrameDriver = {
+  now: defaultNow,
+  raf: defaultRaf,
+  caf: defaultCaf,
+};
+
+/** Swap the frame driver (used by tests and advanced hosts). */
+export function installDriver(next: FrameDriver): () => void {
+  const prev = driver;
+  driver = next;
+  return () => {
+    driver = prev;
+  };
+}
+
+/**
+ * Deterministic test clock: manual `advance(ms)` pumps animations.
+ *
+ * @example
+ * ```ts
+ * const clock = createTestClock();
+ * const restore = installDriver(clock.driver);
+ * animate(x, 100, { duration: 100 });
+ * clock.advance(50);
+ * clock.advance(50);
+ * restore();
+ * ```
+ */
+export function createTestClock(): {
+  driver: FrameDriver;
+  advance: (ms: number) => void;
+  readonly time: number;
+} {
+  let time = 0;
+  let nextId = 1;
+  type Entry = { id: number; time: number; cb: (t: number) => void };
+  let queue: Entry[] = [];
+
+  const clockDriver: FrameDriver = {
+    now: () => time,
+    raf(cb) {
+      const id = nextId++;
+      // Schedule for "next frame" — advanced when time moves.
+      queue.push({ id, time: time, cb });
+      return id;
+    },
+    caf(id) {
+      queue = queue.filter((e) => e.id !== id);
+    },
+  };
+
+  const advance = (ms: number): void => {
+    if (ms < 0) return;
+    const target = time + ms;
+    // Process frames in small steps so springs/tweens see intermediate times.
+    const step = 16.6667;
+    while (time < target) {
+      const nextTime = Math.min(time + step, target);
+      time = nextTime;
+      const batch = queue;
+      queue = [];
+      for (const entry of batch) {
+        entry.cb(time);
+      }
+    }
+  };
+
+  return {
+    driver: clockDriver,
+    advance,
+    get time() {
+      return time;
+    },
+  };
+}

package/src/easings.ts

@@ -0,0 +1,41 @@
+import type { Ease, EaseName, EasingFn } from "./types.js";
+
+/** Cubic-bezier approximation helpers via simple polynomials (good enough, tiny). */
+
+const easings: Record<EaseName, EasingFn> = {
+  linear: (t) => t,
+  easeIn: (t) => t * t,
+  easeOut: (t) => 1 - (1 - t) * (1 - t),
+  easeInOut: (t) =>
+    t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t) =>
+    t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+  easeInBack: (t) => {
+    const c1 = 1.70158;
+    const c3 = c1 + 1;
+    return c3 * t * t * t - c1 * t * t;
+  },
+  easeOutBack: (t) => {
+    const c1 = 1.70158;
+    const c3 = c1 + 1;
+    return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+  },
+  easeInOutBack: (t) => {
+    const c1 = 1.70158;
+    const c2 = c1 * 1.525;
+    return t < 0.5
+      ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+      : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
+  },
+};
+
+/** Resolve a named or custom ease to a function. */
+export function resolveEase(ease: Ease = "easeOut"): EasingFn {
+  if (typeof ease === "function") return ease;
+  return easings[ease] ?? easings.easeOut;
+}
+
+/** List of built-in ease names (docs / tooling). */
+export const easeNames = Object.keys(easings) as EaseName[];

package/src/gsap-bridge.ts

@@ -0,0 +1,183 @@
+/**
+ * GSAP ↔ Powers signal bridge (no hard dependency on `gsap`).
+ * Use `createGsapBridge(gsap)` or the default export from `@lab206/animate/gsap`.
+ */
+import type { Signal } from "@lab206/core";
+import { createPlayback } from "./playback.js";
+import { clearActive, getActive, setActive } from "./registry.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+import type { AnimationPlayback } from "./types.js";
+
+/** Minimal tween handle — real GSAP Tween.kill has a wider signature. */
+export type GsapTweenLike = {
+  kill: (...args: unknown[]) => unknown;
+};
+
+/** Minimal GSAP surface we need — keeps peer types loose. */
+export type GsapLike = {
+  to(target: object, vars: Record<string, unknown>): GsapTweenLike;
+  fromTo?(
+    target: object,
+    fromVars: Record<string, unknown>,
+    toVars: Record<string, unknown>,
+  ): GsapTweenLike;
+};
+
+export type GsapAnimateOptions = {
+  /**
+   * Duration in **milliseconds** (same unit as `animate()`).
+   * Converted to seconds for GSAP. Default: 300.
+   */
+  duration?: number;
+  /** Delay in milliseconds. Default: 0. */
+  delay?: number;
+  /** GSAP ease string, e.g. `"power2.out"`, `"elastic.out(1, 0.4)"`. */
+  ease?: string;
+  /** Override start value (defaults to `target.peek()`). */
+  from?: number;
+  /**
+   * Honor `prefers-reduced-motion` (jump to end). Default: true.
+   */
+  respectReducedMotion?: boolean;
+  /**
+   * Extra GSAP tween vars (overwrite, yoyo, repeat, stagger on multi-targets, …).
+   * Do not set `onUpdate` / `onComplete` here — use the callbacks below.
+   */
+  vars?: Record<string, unknown>;
+  onUpdate?: (value: number) => void;
+  onComplete?: () => void;
+  onCancel?: () => void;
+};
+
+export type GsapBridge = {
+  /**
+   * Animate a number signal with GSAP.
+   * Same interrupt model as `animate()`: a new call cancels the previous on that signal.
+   */
+  gsapAnimate: (
+    target: Signal<number>,
+    to: number,
+    options?: GsapAnimateOptions,
+  ) => AnimationPlayback;
+  /**
+   * Explicit from → to with GSAP (`fromTo`).
+   */
+  gsapFromTo: (
+    target: Signal<number>,
+    from: number,
+    to: number,
+    options?: GsapAnimateOptions,
+  ) => AnimationPlayback;
+};
+
+/**
+ * Bind a GSAP instance (or mock) to Powers signals.
+ *
+ * @example
+ * ```ts
+ * import gsap from "gsap";
+ * import { createGsapBridge } from "@lab206/animate/gsap";
+ *
+ * const { gsapAnimate } = createGsapBridge(gsap);
+ * gsapAnimate(x, 100, { duration: 400, ease: "power3.out" });
+ * ```
+ */
+export function createGsapBridge(gsap: GsapLike): GsapBridge {
+  function run(
+    target: Signal<number>,
+    from: number,
+    to: number,
+    options: GsapAnimateOptions,
+  ): AnimationPlayback {
+    getActive(target)?.cancel();
+
+    const respect =
+      options.respectReducedMotion !== false && prefersReducedMotion();
+
+    let tween: GsapTweenLike | null = null;
+    let finishedCleanup = false;
+
+    const finishClean = () => {
+      if (finishedCleanup) return;
+      finishedCleanup = true;
+      clearActive(target, playback);
+    };
+
+    const apply = (value: number) => {
+      target.set(value);
+      options.onUpdate?.(value);
+    };
+
+    const playback = createPlayback({
+      onCancel: () => {
+        tween?.kill();
+        tween = null;
+        finishClean();
+        options.onCancel?.();
+      },
+      onComplete: () => {
+        apply(to);
+        tween = null;
+        finishClean();
+        options.onComplete?.();
+      },
+    });
+
+    setActive(target, playback);
+
+    if (respect || from === to) {
+      apply(to);
+      playback.complete();
+      return playback;
+    }
+
+    const proxy = { v: from };
+    apply(from);
+
+    const durationSec = Math.max(0, (options.duration ?? 300) / 1000);
+    const delaySec = Math.max(0, (options.delay ?? 0) / 1000);
+    // Strip reserved keys so callers cannot clobber signal wiring
+    const extra = { ...(options.vars ?? {}) };
+    delete extra.v;
+    delete extra.onUpdate;
+    delete extra.onComplete;
+    delete extra.onInterrupt;
+    delete extra.duration;
+    delete extra.delay;
+    delete extra.ease;
+
+    const toVars: Record<string, unknown> = {
+      ...extra,
+      v: to,
+      duration: durationSec,
+      delay: delaySec,
+      ease: options.ease ?? "power2.out",
+      onUpdate: () => {
+        apply(proxy.v);
+      },
+      onComplete: () => {
+        if (playback.playState !== "running") return;
+        playback.complete();
+      },
+    };
+
+    if (typeof gsap.fromTo === "function") {
+      tween = gsap.fromTo(proxy, { v: from }, toVars);
+    } else {
+      tween = gsap.to(proxy, toVars);
+    }
+
+    return playback;
+  }
+
+  return {
+    gsapAnimate(target, to, options = {}) {
+      const from =
+        options.from !== undefined ? options.from : target.peek();
+      return run(target, from, to, options);
+    },
+    gsapFromTo(target, from, to, options = {}) {
+      return run(target, from, to, { ...options, from });
+    },
+  };
+}

package/src/gsap.ts

@@ -0,0 +1,30 @@
+/**
+ * Optional GSAP adapter for Powers.
+ *
+ * Install peer: `pnpm add gsap`
+ * Import: `import { gsapAnimate } from "@lab206/animate/gsap"`
+ *
+ * Default motion remains `@lab206/animate` (no GSAP required).
+ * Use this for timelines, custom eases, ScrollTrigger (via `vars`), etc.
+ */
+import gsap from "gsap";
+import { createGsapBridge, type GsapLike } from "./gsap-bridge.js";
+
+export {
+  createGsapBridge,
+  type GsapLike,
+  type GsapAnimateOptions,
+  type GsapBridge,
+} from "./gsap-bridge.js";
+
+// Cast: we only use to/fromTo + tween.kill
+const bridge = createGsapBridge(gsap as unknown as GsapLike);
+
+/** Animate a number signal with GSAP (duration in ms, same as `animate()`). */
+export const gsapAnimate = bridge.gsapAnimate;
+
+/** GSAP `fromTo` for a number signal. */
+export const gsapFromTo = bridge.gsapFromTo;
+
+/** Re-export native cancel so one import path covers both engines. */
+export { cancel } from "./registry.js";

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @lab206/animate
+ *
+ * Signal-native motion. Learn it in one line:
+ *   animate(mySignal, 100, { duration: 300 })
+ *
+ * Optional spring feel:
+ *   animate(mySignal, 100, spring())
+ *
+ * Optional GSAP (peer dependency):
+ *   import { gsapAnimate } from "@lab206/animate/gsap"
+ *   — or createGsapBridge(gsap) from this package without importing gsap here
+ */
+
+export { animate, spring } from "./animate.js";
+export { cancel } from "./registry.js";
+export {
+  prefersReducedMotion,
+  setReducedMotionOverride,
+} from "./reduced-motion.js";
+export {
+  installDriver,
+  createTestClock,
+  driver,
+} from "./driver.js";
+export { resolveEase, easeNames } from "./easings.js";
+export { createGsapBridge } from "./gsap-bridge.js";
+export type {
+  GsapLike,
+  GsapAnimateOptions,
+  GsapBridge,
+} from "./gsap-bridge.js";
+
+export type {
+  AnimateOptions,
+  AnimationPlayback,
+  Animatable,
+  Ease,
+  EaseName,
+  EasingFn,
+  FrameDriver,
+  PlayState,
+  SpringOptions,
+  TweenOptions,
+} from "./types.js";