@vysmo/easings 0.1.0

package/src/modifiers/chain.ts

@@ -0,0 +1,63 @@
+import { defineEasing } from "../define.js";
+import type { EasingFn } from "../types.js";
+
+export type ChainSegment = {
+  /** Ease for this segment. Input t is [0, 1] within the segment. */
+  ease: EasingFn;
+  /** Fraction of total duration this segment occupies. Must be > 0. */
+  duration: number;
+  /** Starting output value for the segment. Defaults to previous segment's end or 0. */
+  from?: number;
+  /** Ending output value. Defaults to the next segment's `from` or 1. */
+  to?: number;
+};
+
+/**
+ * Chain multiple eases sequentially across [0, 1]. Each segment has its
+ * own duration and output range. Useful for multi-phase animations
+ * (e.g., "power2.in for 30%, then spring for 70%").
+ */
+export function chain(segments: ReadonlyArray<ChainSegment>): EasingFn {
+  if (segments.length === 0) {
+    throw new RangeError("chain: at least one segment required");
+  }
+  const totalDuration = segments.reduce((sum, s) => sum + s.duration, 0);
+  if (totalDuration <= 0) {
+    throw new RangeError("chain: total duration must be > 0");
+  }
+  type ResolvedSegment = {
+    ease: EasingFn;
+    start: number;
+    end: number;
+    from: number;
+    to: number;
+  };
+  const resolved: ResolvedSegment[] = [];
+  let cursor = 0;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i]!;
+    const start = cursor;
+    const end = cursor + seg.duration / totalDuration;
+    const prevEnd = i > 0 ? resolved[i - 1]!.to : 0;
+    const nextFrom = segments[i + 1]?.from;
+    const from = seg.from ?? prevEnd;
+    const to = seg.to ?? nextFrom ?? (i === segments.length - 1 ? 1 : from);
+    resolved.push({ ease: seg.ease, start, end, from, to });
+    cursor = end;
+  }
+  const name = `chain(${segments.map((s) => s.ease.easingName).join(", ")})`;
+  return defineEasing(
+    name,
+    (t) => {
+      for (const seg of resolved) {
+        if (t <= seg.end) {
+          const span = seg.end - seg.start;
+          const localT = span === 0 ? 0 : (t - seg.start) / span;
+          return seg.from + (seg.to - seg.from) * seg.ease(localT);
+        }
+      }
+      return resolved[resolved.length - 1]!.to;
+    },
+    { exactEndpoints: false },
+  );
+}

package/src/modifiers/index.ts

@@ -0,0 +1,6 @@
+export { reverse } from "./reverse.js";
+export { mirror } from "./mirror.js";
+export { yoyo } from "./yoyo.js";
+export { chain, type ChainSegment } from "./chain.js";
+export { blend, compose } from "./blend.js";
+export { slice } from "./slice.js";

package/src/modifiers/mirror.ts

@@ -0,0 +1,14 @@
+import { defineEasing } from "../define.js";
+import type { EasingFn } from "../types.js";
+
+/**
+ * Mirror an ease across the midpoint. The first half plays the ease forward,
+ * scaled into [0, 0.5]; the second half plays it reversed, scaled into
+ * [0.5, 1]. Turns any ease into its inOut variant.
+ */
+export function mirror(ease: EasingFn): EasingFn {
+  return defineEasing(`mirror(${ease.easingName})`, (t) => {
+    if (t < 0.5) return ease(t * 2) / 2;
+    return 1 - ease((1 - t) * 2) / 2;
+  });
+}

package/src/modifiers/reverse.ts

@@ -0,0 +1,7 @@
+import { defineEasing } from "../define.js";
+import type { EasingFn } from "../types.js";
+
+/** Play the ease backward: f(t) → 1 - f(1 - t). Useful to turn any "in" into an "out". */
+export function reverse(ease: EasingFn): EasingFn {
+  return defineEasing(`reverse(${ease.easingName})`, (t) => 1 - ease(1 - t));
+}

