@cube-drone/marquee-html-renderer 0.9.0 → 0.9.1

package/dist/effects.d.ts

@@ -0,0 +1,47 @@
+import type { Attrs, Node } from "@cube-drone/marquee-parser";
+/** The language-defined animated effects (SPEC.md, "Text effects"). */
+export declare const EFFECT_NAMES: ReadonlySet<string>;
+/** One animated unit: `[start, end)` in its text node's `value` (UTF-16
+ * offsets), and the `--mq-o` phase offset it wears. */
+export interface EffectUnit {
+    start: number;
+    end: number;
+    offset: string;
+}
+export interface EffectLook {
+    /** The container's classes: `mq-<name>`, plus `mq-split` when split. */
+    className: string;
+    /** Custom properties on the container (`--mq-speed`, `--mq-rate`, a
+     * reveal's step), in emission order. */
+    vars: [string, string][];
+    /** Data attributes on the container (a marquee's direction). */
+    data: [string, string][];
+    /** Per-unit animation, or null when the run animates as one piece (no
+     * `by=`, no units, or past the unit cap). Keyed by text node identity. */
+    units: Map<Node, EffectUnit[]> | null;
+    /** With units: the word groups - `[start, end)` value ranges, each a run
+     * of text between spaces that holds units - which must wrap as one. Units
+     * are inline-blocks (transforms need them to be), and a line may break on
+     * either side of every inline-block; a `white-space: nowrap` group puts
+     * the break opportunities back where the spaces are. */
+    groups: Map<Node, [number, number][]> | null;
+}
+/** How an effect span looks, or null if `name` isn't an effect. */
+export declare function effectLook(name: string, attrs: Attrs, children: Node[]): EffectLook | null;
+/** A text node, laid out for a split render: plain text that rides along,
+ * animated units, and word groups holding units (and the punctuation that
+ * clings to them) that must not wrap apart. */
+export type SplitPiece = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "unit";
+    text: string;
+    offset: string;
+} | {
+    kind: "group";
+    pieces: SplitPiece[];
+};
+export declare function splitPieces(node: Node & {
+    type: "text";
+}, look: EffectLook): SplitPiece[];

package/dist/effects.js

