@vysmo/easings 0.1.0

package/src/__tests__/endpoint-correctness.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from "vitest";
+import {
+  circIn,
+  circInOut,
+  circOut,
+  cubicIn,
+  cubicInOut,
+  cubicOut,
+  expoIn,
+  expoInOut,
+  expoOut,
+  linear,
+  none,
+  power1In,
+  power1InOut,
+  power1Out,
+  power2In,
+  power2InOut,
+  power2Out,
+  power3In,
+  power3InOut,
+  power3Out,
+  power4In,
+  power4InOut,
+  power4Out,
+  quadIn,
+  quadInOut,
+  quadOut,
+  quartIn,
+  quartInOut,
+  quartOut,
+  quintIn,
+  quintInOut,
+  quintOut,
+  sineIn,
+  sineInOut,
+  sineOut,
+  smoothIn,
+  smoothInOut,
+  smoothOut,
+  type EasingFn,
+} from "../index.js";
+
+const ALL: ReadonlyArray<[string, EasingFn]> = [
+  ["linear", linear],
+  ["none", none],
+  ["power1.in", power1In],
+  ["power1.out", power1Out],
+  ["power1.inOut", power1InOut],
+  ["power2.in", power2In],
+  ["power2.out", power2Out],
+  ["power2.inOut", power2InOut],
+  ["power3.in", power3In],
+  ["power3.out", power3Out],
+  ["power3.inOut", power3InOut],
+  ["power4.in", power4In],
+  ["power4.out", power4Out],
+  ["power4.inOut", power4InOut],
+  ["sine.in", sineIn],
+  ["sine.out", sineOut],
+  ["sine.inOut", sineInOut],
+  ["circ.in", circIn],
+  ["circ.out", circOut],
+  ["circ.inOut", circInOut],
+  ["expo.in", expoIn],
+  ["expo.out", expoOut],
+  ["expo.inOut", expoInOut],
+  ["smooth.in", smoothIn],
+  ["smooth.out", smoothOut],
+  ["smooth.inOut", smoothInOut],
+];
+
+describe("endpoint correctness", () => {
+  it.each(ALL)("%s returns exactly 0 at t=0", (_, fn) => {
+    expect(fn(0)).toBe(0);
+  });
+
+  it.each(ALL)("%s returns exactly 1 at t=1", (_, fn) => {
+    expect(fn(1)).toBe(1);
+  });
+});
+
+describe("monotonicity (non-overshooting easings)", () => {
+  it.each(ALL)("%s is monotonically non-decreasing across [0, 1]", (_, fn) => {
+    let prev = fn(0);
+    for (let i = 1; i <= 100; i++) {
+      const curr = fn(i / 100);
+      expect(curr).toBeGreaterThanOrEqual(prev - 1e-9);
+      prev = curr;
+    }
+  });
+});
+
+describe("aliases are identical to their power counterparts", () => {
+  it("quad == power1", () => {
+    expect(quadIn).toBe(power1In);
+    expect(quadOut).toBe(power1Out);
+    expect(quadInOut).toBe(power1InOut);
+  });
+  it("cubic == power2", () => {
+    expect(cubicIn).toBe(power2In);
+    expect(cubicOut).toBe(power2Out);
+    expect(cubicInOut).toBe(power2InOut);
+  });
+  it("quart == power3", () => {
+    expect(quartIn).toBe(power3In);
+    expect(quartOut).toBe(power3Out);
+    expect(quartInOut).toBe(power3InOut);
+  });
+  it("quint == power4", () => {
+    expect(quintIn).toBe(power4In);
+    expect(quintOut).toBe(power4Out);
+    expect(quintInOut).toBe(power4InOut);
+  });
+  it("none == linear", () => {
+    expect(none).toBe(linear);
+  });
+});
+
+describe("midpoint sanity", () => {
+  it("linear(0.5) === 0.5", () => {
+    expect(linear(0.5)).toBe(0.5);
+  });
+  it("inOut variants cross 0.5 at t=0.5", () => {
+    const inOutEasings: EasingFn[] = [
+      power1InOut,
+      power2InOut,
+      power3InOut,
+      power4InOut,
+      sineInOut,
+      circInOut,
+      expoInOut,
+      smoothInOut,
+    ];
+    for (const fn of inOutEasings) {
+      expect(fn(0.5)).toBeCloseTo(0.5, 6);
+    }
+  });
+  it("in variants stay below 0.5 at t=0.5 (except linear)", () => {
+    const inEasings: EasingFn[] = [power1In, power2In, power3In, power4In, sineIn, circIn, expoIn, smoothIn];
+    for (const fn of inEasings) {
+      expect(fn(0.5)).toBeLessThan(0.5);
+    }
+  });
+  it("out variants exceed 0.5 at t=0.5 (except linear)", () => {
+    const outEasings: EasingFn[] = [
+      power1Out,
+      power2Out,
+      power3Out,
+      power4Out,
+      sineOut,
+      circOut,
+      expoOut,
+      smoothOut,
+    ];
+    for (const fn of outEasings) {
+      expect(fn(0.5)).toBeGreaterThan(0.5);
+    }
+  });
+});
+
+describe("easing names are set", () => {
+  it.each(ALL)("%s has correct easingName property", (name, fn) => {
+    if (name === "none") {
+      expect(fn.easingName).toBe("linear");
+    } else {
+      expect(fn.easingName).toBe(name);
+    }
+  });
+});

