Skip to content

Write HTML. Render video. Built for agents.

13.7 KB
Raw Blame
import { describe, it, expect } from "vitest";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import {
  idFromSelector,
  idSelector,
  isInstantHold,
  keyframeEases,
  parsePercentageKeyframes,
  resolveClipTimingBasis,
  playsNear,
  toClipKeyframes,
  toClipPercentage,
} from "./gsapShared";

describe("keyframeEases", () => {
  it("carries the keyframes' own ease into the tween ease, which GSAP plays the same", () => {
    const anim = {
      ease: "back.out",
      keyframes: { keyframes: [], ease: "sine.inOut", easeEach: "power2.out" },
    } as unknown as GsapAnimation;
    expect(keyframeEases(anim)).toEqual({ ease: "sine.inOut", easeEach: "power2.out" });
  });
});

describe("isInstantHold", () => {
  const animation = (method: GsapAnimation["method"], duration?: number) =>
    ({ method, duration }) as unknown as GsapAnimation;

  it("classifies set and duration-zero to/fromTo writes as instant holds", () => {
    expect(isInstantHold(animation("set"))).toBe(true);
    expect(isInstantHold(animation("to", 0))).toBe(true);
    expect(isInstantHold(animation("fromTo", 0))).toBe(true);
  });

  it("does not classify live tweens or duration-zero from writes as instant holds", () => {
    expect(isInstantHold(animation("to", 1))).toBe(false);
    expect(isInstantHold(animation("fromTo"))).toBe(false);
    expect(isInstantHold(animation("from", 0))).toBe(false);
  });
});

describe("parsePercentageKeyframes", () => {
  it("parses the object/percentage form", () => {
    const out = parsePercentageKeyframes({ "0%": { x: 0, y: 0 }, "100%": { x: 9, y: 4 } });
    expect(out?.keyframes).toEqual([
      { percentage: 0, properties: { x: 0, y: 0 } },
      { percentage: 100, properties: { x: 9, y: 4 } },
    ]);
  });

  it("parses GSAP array-form keyframes at each step's end, as the parser does", () => {
    // A multi-point shuttle path authored as `keyframes: [...]` has no `N%` keys;
    // step i of n ends at (i+1)/n.
    const out = parsePercentageKeyframes([
      { x: 0, y: 0 },
      { x: 520, y: 120 },
      { x: 1040, y: 0 },
      { x: 1480, y: 160 },
    ] as unknown as Record<string, unknown>);
    expect(out?.keyframes.map((k) => k.percentage)).toEqual([25, 50, 75, 100]);
    expect(out?.keyframes.map((k) => k.step)).toEqual([0, 1, 2, 3]);
    expect(out?.keyframes[1]!.properties).toEqual({ x: 520, y: 120 });
    const timed = parsePercentageKeyframes([
      { x: 0, duration: 1 },
      { x: 50, duration: 3 },
    ] as unknown as Record<string, unknown>);
    expect(timed?.keyframes.map((k) => k.percentage)).toEqual([25, 100]);
  });

  it("strips a per-entry ease without shifting the step spacing of the others", () => {
    // GSAP positions array keyframes by array index, so a `{ ease }` carried on an
    // entry is a segment ease (skipped as a property) — it must not change where
    // the surrounding keyframes land. 3 entries → 33.3 / 66.7 / 100, even though the
    // middle entry also carries an ease.
    const out = parsePercentageKeyframes([
      { x: 0 },
      { x: 100, ease: "power2.in" },
      { x: 200 },
    ] as unknown as Record<string, unknown>);
    expect(out?.keyframes.map((k) => k.percentage)).toEqual([33.3, 66.7, 100]);
    expect(out?.keyframes.map((k) => k.properties)).toEqual([{ x: 0 }, { x: 100 }, { x: 200 }]);
  });

  it("keeps the step spacing when an interior array slot has no animatable prop", () => {
    // A degenerate `{ ease }`-only slot contributes no output keyframe, but it is
    // still an array slot GSAP allocates a position to — so the remaining entries
    // keep their 3-slot percentages (33.3 and 100), not a 2-entry spacing.
    const out = parsePercentageKeyframes([
      { x: 0 },
      { ease: "power2.in" },
      { x: 200 },
    ] as unknown as Record<string, unknown>);
    expect(out?.keyframes.map((k) => k.percentage)).toEqual([33.3, 100]);
    expect(out?.keyframes.map((k) => k.properties)).toEqual([{ x: 0 }, { x: 200 }]);
  });

  it("returns null for keyframes with no positional/animatable props", () => {
    expect(parsePercentageKeyframes([] as unknown as Record<string, unknown>)).toBeNull();
    expect(parsePercentageKeyframes({})).toBeNull();
  });
});

