@praxisjs/motion 0.2.3 → 1.0.0

package/src/__tests__/decorators.test.ts

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from "vitest";
+
+import { Tween, Spring } from "../decorators";
+
+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); });
+    },
+  };
+}
+
+// ── @Tween ────────────────────────────────────────────────────────────────────
+
+describe("@Tween", () => {
+  it("returns 0 before any value is set", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("opacity");
+    Tween()(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    expect(instance.opacity).toBe(0);
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("creates a numeric getter/setter on first assignment", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("x");
+    Tween()(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    instance.x = 10;
+    expect(typeof instance.x).toBe("number");
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("updating the property updates the tween target", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("scale");
+    Tween()(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    instance.scale = 1;
+    instance.scale = 2;
+    expect(typeof instance.scale).toBe("number");
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("accepts TweenOptions", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("y");
+    Tween({ duration: 500, easing: "linear", delay: 50 })(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    instance.y = 100;
+    expect(typeof instance.y).toBe("number");
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("each instance gets its own tween", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("val");
+    Tween()(undefined, ctx);
+    const a: Record<string, unknown> = {};
+    const b: Record<string, unknown> = {};
+    run(a);
+    run(b);
+    a.val = 10;
+    b.val = 50;
+    expect(a.val).not.toBe(b.val);
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+});
+
+// ── @Spring ───────────────────────────────────────────────────────────────────
+
+describe("@Spring", () => {
+  it("returns 0 before any value is set", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("x");
+    Spring()(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    expect(instance.x).toBe(0);
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("creates a numeric getter/setter on first assignment", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("y");
+    Spring()(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    instance.y = 42;
+    expect(typeof instance.y).toBe("number");
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("updating the property sets the spring target", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("scale");
+    Spring()(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    instance.scale = 1;
+    instance.scale = 2;
+    expect(typeof instance.scale).toBe("number");
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("accepts SpringOptions", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("opacity");
+    Spring({ stiffness: 0.3, damping: 0.9, mass: 2 })(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    instance.opacity = 1;
+    expect(typeof instance.opacity).toBe("number");
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it("each instance gets its own spring", () => {
+    vi.useFakeTimers();
+    const { ctx, run } = makeCtx("val");
+    Spring()(undefined, ctx);
+    const a: Record<string, unknown> = {};
+    const b: Record<string, unknown> = {};
+    run(a);
+    run(b);
+    a.val = 10;
+    b.val = 50;
+    expect(a.val).not.toBe(b.val);
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+});

package/src/__tests__/easings.test.ts

@@ -2,82 +2,89 @@ import { describe, it, expect } from "vitest";
 
 import { easings, resolveEasing } from "../easings";
 
-const EPSILON = 1e-6;
+describe("easings.linear", () => {
+  it("returns 0 at t=0", () => expect(easings.linear(0)).toBe(0));
+  it("returns 0.5 at t=0.5", () => expect(easings.linear(0.5)).toBe(0.5));
+  it("returns 1 at t=1", () => expect(easings.linear(1)).toBe(1));
+});
 
-function nearly(a: number, b: number) {
-  return Math.abs(a - b) < EPSILON;
-}
+describe("easings.easeIn", () => {
+  it("returns 0 at t=0", () => expect(easings.easeIn(0)).toBe(0));
+  it("returns 0.25 at t=0.5", () => expect(easings.easeIn(0.5)).toBe(0.25));
+  it("returns 1 at t=1", () => expect(easings.easeIn(1)).toBe(1));
+});
 
-describe("easings", () => {
-  describe("boundary conditions (t=0 → 0, t=1 → 1)", () => {
-    for (const [name, fn] of Object.entries(easings)) {
-      it(`${name}(0) === 0`, () => {
-        expect(nearly(fn(0), 0)).toBe(true);
-      });
-      it(`${name}(1) === 1`, () => {
-        expect(nearly(fn(1), 1)).toBe(true);
-      });
-    }
-  });
+describe("easings.easeOut", () => {
+  it("returns 0 at t=0", () => expect(easings.easeOut(0)).toBe(0));
+  it("returns 0.75 at t=0.5", () => expect(easings.easeOut(0.5)).toBe(0.75));
+  it("returns 1 at t=1", () => expect(easings.easeOut(1)).toBe(1));
+});
 
-  describe("linear", () => {
-    it("returns t unchanged", () => {
-      expect(easings.linear(0.5)).toBe(0.5);
-      expect(easings.linear(0.25)).toBe(0.25);
-    });
+describe("easings.easeInOut", () => {
+  it("returns 0 at t=0", () => expect(easings.easeInOut(0)).toBe(0));
+  it("returns 0.5 at t=0.5", () => expect(easings.easeInOut(0.5)).toBe(0.5));
+  it("returns 1 at t=1", () => expect(easings.easeInOut(1)).toBe(1));
+  it("uses easeIn branch for t<0.5", () => {
+    expect(easings.easeInOut(0.25)).toBeCloseTo(0.125);
   });
-
-  describe("easeIn", () => {
-    it("is slower at start than end (t² curve)", () => {
-      expect(easings.easeIn(0.25)).toBeLessThan(0.25);
-    });
+  it("uses easeOut branch for t>=0.5", () => {
+    expect(easings.easeInOut(0.75)).toBeCloseTo(0.875);
   });
+});
 
-  describe("easeOut", () => {
-    it("is faster at start than end", () => {
-      expect(easings.easeOut(0.75)).toBeGreaterThan(0.75);
-    });
-  });
+describe("easings.easeInCubic", () => {
+  it("returns 0 at t=0", () => expect(easings.easeInCubic(0)).toBe(0));
+  it("returns 0.125 at t=0.5", () => expect(easings.easeInCubic(0.5)).toBe(0.125));
+  it("returns 1 at t=1", () => expect(easings.easeInCubic(1)).toBe(1));
+});
 
-  describe("easeInOut", () => {
-    it("is symmetric around 0.5", () => {
-      const v = easings.easeInOut(0.5);
-      expect(nearly(v, 0.5)).toBe(true);
-    });
+describe("easings.bounce", () => {
+  it("returns 0 at t=0", () => expect(easings.bounce(0)).toBe(0));
+  it("returns 1 at t=1", () => expect(easings.bounce(1)).toBeCloseTo(1));
+  it("handles first branch (t < 1/2.75)", () => {
+    const t = 0.2;
+    expect(easings.bounce(t)).toBeGreaterThan(0);
   });
-
-  describe("easeInCubic", () => {
-    it("is t³", () => {
-      expect(nearly(easings.easeInCubic(0.5), 0.125)).toBe(true);
-    });
+  it("handles second branch (t < 2/2.75)", () => {
+    const t = 0.5;
+    expect(easings.bounce(t)).toBeGreaterThan(0.7);
   });
-
-  describe("bounce", () => {
-    it("stays within [0, 1] for t in [0, 1]", () => {
-      for (let t = 0; t <= 1; t += 0.1) {
-        const v = easings.bounce(t);
-        expect(v).toBeGreaterThanOrEqual(0);
-        expect(v).toBeLessThanOrEqual(1 + EPSILON);
-      }
-    });
+  it("handles third branch (t < 2.5/2.75)", () => {
+    const t = 0.85;
+    expect(easings.bounce(t)).toBeGreaterThan(0.9);
+  });
+  it("handles fourth branch (t >= 2.5/2.75)", () => {
+    const t = 0.97;
+    expect(easings.bounce(t)).toBeGreaterThan(0.98);
   });
+});
 
-  describe("elastic", () => {
-    it("returns 0 at t=0 and 1 at t=1", () => {
-      expect(easings.elastic(0)).toBe(0);
-      expect(easings.elastic(1)).toBe(1);
-    });
+describe("easings.elastic", () => {
+  it("returns 0 at t=0", () => expect(easings.elastic(0)).toBe(0));
+  it("returns 1 at t=1", () => expect(easings.elastic(1)).toBe(1));
+  it("returns a negative value mid-range (overshoot)", () => {
+    expect(easings.elastic(0.5)).toBeLessThan(0);
   });
 });
 
 describe("resolveEasing", () => {
-  it("resolves a string key to the easing function", () => {
+  it("resolves a named easing", () => {
     const fn = resolveEasing("linear");
-    expect(fn).toBe(easings.linear);
+    expect(fn(0.5)).toBe(0.5);
+  });
+
+  it("returns a custom function as-is", () => {
+    const custom = (t: number) => t * 2;
+    const fn = resolveEasing(custom);
+    expect(fn).toBe(custom);
+    expect(fn(0.5)).toBe(1);
   });
 
-  it("passes through a custom function", () => {
-    const custom = (t: number) => t * t * t;
-    expect(resolveEasing(custom)).toBe(custom);
+  it("resolves all named easings", () => {
+    const names = ["linear", "easeIn", "easeOut", "easeInOut", "easeInCubic", "bounce", "elastic"] as const;
+    for (const name of names) {
+      const fn = resolveEasing(name);
+      expect(typeof fn).toBe("function");
+    }
   });
 });

package/src/__tests__/spring.test.ts

@@ -1,60 +1,92 @@
 // @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 pending animation", () => {
+    const s = spring(0);
+    s.target.set(100);
+    s.stop();
+    const valueAfterStop = s.value();
+    expect(typeof valueAfterStop).toBe("number");
   });
 
-  it("stop() cancels without throwing", () => {
-    vi.useFakeTimers();
+  it("setting target triggers animation", () => {
     const s = spring(0);
-    expect(() => { s.stop(); }).not.toThrow();
-    vi.clearAllTimers();
-    vi.useRealTimers();
+    s.target.set(100);
+    expect(s.target()).toBe(100);
+    s.stop();
+  });
+
+  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("stop() can be called multiple times safely", () => {
-    vi.useFakeTimers();
-    const s = spring(5);
+  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();
-    expect(() => { s.stop(); }).not.toThrow();
-    vi.clearAllTimers();
-    vi.useRealTimers();
   });
 
-  it("updating target signal triggers animation", () => {
-    vi.useFakeTimers();
+  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);
   });
 });

package/src/__tests__/transition.test.ts

@@ -1,75 +1,103 @@
 // @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();
+});
+
+function makeEl() {
+  return document.createElement("div");
+}
 
-    // enter-from should have been added immediately
+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();
-    await p;
-    vi.useRealTimers();
   });
 
-  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("uses default duration of 300ms", async () => {
+    const t = createTransition({ name: "x" });
+    const el = makeEl();
+    const p = t.enter(el);
+    vi.advanceTimersByTime(300);
+    await p;
+    expect(el.classList.contains("x-enter-to")).toBe(false);
   });
 });