@vysmo/easings 0.1.0

package/src/__tests__/slice.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { linear, power2Out, slice } from "../index.js";
+
+describe("slice", () => {
+  it("slice of linear across full range is identity", () => {
+    const s = slice(linear, 0, 1);
+    expect(s).toBe(linear);
+  });
+
+  it("slice of linear over a sub-range is still linear", () => {
+    const s = slice(linear, 0.25, 0.75);
+    for (let i = 0; i <= 10; i++) {
+      const t = i / 10;
+      expect(s(t)).toBeCloseTo(t, 10);
+    }
+  });
+
+  it("hits new endpoints exactly", () => {
+    const s = slice(power2Out, 0.2, 0.8);
+    expect(s(0)).toBe(0);
+    expect(s(1)).toBe(1);
+  });
+
+  it("slice output at t=0 corresponds to ease(start) remapped", () => {
+    const ease = power2Out;
+    const s = slice(ease, 0.3, 0.9);
+    // At t=0.5 inside the slice, we should see ease(0.6) normalized
+    const expected = (ease(0.6) - ease(0.3)) / (ease(0.9) - ease(0.3));
+    expect(s(0.5)).toBeCloseTo(expected, 10);
+  });
+
+  it("rejects invalid ranges", () => {
+    expect(() => slice(linear, -0.1, 0.5)).toThrow(RangeError);
+    expect(() => slice(linear, 0.5, 0.5)).toThrow(RangeError);
+    expect(() => slice(linear, 0.8, 0.2)).toThrow(RangeError);
+    expect(() => slice(linear, 0, 1.1)).toThrow(RangeError);
+  });
+});

package/src/__tests__/spring-presets.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import {
+  SPRING_PRESETS,
+  gentleSpring,
+  molassesSpring,
+  slowSpring,
+  stiffSpring,
+  wobblySpring,
+} from "../index.js";
+
+describe("spring presets", () => {
+  it("all presets hit endpoints", () => {
+    for (const preset of [gentleSpring, wobblySpring, stiffSpring, slowSpring, molassesSpring]) {
+      expect(preset(0)).toBe(0);
+      expect(preset(1)).toBe(1);
+    }
+  });
+
+  it("wobbly has more oscillation than stiff", () => {
+    let wobblyCrossings = 0;
+    let stiffCrossings = 0;
+    let prevW = wobblySpring(0);
+    let prevS = stiffSpring(0);
+    for (let i = 1; i <= 200; i++) {
+      const w = wobblySpring(i / 200);
+      const s = stiffSpring(i / 200);
+      if ((prevW < 1 && w >= 1) || (prevW > 1 && w <= 1)) wobblyCrossings++;
+      if ((prevS < 1 && s >= 1) || (prevS > 1 && s <= 1)) stiffCrossings++;
+      prevW = w;
+      prevS = s;
+    }
+    expect(wobblyCrossings).toBeGreaterThanOrEqual(stiffCrossings);
+  });
+
+  it("molasses is heavily damped (no overshoot)", () => {
+    let max = 0;
+    for (let i = 0; i <= 200; i++) max = Math.max(max, molassesSpring(i / 200));
+    expect(max).toBeLessThanOrEqual(1 + 1e-6);
+  });
+
+  it("SPRING_PRESETS values are sensible", () => {
+    for (const [, cfg] of Object.entries(SPRING_PRESETS)) {
+      expect(cfg.stiffness).toBeGreaterThan(0);
+      expect(cfg.damping).toBeGreaterThan(0);
+      expect(cfg.mass).toBeGreaterThan(0);
+    }
+  });
+});