package/src/__tests__/modifiers.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import {
+  blend,
+  chain,
+  compose,
+  linear,
+  mirror,
+  power2In,
+  power2Out,
+  power3In,
+  reverse,
+  sineOut,
+  yoyo,
+} from "../index.js";
+
+describe("reverse", () => {
+  it("reverse(power2In) matches power2Out", () => {
+    const rev = reverse(power2In);
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(rev(t)).toBeCloseTo(power2Out(t), 10);
+    }
+  });
+  it("reverse(reverse(f)) === f (up to FP)", () => {
+    const double = reverse(reverse(power2In));
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(double(t)).toBeCloseTo(power2In(t), 10);
+    }
+  });
+  it("propagates name", () => {
+    expect(reverse(power2In).easingName).toBe("reverse(power2.in)");
+  });
+});
+
+describe("mirror", () => {
+  it("mirror(linear) is still linear", () => {
+    const m = mirror(linear);
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(m(t)).toBeCloseTo(t, 10);
+    }
+  });
+  it("mirror of an in-ease crosses 0.5 at t=0.5", () => {
+    const m = mirror(power2In);
+    expect(m(0.5)).toBeCloseTo(0.5, 10);
+  });
+  it("mirror hits endpoints", () => {
+    const m = mirror(power3In);
+    expect(m(0)).toBe(0);
+    expect(m(1)).toBe(1);
+  });
+});
+
+describe("yoyo", () => {
+  it("returns to 0 at t=1", () => {
+    const y = yoyo(power2In);
+    expect(y(1)).toBeCloseTo(0, 10);
+  });
+  it("peaks at t=0.5", () => {
+    const y = yoyo(power2In);
+    expect(y(0.5)).toBeCloseTo(1, 10);
+  });
+  it("is symmetric around t=0.5", () => {
+    const y = yoyo(power2In);
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(y(t)).toBeCloseTo(y(1 - t), 10);
+    }
+  });
+});
+
+describe("chain", () => {
+  it("two equal-duration linear segments reproduce linear", () => {
+    const c = chain([
+      { ease: linear, duration: 1, from: 0, to: 0.5 },
+      { ease: linear, duration: 1, from: 0.5, to: 1 },
+    ]);
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(c(t)).toBeCloseTo(t, 10);
+    }
+  });
+  it("segments respect duration ratios", () => {
+    const c = chain([
+      { ease: linear, duration: 3, from: 0, to: 0.9 },
+      { ease: linear, duration: 1, from: 0.9, to: 1 },
+    ]);
+    expect(c(0.75)).toBeCloseTo(0.9, 10);
+  });
+  it("auto-fills endpoints when omitted", () => {
+    const c = chain([{ ease: sineOut, duration: 1 }]);
+    expect(c(0)).toBeCloseTo(0, 10);
+    expect(c(1)).toBeCloseTo(1, 10);
+  });
+  it("rejects empty segments", () => {
+    expect(() => chain([])).toThrow(RangeError);
+  });
+});
+
+describe("blend", () => {
+  it("weight 0 returns pure a", () => {
+    const b = blend(power2In, power2Out, 0);
+    expect(b).toBe(power2In);
+  });
+  it("weight 1 returns pure b", () => {
+    const b = blend(power2In, power2Out, 1);
+    expect(b).toBe(power2Out);
+  });
+  it("weight 0.5 is the midpoint average", () => {
+    const b = blend(power2In, power2Out, 0.5);
+    for (let i = 1; i < 10; i++) {
+      const t = i / 10;
+      expect(b(t)).toBeCloseTo((power2In(t) + power2Out(t)) / 2, 10);
+    }
+  });
+});
+
+describe("compose", () => {
+  it("compose(a, linear) === a", () => {
+    const c = compose(power2In, linear);
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(c(t)).toBeCloseTo(power2In(t), 10);
+    }
+  });
+  it("compose(power2In, power2In) applies it twice", () => {
+    const c = compose(power2In, power2In);
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(c(t)).toBeCloseTo(power2In(power2In(t)), 10);
+    }
+  });
+});