package/src/modifiers/slice.ts

@@ -0,0 +1,29 @@
+import { defineEasing } from "../define.js";
+import type { EasingFn } from "../types.js";
+
+/**
+ * Extract a sub-section of an easing curve, stretched to fill [0, 1].
+ * Use when you want to play only part of a curve (e.g., just the overshoot
+ * portion of `back.out`, or the settle portion of `elastic.out`).
+ *
+ * The sliced portion is normalised: y(0) = ease(start), y(1) = ease(end),
+ * then remapped so the output hits 0 and 1 at the new endpoints.
+ */
+export function slice(ease: EasingFn, start: number, end: number): EasingFn {
+  if (!(start >= 0 && start < end && end <= 1)) {
+    throw new RangeError(
+      `slice: require 0 <= start < end <= 1; got start=${start}, end=${end}`,
+    );
+  }
+  if (start === 0 && end === 1) return ease;
+  const span = end - start;
+  const baseStart = ease(start);
+  const baseEnd = ease(end);
+  const ySpan = baseEnd - baseStart;
+  return defineEasing(`slice(${ease.easingName}, ${start}, ${end})`, (t) => {
+    const u = start + span * t;
+    const v = ease(u);
+    if (ySpan === 0) return 0;
+    return (v - baseStart) / ySpan;
+  });
+}

package/src/modifiers/yoyo.ts

@@ -0,0 +1,15 @@
+import { defineEasing } from "../define.js";
+import type { EasingFn } from "../types.js";
+
+/**
+ * Round-trip an ease: 0 → 1 → 0 over t in [0, 1]. First half runs the ease
+ * forward, second half runs it reversed. Unlike `mirror` which produces an
+ * inOut, `yoyo` returns to the start.
+ */
+export function yoyo(ease: EasingFn): EasingFn {
+  return defineEasing(
+    `yoyo(${ease.easingName})`,
+    (t) => (t < 0.5 ? ease(t * 2) : ease((1 - t) * 2)),
+    { exactEndpoints: false },
+  );
+}

package/src/parse.ts

