@vysmo/text 0.1.0

package/src/__tests__/presets.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { HANDCURATED_NAMES, listPresets, resolvePreset } from "../presets/index.js";
+import { evaluateSpecs } from "../animate.js";
+import type { PresetName } from "../types.js";
+
+const ALL = listPresets();
+
+describe("preset catalog", () => {
+  it("exposes 14 hand-curated starter presets — 6 enter, 3 exit, 5 emphasis", () => {
+    // Asserts the seed catalog only — `listPresets()` also includes any
+    // entries authored via the Studio's random generator and ingested
+    // into `presets/generated.ts`, which grows independently.
+    expect(HANDCURATED_NAMES).toHaveLength(14);
+    expect(HANDCURATED_NAMES.filter((n) => n.startsWith("enter/"))).toHaveLength(6);
+    expect(HANDCURATED_NAMES.filter((n) => n.startsWith("exit/"))).toHaveLength(3);
+    expect(HANDCURATED_NAMES.filter((n) => n.startsWith("emphasis/"))).toHaveLength(5);
+  });
+
+  it("includes 3D presets that set perspective and (where relevant) transformOrigin", () => {
+    const depth = resolvePreset("enter/depth-zoom");
+    expect(depth.perspective).toBeGreaterThan(0);
+    const flip = resolvePreset("enter/flip-x");
+    expect(flip.perspective).toBeGreaterThan(0);
+    expect(flip.transformOrigin).toBeDefined();
+    const coin = resolvePreset("emphasis/coin-flip");
+    expect(coin.perspective).toBeGreaterThan(0);
+  });
+
+  it("each preset has a namespaced kebab-case name", () => {
+    // Allow digits inside segments — generated names use a placeholder
+    // form like `enter/g-001` until the rename pass assigns semantic
+    // labels. Strict letters-only kebab-case still applies after rename.
+    for (const name of ALL) {
+      expect(name).toMatch(/^(enter|exit|emphasis)\/[a-z0-9]+(-[a-z0-9]+)*$/);
+    }
+  });
+
+  it("resolvePreset returns a fully-formed Preset with ≥1 animation", () => {
+    for (const name of ALL) {
+      const p = resolvePreset(name);
+      expect(p.name).toBe(name);
+      expect(p.stagger).toBeGreaterThan(0);
+      expect(p.animations.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("resolvePreset throws on an unknown name", () => {
+    expect(() => resolvePreset("enter/bogus" as PresetName)).toThrow(/unknown preset/);
+  });
+
+  it("enter presets start invisible (opacity 0 at t=0)", () => {
+    for (const name of ALL.filter((n) => n.startsWith("enter/"))) {
+      const p = resolvePreset(name);
+      const v = evaluateSpecs(p.animations, 0);
+      expect(v.opacity).toBe(0);
+    }
+  });
+
+  it("exit presets end invisible (opacity 0 at end of timeline)", () => {
+    for (const name of ALL.filter((n) => n.startsWith("exit/"))) {
+      const p = resolvePreset(name);
+      const end = Math.max(
+        ...p.animations.map((a) => (a.delay ?? 0) + (a.duration ?? 600)),
+      );
+      const v = evaluateSpecs(p.animations, end);
+      expect(v.opacity).toBe(0);
+    }
+  });
+
+  it("emphasis presets return to their rest state at the end (mod 360 for rotations)", () => {
+    const rotationRest = (deg: number): number => {
+      const m = ((deg % 360) + 360) % 360;
+      return m > 180 ? m - 360 : m;
+    };
+    for (const name of ALL.filter((n) => n.startsWith("emphasis/"))) {
+      const p = resolvePreset(name);
+      const end = Math.max(
+        ...p.animations.map((a) => (a.delay ?? 0) + (a.duration ?? 600)),
+      );
+      const v = evaluateSpecs(p.animations, end);
+      if (v.scale !== undefined) expect(v.scale).toBeCloseTo(1, 3);
+      if (v.translateX !== undefined) expect(v.translateX).toBeCloseTo(0, 3);
+      if (v.rotate !== undefined) expect(rotationRest(v.rotate)).toBeCloseTo(0, 3);
+      if (v.rotateY !== undefined) expect(rotationRest(v.rotateY)).toBeCloseTo(0, 3);
+    }
+  });
+});

package/src/__tests__/properties.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { applyProps, clearProps } from "../properties.js";
+
+function el(): HTMLElement {
+  return document.createElement("span");
+}
+
+describe("applyProps", () => {
+  it("sets opacity as a raw string", () => {
+    const e = el();
+    applyProps(e, { opacity: 0.5 });
+    expect(e.style.opacity).toBe("0.5");
+  });
+
+  it("composes translate/rotate/scale into one transform declaration", () => {
+    const e = el();
+    applyProps(e, { translateX: 10, translateY: -5, rotate: 30, scale: 1.2 });
+    expect(e.style.transform).toMatch(/translate3d\(10px, -5px, 0px\)/);
+    expect(e.style.transform).toMatch(/rotate\(30deg\)/);
+    expect(e.style.transform).toMatch(/scale\(1\.2\)/);
+  });
+
+  it("emits translate3d when any single translate axis is set", () => {
+    const e = el();
+    applyProps(e, { translateY: 20 });
+    expect(e.style.transform).toBe("translate3d(0px, 20px, 0px)");
+  });
+
+  it("composes blur/brightness/etc into one filter declaration", () => {
+    const e = el();
+    applyProps(e, { blur: 4, brightness: 1.2, hueRotate: 90 });
+    expect(e.style.filter).toMatch(/blur\(4px\)/);
+    expect(e.style.filter).toMatch(/brightness\(1\.2\)/);
+    expect(e.style.filter).toMatch(/hue-rotate\(90deg\)/);
+  });
+
+  it("leaves transform/filter untouched when no relevant prop is present", () => {
+    const e = el();
+    e.style.transform = "translateX(100px)";
+    applyProps(e, { opacity: 0.9 });
+    expect(e.style.transform).toBe("translateX(100px)");
+  });
+
+  it("replaces the previous transform composition on each call", () => {
+    const e = el();
+    applyProps(e, { rotate: 10, scale: 2 });
+    applyProps(e, { translateX: 50 });
+    expect(e.style.transform).toBe("translate3d(50px, 0px, 0px)");
+    expect(e.style.transform).not.toContain("rotate");
+  });
+});
+
+describe("clearProps", () => {
+  it("removes opacity/transform/filter from the element", () => {
+    const e = el();
+    applyProps(e, { opacity: 0.3, translateY: 5, blur: 2 });
+    clearProps(e);
+    expect(e.style.opacity).toBe("");
+    expect(e.style.transform).toBe("");
+    expect(e.style.filter).toBe("");
+  });
+});

package/src/__tests__/split.test.ts

@@ -0,0 +1,140 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { splitText } from "../split.js";
+
+let mounted: HTMLElement[] = [];
+
+function mount(text: string, style?: Partial<CSSStyleDeclaration>): HTMLElement {
+  const el = document.createElement("p");
+  el.textContent = text;
+  if (style) Object.assign(el.style, style);
+  document.body.appendChild(el);
+  mounted.push(el);
+  return el;
+}
+
+afterEach(() => {
+  for (const el of mounted) el.remove();
+  mounted = [];
+});
+
+describe("splitText — character mode", () => {
+  it("wraps each visible grapheme in a span, keeping whitespace as text nodes", () => {
+    const el = mount("ab c");
+    const splits = splitText(el, { mode: "character" });
+    expect(splits.slices).toHaveLength(3);
+    for (const s of splits.slices) {
+      expect(s.tagName).toBe("SPAN");
+      expect(s.getAttribute("data-text-slice")).toBe("character");
+      expect(s.style.display).toBe("inline-block");
+    }
+    expect(splits.slices.map((s) => s.textContent).join("")).toBe("abc");
+  });
+
+  it("treats emoji as a single grapheme", () => {
+    const el = mount("a👨‍👩‍👧b");
+    const splits = splitText(el, { mode: "character" });
+    const texts = splits.slices.map((s) => s.textContent);
+    expect(texts).toEqual(["a", "👨‍👩‍👧", "b"]);
+  });
+
+  it("treats combining marks as a single grapheme", () => {
+    // "é" built from e + combining acute (U+0065 U+0301) — two code points, one grapheme.
+    const el = mount("éa");
+    const splits = splitText(el, { mode: "character" });
+    expect(splits.slices).toHaveLength(2);
+    expect(splits.slices[0]!.textContent).toBe("é");
+  });
+
+  it("exposes the original string to screen readers via a visually-hidden copy", () => {
+    const el = mount("Accessible text");
+    splitText(el, { mode: "character" });
+    const sr = el.querySelector("[data-text-sr]") as HTMLElement | null;
+    expect(sr).not.toBeNull();
+    expect(sr!.textContent).toBe("Accessible text");
+    expect(sr!.style.position).toBe("absolute");
+  });
+
+  it("marks visible slices aria-hidden so screen readers use the SR copy", () => {
+    const el = mount("Hi");
+    const splits = splitText(el, { mode: "character" });
+    for (const s of splits.slices) {
+      expect(s.getAttribute("aria-hidden")).toBe("true");
+    }
+  });
+});
+
+describe("splitText — word mode", () => {
+  it("wraps words AND punctuation; only whitespace stays as raw text nodes", () => {
+    const el = mount("Hello, world!");
+    const splits = splitText(el, { mode: "word" });
+    expect(splits.slices.map((s) => s.textContent)).toEqual(["Hello", ",", "world", "!"]);
+    for (const s of splits.slices) {
+      expect(s.getAttribute("data-text-slice")).toBe("word");
+    }
+  });
+
+  it("preserves whitespace between words in rendered text", () => {
+    const el = mount("a bb ccc");
+    splitText(el, { mode: "word" });
+    const visible = el.textContent ?? "";
+    // SR-only copy prepends "a bb ccc"; the split copy appends "a bb ccc" again.
+    expect(visible).toContain("a bb ccc");
+  });
+
+  it("segments Arabic text into word slices with its locale-aware boundaries", () => {
+    // "مرحبا بالعالم" = "Hello world". Word mode keeps each word whole, so
+    // contextual shaping within each span still applies correctly.
+    const el = mount("مرحبا بالعالم", { direction: "rtl" });
+    const splits = splitText(el, { mode: "word", locale: "ar" });
+    const texts = splits.slices.map((s) => s.textContent);
+    expect(texts).toContain("مرحبا");
+    expect(texts).toContain("بالعالم");
+  });
+
+  it("wraps punctuation in non-latin scripts too (CJK fullwidth, Arabic)", () => {
+    const el = mount("你好，世界！", { direction: "ltr" });
+    const splits = splitText(el, { mode: "word", locale: "zh" });
+    const texts = splits.slices.map((s) => s.textContent);
+    expect(texts).toContain("，");
+    expect(texts).toContain("！");
+  });
+});
+
+describe("splitText — line mode", () => {
+  it("groups words into lines by their measured top position", () => {
+    const el = mount("one two three four five six seven eight nine ten eleven twelve", {
+      width: "60px",
+      fontSize: "16px",
+      lineHeight: "20px",
+      fontFamily: "monospace",
+    });
+    const splits = splitText(el, { mode: "line" });
+    expect(splits.slices.length).toBeGreaterThan(1);
+    for (const s of splits.slices) {
+      expect(s.getAttribute("data-text-slice")).toBe("line");
+    }
+    const rendered = splits.slices.map((s) => s.textContent?.trim()).join(" ");
+    for (const word of ["one", "twelve", "seven"]) {
+      expect(rendered).toContain(word);
+    }
+  });
+});
+
+describe("splitText — restore", () => {
+  it("restore() returns the element to its original textContent", () => {
+    const el = mount("Hello world");
+    const splits = splitText(el, { mode: "character" });
+    expect(el.querySelectorAll("[data-text-slice]").length).toBeGreaterThan(0);
+    splits.restore();
+    expect(el.textContent).toBe("Hello world");
+    expect(el.querySelectorAll("[data-text-slice]").length).toBe(0);
+  });
+
+  it("restore() is idempotent", () => {
+    const el = mount("abc");
+    const splits = splitText(el, { mode: "character" });
+    splits.restore();
+    splits.restore();
+    expect(el.textContent).toBe("abc");
+  });
+});

package/src/__tests__/ssr.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * SSR safety: the module graph must load in Node without DOM globals.
+ * Uses the vitest.ssr.config.ts Node runner (see package.json scripts).
+ * The main vitest.config.ts runs all other tests in a browser for DOM
+ * coverage; this file is the exception that runs in plain Node.
+ */
+
+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.animateText).toBe("function");
+    expect(typeof mod.splitText).toBe("function");
+    expect(typeof mod.applyProps).toBe("function");
+    expect(typeof mod.resolvePreset).toBe("function");
+  });
+
+  it("presets are plain-data and safe to access in Node", async () => {
+    const { fadeUp, listPresets, resolvePreset } = await import("../index.js");
+    const { HANDCURATED_NAMES } = await import("../presets/index.js");
+    expect(fadeUp.name).toBe("enter/fade-up");
+    expect(fadeUp.animations.length).toBeGreaterThan(0);
+    // Hand-curated catalog has the 14 starter entries; the registry
+    // returned by listPresets() may be larger if the Studio has
+    // ingested generated presets.
+    expect(HANDCURATED_NAMES).toHaveLength(14);
+    expect(listPresets().length).toBeGreaterThanOrEqual(14);
+    const emphasis = resolvePreset("emphasis/pulse");
+    expect(emphasis.animations[0]!.prop).toBe("scale");
+  });
+
+  it("splitText throws a readable error when called without DOM", async () => {
+    const { splitText } = await import("../index.js");
+    expect(() => splitText({} as unknown as HTMLElement)).toThrow(/browser environment/);
+  });
+
+  it("evaluateSpecs is pure and runs in Node", async () => {
+    const { evaluateSpecs } = await import("../index.js");
+    const v = evaluateSpecs([{ prop: "opacity", from: 0, to: 1, duration: 100 }], 50);
+    expect(v.opacity).toBeCloseTo(0.5, 3);
+  });
+});

