@vectoriox/iox-ui 5.71.1 → 5.72.0

package/src/scene-core/split-text.ts

@@ -0,0 +1,187 @@
+/**
+ * Text into pieces, in the browser only (premium sites SC3, Motion v2 §3c). A saved node keeps its plain text and the
+ * server sends it whole, so every word is in the raw response, editing never meets a piece, and there is no markup for
+ * hydration to disagree with. Each original text node is kept and put back as it was, never rebuilt from a string: a
+ * framework may hold that node, and a layer may hold live components.
+ */
+
+export enum TextRevealBy {
+    Line = 'line',
+    Word = 'word',
+}
+
+/** Past these a text is plainly no heading: it fades whole, and lights up whole. */
+export const REVEAL_PIECE_CAP = 120;
+export const LIGHT_UP_PIECE_CAP = 300;
+
+const SKIPPED_TAGS: ReadonlySet<string> = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'SELECT', 'OPTION']);
+const SHOW_TEXT = 4;
+/** Hebrew through Arabic Extended, and their presentation forms. */
+const RTL_LETTER = /[֐-ࣿיִ-﷿ﹰ-]/;
+
+export interface TextPiece {
+    text: string;
+    /** False for the space between two words, which stays bare text so lines wrap exactly as they did. */
+    word: boolean;
+}
+
+/**
+ * A string as words and the space between them. With `keepLtrRuns` a run of words holding no RTL letter stays ONE word:
+ * an inline-block is neutral to the bidi algorithm, so "Studio Alma" inside a Hebrew heading, split, would read reversed.
+ */
+export function textPieces(text: string, keepLtrRuns = false): TextPiece[] {
+    const pieces: TextPiece[] = (text.match(/\s+|\S+/g) ?? []).map(part => ({ text: part, word: /\S/.test(part) }));
+    if (!keepLtrRuns) return pieces;
+    const merged: TextPiece[] = [];
+    for (const piece of pieces) {
+        const space = merged[merged.length - 1];
+        const word = merged[merged.length - 2];
+        if (piece.word && !RTL_LETTER.test(piece.text) && space && !space.word && word?.word && !RTL_LETTER.test(word.text)) {
+            word.text += space.text + piece.text;
+            merged.pop();
+        } else {
+            merged.push({ ...piece });
+        }
+    }
+    return merged;
+}
+
+export interface SplitTextOptions {
+    cap: number;
+    /** Each piece in a clipping mask, to rise out of (and so an inline-block). Without it a piece is a plain inline span. */
+    mask?: boolean;
+    /** The element reads right-to-left. Only a mask needs to know. */
+    rtl?: boolean;
+}
+
+export interface SplitText {
+    /** In reading order. With a mask, the moving part inside it. */
+    pieces: HTMLElement[];
+    /** Put every original text node back. Safe after the text was replaced: what is gone stays gone. */
+    restore(): void;
+}
+
+interface Replacement {
+    original: Text;
+    nodes: Node[];
+}
+
+function textNodesOf(root: HTMLElement): Text[] {
+    const walker = root.ownerDocument.createTreeWalker(root, SHOW_TEXT);
+    const found: Text[] = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        const parent = node.parentElement;
+        if (parent && !SKIPPED_TAGS.has(parent.tagName) && /\S/.test(node.nodeValue ?? '')) found.push(node as Text);
+    }
+    return found;
+}
+
+function pieceOf(doc: Document, text: string, mask: boolean): { outer: HTMLElement; moving: HTMLElement } {
+    const moving = doc.createElement('span');
+    moving.textContent = text;
+    if (!mask) return { outer: moving, moving };
+    moving.style.display = 'inline-block';
+    const outer = doc.createElement('span');
+    outer.style.display = 'inline-block';
+    // A clip-path and not overflow, which would move the box's baseline. The negative sides leave descenders and italics.
+    outer.style.clipPath = 'inset(-0.1em -0.1em -0.18em -0.1em)';
+    outer.appendChild(moving);
+    return { outer, moving };
+}
+
+/** Split `root`'s text, or null when it holds none or more than `cap` pieces (nothing is changed then). */
+export function splitText(root: HTMLElement, options: SplitTextOptions): SplitText | null {
+    const doc = root.ownerDocument;
+    const mask = !!options.mask;
+    const planned = textNodesOf(root).map(original => ({ original, parts: textPieces(original.nodeValue ?? '', mask && !!options.rtl) }));
+    const count = planned.reduce((sum, { parts }) => sum + parts.filter(part => part.word).length, 0);
+    if (!count || count > options.cap) return null;
+
+    const pieces: HTMLElement[] = [];
+    const replacements: Replacement[] = planned.map(({ original, parts }) => {
+        const nodes = parts.map((part): Node => {
+            if (!part.word) return doc.createTextNode(part.text);
+            const { outer, moving } = pieceOf(doc, part.text, mask);
+            pieces.push(moving);
+            return outer;
+        });
+        const parent = original.parentNode as ParentNode & Node;
+        for (const node of nodes) parent.insertBefore(node, original);
+        parent.removeChild(original);
+        return { original, nodes };
+    });
+
+    return {
+        pieces,
+        restore: () => {
+            for (const { original, nodes } of replacements) {
+                const first = nodes[0];
+                if (!first?.isConnected || !first.parentNode) continue;
+                first.parentNode.insertBefore(original, first);
+                for (const node of nodes) node.parentNode?.removeChild(node);
+            }
+        },
+    };
+}
+
+/** The line each piece stands on: 0, 0, 1, 1, 1, 2… Read once, as a reveal starts. */
+export function lineIndexes(tops: ReadonlyArray<number>, heights: ReadonlyArray<number>): number[] {
+    let line = 0;
+    let top = tops[0] ?? 0;
+    return tops.map((next, i) => {
+        if (next - top > (heights[i] ?? 0) / 2) {
+            line++;
+            top = next;
+        }
+        return line;
+    });
+}
+
+const LINE_STAGGER_MS = 90;
+const WORD_STAGGER_MS = 40;
+/** However long the heading, the last piece starts within this. */
+const STAGGER_BUDGET_MS = 1000;
+
+export function revealStagger(groups: number, by: TextRevealBy): number {
+    const step = by === TextRevealBy.Line ? LINE_STAGGER_MS : WORD_STAGGER_MS;
+    return groups > 1 ? Math.min(step, STAGGER_BUDGET_MS / (groups - 1)) : 0;
+}
+
+/** Past the mask's negative inset, so nothing shows before a piece's turn. */
+const PIECE_FRAMES: Keyframe[] = [{ transform: 'translateY(120%)' }, { transform: 'translateY(0)' }];
+const DEFAULT_PIECE_MS = 700;
+
+const playing = new WeakMap<HTMLElement, Animation>();
+
+/**
+ * Play a text reveal: each piece rises out of its mask, line by line or word by word. Returns ONE animation for the
+ * whole, so a runtime treats it as any other: it finishes when the last piece lands, and on finish or cancel the text
+ * is put back whole, which leaves nothing for a screen reader to stumble on and nothing to re-split on a resize. Null
+ * when there is nothing to split or it is being edited: the caller plays its plain fade.
+ */
+export function playTextReveal(el: HTMLElement, by: TextRevealBy, timing: KeyframeAnimationOptions): Animation | null {
+    playing.get(el)?.cancel();
+    if (el.isContentEditable) return null;
+    const rtl = el.ownerDocument.defaultView?.getComputedStyle(el).direction === 'rtl';
+    const split = splitText(el, { cap: REVEAL_PIECE_CAP, mask: true, rtl });
+    if (!split) return null;
+
+    const boxes = by === TextRevealBy.Line ? split.pieces.map(piece => (piece.parentElement as HTMLElement).getBoundingClientRect()) : [];
+    const order = by === TextRevealBy.Line ? lineIndexes(boxes.map(box => box.top), boxes.map(box => box.height)) : split.pieces.map((_, i) => i);
+    const groups = Math.max(...order) + 1;
+    const step = revealStagger(groups, by);
+    const duration = Number(timing.duration) || DEFAULT_PIECE_MS;
+    const delay = timing.delay ?? 0;
+    const pieces = split.pieces.map((piece, i) => piece.animate(PIECE_FRAMES, { duration, delay: delay + order[i] * step, easing: timing.easing, fill: 'both' }));
+    // The element itself just stands visible: its entrance's first frame had hidden it whole.
+    const whole = el.animate([{ opacity: 1 }, { opacity: 1 }], { duration: delay + duration + step * (groups - 1), fill: timing.fill ?? 'both' });
+    playing.set(el, whole);
+    const finished = (): void => {
+        if (playing.get(el) === whole) playing.delete(el);
+        for (const piece of pieces) piece.cancel();
+        split.restore();
+    };
+    whole.addEventListener('finish', finished, { once: true });
+    whole.addEventListener('cancel', finished, { once: true });
+    return whole;
+}