package/src/__tests__/ssr.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * easings vitest config runs in Node (no `browser.enabled`) so the mere
+ * fact these tests execute proves the library is SSR-safe at import time.
+ * Additional checks verify no DOM globals are required.
+ */
+
+describe("SSR safety", () => {
+  it("window is undefined in this runtime", () => {
+    expect(typeof window).toBe("undefined");
+  });
+
+  it("module loads without DOM globals", async () => {
+    const mod = await import("../index.js");
+    expect(mod).toBeDefined();
+    expect(typeof mod.linear).toBe("function");
+    expect(typeof mod.defineEasing).toBe("function");
+    expect(typeof mod.parseEasing).toBe("function");
+  });
+
+  it("all catalog functions execute without DOM", async () => {
+    const {
+      linear,
+      power2Out,
+      backOut,
+      elasticOut,
+      bounceOut,
+      steps,
+      spring,
+      bezier,
+      rough,
+      wiggle,
+    } = await import("../index.js");
+    expect(linear(0.5)).toBe(0.5);
+    expect(power2Out(0.5)).toBeCloseTo(0.875, 3);
+    expect(backOut(0.5)).toBeGreaterThan(0.9);
+    expect(elasticOut(0.5)).toBeGreaterThan(0);
+    expect(bounceOut(0.5)).toBeGreaterThan(0);
+    expect(steps(0.5)).toBe(0.4);
+    expect(spring(0.5)).toBeGreaterThan(0);
+    expect(bezier(0.42, 0, 0.58, 1)(0.5)).toBeCloseTo(0.5, 3);
+    expect(rough.with({ seed: 1 })(0.5)).toBeGreaterThan(0);
+    expect(wiggle.with({ wiggles: 5 })(0.5)).toBeCloseTo(0, 6);
+  });
+
+  it("CSS subpath loads without DOM", async () => {
+    const { toCSSLinear, toCSSBezier } = await import("../css.js");
+    expect(typeof toCSSLinear).toBe("function");
+    expect(typeof toCSSBezier).toBe("function");
+  });
+
+  it("parse subpath loads without DOM", async () => {
+    const { parseEasing } = await import("../parse.js");
+    expect(typeof parseEasing).toBe("function");
+  });
+
+  it("reduced-motion subpath loads without DOM and returns false", async () => {
+    const { prefersReducedMotion } = await import("../reduced-motion.js");
+    expect(prefersReducedMotion()).toBe(false);
+  });
+});

package/src/__tests__/types-check.ts

@@ -0,0 +1,104 @@
+/**
+ * Compile-time inference assertions. Not a runtime test — `pnpm typecheck`
+ * must pass with ZERO emitted errors, and every `@ts-expect-error` must
+ * actually catch a real type error. Guards against regressions in the
+ * parametric .with() API and the defineEasing factories.
+ */
+
+import {
+  anticipateIn,
+  backOut,
+  bezier,
+  custom,
+  defineEasing,
+  defineParametricEasing,
+  elasticOut,
+  linear,
+  parseEasing,
+  power2Out,
+  spring,
+  steps,
+  toCSSLinear,
+  type EasingFn,
+  type ParametricEasing,
+} from "../index.js";
+
+// --------- Valid usage: should compile ---------
+
+const _a: EasingFn = power2Out;
+const _b: number = power2Out(0.5);
+const _c: string = power2Out.easingName;
+
+// Parametric eases: callable AND have .with() + .defaults
+const _d: EasingFn = backOut;
+const _e: EasingFn = backOut.with({ overshoot: 2 });
+const _f: EasingFn = backOut.with({});
+const _g: Readonly<{ overshoot: number }> = backOut.defaults;
+
+// Spring with full params
+const _h = spring.with({ stiffness: 200, damping: 20, mass: 1, velocity: 0 });
+
+// Partial is allowed
+const _i = spring.with({ stiffness: 200 });
+
+// Elastic params
+const _j = elasticOut.with({ amplitude: 1.2, period: 0.4 });
+
+// Steps params with correct string literal
+const _k = steps.with({ count: 5, position: "start" });
+const _l = steps.with({ count: 5, position: "end" });
+const _m = steps.with({ count: 5, position: "none" });
+
+// Anticipate
+const _n = anticipateIn.with({ overshoot: 2 });
+
+// Builders
+const _o: EasingFn = bezier(0.42, 0, 0.58, 1);
+const _p: EasingFn = custom([
+  [0, 0],
+  [0.5, 0.8],
+  [1, 1],
+]);
+
+// parseEasing returns EasingFn
+const _q: EasingFn = parseEasing("power2.out");
+
+// CSS
+const _r: string = toCSSLinear(power2Out);
+const _s: string = toCSSLinear((t: number) => t);
+
+// defineEasing factory
+const _customEase: EasingFn = defineEasing("myEase", (t) => t * t);
+const _customParametric: ParametricEasing<{ strength: number }> = defineParametricEasing(
+  "myParam",
+  { strength: 1 },
+  ({ strength }) => (t) => t * strength,
+);
+
+// Linear is a plain EasingFn, not parametric
+const _t: EasingFn = linear;
+
+// --------- Invalid usage: must be caught ---------
+
+// @ts-expect-error — power2Out has no .with() method (not parametric)
+power2Out.with({});
+
+// @ts-expect-error — unknown param key
+backOut.with({ nonexistent: 1 });
+
+// @ts-expect-error — wrong value type (string for numeric param)
+backOut.with({ overshoot: "big" });
+
+// @ts-expect-error — wrong value type for steps.position
+steps.with({ count: 5, position: "both" });
+
+// @ts-expect-error — input must be number
+power2Out("not a number");
+
+// @ts-expect-error — no args
+power2Out();
+
+// @ts-expect-error — linear is not parametric
+linear.with({});
+
+export {};

