@vysmo/text 0.1.0

package/src/presets/index.ts

@@ -0,0 +1,62 @@
+import type { Preset, PresetName } from "../types.js";
+import { blurIn, depthZoom, elasticRise, fadeUp, flipX, scaleIn } from "./enter.js";
+import { fadeDown, flipAway, scaleOut } from "./exit.js";
+import { coinFlip, pulse, shake, spin, wobble } from "./emphasis.js";
+import { ALL_GENERATED } from "./generated.js";
+
+const HANDCURATED: Record<string, Preset> = {
+  "enter/fade-up": fadeUp,
+  "enter/elastic-rise": elasticRise,
+  "enter/blur-in": blurIn,
+  "enter/scale-in": scaleIn,
+  "enter/flip-x": flipX,
+  "enter/depth-zoom": depthZoom,
+  "exit/fade-down": fadeDown,
+  "exit/scale-out": scaleOut,
+  "exit/flip-away": flipAway,
+  "emphasis/pulse": pulse,
+  "emphasis/shake": shake,
+  "emphasis/wobble": wobble,
+  "emphasis/coin-flip": coinFlip,
+  "emphasis/spin": spin,
+};
+
+// Merge handcurated + generated into a single runtime registry. Generated
+// entries don't shadow handcurated ones — the catalog grows by addition.
+const PRESETS: Record<string, Preset> = { ...HANDCURATED };
+for (const { name, preset } of ALL_GENERATED) PRESETS[name] = preset;
+
+/**
+ * The hand-curated seed catalog, keyed by the closed
+ * `HandcuratedPresetName` literal union. Useful for tests + tooling
+ * that want to assert against the seed set without picking up
+ * generated entries (which grow dynamically via `ALL_GENERATED`).
+ */
+export const HANDCURATED_NAMES: readonly string[] = Object.keys(HANDCURATED);
+
+export function resolvePreset(name: PresetName): Preset {
+  const p = PRESETS[name];
+  if (!p) throw new Error(`@vysmo/text: unknown preset "${name}"`);
+  return p;
+}
+
+export function listPresets(): PresetName[] {
+  return Object.keys(PRESETS) as PresetName[];
+}
+
+export {
+  fadeUp,
+  elasticRise,
+  blurIn,
+  scaleIn,
+  flipX,
+  depthZoom,
+  fadeDown,
+  scaleOut,
+  flipAway,
+  pulse,
+  shake,
+  wobble,
+  coinFlip,
+  spin,
+};

package/src/properties.ts