@@ -0,0 +1,252 @@
+// The effect vocabulary's look, as data: which classes, custom properties
+// and data attributes an effect span's container wears, and - for by=letter
+// / by=word - exactly which runs of which text nodes are animated units and
+// with what phase offset. The HTML renderer builds its markup from this, and
+// any other surface that draws effects (the live editor's in-place marks)
+// takes the same answer, so the two can't disagree about segmentation,
+// phase order, offsets, or caps.
+const TOKEN = /^[a-z][a-z0-9-]{0,31}$/;
+const COUNT = /^[0-9]{1,4}$/;
+/** The language-defined animated effects (SPEC.md, "Text effects"). */
+export const EFFECT_NAMES = new Set([
+    "marquee", "blink", "rainbow", "bounce", "jitter", "wave", "rubber", "typewriter", "fadein",
+]);
+/** How an effect span looks, or null if `name` isn't an effect. */
+export function effectLook(name, attrs, children) {
+    if (!EFFECT_NAMES.has(name)) {
+        return null;
+    }
+    const look = { className: `mq-${name}`, vars: [], data: [], units: null, groups: null };
+    const by = attrs["by"] === "letter" || attrs["by"] === "word" ? attrs["by"] : null;
+    let splitBy = null;
+    switch (name) {
+        case "marquee":
+            if (TOKEN.test(attrs["direction"] ?? "")) {
+                look.data.push(["direction", attrs["direction"]]);
+            }
+            if (COUNT.test(attrs["speed"] ?? "")) {
+                look.vars.push(["--mq-speed", attrs["speed"]]);
+            }
+            return look;
+        case "blink":
+            // Split blink: ramp is theater-marquee chase lights, scatter is
+            // twinkle. The rate rides the container; units inherit it.
+            if (COUNT.test(attrs["rate"] ?? "")) {
+                look.vars.push(["--mq-rate", attrs["rate"]]);
+            }
+            splitBy = by;
+            break;
+        case "typewriter":
+            // Inherently per-unit: the reveal IS a by=letter effect (by=word for
+            // word-at-a-time). speed= is units per second; the container carries
+            // the per-unit delay step, each unit its ordinal in --mq-o.
+            splitBy = by === "word" ? "word" : "letter";
+            look.vars.push(["--mq-tw-step", `${revealStep(attrs["speed"], 14)}s`]);
+            break;
+        case "fadein":
+            // Bare [fadein] fades the whole run in once; by= drifts units in on
+            // staggered starts (the same one-shot family as typewriter).
+            if (by !== null) {
+                splitBy = by;
+                look.vars.push(["--mq-fi-step", `${revealStep(attrs["speed"], 16)}s`]);
+            }
+            break;
+        default: // rainbow, bounce, jitter, wave, rubber
+            splitBy = by;
+    }
+    if (splitBy === null) {
+        return look;
+    }
+    const units = splitUnits(name, splitBy, attrs["phase"], children);
+    if (units === null) {
+        // Past the cap (or nothing to split): the run animates whole, and the
+        // split's container knobs go with the split.
+        look.vars = [];
+        return look;
+    }
+    look.className += " mq-split";
+    look.units = units;
+    look.groups = wordGroups(units);
+    return look;
+}
+export function splitPieces(node, look) {
+    const units = look.units?.get(node) ?? [];
+    const groups = look.groups?.get(node) ?? [];
+    const lay = (from, to) => {
+        const out = [];
+        let at = from;
+        for (const u of units) {
+            if (u.start < from || u.end > to)
+                continue;
+            if (u.start > at)
+                out.push({ kind: "text", text: node.value.slice(at, u.start) });
+            out.push({ kind: "unit", text: node.value.slice(u.start, u.end), offset: u.offset });
+            at = u.end;
+        }
+        if (to > at)
+            out.push({ kind: "text", text: node.value.slice(at, to) });
+        return out;
+    };
+    const out = [];
+    let at = 0;
+    for (const [start, end] of groups) {
+        out.push(...lay(at, start), { kind: "group", pieces: lay(start, end) });
+        at = end;
+    }
+    out.push(...lay(at, node.value.length));
+    return out;
+}
+/** Scripts written without spaces between words wrap between characters,
+ * so their runs are never grouped (a whole sentence would become one
+ * unbreakable word): Han, kana, fullwidth forms, Thai, Lao, Khmer, Myanmar. */
+const SPACELESS = /[\u0E00-\u0EFF\u1000-\u109F\u1780-\u17FF\u2E80-\u9FFF\uF900-\uFAFF\uFF00-\uFFEF\u{20000}-\u{3FFFF}]/u;
+function wordGroups(units) {
+    const out = new Map();
+    for (const [node, list] of units) {
+        if (node.type !== "text")
+            continue;
+        const groups = [];
+        for (const m of node.value.matchAll(/\S+/g)) {
+            const start = m.index;
+            const end = start + m[0].length;
+            const inside = list.filter((u) => u.start >= start && u.end <= end);
+            // Nothing to hold together: no units, a spaceless script, or a run
+            // that is exactly one unit (already a single inline-block).
+            if (inside.length === 0 || SPACELESS.test(m[0]))
+                continue;
+            if (inside.length === 1 && inside[0].start === start && inside[0].end === end)
+                continue;
+            groups.push([start, end]);
+        }
+        out.set(node, groups);
+    }
+    return out;
+}
+// -- per-unit effects (by=letter / by=word): each unit carries a phase
+// offset in --mq-o; the stylesheet replays the effect's keyframes through a
+// negative animation-delay. Locale pinned so segmentation (and thus output)
+// is stable.
+const SEGMENTERS = {
+    letter: new Intl.Segmenter("en", { granularity: "grapheme" }),
+    word: new Intl.Segmenter("en", { granularity: "word" }),
+};
+/** DOM-weight discipline: past this many units, the run animates whole.
+ * Loopers pay a live animation per element forever, so they cap low;
+ * typewriter's units are 1ms one-shots (finished animations cost nothing)
+ * and its natural material is long text, so it caps high. */
+const MAX_SPLIT_UNITS = 400;
+const MAX_REVEAL_UNITS = 2000;
+function splitUnits(effect, by, phaseAttr, children) {
+    // Each effect has a natural phase order (jitter scatters, the rest sweep);
+    // the knob overrides it either way. Invalid values degrade to the default.
+    const phase = phaseAttr === "scatter" || phaseAttr === "ramp" ? phaseAttr : effect === "jitter" ? "scatter" : "ramp";
+    const total = countUnits(children, by);
+    const cap = isReveal(effect) ? MAX_REVEAL_UNITS : MAX_SPLIT_UNITS;
+    if (total === 0 || total > cap) {
+        return null;
+    }
+    const state = { effect, by, phase, i: 0, total };
+    const units = new Map();
+    collectUnits(children, state, units);
+    return units;
+}
+/** The nodes a split descends into: text, through emphasis/strong/strike.
+ * Anything else (a link, an emoji, a nested span) renders whole, un-split. */
+function collectUnits(nodes, state, out) {
+    for (const node of nodes) {
+        if (node.type === "text") {
+            const list = [];
+            for (const seg of SEGMENTERS[state.by].segment(node.value)) {
+                if (isUnit(seg, state.by)) {
+                    list.push({ start: seg.index, end: seg.index + seg.segment.length, offset: unitOffset(state) });
+                    state.i += 1;
+                }
+            }
+            out.set(node, list);
+        }
+        else if (node.type === "emphasis" || node.type === "strong" || node.type === "strikethrough") {
+            collectUnits(node.children, state, out);
+        }
+    }
+}
+function countUnits(nodes, by) {
+    let n = 0;
+    for (const node of nodes) {
+        if (node.type === "text") {
+            for (const seg of SEGMENTERS[by].segment(node.value)) {
+                if (isUnit(seg, by)) {
+                    n += 1;
+                }
+            }
+        }
+        else if (node.type === "emphasis" || node.type === "strong" || node.type === "strikethrough") {
+            n += countUnits(node.children, by);
+        }
+    }
+    return n;
+}
+/** A segment gets wrapped if it's animatable: for words, word-like segments
+ * (spaces and bare punctuation ride along); for letters, anything that
+ * isn't whitespace. */
+function isUnit(seg, by) {
+    return by === "word" ? seg.isWordLike === true : !/^\s+$/.test(seg.segment);
+}
+/** Offsets are deterministic (goldens exist; a document renders the same
+ * twice) in both phase orders: ramp sweeps, scatter scrambles by a fixed
+ * integer hash - randomness-shaped, never random. */
+function unitOffset(state) {
+    // Reveal offsets (typewriter, fadein) are sequential INTEGERS (the
+    // ordinal; delay = ordinal x step), unlike the cyclic 0..1 fractions the
+    // looping effects replay. phase=scatter reveals in a
+    // scrambled-but-deterministic order: a stride at the run's golden-ratio
+    // point, nudged coprime with the total, walks a well-spread permutation
+    // at EVERY length. (A fixed prime stride is a trap: 7919 mod 40 = 39 =
+    // -1, so forty-unit runs typed in backwards.)
+    if (isReveal(state.effect)) {
+        const o = state.phase === "scatter" ? (state.i * scatterStride(state.total)) % state.total : state.i;
+        return String(o);
+    }
+    let o;
+    if (state.phase === "scatter") {
+        o = ((state.i * 7919) % 101) / 101;
+    }
+    else {
+        switch (state.effect) {
+            case "rainbow":
+                o = state.i / state.total; // gradient across the whole run
+                break;
+            case "wave":
+                o = (state.i % 8) / 8; // fixed ripple wavelength
+                break;
+            case "bounce":
+                o = (state.i % 6) / 6;
+                break;
+            default:
+                o = (state.i % 8) / 8; // jitter in ramp mode: a rippling shudder
+                break;
+        }
+    }
+    return String(Math.round(o * 1000) / 1000);
+}
+/** speed= (units per second, a COUNT) into a per-unit delay step in
+ * seconds; invalid or absent falls to the effect's default rate. */
+function revealStep(speedAttr, dflt) {
+    const speed = speedAttr !== undefined && COUNT.test(speedAttr) && Number(speedAttr) > 0 ? Number(speedAttr) : dflt;
+    return Math.round(1000 / speed) / 1000;
+}
+/** The one-shot reveals: sequential ordinals, the high unit cap. */
+function isReveal(effect) {
+    return effect === "typewriter" || effect === "fadein";
+}
+function gcd(a, b) {
+    return b === 0 ? a : gcd(b, a % b);
+}
+/** The smallest stride >= ~61.8% of total that's coprime with it (falls
+ * back to 1 for degenerate totals - a 1- or 2-unit "scramble" is fate). */
+function scatterStride(total) {
+    let stride = Math.max(1, Math.round(total * 0.618));
+    while (stride < total && gcd(stride, total) !== 1) {
+        stride += 1;
+    }
+    return gcd(stride, total) === 1 ? stride : 1;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { Profile } from "./profile.ts";
 export { render, escapeText, escapeAttr, FONTS, usedFontTokens, containerLook } from "./render.ts";
 export { bareWebProfile } from "./profile.ts";
+export { EFFECT_NAMES, effectLook, splitPieces, type EffectLook, type EffectUnit, type SplitPiece } from "./effects.ts";
 export type { EmojiResolution, Profile, MediaResolution, TurbolinkLevel } from "./profile.ts";
 /** Parse and render in one step. Throws UnsupportedVersionError for unknown
  * dialect versions, exactly as the parser does. */

package/dist/index.js

@@ -8,6 +8,7 @@ import { parse } from "@cube-drone/marquee-parser";
 import { render } from "./render.js";
 export { render, escapeText, escapeAttr, FONTS, usedFontTokens, containerLook } from "./render.js";
 export { bareWebProfile } from "./profile.js";
+export { EFFECT_NAMES, effectLook, splitPieces } from "./effects.js";
 /** Parse and render in one step. Throws UnsupportedVersionError for unknown
  * dialect versions, exactly as the parser does. */
 export function renderMarquee(source, profile) {