@motionscript/code 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/node.js

@@ -4,14 +4,21 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { node, Clip, Node2D, property, insetsProperty, lerpNumber, command, driveCommand, } from "@motionscript/sdk";
-import { rangeToCharOffsets, charOffsetsToRange, TokenAdvanceCache, tokenizeCodeToIdLines, defaultCodeDiff, layoutCode, metricsSignature, makeAnim, defaultCodePhases, resolveTokenStates, moveProgress, canHighlight, ensureHighlighter, DefaultHighlightStyle, drawCode, } from "./engine.js";
+import { node, Clip, Node2D, property, insetsProperty, lerpNumber, colorOps, command, driveCommand, } from "@motionscript/sdk";
+import { rangeToCharOffsets, charOffsetsToRange, TokenAdvanceCache, tokenizeCodeToIdLines, defaultCodeDiff, layoutCode, metricsSignature, makeAnim, defaultCodePhases, resolveTokenStates, moveProgress, canHighlight, ensureHighlighter, normalizeSource, DefaultHighlightStyle, drawCode, } from "./engine.js";
+/** A row band's paint and corner radius when `highlightRows` is given neither. */
+const ROW_BAND_COLOR = "rgba(255, 255, 255, 0.12)";
+const ROW_BAND_RADIUS = 6;
 let Code = class Code extends Node2D {
     /** The settled structure. During an edit, the structure the edit lands on. */
     tokenLines = [];
-    tokenized = false;
     /** The source `tokenLines` spells, so a frame compares it with `code` without joining every token. */
     _linesSource = "";
+    /** What `tokenLines` were coloured and split with, so a frame notices a `language` or `theme` that has moved since. */
+    _linesBasis = { language: "", theme: "", highlighted: false };
+    /** The last `code` seen and its normalised form, so a frame that finds it unchanged does not scan it. */
+    _rawCode = null;
+    _normalCode = "";
     transitions = [];
     // Caches expensive scope.measureText() calls; cleared when the font
     // signature (fontSize|fontFamily) changes. See TokenAdvanceCache.
@@ -27,6 +34,8 @@ let Code = class Code extends Node2D {
     // tokens whose id is NOT in the highlight set. null means "not highlighting".
     highlightDimOpacity = null;
     highlightedIds = new Set();
+    // The bands highlightRows() left behind whole rows; empty means none.
+    rowBands = [];
     /**
      * Which token became which across an edit, and when each part of that
      * edit happens. Construction-time-only (see {@link CodeStrategies}) —
@@ -36,10 +45,10 @@ let Code = class Code extends Node2D {
     phaseStrategy;
     constructor(props) {
         super(props);
-        this.diffStrategy = props.diffStrategy ?? defaultCodeDiff;
-        this.phaseStrategy = props.phaseStrategy ?? defaultCodePhases;
-        this.applyProp("width", props.width ?? "hug");
-        this.applyProp("height", props.height ?? "hug");
+        this.diffStrategy = props?.diffStrategy ?? defaultCodeDiff;
+        this.phaseStrategy = props?.phaseStrategy ?? defaultCodePhases;
+        this.applyProp("width", props?.width ?? "hug");
+        this.applyProp("height", props?.height ?? "hug");
         this.applyProp("_driven", false);
         // Best-effort, for a highlighter constructed outside the asset pipeline
         // entirely (a bare `new Code(...)` in a test or a headless measure). On
@@ -48,19 +57,7 @@ let Code = class Code extends Node2D {
         // there the tokens are right the first time rather than upgrading later.
         // (Theme is a synchronous color style; only the language parser loads.)
         ensureHighlighter(undefined, [this.language]).catch(() => { });
-        this.tokenize();
-    }
-    set(props) {
-        super.set(props);
-        if (props.code !== undefined || props.language !== undefined || props.theme !== undefined) {
-            this.tokenized = false;
-        }
-    }
-    tokenize() {
-        this.setLines(this._structureFor(this.code), this.code);
-        // Only consider ourselves tokenized once we actually highlighted; while
-        // the language is still loading we keep retrying on each render.
-        this.tokenized = canHighlight(this.language, this.theme);
+        this._sync();
     }
     /**
      * Swap in a new settled structure, invalidating the layout cache.
@@ -69,11 +66,12 @@ let Code = class Code extends Node2D {
      * counter rather than a hash of the content — a write that skipped the bump
      * would keep serving the previous frame's geometry for the new listing.
      */
-    setLines(lines, source) {
+    setLines(lines, source, basis = this._basis()) {
         if (this.tokenLines === lines)
             return;
         this.tokenLines = lines;
         this._linesSource = source;
+        this._linesBasis = basis;
         this.structureVersion++;
         this.layoutCache = null;
         this.layoutCacheKey = null;
@@ -116,6 +114,15 @@ let Code = class Code extends Node2D {
         }
         return null;
     }
+    /** The row-band change in flight, if any; the latest wins. */
+    activeRows() {
+        for (let i = this.transitions.length - 1; i >= 0; i--) {
+            const tr = this.transitions[i];
+            if (tr.kind === "rows")
+                return tr;
+        }
+        return null;
+    }
     settledLayout(m, scope) {
         const key = `${this.structureVersion}|${metricsSignature(m)}|${this.advanceCache.signature(m.fontSize, m.fontFamily)}`;
         if (this.layoutCache && this.layoutCacheKey === key)
@@ -188,14 +195,9 @@ let Code = class Code extends Node2D {
         // column-by-column rather than merely look different.
         ctx.pushTextStyle(null);
         try {
+            // Also what upgrades a frame drawn as plain text to full highlighting
+            // the moment the asset loader resolves the grammar.
             this._sync();
-            // Keep retrying until the language+theme have actually loaded, so a frame
-            // that rendered as plain text upgrades to full highlighting the moment the
-            // asset loader resolves. Never mid-edit: re-tokenizing mints fresh ids,
-            // and an in-flight transition is keyed by the ones it captured.
-            if (!this.tokenized && !this.activeEdit() && canHighlight(this.language, this.theme)) {
-                this.tokenize();
-            }
             super.renderContent(ctx);
         }
         finally {
@@ -425,6 +427,25 @@ let Code = class Code extends Node2D {
             this.highlightedIds = done ? new Set() : previousIds;
         });
     }
+    /**
+     * Lay a band of `color` behind whole rows: every line a range touches, across
+     * the block. Persistent, and independent of {@link highlight}'s dimming. A
+     * second call slides and resizes the bands onto their new rows, pairing them
+     * in the order given; `resetRowHighlight()` fades them out. A band keeps to
+     * its lines when an edit moves them.
+     */
+    highlightRows(args) {
+        this._sync();
+        const { target, color, radius } = args.data;
+        const paint = colorOps.resolve(color ?? ROW_BAND_COLOR);
+        const bands = this.rowBandsIn(normalizeCodeRanges(target), paint, Math.max(0, radius ?? ROW_BAND_RADIUS));
+        return this.runRows(this.rowBands, bands, args.duration, args.easing);
+    }
+    /** Fade every row band out and clear them. */
+    resetRowHighlight(args) {
+        this._sync();
+        return this.runRows(this.rowBands, [], args.duration, args.easing);
+    }
     /**
      * Animate the listing to a new source.
      *
@@ -440,10 +461,15 @@ let Code = class Code extends Node2D {
      * of two unrelated listings rather than as an edit being made.
      */
     editTo(next, duration, easing) {
+        if (!this.mounted)
+            return driveCommand(duration, () => { });
+        next = normalizeSource(next);
         const from = this.tokenLines;
         const fromCode = this.joinedSource();
         if (next === fromCode)
             return driveCommand(duration, () => { });
+        const fromBasis = this._linesBasis;
+        const basis = this._basis();
         const edit = this.diffStrategy(from, tokenizeCodeToIdLines(next, this.language, this.theme));
         const transition = {
             kind: "structural",
@@ -459,12 +485,10 @@ let Code = class Code extends Node2D {
             fromLayout: null,
             toLayout: null,
         };
-        // A tokenize triggered by the grammar landing mid-edit would mint fresh
+        // A re-tokenize triggered by the grammar landing mid-edit would mint fresh
         // ids underneath this transition, and the transition is keyed by the ones
-        // it captured — so the retry in `onRender` is gated on there being no edit
-        // in flight, which means this flag has to be honest now rather than once
-        // the edit settles.
-        this.tokenized = canHighlight(this.language, this.theme);
+        // it captured — so `_sync` leaves the structure alone while an edit is in
+        // flight, and compares the basis recorded here once it settles.
         return driveCommand(duration, (t) => {
             this._drive();
             const running = t > 0 && t < 1;
@@ -478,11 +502,11 @@ let Code = class Code extends Node2D {
             // starts, the listing is what preceded it; at or past the end, the
             // result. A `finally` could only ever have run forwards.
             if (t <= 0) {
-                this.setLines(from, fromCode);
+                this.setLines(from, fromCode, fromBasis);
                 this._writeProp("code", fromCode);
             }
             else {
-                this.setLines(edit.lines, next);
+                this.setLines(edit.lines, next, basis);
                 this._writeProp("code", next);
             }
         });
@@ -497,6 +521,8 @@ let Code = class Code extends Node2D {
      * way*, and `progress` is assigned from `t` rather than accumulated.
      */
     runDim(tokens, duration, easing, settle) {
+        if (!this.mounted)
+            return driveCommand(duration, () => { });
         const transition = { kind: "dim", tokens, progress: 0 };
         return driveCommand(duration, (t) => {
             this._drive();
@@ -510,6 +536,23 @@ let Code = class Code extends Node2D {
             settle?.(t >= 1);
         });
     }
+    /** The same membership rule as {@link runDim}: on the stack strictly inside the run, settled at either end. */
+    runRows(from, to, duration, easing) {
+        if (!this.mounted || (from.length === 0 && to.length === 0))
+            return driveCommand(duration, () => { });
+        const transition = { kind: "rows", from, to, progress: 0 };
+        return driveCommand(duration, (t) => {
+            this._drive();
+            const running = t > 0 && t < 1;
+            const index = this.transitions.indexOf(transition);
+            if (running && index < 0)
+                this.transitions.push(transition);
+            else if (!running && index >= 0)
+                this.transitions.splice(index, 1);
+            transition.progress = easing ? easing(t) : t;
+            this.rowBands = t >= 1 ? to : from;
+        });
+    }
     /**
      * Route a tweened `code` through the diff engine.
      *
@@ -520,9 +563,11 @@ let Code = class Code extends Node2D {
      * the rest of the step's props tween alongside it untouched.
      */
     _prepareStep(to, duration, easing) {
+        if (!this.mounted)
+            return super._prepareStep(to, duration, easing);
         this._sync();
-        const next = to.code;
-        if (typeof next !== "string" || next === this.joinedSource()) {
+        const next = typeof to.code === "string" ? normalizeSource(to.code) : undefined;
+        if (next === undefined || next === this.joinedSource()) {
             return super._prepareStep(to, duration, easing);
         }
         const rest = { ...to };
@@ -625,6 +670,19 @@ let Code = class Code extends Node2D {
         return result;
     }
     // ── Drawing ─────────────────────────────────────────────────────────────
+    /** One band per range, over every line it touches; a range past the end of the listing gives none. */
+    rowBandsIn(codeRanges, color, radius) {
+        const count = this.tokenLines.length;
+        const bands = [];
+        for (const range of codeRanges) {
+            const first = Math.max(1, Math.round(range.startLine ?? 1));
+            const last = Math.min(count, range.endLine == null || range.endLine === Infinity ? count : Math.round(range.endLine));
+            if (first > last)
+                continue;
+            bands.push({ startId: this.tokenLines[first - 1].id, endId: this.tokenLines[last - 1].id, color, radius });
+        }
+        return bands;
+    }
     /**
      * Thin delegator: everything about *how* a frame is painted (settled or
      * mid structural-edit, entry/exit motion, colour cross-fade) lives in
@@ -641,6 +699,9 @@ let Code = class Code extends Node2D {
             ...this.frameLayout(draw),
             tokenStates: resolveTokenStates(this.tokenLines, this.transitions, this.highlightDimOpacity, this.highlightedIds),
             highlightActive: this.highlightDimOpacity !== null || this.transitions.some(tr => tr.kind === "dim"),
+            rowBands: this.rowBands,
+            rowsEdit: this.activeRows(),
+            boxW: this.layoutBounds.width,
         });
     }
     /** Each source the props have named, tokenized once, so a listing derived again keeps the ids a highlight selected. */
@@ -650,28 +711,59 @@ let Code = class Code extends Node2D {
         this._sync();
         this._writeProp("_driven", true);
     }
+    /**
+     * Bring the settled structure up to the props it is derived from.
+     *
+     * Pulled from every reader rather than pushed from a prop write, because
+     * `code`, `language` and `theme` can each be tweened or bound, and neither
+     * has a write to hang a subscription on. Never mid-edit: re-tokenizing mints
+     * fresh ids, and an in-flight transition is keyed by the ones it captured.
+     */
     _sync() {
+        const code = this._normalised();
         if (!this._driven) {
             this.transitions.length = 0;
             this.highlightDimOpacity = null;
             if (this.highlightedIds.size > 0)
                 this.highlightedIds = new Set();
-            this.setLines(this._structureFor(this.code), this.code);
+            if (this.rowBands.length > 0)
+                this.rowBands = [];
+            this.setLines(this._structureFor(code), code);
+        }
+        else if (!this.activeEdit()) {
+            const basis = this._basis();
+            const was = this._linesBasis;
+            if (this._linesSource === code && was.language === basis.language && was.theme === basis.theme && was.highlighted === basis.highlighted)
+                return;
+            const lines = this._structureFor(code);
+            // The same text split the same way, only coloured differently: the
+            // tokens are the ones a highlight or a transition already names.
+            if (this._linesSource === code && was.language === basis.language && was.highlighted === basis.highlighted) {
+                adoptIds(this.tokenLines, lines);
+            }
+            this.setLines(lines, code, basis);
         }
-        else if (this._linesSource !== this.code && !this.activeEdit()) {
-            // A `set` or a binding moved `code` outside a listing command.
-            this.setLines(this._structureFor(this.code), this.code);
+    }
+    _normalised() {
+        const code = this.code;
+        if (code !== this._rawCode) {
+            this._rawCode = code;
+            this._normalCode = normalizeSource(code);
         }
+        return this._normalCode;
+    }
+    _basis() {
+        return { language: this.language, theme: this.theme, highlighted: canHighlight(this.language, this.theme) };
     }
     _structureFor(code) {
-        const highlighted = canHighlight(this.language, this.theme);
+        const { language, theme, highlighted } = this._basis();
         let entry = this._derived.get(code);
-        if (!entry || entry.language !== this.language || entry.theme !== this.theme || entry.highlighted !== highlighted) {
+        if (!entry || entry.language !== language || entry.theme !== theme || entry.highlighted !== highlighted) {
             entry = {
-                language: this.language,
-                theme: this.theme,
+                language,
+                theme,
                 highlighted,
-                lines: tokenizeCodeToIdLines(code, this.language, this.theme),
+                lines: tokenizeCodeToIdLines(code, language, theme),
             };
             this._derived.delete(code);
             this._derived.set(code, entry);
@@ -745,6 +837,18 @@ __decorate([
 __decorate([
     command()
 ], Code.prototype, "resetHighlight", null);
+__decorate([
+    command({
+        args: [
+            { key: "target", kind: "selector" },
+            { key: "color", kind: "color", default: ROW_BAND_COLOR },
+            { key: "radius", kind: "number", default: ROW_BAND_RADIUS, min: 0, step: 1 },
+        ],
+    })
+], Code.prototype, "highlightRows", null);
+__decorate([
+    command()
+], Code.prototype, "resetRowHighlight", null);
 Code = __decorate([
     node({
         key: "code",
@@ -758,6 +862,25 @@ Code = __decorate([
     })
 ], Code);
 export { Code };
+/** Carry `from`'s line and token ids onto `to` when the two spell the same tokens. */
+function adoptIds(from, to) {
+    if (from.length !== to.length)
+        return;
+    for (let i = 0; i < from.length; i++) {
+        const a = from[i].tokens;
+        const b = to[i].tokens;
+        if (a.length !== b.length)
+            return;
+        for (let j = 0; j < a.length; j++)
+            if (a[j].content !== b[j].content)
+                return;
+    }
+    for (let i = 0; i < from.length; i++) {
+        to[i].id = from[i].id;
+        for (let j = 0; j < from[i].tokens.length; j++)
+            to[i].tokens[j].id = from[i].tokens[j].id;
+    }
+}
 /** Sources a node keeps tokenized, oldest dropped first; a bound `code` can name any number of them. */
 const DERIVED_LISTINGS = 16;
 /**
@@ -765,13 +888,17 @@ const DERIVED_LISTINGS = 16;
  * `CodeRange` (a plain object, not iterable) becomes a one-element array; a
  * `CodeRangeChain`/plain array of ranges spreads as-is. `CodeRange` and
  * `CodeRangeChain` are distinguished by iterability, not `instanceof` — a
- * bare array of `CodeRange`s (no chain) works the same way.
+ * bare array of `CodeRange`s (no chain) works the same way. The `{ list }` shape
+ * a chain used to serialise as is read as the chain it came from.
  */
 function normalizeCodeRanges(codeRange) {
     const maybeIterable = codeRange;
     if (typeof maybeIterable[Symbol.iterator] === "function") {
         return [...codeRange];
     }
+    const stored = codeRange.list;
+    if (Array.isArray(stored))
+        return [...stored];
     return [codeRange];
 }
 const grammarLoaders = new Map();