@@ -0,0 +1,78 @@
+import type { TextProperty } from "./types.js";
+
+export type PropValues = Partial<Record<TextProperty, number>>;
+
+const TRANSFORM_PROPS: ReadonlyArray<TextProperty> = [
+  "translateX",
+  "translateY",
+  "translateZ",
+  "rotate",
+  "rotateX",
+  "rotateY",
+  "rotateZ",
+  "scale",
+  "scaleX",
+  "scaleY",
+  "skewX",
+  "skewY",
+];
+
+const FILTER_PROPS: ReadonlyArray<TextProperty> = [
+  "blur",
+  "brightness",
+  "contrast",
+  "saturate",
+  "hueRotate",
+];
+
+/**
+ * Compose numeric per-axis values into the CSS strings the browser wants.
+ * `transform` and `filter` are each composed as a single declaration so
+ * successive writes don't leak stale parts from previous frames.
+ */
+export function applyProps(el: HTMLElement, vals: PropValues): void {
+  if (vals.opacity !== undefined) {
+    el.style.opacity = String(vals.opacity);
+  }
+
+  const hasTransform = TRANSFORM_PROPS.some((p) => vals[p] !== undefined);
+  if (hasTransform) {
+    const parts: string[] = [];
+    if (
+      vals.translateX !== undefined ||
+      vals.translateY !== undefined ||
+      vals.translateZ !== undefined
+    ) {
+      parts.push(
+        `translate3d(${vals.translateX ?? 0}px, ${vals.translateY ?? 0}px, ${vals.translateZ ?? 0}px)`,
+      );
+    }
+    if (vals.rotate !== undefined) parts.push(`rotate(${vals.rotate}deg)`);
+    if (vals.rotateX !== undefined) parts.push(`rotateX(${vals.rotateX}deg)`);
+    if (vals.rotateY !== undefined) parts.push(`rotateY(${vals.rotateY}deg)`);
+    if (vals.rotateZ !== undefined) parts.push(`rotateZ(${vals.rotateZ}deg)`);
+    if (vals.scale !== undefined) parts.push(`scale(${vals.scale})`);
+    if (vals.scaleX !== undefined) parts.push(`scaleX(${vals.scaleX})`);
+    if (vals.scaleY !== undefined) parts.push(`scaleY(${vals.scaleY})`);
+    if (vals.skewX !== undefined) parts.push(`skewX(${vals.skewX}deg)`);
+    if (vals.skewY !== undefined) parts.push(`skewY(${vals.skewY}deg)`);
+    el.style.transform = parts.join(" ");
+  }
+
+  const hasFilter = FILTER_PROPS.some((p) => vals[p] !== undefined);
+  if (hasFilter) {
+    const parts: string[] = [];
+    if (vals.blur !== undefined) parts.push(`blur(${vals.blur}px)`);
+    if (vals.brightness !== undefined) parts.push(`brightness(${vals.brightness})`);
+    if (vals.contrast !== undefined) parts.push(`contrast(${vals.contrast})`);
+    if (vals.saturate !== undefined) parts.push(`saturate(${vals.saturate})`);
+    if (vals.hueRotate !== undefined) parts.push(`hue-rotate(${vals.hueRotate}deg)`);
+    el.style.filter = parts.join(" ");
+  }
+}
+
+export function clearProps(el: HTMLElement): void {
+  el.style.removeProperty("opacity");
+  el.style.removeProperty("transform");
+  el.style.removeProperty("filter");
+}

package/src/split.ts