package/src/__tests__/parametric.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import {
+  backIn,
+  backInOut,
+  backOut,
+  bounceIn,
+  bounceInOut,
+  bounceOut,
+  elasticIn,
+  elasticInOut,
+  elasticOut,
+  steps,
+  type EasingFn,
+  type ParametricEasing,
+} from "../index.js";
+
+const PARAMETRIC = [
+  ["back.in", backIn],
+  ["back.out", backOut],
+  ["back.inOut", backInOut],
+  ["elastic.in", elasticIn],
+  ["elastic.out", elasticOut],
+  ["elastic.inOut", elasticInOut],
+  ["steps", steps],
+] as const;
+
+const BOUNCE = [
+  ["bounce.in", bounceIn],
+  ["bounce.out", bounceOut],
+  ["bounce.inOut", bounceInOut],
+] as const;
+
+describe("parametric easings hit endpoints", () => {
+  it.each(PARAMETRIC)("%s(0) === 0 at defaults", (_, fn) => {
+    expect((fn as EasingFn)(0)).toBe(0);
+  });
+  it.each(PARAMETRIC)("%s(1) === 1 at defaults", (_, fn) => {
+    expect((fn as EasingFn)(1)).toBe(1);
+  });
+  it.each(BOUNCE)("%s(0) === 0", (_, fn) => {
+    expect(fn(0)).toBe(0);
+  });
+  it.each(BOUNCE)("%s(1) === 1", (_, fn) => {
+    expect(fn(1)).toBe(1);
+  });
+});
+
+describe("back has overshoot", () => {
+  it("back.out exceeds 1 somewhere in (0, 1)", () => {
+    let max = 0;
+    for (let i = 0; i <= 100; i++) max = Math.max(max, backOut(i / 100));
+    expect(max).toBeGreaterThan(1);
+  });
+  it("back.in goes below 0 somewhere in (0, 1)", () => {
+    let min = 1;
+    for (let i = 0; i <= 100; i++) min = Math.min(min, backIn(i / 100));
+    expect(min).toBeLessThan(0);
+  });
+  it("custom overshoot changes curve shape", () => {
+    const soft = backOut.with({ overshoot: 0.5 });
+    const hard = backOut.with({ overshoot: 4 });
+    let softMax = 0;
+    let hardMax = 0;
+    for (let i = 0; i <= 100; i++) {
+      softMax = Math.max(softMax, soft(i / 100));
+      hardMax = Math.max(hardMax, hard(i / 100));
+    }
+    expect(hardMax).toBeGreaterThan(softMax);
+  });
+});
+
+describe("elastic oscillates", () => {
+  it("elastic.out crosses 1 multiple times (oscillation)", () => {
+    let crossings = 0;
+    let prev = 0;
+    for (let i = 1; i <= 100; i++) {
+      const curr = elasticOut(i / 100);
+      if ((prev < 1 && curr >= 1) || (prev > 1 && curr <= 1)) crossings++;
+      prev = curr;
+    }
+    expect(crossings).toBeGreaterThanOrEqual(2);
+  });
+  it("custom amplitude changes overshoot", () => {
+    const big = elasticOut.with({ amplitude: 3 });
+    const small = elasticOut.with({ amplitude: 1 });
+    let bigMax = 0;
+    let smallMax = 0;
+    for (let i = 0; i <= 100; i++) {
+      bigMax = Math.max(bigMax, big(i / 100));
+      smallMax = Math.max(smallMax, small(i / 100));
+    }
+    expect(bigMax).toBeGreaterThan(smallMax);
+  });
+});
+
+describe("bounce produces stepped peaks", () => {
+  it("bounce.out has multiple local maxima between 0 and 1", () => {
+    let peaks = 0;
+    let prev = bounceOut(0);
+    let trend: 1 | -1 = 1;
+    for (let i = 1; i <= 200; i++) {
+      const curr = bounceOut(i / 200);
+      if (trend === 1 && curr < prev) {
+        peaks++;
+        trend = -1;
+      } else if (trend === -1 && curr > prev) {
+        trend = 1;
+      }
+      prev = curr;
+    }
+    expect(peaks).toBeGreaterThanOrEqual(3);
+  });
+});
+
+describe("steps produces discrete values", () => {
+  it("steps (default end, count 5) produces exactly 5 unique values across [0, 1)", () => {
+    const values = new Set<number>();
+    for (let i = 0; i < 100; i++) values.add(steps(i / 100));
+    expect(values.size).toBeLessThanOrEqual(5);
+  });
+  it("steps with count 10 produces finer granularity", () => {
+    const fine = steps.with({ count: 10 });
+    const values = new Set<number>();
+    for (let i = 0; i < 100; i++) values.add(fine(i / 100));
+    expect(values.size).toBeGreaterThan(5);
+  });
+  it("steps position: start outputs 1/n at t=0", () => {
+    const s = steps.with({ count: 4, position: "start" });
+    expect(s(0)).toBeCloseTo(0.25, 10);
+  });
+  it("steps position: none outputs 0 at t=0 and 1 at t=1", () => {
+    const s = steps.with({ count: 5, position: "none" });
+    expect(s(0)).toBe(0);
+    expect(s(1)).toBe(1);
+  });
+});
+
+describe("parametric factories preserve defaults immutably", () => {
+  it.each(PARAMETRIC)("%s.defaults is frozen", (_, fn) => {
+    const parametric = fn as ParametricEasing<object>;
+    expect(Object.isFrozen(parametric.defaults)).toBe(true);
+  });
+  it(".with() produces independent EasingFn", () => {
+    const a = backOut.with({ overshoot: 2 });
+    const b = backOut.with({ overshoot: 5 });
+    expect(a(0.5)).not.toBe(b(0.5));
+  });
+});