package/src/builders/anticipate.ts

@@ -0,0 +1,66 @@
+import { defineParametricEasing } from "../define.js";
+
+export type AnticipateParams = {
+  /** Depth of the backward dip before the forward motion. Default 1.525 (Framer Motion default). */
+  overshoot: number;
+};
+
+const DEFAULTS: AnticipateParams = { overshoot: 1.525 };
+
+function anticipateInBuild({ overshoot: s }: AnticipateParams) {
+  const n = Math.max(1, s + 3);
+  return (t: number) => {
+    if (t < 0.5) {
+      const p = t * 2;
+      return 0.5 * (p * p * ((s + 1) * p - s));
+    }
+    const p = t * 2 - 1;
+    return 0.5 + 0.5 * (1 - (1 - p) ** n);
+  };
+}
+
+function anticipateOutBuild({ overshoot: s }: AnticipateParams) {
+  const n = Math.max(1, s + 3);
+  return (t: number) => {
+    if (t < 0.5) {
+      const p = t * 2;
+      return 0.5 * (p ** n);
+    }
+    const u = 1 - t;
+    const p = u * 2;
+    return 1 - 0.5 * (p * p * ((s + 1) * p - s));
+  };
+}
+
+function anticipateInOutBuild({ overshoot: s }: AnticipateParams) {
+  return (t: number) => {
+    if (t < 0.5) {
+      const p = t * 2;
+      return 0.5 * (p * p * ((s + 1) * p - s));
+    }
+    const u = 1 - t;
+    const p = u * 2;
+    return 1 - 0.5 * (p * p * ((s + 1) * p - s));
+  };
+}
+
+/**
+ * Character-animation-style anticipation: wind-up before the forward motion.
+ *
+ * - `anticipateIn` (formerly just `anticipate`): dip at start, smooth arrival.
+ * - `anticipateOut`: smooth departure, overshoot dip near the end.
+ * - `anticipateInOut`: dip at start AND overshoot near the end (wind-up + follow-through).
+ *
+ * The second half of `anticipateIn` uses a power-n ease where n matches the
+ * first-half slope at t=0.5, giving C¹ continuity regardless of overshoot.
+ */
+export const anticipateIn = defineParametricEasing("anticipate.in", DEFAULTS, anticipateInBuild);
+export const anticipateOut = defineParametricEasing("anticipate.out", DEFAULTS, anticipateOutBuild);
+export const anticipateInOut = defineParametricEasing(
+  "anticipate.inOut",
+  DEFAULTS,
+  anticipateInOutBuild,
+);
+
+/** Alias for `anticipateIn` (Framer Motion's default shape). */
+export const anticipate = anticipateIn;

package/src/builders/bezier.ts

