@vectoriox/iox-ui 5.71.2 → 5.72.1

package/fesm2022/vectoriox-iox-ui-scene-core.mjs

@@ -20,13 +20,26 @@ var SceneProp;
     SceneProp["Rotate"] = "rotate";
     /** 0–1. */
     SceneProp["Opacity"] = "opacity";
-    /** Inset from every side, in % of the layer (0 = whole, 50 = gone). */
+    /** How much of the layer shows, in % (100 = whole, 0 = gone). Its track's `from` says where it opens from. */
     SceneProp["Clip"] = "clip";
+    /** How many of the layer's words are lit, in % (100 = all): the word-by-word light-up. Split in the browser only. */
+    SceneProp["Words"] = "words";
     /** The layer's background colour. */
     SceneProp["Ground"] = "ground";
     /** The layer's text colour. */
     SceneProp["Ink"] = "ink";
 })(SceneProp || (SceneProp = {}));
+/** Where a reveal opens from. Start and End mirror in RTL. */
+var SceneRevealFrom;
+(function (SceneRevealFrom) {
+    SceneRevealFrom["Centre"] = "centre";
+    SceneRevealFrom["Bottom"] = "bottom";
+    SceneRevealFrom["Top"] = "top";
+    SceneRevealFrom["Start"] = "start";
+    SceneRevealFrom["End"] = "end";
+})(SceneRevealFrom || (SceneRevealFrom = {}));
+/** What a reveal opens from when nobody has said: the page's own direction of travel, upward as it scrolls. */
+const SCENE_REVEAL_DEFAULT = SceneRevealFrom.Bottom;
 var SceneAttribute;
 (function (SceneAttribute) {
     SceneAttribute["Root"] = "data-iox-scene";
@@ -44,6 +57,9 @@ const smoothstep = (t) => t * t * (3 - 2 * t);
 const COLOUR = /^(#[0-9a-f]{3,8}|(rgb|hsl)a?\([\d\s.,%/]+\)|var\(--iox-[\w-]+\))$/i;
 const COLOUR_PROPS = new Set([SceneProp.Ground, SceneProp.Ink]);
 const ALL_PROPS = new Set(Object.values(SceneProp));
+const REVEAL_FROMS = new Set(Object.values(SceneRevealFrom));
+const PERCENT$1 = 100;
+const clampPercent = (v) => Math.min(PERCENT$1, Math.max(0, v));
 function validKey(key, colour) {
     if (!Array.isArray(key) || key.length !== 2)
         return false;
@@ -68,11 +84,35 @@ function normalizeTracks(tracks) {
             .filter(key => validKey(key, COLOUR_PROPS.has(prop)))
             .slice()
             .sort((a, b) => a[0] - b[0]);
-        if (keys.length)
-            out.push({ prop, keys });
+        if (!keys.length)
+            continue;
+        out.push(prop === SceneProp.Clip ? clipTrack(keys, track.from) : { prop, keys });
     }
     return out;
 }
+/**
+ * A Clip track with a direction. One with none was saved when a reveal could only close in from every side, its value
+ * the inset per side (50 = gone): it reads as the same movement, from the centre, in % showing.
+ */
+function clipTrack(keys, from) {
+    if (typeof from === 'string' && REVEAL_FROMS.has(from))
+        return { prop: SceneProp.Clip, from: from, keys };
+    return { prop: SceneProp.Clip, from: SceneRevealFrom.Centre, keys: keys.map(([p, inset]) => [p, clampPercent(PERCENT$1 - Number(inset) * 2)]) };
+}
+/**
+ * The clip-path of a layer `showing` % revealed, opening from `from`. The one shape behind a Scene's Clip track and the
+ * clipReveal action. `clip-path` has no logical sides, so Start and End take the direction from `inlineSign`.
+ */
+function revealClipPath(showing, from = SCENE_REVEAL_DEFAULT, inlineSign = 1) {
+    const hidden = round(PERCENT$1 - clampPercent(showing));
+    switch (from) {
+        case SceneRevealFrom.Centre: return `inset(${round(hidden / 2)}%)`;
+        case SceneRevealFrom.Top: return `inset(0 0 ${hidden}% 0)`;
+        case SceneRevealFrom.Start: return inlineSign === 1 ? `inset(0 ${hidden}% 0 0)` : `inset(0 0 0 ${hidden}%)`;
+        case SceneRevealFrom.End: return inlineSign === 1 ? `inset(0 0 0 ${hidden}%)` : `inset(0 ${hidden}% 0 0)`;
+        default: return `inset(${hidden}% 0 0 0)`;
+    }
+}
 /** The two keys around `p` and how far between them it eases. */
 function span(keys, p) {
     const at = clamp01(p);
@@ -120,7 +160,7 @@ const TRANSFORM_REST = { [SceneProp.X]: 0, [SceneProp.Y]: 0, [SceneProp.Scale]:
 function sceneFrame(tracks, p, options = {}) {
     const frame = {};
     const moves = {};
-    for (const { prop, keys } of tracks) {
+    for (const { prop, keys, from } of tracks) {
         if (prop in TRANSFORM_REST)
             moves[prop] = valueAt(keys, p);
         else if (prop === SceneProp.Opacity) {
@@ -129,7 +169,7 @@ function sceneFrame(tracks, p, options = {}) {
             frame.pointerEvents = opacity > 0 ? '' : 'none';
         }
         else if (prop === SceneProp.Clip)
-            frame.clipPath = `inset(${Math.min(50, Math.max(0, valueAt(keys, p)))}%)`;
+            frame.clipPath = revealClipPath(valueAt(keys, p), from ?? SceneRevealFrom.Centre, options.inlineSign ?? 1);
         else if (prop === SceneProp.Ground)
             frame.backgroundColor = colourAt(keys, p);
         else if (prop === SceneProp.Ink)
@@ -142,6 +182,17 @@ function sceneFrame(tracks, p, options = {}) {
     }
     return frame;
 }
+/** How far an unlit word still shows: readable as a shape, plainly not yet said. */
+const SCENE_WORD_DIM = 0.16;
+/** How many of a layer's words are lit at `p`, in %; null when it has no such track. */
+function sceneWordsLit(tracks, p) {
+    const track = tracks.find(t => t.prop === SceneProp.Words);
+    return track ? clampPercent(valueAt(track.keys, p)) : null;
+}
+/** Word `index` of `count`, with `lit` % lit: words light one after the other, each easing in as the last finishes. */
+function sceneWordOpacity(index, count, lit) {
+    return round(SCENE_WORD_DIM + (1 - SCENE_WORD_DIM) * clamp01((lit / PERCENT$1) * count - index));
+}
 const CSS_NAME = {
     transform: 'transform',
     opacity: 'opacity',
@@ -175,7 +226,11 @@ function sceneNodeAttributes(node) {
 /** The frame a layer ships in from the server: where it stands before anyone has scrolled. Without it the page would
  *  paint every layer at once, and then jump when the script arrives. */
 function sceneFirstFrame(node) {
-    return sceneFrame(normalizeTracks(node?.sceneTracks), 0);
+    const tracks = normalizeTracks(node?.sceneTracks);
+    const frame = sceneFrame(tracks, 0);
+    // The words are split in the browser, so until then the whole layer stands for them, or it paints lit and then dims.
+    const lit = sceneWordsLit(tracks, 0);
+    return lit !== null && lit < PERCENT$1 && frame.opacity === undefined ? { ...frame, opacity: String(SCENE_WORD_DIM) } : frame;
 }
 /**
  * Make an element carry its node's Scene attributes: the live sync on the canvas and the component path's stamp.
@@ -232,7 +287,8 @@ const SCENE_TRACK_DEFS = [
     { prop: SceneProp.Scale, colour: false, rest: 1, min: 0, max: 2000, step: 1, factor: 100, unit: PERCENT },
     { prop: SceneProp.Rotate, colour: false, rest: 0, min: -720, max: 720, step: 1, factor: 1, unit: DEGREES },
     { prop: SceneProp.Opacity, colour: false, rest: 1, min: 0, max: 100, step: 1, factor: 100, unit: PERCENT },
-    { prop: SceneProp.Clip, colour: false, rest: 0, min: 0, max: 50, step: 1, factor: 1, unit: PERCENT },
+    { prop: SceneProp.Clip, colour: false, rest: 100, min: 0, max: 100, step: 1, factor: 1, unit: PERCENT },
+    { prop: SceneProp.Words, colour: false, rest: 100, min: 0, max: 100, step: 1, factor: 1, unit: PERCENT },
     { prop: SceneProp.Ground, colour: true, rest: 0, min: 0, max: 0, step: 0, factor: 1, unit: '' },
     { prop: SceneProp.Ink, colour: true, rest: 0, min: 0, max: 0, step: 0, factor: 1, unit: '' },
 ];
@@ -277,9 +333,23 @@ function replaceTrack(tracks, prop, keys) {
         return rest;
     const at = tracks.findIndex(t => t.prop === prop);
     const next = [...rest];
-    next.splice(at < 0 ? rest.length : at, 0, { prop, keys });
+    const from = prop === SceneProp.Clip ? { from: tracks[at]?.from ?? SCENE_REVEAL_DEFAULT } : {};
+    next.splice(at < 0 ? rest.length : at, 0, { prop, ...from, keys });
     return next;
 }
+/** Where a layer's reveal opens from: its track's direction, else where a new one would open from. */
+function sceneRevealFromOf(tracks) {
+    return trackOf(tracks, SceneProp.Clip)?.from ?? SCENE_REVEAL_DEFAULT;
+}
+/**
+ * Open a layer's reveal from `from`. With no reveal yet it starts one with a key at `p` holding the layer whole, so the
+ * direction is kept and nothing on screen changes until the author sets a second key.
+ */
+function withSceneRevealFrom(tracks, from, p) {
+    if (!trackOf(tracks, SceneProp.Clip))
+        return [...tracks, { prop: SceneProp.Clip, from, keys: [[sceneKeyPosition(p), sceneTrackDef(SceneProp.Clip).rest]] }];
+    return tracks.map(track => (track.prop === SceneProp.Clip ? { ...track, from } : track));
+}
 /**
  * Set a key at `p`, in the author's units. A number is clamped to its bounds; a colour that is no colour changes nothing,
  * because `normalizeTracks` would drop it anyway and the author's other keys must survive.
@@ -467,6 +537,166 @@ function buildSceneRecipe(create, words = {}) {
     return root;
 }
 
+/**
+ * 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.
+ */
+var TextRevealBy;
+(function (TextRevealBy) {
+    TextRevealBy["Line"] = "line";
+    TextRevealBy["Word"] = "word";
+})(TextRevealBy || (TextRevealBy = {}));
+/** Past these a text is plainly no heading: it fades whole, and lights up whole. */
+const REVEAL_PIECE_CAP = 120;
+const LIGHT_UP_PIECE_CAP = 300;
+const SKIPPED_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'SELECT', 'OPTION']);
+const SHOW_TEXT = 4;
+/** Hebrew through Arabic Extended, and their presentation forms. */
+const RTL_LETTER = /[֐-ࣿיִ-﷿ﹰ-]/;
+/**
+ * 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.
+ */
+function textPieces(text, keepLtrRuns = false) {
+    const pieces = (text.match(/\s+|\S+/g) ?? []).map(part => ({ text: part, word: /\S/.test(part) }));
+    if (!keepLtrRuns)
+        return pieces;
+    const merged = [];
+    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;
+}
+function textNodesOf(root) {
+    const walker = root.ownerDocument.createTreeWalker(root, SHOW_TEXT);
+    const found = [];
+    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);
+    }
+    return found;
+}
+function pieceOf(doc, text, mask) {
+    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). */
+function splitText(root, options) {
+    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 = [];
+    const replacements = planned.map(({ original, parts }) => {
+        const nodes = parts.map((part) => {
+            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;
+        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. */
+function lineIndexes(tops, heights) {
+    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;
+function revealStagger(groups, by) {
+    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 = [{ transform: 'translateY(120%)' }, { transform: 'translateY(0)' }];
+const DEFAULT_PIECE_MS = 700;
+const playing = new WeakMap();
+/**
+ * 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.
+ */
+function playTextReveal(el, by, timing) {
+    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.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 = () => {
+        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;
+}
+
 /**
  * The ONE scroll loop (premium-sites plan §5b, SC0). Every Scene on a page reads one progress value from it, on the
  * canvas and on the live site alike. It reads where the root is and nothing else, so it has one code path: under the
@@ -568,8 +798,10 @@ class ScrollDriver {
         this.resize?.unobserve(root);
         if (scene.stage)
             scene.stage.style.removeProperty('translate');
-        for (const layer of scene.layers)
+        for (const layer of scene.layers) {
             layer.el.style.removeProperty('will-change');
+            this.restoreWords(layer);
+        }
         this.scenes.delete(root);
     }
     /** Read a root's layers again now, keeping where it stands: an editor changed their tracks. */
@@ -648,11 +880,16 @@ class ScrollDriver {
         layer.el.style.removeProperty('will-change');
         for (const key of Object.keys(layer.last))
             layer.el.style[key] = '';
+        this.restoreWords(layer);
+    }
+    restoreWords(layer) {
+        layer.words?.restore();
+        layer.words = null;
     }
     readLayer(el, scene) {
         const previous = scene.layers.find(layer => layer.el === el);
         el.style.setProperty('will-change', TRANSFORM_WILL_CHANGE);
-        return { el, tracks: parseTracks(el.getAttribute(SceneAttribute.Tracks)), phoneTracks: parseTracks(el.getAttribute(SceneAttribute.PhoneTracks)), last: previous?.last ?? {}, stale: true };
+        return { el, tracks: parseTracks(el.getAttribute(SceneAttribute.Tracks)), phoneTracks: parseTracks(el.getAttribute(SceneAttribute.PhoneTracks)), last: previous?.last ?? {}, stale: true, words: previous?.words ?? null, wordsRefused: false };
     }
     remeasureAll() {
         for (const scene of this.scenes.values())
@@ -677,6 +914,7 @@ class ScrollDriver {
     write(scene) {
         for (const layer of scene.layers) {
             const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
+            this.writeWords(layer, sceneWordsLit(tracks, scene.progress));
             const frame = sceneFrame(tracks, scene.progress, { inlineSign: scene.inlineSign });
             for (const key of Object.keys(frame)) {
                 if (layer.stale || frame[key] !== layer.last[key])
@@ -691,6 +929,29 @@ class ScrollDriver {
             layer.stale = false;
         }
     }
+    /** One opacity per word, and a write only for the few the scroll actually changed. */
+    writeWords(layer, lit) {
+        if (lit === null) {
+            this.restoreWords(layer);
+            return;
+        }
+        // Gone from the page: the text was replaced under it (an edit on the canvas), so its words are new.
+        if (layer.words && !layer.words.pieces[0]?.isConnected)
+            layer.words = null;
+        if (!layer.words && !layer.wordsRefused) {
+            layer.words = splitText(layer.el, { cap: LIGHT_UP_PIECE_CAP });
+            layer.wordsRefused = !layer.words;
+            // The whole layer stood for its words until now (`sceneFirstFrame`); an Opacity track's frame writes after this.
+            layer.el.style.removeProperty('opacity');
+            layer.stale = true;
+        }
+        const pieces = layer.words?.pieces ?? [];
+        pieces.forEach((piece, i) => {
+            const opacity = String(sceneWordOpacity(i, pieces.length, lit));
+            if (piece.style.opacity !== opacity)
+                piece.style.opacity = opacity;
+        });
+    }
 }
 /** A page's Scenes, driven by one driver; null when it holds none, or when the visitor asked for less motion (the
  *  page's own CSS then lets each Scene flow). The live site's door. */
@@ -717,5 +978,5 @@ function attachScenes(container, options = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { SCENE_BUDGET, SCENE_DAMPING, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WORDS, SceneAttribute, SceneProp, ScrollDriver, applySceneFirstFrame, attachScenes, buildSceneRecipe, colourAt, dampToward, movedSceneKey, normalizeTracks, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, sceneRootOnPath, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, scenesIn, syncSceneAttributes, valueAt, withSceneKey, withoutSceneKey };
+export { LIGHT_UP_PIECE_CAP, REVEAL_PIECE_CAP, SCENE_BUDGET, SCENE_DAMPING, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_REVEAL_DEFAULT, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WORDS, SCENE_WORD_DIM, SceneAttribute, SceneProp, SceneRevealFrom, ScrollDriver, TextRevealBy, applySceneFirstFrame, attachScenes, buildSceneRecipe, colourAt, dampToward, lineIndexes, movedSceneKey, normalizeTracks, playTextReveal, revealClipPath, revealStagger, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, sceneRevealFromOf, sceneRootOnPath, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withSceneRevealFrom, withoutSceneKey };
 //# sourceMappingURL=vectoriox-iox-ui-scene-core.mjs.map