@@ -0,0 +1,180 @@
+import type { SplitMode, SplitOptions, Splits } from "./types.js";
+
+const WHITESPACE_ONLY = /^\s+$/;
+
+function hasSegmenter(): boolean {
+  return typeof Intl !== "undefined" && typeof Intl.Segmenter === "function";
+}
+
+function graphemeSegments(text: string, locale: string | undefined): string[] {
+  if (hasSegmenter()) {
+    const seg = new Intl.Segmenter(locale, { granularity: "grapheme" });
+    return Array.from(seg.segment(text), (s) => s.segment);
+  }
+  return Array.from(text);
+}
+
+function wordSegments(
+  text: string,
+  locale: string | undefined,
+): Array<{ segment: string; isWordLike: boolean }> {
+  if (hasSegmenter()) {
+    const seg = new Intl.Segmenter(locale, { granularity: "word" });
+    return Array.from(seg.segment(text), (s) => ({
+      segment: s.segment,
+      isWordLike: s.isWordLike ?? false,
+    }));
+  }
+  const parts = text.split(/(\s+)/).filter((s) => s.length > 0);
+  return parts.map((segment) => ({
+    segment,
+    isWordLike: !WHITESPACE_ONLY.test(segment),
+  }));
+}
+
+function makeSliceSpan(text: string, kind: SplitMode): HTMLElement {
+  const span = document.createElement("span");
+  span.textContent = text;
+  span.style.display = "inline-block";
+  span.style.willChange = "transform, opacity, filter";
+  span.setAttribute("data-text-slice", kind);
+  span.setAttribute("aria-hidden", "true");
+  return span;
+}
+
+function appendScreenReaderCopy(element: HTMLElement, text: string): void {
+  const sr = document.createElement("span");
+  sr.textContent = text;
+  sr.setAttribute("data-text-sr", "");
+  const s = sr.style;
+  s.position = "absolute";
+  s.width = "1px";
+  s.height = "1px";
+  s.padding = "0";
+  s.margin = "-1px";
+  s.overflow = "hidden";
+  s.clip = "rect(0, 0, 0, 0)";
+  s.whiteSpace = "nowrap";
+  s.border = "0";
+  element.appendChild(sr);
+}
+
+/**
+ * Split an element's text into per-slice spans suitable for independent
+ * transform/filter/opacity animation. Grapheme-safe via `Intl.Segmenter`
+ * when available (falls back to `Array.from(text)` for character mode and
+ * a whitespace-preserving regex for word mode).
+ *
+ * Line mode requires the element to be in the DOM and laid out — line
+ * boundaries are detected via `getBoundingClientRect().top` after words
+ * have been inserted.
+ *
+ * Script compatibility:
+ * - LTR and RTL (Arabic, Hebrew): word and line modes work correctly; the
+ *   browser's bidi algorithm places inline-block siblings in visual order.
+ * - Connected / contextually-shaped scripts (Arabic, Devanagari, Lao,
+ *   Khmer, …): character mode breaks shaping because each grapheme lands
+ *   in its own inline-block box, preventing letters from joining. Prefer
+ *   word or line mode for these scripts.
+ */
+export function splitText(element: HTMLElement, options: SplitOptions = {}): Splits {
+  if (typeof document === "undefined") {
+    throw new Error("splitText: requires a browser environment");
+  }
+
+  const mode: SplitMode = options.mode ?? "character";
+  const original = element.textContent ?? "";
+
+  element.textContent = "";
+  appendScreenReaderCopy(element, original);
+
+  const slices: HTMLElement[] = [];
+
+  if (mode === "character") {
+    for (const g of graphemeSegments(original, options.locale)) {
+      if (WHITESPACE_ONLY.test(g)) {
+        element.appendChild(document.createTextNode(g));
+      } else {
+        const span = makeSliceSpan(g, "character");
+        element.appendChild(span);
+        slices.push(span);
+      }
+    }
+  } else if (mode === "word") {
+    // Wrap every non-whitespace segment (words AND punctuation) so nothing
+    // is left behind at opacity 0 / blur. Intl.Segmenter's word granularity
+    // classifies commas/exclamations/etc as `isWordLike: false`; relying on
+    // that would leave punctuation unanimated while its neighbours faded.
+    for (const { segment } of wordSegments(original, options.locale)) {
+      if (WHITESPACE_ONLY.test(segment)) {
+        element.appendChild(document.createTextNode(segment));
+      } else {
+        const span = makeSliceSpan(segment, "word");
+        element.appendChild(span);
+        slices.push(span);
+      }
+    }
+  } else {
+    // Line mode: insert temporary word spans, measure, wrap each visual
+    // line into a single line span, then demote inner word spans back to
+    // plain text so only the line span carries animatable style.
+    const tempWords: HTMLElement[] = [];
+    for (const { segment } of wordSegments(original, options.locale)) {
+      if (WHITESPACE_ONLY.test(segment)) {
+        element.appendChild(document.createTextNode(segment));
+      } else {
+        const span = makeSliceSpan(segment, "word");
+        element.appendChild(span);
+        tempWords.push(span);
+      }
+    }
+
+    const groups: HTMLElement[][] = [];
+    let currentTop: number | null = null;
+    let currentGroup: HTMLElement[] = [];
+    for (const span of tempWords) {
+      const top = Math.round(span.getBoundingClientRect().top);
+      if (currentTop === null || Math.abs(top - currentTop) > 1) {
+        if (currentGroup.length > 0) groups.push(currentGroup);
+        currentGroup = [];
+        currentTop = top;
+      }
+      currentGroup.push(span);
+    }
+    if (currentGroup.length > 0) groups.push(currentGroup);
+
+    for (const group of groups) {
+      const firstWord = group[0]!;
+      const lastWord = group[group.length - 1]!;
+      const lineWrap = makeSliceSpan("", "line");
+      lineWrap.textContent = "";
+      firstWord.parentNode!.insertBefore(lineWrap, firstWord);
+      let node: ChildNode | null = firstWord;
+      while (node) {
+        const next: ChildNode | null = node.nextSibling;
+        lineWrap.appendChild(node);
+        if (node === lastWord) break;
+        node = next;
+      }
+      // Demote inner word spans to plain text — only the line span animates.
+      for (const word of group) {
+        word.replaceWith(document.createTextNode(word.textContent ?? ""));
+      }
+      slices.push(lineWrap);
+    }
+  }
+
+  let restored = false;
+  const splits: Splits = {
+    slices,
+    mode,
+    original,
+    restore() {
+      if (restored) return;
+      restored = true;
+      element.textContent = original;
+    },
+  };
+
+  return splits;
+}