@@ -0,0 +1,71 @@
+import { defineEasing } from "../define.js";
+import type { EasingFn } from "../types.js";
+
+const NEWTON_ITERATIONS = 8;
+const NEWTON_MIN_SLOPE = 1e-6;
+const SUBDIVISION_PRECISION = 1e-7;
+const SUBDIVISION_MAX_ITERATIONS = 32;
+
+function a(c1: number, c2: number): number {
+  return 1 - 3 * c2 + 3 * c1;
+}
+function b(c1: number, c2: number): number {
+  return 3 * c2 - 6 * c1;
+}
+function c(c1: number): number {
+  return 3 * c1;
+}
+
+function sampleCurve(t: number, A: number, B: number, C: number): number {
+  return ((A * t + B) * t + C) * t;
+}
+
+function sampleDerivative(t: number, A: number, B: number, C: number): number {
+  return (3 * A * t + 2 * B) * t + C;
+}
+
+function solveCurveX(x: number, ax: number, bx: number, cx: number): number {
+  let t = x;
+  for (let i = 0; i < NEWTON_ITERATIONS; i++) {
+    const slope = sampleDerivative(t, ax, bx, cx);
+    if (Math.abs(slope) < NEWTON_MIN_SLOPE) break;
+    const currentX = sampleCurve(t, ax, bx, cx) - x;
+    t -= currentX / slope;
+  }
+  let lo = 0;
+  let hi = 1;
+  t = x;
+  if (t < lo) return lo;
+  if (t > hi) return hi;
+  for (let i = 0; i < SUBDIVISION_MAX_ITERATIONS; i++) {
+    const currentX = sampleCurve(t, ax, bx, cx);
+    if (Math.abs(currentX - x) < SUBDIVISION_PRECISION) return t;
+    if (currentX < x) lo = t;
+    else hi = t;
+    t = (lo + hi) / 2;
+  }
+  return t;
+}
+
+export function bezier(p1x: number, p1y: number, p2x: number, p2y: number): EasingFn {
+  if (p1x < 0 || p1x > 1 || p2x < 0 || p2x > 1) {
+    throw new RangeError(
+      `bezier: control point x coordinates must be in [0, 1]; got p1x=${p1x}, p2x=${p2x}`,
+    );
+  }
+  const ax = a(p1x, p2x);
+  const bx = b(p1x, p2x);
+  const cx = c(p1x);
+  const ay = a(p1y, p2y);
+  const by = b(p1y, p2y);
+  const cy = c(p1y);
+  const linear = p1x === p1y && p2x === p2y;
+  const name = `bezier(${p1x}, ${p1y}, ${p2x}, ${p2y})`;
+  if (linear) return defineEasing(name, (t) => t);
+  return defineEasing(name, (t) => sampleCurve(solveCurveX(t, ax, bx, cx), ay, by, cy));
+}
+
+export const bezierEase = bezier(0.25, 0.1, 0.25, 1);
+export const bezierEaseIn = bezier(0.42, 0, 1, 1);
+export const bezierEaseOut = bezier(0, 0, 0.58, 1);
+export const bezierEaseInOut = bezier(0.42, 0, 0.58, 1);

package/src/builders/breathe.ts

@@ -0,0 +1,31 @@
+import { defineParametricEasing } from "../define.js";
+
+export type BreatheParams = {
+  /**
+   * Number of in-out breath cycles across [0, 1]. 0.5 = single inhale
+   * (0 → 1). 1 = inhale + exhale (0 → 1 → 0). 2 = two full cycles. The
+   * curve oscillates in [0, 1] so it maps cleanly to opacity / scale /
+   * any normalised animatable.
+   */
+  cycles: number;
+};
+
+const DEFAULTS: BreatheParams = { cycles: 1 };
+
+const TAU = Math.PI * 2;
+
+// (1 - cos(τ·c·t)) / 2 — cosine wave shifted into [0, 1]. Distinct from
+// `wiggle` (which oscillates [-1, 1] for shake/vibration); breathe
+// stays positive and is intended for idle/ambient animations.
+//
+// exactEndpoints: false — for cycles ≠ 0.5n, the natural curve doesn't
+// land at 1 at t=1, and clamping defeats the rhythmic intent.
+export const breathe = defineParametricEasing(
+  "breathe",
+  DEFAULTS,
+  ({ cycles }) => {
+    const c = Math.max(0, cycles);
+    return (t) => (1 - Math.cos(TAU * c * t)) / 2;
+  },
+  { exactEndpoints: false },
+);