describe("idSelector", () => {
  it("uses #id for valid CSS identifiers", () => {
    expect(idSelector("hero-word")).toBe("#hero-word");
    expect(idSelector("el_1")).toBe("#el_1");
  });

  it("uses an attribute selector for ids that #id can't address (digit-leading, dots, spaces)", () => {
    // #01-... / #a.b / #a b throw a SyntaxError in querySelector / GSAP, crashing
    // the preview when such a target is committed (e.g. dragging the element).
    expect(idSelector("01-hook-hero-word")).toBe('[id="01-hook-hero-word"]');
    expect(idSelector("my.class")).toBe('[id="my.class"]');
    expect(idSelector("1box")).toBe('[id="1box"]');
  });

  it("escapes quotes and backslashes in the attribute selector value", () => {
    expect(idSelector('1"x')).toBe('[id="1\\"x"]');
  });

  it("only ever emits #id for ids that can't break querySelector", () => {
    // Every id resolves to either a plain #id (only when safe) or an attribute
    // selector — never a #id that would throw a SyntaxError.
    for (const id of ["hero-word", "01-hook", "a.b", "a b", "1", "--x", '1"q']) {
      const sel = idSelector(id);
      if (sel.startsWith("#")) expect(sel).toBe(`#${id}`);
      else expect(sel.startsWith('[id="')).toBe(true);
    }
  });
});

describe("toClipPercentage", () => {
  // Selection keys embed this number, so every keyframe-cache writer has to round
  // it identically: a coarser writer rewrites the cache with a different value and
  // orphans the live selection key built from the finer one.
  it("keeps three decimals so a beat-snapped keyframe lands on its beat", () => {
    expect(toClipPercentage(1 / 3, 0, 1, 0)).toBe(33.333);
    expect(toClipPercentage(2.5, 2, 4, 0)).toBe(12.5);
  });

  it("passes the tween percentage through for a zero-length clip", () => {
    expect(toClipPercentage(5, 0, 0, 42)).toBe(42);
  });
});

describe("toClipKeyframes", () => {
  // Fixture carries only the fields the function under test reads; the
  // double-cast is the documented way to stand in for the full runtime shape
  // (CONTRIBUTING.md).
  const durationless = {
    id: "a1",
    method: "to",
    targetSelector: "#box",
    vars: {},
    resolvedStart: 0,
  } as unknown as GsapAnimation;

  it("places a duration-less tween's keyframes where GSAP plays them, not across the clip", () => {
    const rows = toClipKeyframes([{ percentage: 0 }, { percentage: 100 }], durationless, 0, 4);
    expect(rows.map((row) => row.percentage)).toEqual([0, 12.5]);
  });

  it("matches a keyframe by the time it plays, not its warped progress", () => {
    const eased = {
      ...durationless,
      duration: 1,
      ease: "power2.in",
      keyframes: { format: "percentage", keyframes: [] },
    } as unknown as GsapAnimation;
    // At 20% of the time power2.in (cubic) shows 0.8% progress: close in progress, far in time.
    expect(playsNear(eased, 0, 0.8)).toBe(false);
    expect(playsNear(eased, 50, 50.5)).toBe(true);
  });

  it("places a keyframe where an outer ease makes GSAP reach it", () => {
    const eased = {
      ...durationless,
      duration: 1,
      ease: "power2.in",
      keyframes: { format: "percentage", keyframes: [] },
    } as unknown as GsapAnimation;
    const rows = toClipKeyframes(
      [{ percentage: 0 }, { percentage: 50 }, { percentage: 100 }],
      eased,
      0,
      1,
    );
    // GSAP's power2 is cubic: it reaches 50% at the cube root of 0.5.
    expect(rows.map((row) => row.percentage)).toEqual([0, 79.37, 100]);
  });

  it("keeps the tween percentage and the animation identity on every row", () => {
    const rows = toClipKeyframes([{ percentage: 50 }], durationless, 0, 4);
    expect(rows[0]).toMatchObject({ tweenPercentage: 50, animationId: "a1" });
  });
});