@@ -0,0 +1,167 @@
+import {
+  backIn,
+  backInOut,
+  backOut,
+  bounceIn,
+  bounceInOut,
+  bounceOut,
+  circIn,
+  circInOut,
+  circOut,
+  cubicIn,
+  cubicInOut,
+  cubicOut,
+  elasticIn,
+  elasticInOut,
+  elasticOut,
+  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,
+  steps,
+} from "./easings/index.js";
+import {
+  anticipate,
+  anticipateIn,
+  anticipateInOut,
+  anticipateOut,
+  bezier,
+  spring,
+  wiggle,
+} from "./builders/index.js";
+import type { EasingFn, ParametricEasing } from "./types.js";
+
+type Buildable = EasingFn | ParametricEasing<Record<string, number | string>>;
+
+const REGISTRY: Record<string, Buildable> = {
+  linear,
+  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,
+  "quad.in": quadIn,
+  "quad.out": quadOut,
+  "quad.inOut": quadInOut,
+  "cubic.in": cubicIn,
+  "cubic.out": cubicOut,
+  "cubic.inOut": cubicInOut,
+  "quart.in": quartIn,
+  "quart.out": quartOut,
+  "quart.inOut": quartInOut,
+  "quint.in": quintIn,
+  "quint.out": quintOut,
+  "quint.inOut": quintInOut,
+  "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,
+  "back.in": backIn as Buildable,
+  "back.out": backOut as Buildable,
+  "back.inOut": backInOut as Buildable,
+  "elastic.in": elasticIn as Buildable,
+  "elastic.out": elasticOut as Buildable,
+  "elastic.inOut": elasticInOut as Buildable,
+  "bounce.in": bounceIn,
+  "bounce.out": bounceOut,
+  "bounce.inOut": bounceInOut,
+  steps: steps as Buildable,
+  spring: spring as Buildable,
+  wiggle: wiggle as Buildable,
+  anticipate: anticipate as Buildable,
+  "anticipate.in": anticipateIn as Buildable,
+  "anticipate.out": anticipateOut as Buildable,
+  "anticipate.inOut": anticipateInOut as Buildable,
+};
+
+const PARSE_RE = /^([a-zA-Z][\w]*(?:\.[a-zA-Z][\w]*)?)(?:\((.*)\))?$/;
+const CUBIC_BEZIER_RE = /^cubic-bezier\(\s*([^,]+),\s*([^,]+),\s*([^,]+),\s*([^)]+)\s*\)$/;
+
+function isParametric(x: unknown): x is ParametricEasing<Record<string, number | string>> {
+  return (
+    typeof x === "function" &&
+    "defaults" in (x as object) &&
+    "with" in (x as object)
+  );
+}
+
+function coerceArg(raw: string): number | string {
+  const trimmed = raw.trim().replace(/^["']|["']$/g, "");
+  const n = Number(trimmed);
+  return Number.isFinite(n) ? n : trimmed;
+}
+
+/**
+ * Parse a GSAP-style string reference into an EasingFn. Examples:
+ *
+ * - `"linear"`, `"power2.out"`, `"sine.inOut"` — core + variant
+ * - `"back.out(2)"` — parametric with positional arg
+ * - `"elastic.out(1.2, 0.4)"` — multiple positional args (amplitude, period)
+ * - `"steps(5, start)"` — mix of numeric and string args
+ * - `"cubic-bezier(0.42, 0, 0.58, 1)"` — CSS-style, exact bezier
+ *
+ * Throws a RangeError for unknown names or malformed input.
+ */
+export function parseEasing(spec: string): EasingFn {
+  const input = spec.trim();
+  const cb = CUBIC_BEZIER_RE.exec(input);
+  if (cb) {
+    const [, a, b, c, d] = cb;
+    return bezier(Number(a), Number(b), Number(c), Number(d));
+  }
+  const match = PARSE_RE.exec(input);
+  if (!match) throw new RangeError(`parseEasing: cannot parse '${spec}'`);
+  const [, name, argsStr] = match;
+  const entry = REGISTRY[name!];
+  if (!entry) throw new RangeError(`parseEasing: unknown easing '${name}'`);
+  const args = argsStr !== undefined && argsStr.length > 0 ? argsStr.split(",").map(coerceArg) : [];
+  if (args.length === 0) return entry as EasingFn;
+  if (!isParametric(entry)) {
+    throw new RangeError(`parseEasing: '${name}' is not parametric but received arguments`);
+  }
+  const keys = Object.keys(entry.defaults);
+  const params: Record<string, number | string> = {};
+  args.forEach((value, i) => {
+    const key = keys[i];
+    if (key !== undefined) params[key] = value;
+  });
+  return entry.with(params);
+}

package/src/reduced-motion.ts

@@ -0,0 +1,26 @@
+import { linear } from "./easings/linear.js";
+import type { EasingFn } from "./types.js";
+
+/**
+ * Check if the user has requested reduced motion via OS-level setting.
+ * Returns false when no DOM is available (SSR / Node).
+ */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * Wrap an easing to respect the user's `prefers-reduced-motion` setting.
+ * When reduced motion is requested, returns `fallback` (default: linear);
+ * otherwise returns the original ease.
+ *
+ * Evaluated at call time — not reactive to preference changes during the
+ * lifetime of a single animation. For long-running apps, re-evaluate when
+ * starting new animations.
+ */
+export function respectReducedMotion(ease: EasingFn, fallback: EasingFn = linear): EasingFn {
+  return prefersReducedMotion() ? fallback : ease;
+}

package/src/types.ts

@@ -0,0 +1,8 @@
+export type EasingFn = ((t: number) => number) & {
+  readonly easingName: string;
+};
+
+export type ParametricEasing<P extends object> = EasingFn & {
+  readonly defaults: Readonly<P>;
+  with(params: Partial<P>): EasingFn;
+};