package/src/stagger.ts

@@ -0,0 +1,55 @@
+import type { StaggerOrder } from "./types.js";
+
+/**
+ * Given N slices, a per-step gap, and an order strategy, return the
+ * start-delay (in ms) to apply to each slice — index-aligned.
+ *
+ * - "start":  0, 1g, 2g, 3g, …
+ * - "end":    reversed
+ * - "center": grows outward from the center index
+ * - "edges":  grows inward from the edges toward the center
+ * - "random": a uniform random permutation of the above ranks
+ */
+export function computeStaggerDelays(
+  count: number,
+  stagger: number,
+  order: StaggerOrder,
+  rng: () => number = Math.random,
+): number[] {
+  if (count <= 0) return [];
+  if (stagger <= 0) return new Array<number>(count).fill(0);
+
+  const ranks = new Array<number>(count);
+
+  switch (order) {
+    case "start":
+      for (let i = 0; i < count; i++) ranks[i] = i;
+      break;
+    case "end":
+      for (let i = 0; i < count; i++) ranks[i] = count - 1 - i;
+      break;
+    case "center": {
+      const mid = (count - 1) / 2;
+      for (let i = 0; i < count; i++) ranks[i] = Math.round(Math.abs(i - mid));
+      break;
+    }
+    case "edges": {
+      const mid = (count - 1) / 2;
+      for (let i = 0; i < count; i++) ranks[i] = Math.round(mid - Math.abs(i - mid));
+      break;
+    }
+    case "random": {
+      const perm = Array.from({ length: count }, (_, i) => i);
+      for (let i = perm.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        const tmp = perm[i]!;
+        perm[i] = perm[j]!;
+        perm[j] = tmp;
+      }
+      for (let rank = 0; rank < count; rank++) ranks[perm[rank]!] = rank;
+      break;
+    }
+  }
+
+  return ranks.map((r) => r * stagger);
+}

package/src/types.ts