describe("resolveClipTimingBasis", () => {
  // Measured on v-product-promo: `captions-comp` mounts at 1.5s for 12.5s, and the
  // six tweens inside it resolve to 0..12.5 — composition-local, not main-timeline
  // absolute. Subtracting the host's 1.5 mount from a 0s tween cached pct -12.
  const host = { id: "captions-comp", domId: "captions-comp", start: 1.5, duration: 12.5 };
  const children = [{ id: "line", hostId: "captions-comp" }];

  it("gives a sub-composition inner element the host window in the tween's own frame", () => {
    expect(resolveClipTimingBasis("line", "captions.html", [host], children)).toEqual({
      elStart: 0,
      elDuration: 12.5,
    });
  });

  it("leaves a root-composition element on the main timeline", () => {
    const box = { id: "box", domId: "box", start: 3, duration: 2 };
    expect(resolveClipTimingBasis("box", "index.html", [box], [])).toEqual({
      elStart: 3,
      elDuration: 2,
    });
  });

  it("rebases an expanded sub-comp child by its host mount", () => {
    // Expanded children carry host-ABSOLUTE display starts; the tweens they own are
    // still composition-local, so the basis is the child's local start.
    const pill = { id: "pill", domId: "pill", start: 8, duration: 4, parentCompositionStart: 6 };
    expect(resolveClipTimingBasis("pill", "scene.html", [pill], [])).toEqual({
      elStart: 2,
      elDuration: 4,
    });
  });

  it("rebases by the parent composition clip when the child is not expanded", () => {
    const parent = { id: "scene-comp", domId: "scene-comp", start: 5, duration: 10 };
    const pill = {
      id: "pill",
      domId: "pill",
      start: 7,
      duration: 3,
      parentCompositionId: "scene-comp",
    };
    expect(resolveClipTimingBasis("pill", "scene.html", [parent, pill], [])).toEqual({
      elStart: 2,
      elDuration: 3,
    });
  });

  it("treats a child whose parent composition is missing as starting at 0", () => {
    // The mount is unknowable, so the only safe frame is the child's own. The
    // old `?? 0` handed back `start` unchanged, which is a main-timeline value
    // masquerading as a composition-local one and caches negative percentages.
    const pill = {
      id: "pill",
      domId: "pill",
      start: 7,
      duration: 3,
      parentCompositionId: "not-in-elements",
    };
    expect(resolveClipTimingBasis("pill", "scene.html", [pill], [])).toEqual({
      elStart: 0,
      elDuration: 3,
    });
  });

  it("keeps a main-timeline clip's own start when it names no parent", () => {
    const box = { id: "box", domId: "box", start: 4, duration: 2 };
    expect(resolveClipTimingBasis("box", "index.html", [box], [])).toEqual({
      elStart: 4,
      elDuration: 2,
    });
  });

  it("falls back to a unit window when neither the element nor a host resolves", () => {
    expect(resolveClipTimingBasis("ghost", "index.html", [], [])).toEqual({
      elStart: 0,
      elDuration: 1,
    });
  });
});

describe("sub-composition keyframe percentages", () => {
  const host = { id: "captions-comp", domId: "captions-comp", start: 1.5, duration: 12.5 };
  const children = [{ id: "line", hostId: "captions-comp" }];
  const basis = () => resolveClipTimingBasis("line", "captions.html", [host], children);
  const inner = (resolvedStart: number, duration?: number) =>
    ({
      id: `t-${resolvedStart}`,
      method: "to",
      targetSelector: "#line",
      vars: {},
      resolvedStart,
      duration,
    }) as unknown as GsapAnimation;
  const percentages = (animation: GsapAnimation) => {
    const { elStart, elDuration } = basis();
    return toClipKeyframes(
      [{ percentage: 0 }, { percentage: 100 }],
      animation,
      elStart,
      elDuration,
    ).map((row) => row.percentage);
  };

  it("puts a tween on the host's first frame at 0%, never below zero", () => {
    // A clip-relative percentage can never be negative; this one cached -12.
    expect(percentages(inner(0))).toEqual([0, 4]);
  });

  it("puts the last tween's end keyframe at 100%", () => {
    expect(percentages(inner(12.1, 0.4))).toEqual([96.8, 100]);
  });

  it("keeps every measured tween of the fixture inside 0..100", () => {
    for (const start of [0, 3.2, 3.5, 7.7, 8, 12.1]) {
      for (const percentage of percentages(inner(start, 0.4))) {
        expect(percentage).toBeGreaterThanOrEqual(0);
        expect(percentage).toBeLessThanOrEqual(100);
      }
    }
  });

  it("keeps a root-composition tween at the head of its own clip", () => {
    const box = { id: "box", domId: "box", start: 3, duration: 2 };
    const { elStart, elDuration } = resolveClipTimingBasis("box", "index.html", [box], []);
    const rows = toClipKeyframes([{ percentage: 0 }], inner(3, 2), elStart, elDuration);
    expect(rows[0]!.percentage).toBe(0);
  });

  it("passes tween percentages through for a zero-length clip", () => {
    expect(toClipKeyframes([{ percentage: 40 }], inner(0, 0.4), 0, 0)[0]!.percentage).toBe(40);
  });

  it("round-trips a clip percentage through the basis it was written with", () => {
    // The drag commit converts a dropped clip-% back to a time with this basis
    // (useTimelineEditCallbacks) and compares it against the tween's own
    // resolvedStart, so the basis has to be in the tween's frame on both sides.
    const { elStart, elDuration } = basis();
    const absTime = elStart + (40 / 100) * elDuration;
    expect(absTime).toBe(5);
    expect(toClipPercentage(absTime, elStart, elDuration, 0)).toBe(40);
  });
});

describe("idFromSelector", () => {
  it("round-trips every shape idSelector emits", () => {
    for (const id of ["hero-word", "el_1", "01-hook-hero-word", "my.class", "1box", '1"x']) {
      expect(idFromSelector(idSelector(id))).toBe(id);
    }
  });

  it("returns null for a selector that does not address an id", () => {
    expect(idFromSelector(".dot")).toBeNull();
    expect(idFromSelector("[data-hf-id='x']")).toBeNull();
    expect(idFromSelector(undefined)).toBeNull();
  });
});