package/src/__tests__/stagger.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { computeStaggerDelays } from "../stagger.js";
+
+describe("computeStaggerDelays", () => {
+  it("start order returns 0, g, 2g, ...", () => {
+    expect(computeStaggerDelays(4, 10, "start")).toEqual([0, 10, 20, 30]);
+  });
+
+  it("end order reverses start", () => {
+    expect(computeStaggerDelays(4, 10, "end")).toEqual([30, 20, 10, 0]);
+  });
+
+  it("center order grows outward from the center", () => {
+    const d = computeStaggerDelays(5, 10, "center");
+    // mid = 2 → ranks: |0-2|, |1-2|, |2-2|, |3-2|, |4-2| = 2,1,0,1,2
+    expect(d).toEqual([20, 10, 0, 10, 20]);
+  });
+
+  it("edges order is the inverse of center — fires outer first", () => {
+    const d = computeStaggerDelays(5, 10, "edges");
+    // ranks: mid - |i-mid| = 0,1,2,1,0
+    expect(d).toEqual([0, 10, 20, 10, 0]);
+  });
+
+  it("random order produces a permutation of [0..N-1] × stagger", () => {
+    const rng = makeRng(42);
+    const d = computeStaggerDelays(6, 10, "random", rng);
+    const sorted = [...d].sort((a, b) => a - b);
+    expect(sorted).toEqual([0, 10, 20, 30, 40, 50]);
+  });
+
+  it("returns all zeros when stagger is 0", () => {
+    expect(computeStaggerDelays(4, 0, "start")).toEqual([0, 0, 0, 0]);
+  });
+
+  it("returns [] for count 0", () => {
+    expect(computeStaggerDelays(0, 10, "start")).toEqual([]);
+  });
+});
+
+function makeRng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    return s / 0xffffffff;
+  };
+}