@@ -0,0 +1,245 @@
+import type { EasingFn } from "@vysmo/easings";
+import type { Scheduler } from "@vysmo/animations";
+
+export type SplitMode = "character" | "word" | "line";
+
+export type SplitOptions = {
+  /** Granularity of the split. Default "character". */
+  mode?: SplitMode;
+  /** BCP-47 locale for Intl.Segmenter. Falls back to the environment default. */
+  locale?: string;
+};
+
+export type Splits = {
+  /** Slice elements in document order (characters, words, or lines). */
+  readonly slices: HTMLElement[];
+  /** The split granularity. */
+  readonly mode: SplitMode;
+  /** The original text captured before the split. */
+  readonly original: string;
+  /** Restore the element's original text. Idempotent. */
+  restore(): void;
+};
+
+/**
+ * The animatable axes understood by animateText. Numeric-only by design — the
+ * runtime composes these into `transform` / `filter` / `opacity` strings per
+ * frame, so shape mismatches are impossible and per-slice blending stays cheap.
+ */
+export type TextProperty =
+  | "opacity"
+  | "translateX"
+  | "translateY"
+  | "translateZ"
+  | "scale"
+  | "scaleX"
+  | "scaleY"
+  | "rotate"
+  | "rotateX"
+  | "rotateY"
+  | "rotateZ"
+  | "skewX"
+  | "skewY"
+  | "blur"
+  | "brightness"
+  | "contrast"
+  | "saturate"
+  | "hueRotate";
+
+/**
+ * A scalar or a uniform range. Range values resolve **per slice** at
+ * animate-start: every slice samples its own value, so animations like
+ * "letters scatter from random offsets and converge on 0" become a
+ * one-line spec change. `{ min: x, max: x }` resolves to the constant
+ * `x` without consuming an rng draw.
+ */
+export type TextValue = number | { min: number; max: number };
+
+/**
+ * Transform-origin in normalized form. `x`/`y` are fractions (0..1, where
+ * 0 is left/top and 1 is right/bottom — `{ x: 0.5, y: 1 }` = bottom
+ * center). Optional `z` is in pixels and lets 3D transforms pivot in
+ * front of / behind the slice. Stored as data instead of a CSS string so
+ * the same preset can drive a future canvas/Skia runtime without parsing.
+ */
+export type TransformOrigin = {
+  x: number;
+  y: number;
+  z?: number;
+};
+
+export type TextAnimationSpec = {
+  prop: TextProperty;
+  from: TextValue;
+  to: TextValue;
+  /** Duration in milliseconds. Default 600. */
+  duration?: number;
+  /**
+   * Delay (ms) from the slice's stagger offset before this spec begins.
+   * Sequential specs targeting the same prop chain via their delays.
+   */
+  delay?: number;
+  /**
+   * Easing for this spec. Default linear.
+   *
+   * Two forms accepted:
+   * - **String** (preferred for catalog presets) — a GSAP-style spec like
+   *   `"power2.out"`, `"back.out(2)"`, `"elastic.out(1.2, 0.4)"`,
+   *   `"cubic-bezier(0.42, 0, 0.58, 1)"`. Resolved at animate-start via
+   *   `parseEasing()` from `@vysmo/easings`. Strings are JSON-serializable
+   *   so the same preset data can drive a future canvas/Skia runtime
+   *   without losing fidelity.
+   * - **Function** — any `EasingFn`/`(t: number) => number`. Use this when
+   *   you bring a custom curve that isn't in the catalog.
+   */
+  ease?: string | EasingFn | ((t: number) => number);
+  /**
+   * Override the root stagger for this spec only. Enables a per-prop cadence
+   * — e.g. translateY staggered at 30ms while opacity staggers at 10ms —
+   * which is the main knob the authoring studio uses to explore variety.
+   */
+  stagger?: number;
+  /** Override the root staggerOrder for this spec only. */
+  staggerOrder?: StaggerOrder;
+  /**
+   * Per-slice random delay in ms added on top of the slice's stagger
+   * offset. Each slice gets its own value uniformly sampled from
+   * `[0, jitterDelay]` at animate-start. Default 0. Useful for breaking
+   * the "metronome" feel of pure stagger by spraying start times.
+   */
+  jitterDelay?: number;
+  /**
+   * Override the preset / option-level `transformOrigin` for the
+   * duration of this spec. Written to each slice's inline style at the
+   * moment the spec's window opens for that slice; persists until the
+   * next override on the same slice (or `stop()`). When two specs with
+   * different origins overlap on a slice, the most recently-opened
+   * spec wins (last-write-wins).
+   */
+  transformOrigin?: TransformOrigin;
+  /**
+   * Override the container `perspective` (in px) for the duration of
+   * this spec. Written to the container element when the spec's window
+   * first opens for any slice; persists until the next override (or
+   * `stop()`). Container-scoped, so it affects every slice — same
+   * scope as the option / preset-level `perspective`.
+   */
+  perspective?: number;
+};
+
+export type StaggerOrder = "start" | "end" | "center" | "edges" | "random";
+
+export type AnimateTextOptions = {
+  /** Split granularity. Overridden by the preset's split when unset. Default "character". */
+  split?: SplitMode;
+  /** BCP-47 locale for Intl.Segmenter. */
+  locale?: string;
+  /** Milliseconds between consecutive slices starting to animate. Default 30. */
+  stagger?: number;
+  /** Order in which slices receive their stagger offset. Default "start". */
+  staggerOrder?: StaggerOrder;
+  /** One or more animated properties running in parallel per slice. */
+  animations?: TextAnimationSpec[];
+  /**
+   * Preset to apply. Accepts either the catalog name (convenience, pulls
+   * the whole registry) or a `Preset` object reference (tree-shakable —
+   * the unused 14/15/… presets stay out of the bundle).
+   */
+  preset?: PresetName | Preset;
+  /**
+   * CSS perspective (px) applied to the container so children's rotateX /
+   * rotateY / translateZ render with depth. Required for 3D transforms to
+   * look 3D — without it, rotateY(90deg) is just a 1px-wide line.
+   */
+  perspective?: number;
+  /** CSS perspective-origin string applied to the container (e.g., "50% 30%"). */
+  perspectiveOrigin?: string;
+  /** Transform-origin applied to every slice. `{ x: 0.5, y: 0 }` = top center. */
+  transformOrigin?: TransformOrigin;
+  /** Begin playing automatically. Default true. */
+  autoPlay?: boolean;
+  /** When true, skip animation under prefers-reduced-motion. Default true. */
+  respectReducedMotion?: boolean;
+  /**
+   * Delay in ms before the first play begins. Useful for sequencing an
+   * entry after some other animation completes.
+   */
+  delay?: number;
+  /**
+   * How many times the whole choreography plays. `1` (default) = play
+   * once. A number > 1 = that many cycles. `"infinite"` = loop forever
+   * (or until `.stop()`). Emphasis presets like pulse typically want
+   * `repeat: 3, repeatDelay: 400` for a "triple-tap" feel.
+   */
+  repeat?: number | "infinite";
+  /** Delay between successive cycles when `repeat > 1`. Default 0. */
+  repeatDelay?: number;
+  /** Override the time source for deterministic playback in tests. */
+  scheduler?: Scheduler;
+  /** Deterministic RNG for "random" stagger order. Defaults to Math.random. */
+  rng?: () => number;
+};
+
+export type AnimateTextHandle = {
+  /** Start or resume playback. */
+  play(): AnimateTextHandle;
+  /** Pause playback, preserving progress. */
+  pause(): AnimateTextHandle;
+  /** Stop playback and reset slices to their un-animated style. */
+  stop(): AnimateTextHandle;
+  /** Jump every slice to the given progress in [0, 1]. */
+  seek(progress: number): AnimateTextHandle;
+  /** Resolves when every slice has finished naturally. */
+  readonly finished: Promise<void>;
+  /** The split result backing this animation. */
+  readonly splits: Splits;
+};
+
+export type Preset = {
+  name: PresetName;
+  /** Split granularity this preset was tuned against. */
+  split?: SplitMode;
+  /** Default stagger; callers can override. */
+  stagger: number;
+  /** Stagger order this preset was tuned against. */
+  staggerOrder?: StaggerOrder;
+  animations: TextAnimationSpec[];
+  /** Container perspective (px) required for this preset's 3D transforms. */
+  perspective?: number;
+  /** Slice-level transform-origin this preset was tuned against. */
+  transformOrigin?: TransformOrigin;
+  /** Default play count for this preset (e.g. emphasis/pulse repeating 3×). */
+  repeat?: number | "infinite";
+  /** Default gap between cycles in ms. */
+  repeatDelay?: number;
+};
+
+/**
+ * Hand-curated preset names — the seed catalog. These autocomplete in
+ * IDEs and stay typed in tests / consumer code.
+ */
+export type HandcuratedPresetName =
+  | "enter/fade-up"
+  | "enter/elastic-rise"
+  | "enter/blur-in"
+  | "enter/scale-in"
+  | "enter/flip-x"
+  | "enter/depth-zoom"
+  | "exit/fade-down"
+  | "exit/scale-out"
+  | "exit/flip-away"
+  | "emphasis/pulse"
+  | "emphasis/shake"
+  | "emphasis/wobble"
+  | "emphasis/coin-flip"
+  | "emphasis/spin";
+
+/**
+ * Any registered preset name — handcurated entries autocomplete via the
+ * literal union; the `string & {}` branch keeps the type open for the
+ * generated catalog (300+ entries authored via the Studio's random
+ * generator). Lookup at runtime is a string key against `PRESETS`, so
+ * unknown names throw at `resolvePreset` rather than at the type
+ * boundary.
+ */
+export type PresetName = HandcuratedPresetName | (string & {});