package/src/__tests__/parse.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  backOut,
+  bounceInOut,
+  elasticOut,
+  linear,
+  parseEasing,
+  power2Out,
+  sineInOut,
+} from "../index.js";
+
+describe("parseEasing", () => {
+  it("parses plain linear", () => {
+    expect(parseEasing("linear")).toBe(linear);
+  });
+
+  it("parses dotted variants", () => {
+    expect(parseEasing("power2.out")).toBe(power2Out);
+    expect(parseEasing("sine.inOut")).toBe(sineInOut);
+    expect(parseEasing("bounce.inOut")).toBe(bounceInOut);
+  });
+
+  it("parses parametric with one arg", () => {
+    const fn = parseEasing("back.out(2)");
+    const native = backOut.with({ overshoot: 2 });
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(fn(t)).toBeCloseTo(native(t), 10);
+    }
+  });
+
+  it("parses parametric with multiple args", () => {
+    const fn = parseEasing("elastic.out(1.2, 0.4)");
+    const native = elasticOut.with({ amplitude: 1.2, period: 0.4 });
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(fn(t)).toBeCloseTo(native(t), 10);
+    }
+  });
+
+  it("parses steps with numeric + string arg", () => {
+    const fn = parseEasing("steps(4, start)");
+    expect(fn(0)).toBe(0.25);
+    expect(fn(1)).toBe(1);
+  });
+
+  it("parses CSS cubic-bezier() form", () => {
+    const fn = parseEasing("cubic-bezier(0.42, 0, 0.58, 1)");
+    expect(fn(0)).toBe(0);
+    expect(fn(1)).toBe(1);
+    expect(fn(0.5)).toBeCloseTo(0.5, 3);
+  });
+
+  it("trims whitespace", () => {
+    expect(parseEasing("  power2.out  ")).toBe(power2Out);
+  });
+
+  it("throws on unknown names", () => {
+    expect(() => parseEasing("unknownEase")).toThrow(RangeError);
+    expect(() => parseEasing("power2.foo")).toThrow(RangeError);
+  });
+
+  it("throws on malformed input", () => {
+    expect(() => parseEasing("")).toThrow(RangeError);
+    expect(() => parseEasing(".power2")).toThrow(RangeError);
+  });
+
+  it("throws when passing args to non-parametric", () => {
+    expect(() => parseEasing("linear(2)")).toThrow(RangeError);
+  });
+});