package/src/__tests__/types-check.ts

@@ -0,0 +1,80 @@
+import {
+  animateText,
+  evaluateSpecs,
+  listPresets,
+  resolvePreset,
+  splitText,
+  type AnimateTextHandle,
+  type AnimateTextOptions,
+  type HandcuratedPresetName,
+  type Preset,
+  type PresetName,
+  type Splits,
+  type TextAnimationSpec,
+} from "../index.js";
+import { power2Out } from "@vysmo/easings";
+
+// --- HandcuratedPresetName is a closed union (typos rejected) --------------
+
+const _h: HandcuratedPresetName = "enter/fade-up";
+void _h;
+
+// @ts-expect-error — typo is rejected against the closed union
+const _hBad: HandcuratedPresetName = "enter/fadeup";
+void _hBad;
+
+// --- PresetName is open (so the catalog can grow via generated entries) ----
+
+const _n: PresetName = "enter/fade-up";
+const _nGen: PresetName = "enter/some-generated-name";
+void [_n, _nGen];
+
+// --- listPresets / resolvePreset return the union and a full Preset --------
+
+const names = listPresets();
+const _names: PresetName[] = names;
+void _names;
+
+const p: Preset = resolvePreset("emphasis/shake");
+const _pname: PresetName = p.name;
+const _pstagger: number = p.stagger;
+const _panims: TextAnimationSpec[] = p.animations;
+void [_pname, _pstagger, _panims];
+
+// --- animateText options accept a preset OR raw animations -----------------
+
+declare const el: HTMLElement;
+
+const opt1: AnimateTextOptions = { preset: "enter/scale-in" };
+const opt2: AnimateTextOptions = {
+  animations: [{ prop: "opacity", from: 0, to: 1, duration: 300, ease: power2Out }],
+  stagger: 20,
+  staggerOrder: "center",
+};
+void [opt1, opt2];
+
+const handle: AnimateTextHandle = animateText(el, { preset: "enter/fade-up" });
+const _s: Splits = handle.splits;
+const _f: Promise<void> = handle.finished;
+void [_s, _f];
+
+// --- animateText rejects bogus props at compile time -----------------------
+
+animateText(el, {
+  animations: [
+    // @ts-expect-error — "wiggle" is not a TextProperty
+    { prop: "wiggle", from: 0, to: 1 },
+  ],
+});
+
+// --- splitText returns Splits with slices: HTMLElement[] -------------------
+
+const splits = splitText(el, { mode: "word" });
+const _slices: HTMLElement[] = splits.slices;
+void _slices;
+
+// --- evaluateSpecs runs purely on TextAnimationSpec[] ----------------------
+
+const v = evaluateSpecs(p.animations, 100);
+const _opacity: number | undefined = v.opacity;
+void _opacity;