package/src/builders/custom.ts

@@ -0,0 +1,43 @@
+import { defineEasing } from "../define.js";
+import type { EasingFn } from "../types.js";
+
+export type CustomPoint = readonly [x: number, y: number];
+
+/**
+ * Build an easing from a sequence of (x, y) control points, interpolated
+ * linearly between them. Use for hand-drawn curves, exported visualiser
+ * data, or any non-analytic easing shape.
+ *
+ * Points must be in ascending x order with x in [0, 1]. Endpoints are
+ * clamped to (0, 0) and (1, 1) by the framework — provide those points
+ * explicitly if you want to see the un-clamped curve.
+ */
+export function custom(points: ReadonlyArray<CustomPoint>): EasingFn {
+  if (points.length < 2) {
+    throw new RangeError(`custom: at least 2 points required; got ${points.length}`);
+  }
+  for (let i = 1; i < points.length; i++) {
+    const prev = points[i - 1]!;
+    const curr = points[i]!;
+    if (curr[0] < prev[0]) {
+      throw new RangeError(
+        `custom: points must be sorted by ascending x; got ${prev[0]} then ${curr[0]} at index ${i}`,
+      );
+    }
+  }
+  const name = `custom(${points.length} points)`;
+  return defineEasing(name, (t) => {
+    if (t <= points[0]![0]) return points[0]![1];
+    for (let i = 1; i < points.length; i++) {
+      const [x1, y1] = points[i]!;
+      if (t <= x1) {
+        const [x0, y0] = points[i - 1]!;
+        const span = x1 - x0;
+        if (span === 0) return y1;
+        const u = (t - x0) / span;
+        return y0 + (y1 - y0) * u;
+      }
+    }
+    return points[points.length - 1]![1];
+  });
+}

package/src/builders/expoScale.ts

@@ -0,0 +1,30 @@
+import { defineEasing } from "../define.js";
+import { linear } from "../easings/linear.js";
+import type { EasingFn } from "../types.js";
+
+/**
+ * Ease tuned for scale animations spanning large ratios (e.g. 0.01 → 100).
+ * Linear interpolation across such ranges feels jerky because perception
+ * is logarithmic. `expoScale` maps t so that when used as
+ * `scale = startScale + (endScale - startScale) * expoScale(t)`, the
+ * visual motion is uniform across orders of magnitude.
+ *
+ * Optionally combine with another ease: the result of `ease(t)` is what
+ * gets log-mapped.
+ */
+export function expoScale(startScale: number, endScale: number, ease: EasingFn = linear): EasingFn {
+  if (startScale <= 0 || endScale <= 0) {
+    throw new RangeError(
+      `expoScale: startScale and endScale must be positive; got ${startScale}, ${endScale}`,
+    );
+  }
+  if (startScale === endScale) {
+    return defineEasing(`expoScale(${startScale}, ${endScale})`, () => 0);
+  }
+  const ratio = endScale / startScale;
+  const span = endScale - startScale;
+  return defineEasing(`expoScale(${startScale}, ${endScale})`, (t) => {
+    const eased = ease(t);
+    return (startScale * ratio ** eased - startScale) / span;
+  });
+}

package/src/builders/gravity.ts

@@ -0,0 +1,27 @@
+import { defineParametricEasing } from "../define.js";
+
+export type GravityParams = {
+  /**
+   * How heavy the falling object feels. 0 = floats (linear), 1 ≈ Earth
+   * gravity (quadratic fall, equivalent to power1.in), 2 = cubic fall
+   * (power2.in), higher = molasses. Continuous, so designers get a
+   * single "weight" knob instead of choosing between named power
+   * curves.
+   */
+  weight: number;
+};
+
+const DEFAULTS: GravityParams = { weight: 1 };
+
+// Math: f(t) = t^(1 + weight). Keeps endpoints exact, monotonic for
+// weight ≥ 0, and continuously interpolates the catalog's power-in
+// family so a designer can dial "heavier" without picking a number
+// from a discrete set.
+export const gravity = defineParametricEasing(
+  "gravity",
+  DEFAULTS,
+  ({ weight }) => {
+    const exp = 1 + Math.max(0, weight);
+    return (t) => Math.pow(t, exp);
+  },
+);