package/src/__tests__/property.test.ts

@@ -0,0 +1,110 @@
+import fc from "fast-check";
+import { describe, expect, it } from "vitest";
+import {
+  circIn,
+  circInOut,
+  circOut,
+  cubicIn,
+  cubicInOut,
+  cubicOut,
+  expoIn,
+  expoInOut,
+  expoOut,
+  linear,
+  quartIn,
+  quartInOut,
+  quartOut,
+  quintIn,
+  quintInOut,
+  quintOut,
+  sineIn,
+  sineInOut,
+  sineOut,
+  type EasingFn,
+} from "../index.js";
+
+// Non-overshooting easings: output in [0, 1] for t in [0, 1]
+const NON_OVERSHOOT: Array<[string, EasingFn]> = [
+  ["linear", linear],
+  ["cubicIn", cubicIn],
+  ["cubicOut", cubicOut],
+  ["cubicInOut", cubicInOut],
+  ["quartIn", quartIn],
+  ["quartOut", quartOut],
+  ["quartInOut", quartInOut],
+  ["quintIn", quintIn],
+  ["quintOut", quintOut],
+  ["quintInOut", quintInOut],
+  ["sineIn", sineIn],
+  ["sineOut", sineOut],
+  ["sineInOut", sineInOut],
+  ["circIn", circIn],
+  ["circOut", circOut],
+  ["circInOut", circInOut],
+  ["expoIn", expoIn],
+  ["expoOut", expoOut],
+  ["expoInOut", expoInOut],
+];
+
+const tArb = fc.double({ min: 0, max: 1, noNaN: true });
+
+describe("property: endpoints always clamp", () => {
+  it.each(NON_OVERSHOOT)("%s(0) is exactly 0", (_, fn) => {
+    expect(fn(0)).toBe(0);
+  });
+  it.each(NON_OVERSHOOT)("%s(1) is exactly 1", (_, fn) => {
+    expect(fn(1)).toBe(1);
+  });
+});
+
+describe("property: output stays in [0, 1] for non-overshoot eases", () => {
+  it.each(NON_OVERSHOOT)("%s output is always in [0, 1]", (_, fn) => {
+    fc.assert(
+      fc.property(tArb, (t) => {
+        const y = fn(t);
+        return y >= -1e-9 && y <= 1 + 1e-9;
+      }),
+      { numRuns: 200 },
+    );
+  });
+});
+
+describe("property: monotonicity for non-overshoot eases", () => {
+  it.each(NON_OVERSHOOT)("%s is monotonically non-decreasing", (_, fn) => {
+    fc.assert(
+      fc.property(
+        fc.double({ min: 0, max: 0.9999, noNaN: true }),
+        fc.double({ min: 0, max: 0.01, noNaN: true }),
+        (t, delta) => {
+          const a = fn(t);
+          const b = fn(Math.min(1, t + delta));
+          return b >= a - 1e-9;
+        },
+      ),
+      { numRuns: 200 },
+    );
+  });
+});
+
+describe("property: defensive input handling", () => {
+  it("all eases return finite output for any finite input", () => {
+    const EXTENDED: EasingFn[] = NON_OVERSHOOT.map(([, fn]) => fn);
+    fc.assert(
+      fc.property(
+        fc.double({ min: -100, max: 100, noNaN: true }),
+        fc.integer({ min: 0, max: EXTENDED.length - 1 }),
+        (t, idx) => {
+          const result = EXTENDED[idx]!(t);
+          return Number.isFinite(result);
+        },
+      ),
+      { numRuns: 300 },
+    );
+  });
+
+  it("all eases return 0 on NaN input", () => {
+    for (const [, fn] of NON_OVERSHOOT) {
+      expect(fn(Number.NaN)).toBe(0);
+    }
+  });
+});

