@praxisjs/motion 0.2.3 → 1.1.0

package/src/__tests__/spring.test.ts

@@ -1,60 +1,116 @@
 // @vitest-environment jsdom
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
 import { spring } from "../spring";
 
-describe("spring", () => {
-  it("initializes value to the starting number", () => {
-    vi.useFakeTimers();
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
+
+describe("spring()", () => {
+  it("starts at the initial value", () => {
     const s = spring(42);
     expect(s.value()).toBe(42);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    s.stop();
   });
 
-  it("target signal starts at the initial value", () => {
-    vi.useFakeTimers();
+  it("target starts equal to initial value", () => {
     const s = spring(10);
     expect(s.target()).toBe(10);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    s.stop();
   });
 
-  it("stop() cancels without throwing", () => {
-    vi.useFakeTimers();
+  it("stop() cancels pending animation", () => {
     const s = spring(0);
-    expect(() => { s.stop(); }).not.toThrow();
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    s.target.set(100);
+    s.stop();
+    const valueAfterStop = s.value();
+    expect(typeof valueAfterStop).toBe("number");
   });
 
-  it("stop() can be called multiple times safely", () => {
-    vi.useFakeTimers();
-    const s = spring(5);
+  it("setting target triggers animation", () => {
+    const s = spring(0);
+    s.target.set(100);
+    expect(s.target()).toBe(100);
     s.stop();
-    expect(() => { s.stop(); }).not.toThrow();
-    vi.clearAllTimers();
-    vi.useRealTimers();
   });
 
-  it("updating target signal triggers animation", () => {
-    vi.useFakeTimers();
+  it("accepts custom stiffness and damping", () => {
+    const s = spring(0, { stiffness: 0.5, damping: 0.9 });
+    s.target.set(50);
+    expect(s.target()).toBe(50);
+    s.stop();
+  });
+
+  it("accepts custom mass and precision", () => {
+    const s = spring(0, { mass: 2, precision: 0.01 });
+    s.target.set(100);
+    expect(typeof s.value()).toBe("number");
+    s.stop();
+  });
+
+  it("value is a computed (function)", () => {
     const s = spring(0);
+    expect(typeof s.value).toBe("function");
+    s.stop();
+  });
+
+  it("target is a signal with a set method", () => {
+    const s = spring(0);
+    expect(typeof s.target.set).toBe("function");
+    s.stop();
+  });
+
+  it("settting target multiple times accumulates velocity direction", () => {
+    const s = spring(0, { stiffness: 0.5, damping: 0.5 });
+    s.target.set(10);
+    s.target.set(20);
+    expect(s.target()).toBe(20);
+    s.stop();
+  });
+
+  it("tick advances value toward target", () => {
+    const s = spring(0, { stiffness: 0.5, damping: 0.8, precision: 0.01 });
     s.target.set(100);
-    // Run a few frames
-    vi.advanceTimersByTime(100);
-    // Value should have moved towards 100
+    vi.advanceTimersByTime(50);
     expect(s.value()).toBeGreaterThan(0);
     s.stop();
-    vi.clearAllTimers();
-    vi.useRealTimers();
   });
 
-  it("accepts custom spring options", () => {
-    vi.useFakeTimers();
-    const s = spring(0, { stiffness: 0.5, damping: 0.9, mass: 2, precision: 0.01 });
-    expect(s.value()).toBe(0);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+  it("moves value closer to target over time", () => {
+    const s = spring(0, { stiffness: 0.5, damping: 0.95, precision: 0.01 });
+    s.target.set(100);
+    vi.advanceTimersByTime(500);
+    // Value should have moved significantly toward target
+    expect(s.value()).toBeGreaterThan(10);
+  });
+
+  it("stiffness = 0 throws a descriptive error", () => {
+    expect(() => spring(0, { stiffness: 0 })).toThrow("stiffness must be greater than 0");
+  });
+
+  it("initial value already equals target — animation stops immediately (no rAF loop)", () => {
+    const s = spring(50, { stiffness: 0.5, damping: 0.8, precision: 0.001 });
+    // target is also 50 (the default), so the spring should converge instantly
+    const initial = s.value();
+    vi.advanceTimersByTime(200);
+    // Value should remain at (or very close to) 50 — no drift
+    expect(s.value()).toBeCloseTo(initial, 3);
+    s.stop();
+  });
+
+  it("stop() called while animating — value is frozen and does not continue to change", () => {
+    const s = spring(0, { stiffness: 0.5, damping: 0.8 });
+    s.target.set(100);
+    vi.advanceTimersByTime(50);
+    s.stop();
+    const valueAfterStop = s.value();
+    vi.advanceTimersByTime(500);
+    expect(s.value()).toBe(valueAfterStop);
   });
 });

package/src/__tests__/transition.test.ts

@@ -1,75 +1,152 @@
 // @vitest-environment jsdom
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
 import { createTransition } from "../transition";
 
-describe("createTransition", () => {
-  it("enter() adds and removes CSS classes", async () => {
-    vi.useFakeTimers();
-    const t = createTransition({ name: "fade", duration: 100 });
-    const el = document.createElement("div");
+beforeEach(() => {
+  vi.useFakeTimers();
+});
 
-    const p = t.enter(el);
+afterEach(() => {
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
 
-    // enter-from should have been added immediately
+function makeEl() {
+  return document.createElement("div");
+}
+
+describe("createTransition()", () => {
+  it("enter() adds enter-from class immediately", () => {
+    const t = createTransition({ name: "fade" });
+    const el = makeEl();
+    void t.enter(el);
     expect(el.classList.contains("fade-enter-from")).toBe(true);
+  });
 
-    // requestAnimationFrame fires
-    await vi.runAllTimersAsync();
+  it("enter() removes enter-from and adds enter-to after rAF", () => {
+    const t = createTransition({ name: "fade", duration: 1000 });
+    const el = makeEl();
+    void t.enter(el);
+    // Advance past rAF (16ms) but not past duration (1000ms)
+    vi.advanceTimersByTime(20);
+    expect(el.classList.contains("fade-enter-from")).toBe(false);
+    expect(el.classList.contains("fade-enter-to")).toBe(true);
+  });
 
+  it("enter() resolves and cleans up after duration", async () => {
+    const t = createTransition({ name: "fade", duration: 300 });
+    const el = makeEl();
+    const p = t.enter(el);
+    vi.advanceTimersByTime(300);
     await p;
-    expect(el.classList.contains("fade-enter-from")).toBe(false);
     expect(el.classList.contains("fade-enter-to")).toBe(false);
-    vi.useRealTimers();
   });
 
-  it("leave() adds and removes CSS classes", async () => {
-    vi.useFakeTimers();
-    const t = createTransition({ name: "slide", duration: 100 });
-    const el = document.createElement("div");
-
-    const p = t.leave(el);
+  it("leave() adds leave-from class immediately", () => {
+    const t = createTransition({ name: "slide" });
+    const el = makeEl();
+    void t.leave(el);
     expect(el.classList.contains("slide-leave-from")).toBe(true);
+  });
 
-    await vi.runAllTimersAsync();
-    await p;
-
+  it("leave() removes leave-from and adds leave-to after rAF", () => {
+    const t = createTransition({ name: "slide", duration: 1000 });
+    const el = makeEl();
+    void t.leave(el);
+    // Advance past rAF (16ms) but not past duration (1000ms)
+    vi.advanceTimersByTime(20);
     expect(el.classList.contains("slide-leave-from")).toBe(false);
+    expect(el.classList.contains("slide-leave-to")).toBe(true);
+  });
+
+  it("leave() resolves and cleans up after duration", async () => {
+    const t = createTransition({ name: "slide", duration: 200 });
+    const el = makeEl();
+    const p = t.leave(el);
+    vi.advanceTimersByTime(200);
+    await p;
     expect(el.classList.contains("slide-leave-to")).toBe(false);
-    vi.useRealTimers();
   });
 
-  it("calls onEnter callback", async () => {
-    vi.useFakeTimers();
+  it("uses default name 'transition' when none provided", () => {
+    const t = createTransition();
+    const el = makeEl();
+    void t.enter(el);
+    expect(el.classList.contains("transition-enter-from")).toBe(true);
+  });
+
+  it("calls onEnter callback with element", () => {
     const onEnter = vi.fn();
-    const t = createTransition({ onEnter, duration: 0 });
-    const el = document.createElement("div");
-    const p = t.enter(el);
+    const t = createTransition({ onEnter });
+    const el = makeEl();
+    void t.enter(el);
     expect(onEnter).toHaveBeenCalledWith(el);
-    await vi.runAllTimersAsync();
-    await p;
-    vi.useRealTimers();
   });
 
-  it("calls onLeave callback", async () => {
-    vi.useFakeTimers();
+  it("calls onLeave callback with element", () => {
     const onLeave = vi.fn();
-    const t = createTransition({ onLeave, duration: 0 });
-    const el = document.createElement("div");
-    const p = t.leave(el);
+    const t = createTransition({ onLeave });
+    const el = makeEl();
+    void t.leave(el);
     expect(onLeave).toHaveBeenCalledWith(el);
-    await vi.runAllTimersAsync();
+  });
+
+  it("uses default duration of 300ms", async () => {
+    const t = createTransition({ name: "x" });
+    const el = makeEl();
+    const p = t.enter(el);
+    vi.advanceTimersByTime(300);
     await p;
-    vi.useRealTimers();
+    expect(el.classList.contains("x-enter-to")).toBe(false);
   });
 
-  it("uses 'transition' as default name", async () => {
-    vi.useFakeTimers();
-    const t = createTransition();
-    const el = document.createElement("div");
-    t.enter(el);
-    expect(el.classList.contains("transition-enter-from")).toBe(true);
-    await vi.runAllTimersAsync();
-    vi.useRealTimers();
+  it("enter() interrupted by leave() before completion — no mixed CSS classes left", async () => {
+    const t = createTransition({ name: "fade", duration: 300 });
+    const el = makeEl();
+
+    // Start enter but don't resolve it yet
+    const enterP = t.enter(el);
+    vi.advanceTimersByTime(20); // past rAF, enter-to is now present
+
+    // Immediately start leave
+    const leaveP = t.leave(el);
+    vi.advanceTimersByTime(300);
+
+    await leaveP;
+    // Advance well past enter duration too
+    vi.advanceTimersByTime(300);
+    await enterP;
+
+    // After both complete, no transition classes should remain
+    expect(el.classList.contains("fade-enter-from")).toBe(false);
+    expect(el.classList.contains("fade-enter-to")).toBe(false);
+    expect(el.classList.contains("fade-leave-from")).toBe(false);
+    expect(el.classList.contains("fade-leave-to")).toBe(false);
+  });
+
+  it("onEnter callback throws — promise rejects with that error", async () => {
+    const t = createTransition({
+      onEnter: () => { throw new Error("enter callback error"); },
+    });
+    const el = makeEl();
+    await expect(t.enter(el)).rejects.toThrow("enter callback error");
+  });
+
+  it("onLeave callback throws — promise rejects with that error", async () => {
+    const t = createTransition({
+      onLeave: () => { throw new Error("leave callback error"); },
+    });
+    const el = makeEl();
+    await expect(t.leave(el)).rejects.toThrow("leave callback error");
+  });
+
+  it("duration = 0 — resolves immediately without hanging", async () => {
+    const t = createTransition({ name: "fast", duration: 0 });
+    const el = makeEl();
+    const p = t.enter(el);
+    vi.advanceTimersByTime(0);
+    await p;
+    expect(el.classList.contains("fast-enter-to")).toBe(false);
   });
 });

package/src/__tests__/tween.test.ts

@@ -1,136 +1,155 @@
 // @vitest-environment jsdom
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
-import { Animate } from "../decorators";
 import { tween } from "../tween";
 
-// ── tween ─────────────────────────────────────────────────────────────────────
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
 
-describe("tween", () => {
-  it("starts with the from value", () => {
-    vi.useFakeTimers();
+function flushRaf(frames = 60) {
+  for (let i = 0; i < frames; i++) {
+    vi.runAllTicks();
+    const cbs = (globalThis as unknown as { __rafCallbacks?: Array<(t: number) => void> }).__rafCallbacks;
+    if (cbs?.length) {
+      const batch = [...cbs];
+      cbs.length = 0;
+      batch.forEach((cb) => cb(performance.now()));
+    }
+  }
+}
+
+describe("tween()", () => {
+  it("starts at the `from` value", () => {
     const t = tween(0, 100);
     expect(t.value()).toBe(0);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    t.stop();
   });
 
-  it("target starts at the to value", () => {
-    vi.useFakeTimers();
+  it("exposes the target signal", () => {
     const t = tween(0, 100);
     expect(t.target()).toBe(100);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    t.stop();
   });
 
-  it("playing is initially true (animation started immediately)", () => {
-    vi.useFakeTimers();
+  it("playing is true when animating", () => {
     const t = tween(0, 100);
     expect(t.playing()).toBe(true);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    t.stop();
   });
 
-  it("stop() sets playing to false", () => {
-    vi.useFakeTimers();
+  it("stop() halts animation and sets playing to false", () => {
     const t = tween(0, 100);
     t.stop();
     expect(t.playing()).toBe(false);
-    vi.clearAllTimers();
-    vi.useRealTimers();
   });
 
-  it("reset() restores to from value and clears progress", () => {
-    vi.useFakeTimers();
-    const t = tween(5, 100);
+  it("reset() returns value to `from` and resets progress", () => {
+    const t = tween(0, 100);
+    t.stop();
     t.reset();
-    expect(t.value()).toBe(5);
+    expect(t.value()).toBe(0);
     expect(t.progress()).toBe(0);
-    vi.clearAllTimers();
-    vi.useRealTimers();
   });
 
-  it("progress moves towards 1 as animation advances", () => {
-    vi.useFakeTimers();
-    const t = tween(0, 100, { duration: 300 });
-    vi.advanceTimersByTime(300);
-    // After full duration, value should be near the target
-    expect(t.progress()).toBeGreaterThanOrEqual(0);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+  it("progress starts at 0", () => {
+    const t = tween(0, 100);
+    expect(t.progress()).toBe(0);
+    t.stop();
+  });
+
+  it("accepts custom easing as function", () => {
+    const t = tween(0, 100, { easing: (x) => x, duration: 300 });
+    expect(t.value()).toBe(0);
+    t.stop();
+  });
+
+  it("accepts custom duration and delay", () => {
+    const t = tween(0, 100, { duration: 500, delay: 100 });
+    expect(t.value()).toBe(0);
+    t.stop();
   });
 
-  it("changing target restarts animation", () => {
-    vi.useFakeTimers();
+  it("setting target to same value re-triggers start", () => {
     const t = tween(0, 50);
+    const before = t.value();
+    t.target.set(50);
+    expect(t.value()).toBe(before);
+    t.stop();
+  });
+
+  it("changing target while playing updates target", () => {
+    const t = tween(0, 100);
     t.target.set(200);
-    expect(t.playing()).toBe(true);
+    expect(t.target()).toBe(200);
+    t.stop();
+  });
+
+  it("animate loop runs and updates value toward target", () => {
+    const t = tween(0, 100, { duration: 100, easing: "linear" });
+    // Advance through multiple rAF frames
+    vi.advanceTimersByTime(50);
+    // Value should be moving toward 100
+    const mid = t.value();
+    expect(mid).toBeGreaterThan(0);
+    vi.advanceTimersByTime(100);
     t.stop();
-    vi.clearAllTimers();
-    vi.useRealTimers();
   });
 
-  it("accepts custom easing and delay options", () => {
-    vi.useFakeTimers();
-    const t = tween(0, 100, { easing: "linear", delay: 100, duration: 200 });
+  it("completes animation and stops playing", () => {
+    const t = tween(0, 100, { duration: 100 });
+    vi.advanceTimersByTime(500);
+    // After several durations, value should be at or near target
+    expect(t.value()).toBeGreaterThan(50);
+  });
+
+  it("delay defers animation start", () => {
+    const t = tween(0, 100, { duration: 100, delay: 50 });
+    vi.advanceTimersByTime(10);
+    // Within delay, value stays at 0
     expect(t.value()).toBe(0);
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    t.stop();
   });
-});
 
-// ── Animate decorator ─────────────────────────────────────────────────────────
-
-describe("Animate decorator", () => {
-  function makeCtx(name: string) {
-    const initializers: Array<(this: unknown) => void> = [];
-    return {
-      ctx: {
-        name,
-        kind: "field" as const,
-        addInitializer(fn: (this: unknown) => void) {
-          initializers.push(fn);
-        },
-      } as ClassFieldDecoratorContext,
-      run(instance: unknown) {
-        initializers.forEach((fn) => { fn.call(instance); });
-      },
-    };
-  }
+  it("duration = 0 — resolves immediately with value at `to`", () => {
+    // duration is clamped to 1ms minimum; after a single rAF the tween should complete
+    const t = tween(0, 100, { duration: 0, easing: "linear" });
+    vi.advanceTimersByTime(50);
+    expect(t.value()).toBe(100);
+    expect(t.playing()).toBe(false);
+  });
+
+  it("from === to — resolves immediately without animating", () => {
+    const t = tween(42, 42, { duration: 300, easing: "linear" });
+    // Even before any rAF fires the start value equals the target
+    expect(t.value()).toBe(42);
+    vi.advanceTimersByTime(300);
+    expect(t.value()).toBe(42);
+    t.stop();
+  });
 
-  it("creates a numeric getter/setter on first assignment", () => {
-    vi.useFakeTimers();
-    const { ctx, run } = makeCtx("x");
-    Animate()(undefined, ctx);
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    instance.x = 10;
-    expect(typeof instance.x).toBe("number");
-    vi.clearAllTimers();
-    vi.useRealTimers();
-  });
-
-  it("returns 0 before any value is set", () => {
-    vi.useFakeTimers();
-    const { ctx, run } = makeCtx("opacity");
-    Animate()(undefined, ctx);
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    expect(instance.opacity).toBe(0);
-    vi.clearAllTimers();
-    vi.useRealTimers();
-  });
-
-  it("updating the property updates the tween target", () => {
-    vi.useFakeTimers();
-    const { ctx, run } = makeCtx("scale");
-    Animate()(undefined, ctx);
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    instance.scale = 1;
-    instance.scale = 2; // second set updates tween target
-    expect(typeof instance.scale).toBe("number");
-    vi.clearAllTimers();
-    vi.useRealTimers();
+  it("progress() is 0 during delay phase before animation starts", () => {
+    const t = tween(0, 100, { duration: 100, delay: 200 });
+    vi.advanceTimersByTime(50); // well within delay
+    expect(t.progress()).toBe(0);
+    t.stop();
+  });
+
+  it("easing function is called with t in [0,1] range only", () => {
+    const tValues: number[] = [];
+    const captureEasing = (t: number) => { tValues.push(t); return t; };
+    const tw = tween(0, 100, { duration: 100, easing: captureEasing });
+    vi.advanceTimersByTime(300);
+    tw.stop();
+    expect(tValues.length).toBeGreaterThan(0);
+    for (const t of tValues) {
+      expect(t).toBeGreaterThanOrEqual(0);
+      expect(t).toBeLessThanOrEqual(1);
+    }
   });
 });

package/src/decorators.ts

@@ -1,21 +1,48 @@
+import { createFieldDecorator, type FieldBinding } from "@praxisjs/decorators";
+
+import { spring, type SpringOptions } from "./spring";
 import { tween, type TweenOptions, type Tween } from "./tween";
 
-export function Animate(options: TweenOptions = {}) {
-  return function (_value: undefined, context: ClassFieldDecoratorContext): void {
-    const tweens = new WeakMap<object, Tween>();
+type SpringInstance = ReturnType<typeof spring>;
+
+export function Tween(options: TweenOptions = {}) {
+  const tweens = new WeakMap<object, Tween>();
 
-    context.addInitializer(function (this: unknown) {
-      Object.defineProperty(this, context.name, {
-        get(this: object): number {
-          return tweens.get(this)?.value() ?? 0;
+  return createFieldDecorator({
+    bind(_instance, _name, _initialValue): FieldBinding {
+      return {
+        descriptor: {
+          get(this: object): number {
+            return tweens.get(this)?.value() ?? 0;
+          },
+          set(this: object, value: number): void {
+            if (!tweens.has(this)) tweens.set(this, tween(value, value, options));
+            tweens.get(this)?.target.set(value);
+          },
         },
-        set(this: object, value: number): void {
-          if (!tweens.has(this)) tweens.set(this, tween(value, value, options));
-          tweens.get(this)?.target.set(value);
+      };
+    },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  }) as unknown as (_value: undefined, context: ClassFieldDecoratorContext<any>) => void;
+}
+
+export function Spring(options: SpringOptions = {}) {
+  const springs = new WeakMap<object, SpringInstance>();
+
+  return createFieldDecorator({
+    bind(_instance, _name, _initialValue): FieldBinding {
+      return {
+        descriptor: {
+          get(this: object): number {
+            return springs.get(this)?.value() ?? 0;
+          },
+          set(this: object, value: number): void {
+            if (!springs.has(this)) springs.set(this, spring(value, options));
+            springs.get(this)?.target.set(value);
+          },
         },
-        enumerable: true,
-        configurable: true,
-      });
-    });
-  };
+      };
+    },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  }) as unknown as (_value: undefined, context: ClassFieldDecoratorContext<any>) => void;
 }