package/src/builders/index.ts

@@ -0,0 +1,24 @@
+export { bezier, bezierEase, bezierEaseIn, bezierEaseOut, bezierEaseInOut } from "./bezier.js";
+export { spring, type SpringParams } from "./spring.js";
+export { custom, type CustomPoint } from "./custom.js";
+export { rough, type RoughParams } from "./rough.js";
+export { wiggle, type WiggleParams, type WiggleType } from "./wiggle.js";
+export { slow, type SlowParams } from "./slow.js";
+export { expoScale } from "./expoScale.js";
+export { gravity, type GravityParams } from "./gravity.js";
+export { breathe, type BreatheParams } from "./breathe.js";
+export {
+  anticipate,
+  anticipateIn,
+  anticipateOut,
+  anticipateInOut,
+  type AnticipateParams,
+} from "./anticipate.js";
+export {
+  SPRING_PRESETS,
+  gentleSpring,
+  wobblySpring,
+  stiffSpring,
+  slowSpring,
+  molassesSpring,
+} from "./spring-presets.js";

package/src/builders/rough.ts

@@ -0,0 +1,83 @@
+import { defineParametricEasing } from "../define.js";
+import { linear } from "../easings/linear.js";
+import type { EasingFn } from "../types.js";
+
+export type RoughParams = {
+  /** Base ease to perturb. Default linear. */
+  template: EasingFn;
+  /** Magnitude of jitter. Typical 0.05–0.3. Default 0.15. */
+  strength: number;
+  /** Number of jitter points along the curve. More = finer noise. Default 20. */
+  points: number;
+  /** Taper the jitter so it dies toward endpoints. */
+  taper: "none" | "in" | "out" | "both";
+  /** Randomize x-spacing of jitter points. Default true. */
+  randomize: boolean;
+  /** Seed for deterministic output. Pass to get the same rough curve every call. */
+  seed: number;
+};
+
+const DEFAULTS: RoughParams = {
+  template: linear,
+  strength: 0.15,
+  points: 20,
+  taper: "both",
+  randomize: true,
+  seed: 0,
+};
+
+function mulberry32(seed: number) {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function taperAmount(taper: RoughParams["taper"], x: number): number {
+  switch (taper) {
+    case "in":
+      return x;
+    case "out":
+      return 1 - x;
+    case "both":
+      return 2 * (0.5 - Math.abs(x - 0.5));
+    case "none":
+      return 1;
+  }
+}
+
+export const rough = defineParametricEasing(
+  "rough",
+  DEFAULTS,
+  ({ template, strength, points, taper, randomize, seed }) => {
+    const seedValue = seed === 0 ? Math.floor(Math.random() * 2 ** 31) : seed;
+    const rng = mulberry32(seedValue);
+    const n = Math.max(3, Math.floor(points));
+    const xs: number[] = [0];
+    for (let i = 1; i < n - 1; i++) xs.push(randomize ? rng() : i / (n - 1));
+    xs.push(1);
+    xs.sort((a, b) => a - b);
+    const ys: number[] = xs.map((x) => {
+      const base = template(x);
+      const jitter = (rng() - 0.5) * 2 * strength * taperAmount(taper, x);
+      return base + jitter;
+    });
+    return (t: number) => {
+      for (let i = 1; i < xs.length; i++) {
+        const x1 = xs[i]!;
+        if (t <= x1) {
+          const x0 = xs[i - 1]!;
+          const span = x1 - x0;
+          if (span === 0) return ys[i]!;
+          const u = (t - x0) / span;
+          return ys[i - 1]! + (ys[i]! - ys[i - 1]!) * u;
+        }
+      }
+      return ys[ys.length - 1]!;
+    };
+  },
+);