package/src/__tests__/reduced-motion.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  linear,
+  power2Out,
+  prefersReducedMotion,
+  respectReducedMotion,
+  steps,
+} from "../index.js";
+
+describe("prefersReducedMotion", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns false when window is undefined (SSR)", () => {
+    vi.stubGlobal("window", undefined);
+    expect(prefersReducedMotion()).toBe(false);
+  });
+
+  it("returns false when matchMedia is unavailable", () => {
+    vi.stubGlobal("window", {} as unknown);
+    expect(prefersReducedMotion()).toBe(false);
+  });
+
+  it("returns true when media query matches", () => {
+    vi.stubGlobal("window", {
+      matchMedia: () => ({ matches: true }),
+    } as unknown);
+    expect(prefersReducedMotion()).toBe(true);
+  });
+
+  it("returns false when media query does not match", () => {
+    vi.stubGlobal("window", {
+      matchMedia: () => ({ matches: false }),
+    } as unknown);
+    expect(prefersReducedMotion()).toBe(false);
+  });
+});
+
+describe("respectReducedMotion", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns the original ease when reduced motion is off", () => {
+    vi.stubGlobal("window", {
+      matchMedia: () => ({ matches: false }),
+    } as unknown);
+    expect(respectReducedMotion(power2Out)).toBe(power2Out);
+  });
+
+  it("returns linear fallback by default when reduced motion is on", () => {
+    vi.stubGlobal("window", {
+      matchMedia: () => ({ matches: true }),
+    } as unknown);
+    expect(respectReducedMotion(power2Out)).toBe(linear);
+  });
+
+  it("accepts a custom fallback", () => {
+    vi.stubGlobal("window", {
+      matchMedia: () => ({ matches: true }),
+    } as unknown);
+    const fallback = steps;
+    expect(respectReducedMotion(power2Out, fallback)).toBe(fallback);
+  });
+});