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

package/src/tokens.ts

@@ -1,75 +1,79 @@
-import { canHighlight, highlightToTokens } from "./highlight";
-import { CodeTheme } from "./style";
-
-// IdToken is our internal wrapper around a highlighter token that gives every
-// token a stable identity across line insertions/removals. All animation state
-// is keyed by `id`, so concurrent edits at different positions don't clobber
-// each other while one is mid-animation.
-export interface IdToken {
-    id: number;
-    content: string;
-    color?: string;
-}
-
-// IdLine wraps a row of tokens with its own stable id, so per-line animations
-// (heightScale during insert/remove) survive line insertions/removals.
-export interface IdLine {
-    id: number;
-    tokens: IdToken[];
-}
-
-// Module-global, monotonic id counters shared across all Code nodes — ids only
-// need to be unique within a node, but a global counter is the simplest way to
-// guarantee that and never collides.
-let nextTokenId = 1;
-let nextLineId = 1;
-
-export function makeIdToken(content: string, color?: string): IdToken {
-    return { id: nextTokenId++, content, color };
-}
-
-export function makeIdLine(tokens: IdToken[]): IdLine {
-    return { id: nextLineId++, tokens };
-}
-
-export function tokenizeCodeToIdLines(code: string, language: string, theme: CodeTheme): IdLine[] {
-    // Until the language parser has loaded (it streams in via the asset loader),
-    // fall back to flat, uncolored lines instead of throwing on an unloaded
-    // grammar. The node re-tokenizes once the load completes.
-    if (!canHighlight(language, theme)) {
-        return code.split('\n').map(line => makeIdLine([makeIdToken(line, '#d1d5db')]));
-    }
-    return highlightToTokens(code, language, theme).map(line =>
-        makeIdLine(line.map(tok => makeIdToken(tok.content, tok.color))),
-    );
-}
-
-/**
- * Split `tokens` at character offset `col` (relative to the joined content of
- * the tokens). If `col` falls inside a token, that token is split into two new
- * tokens with fresh ids (the original id is discarded — it didn't exist as a
- * single unit on either side of the cut).
- */
-export function splitTokensAt(
-    tokens: IdToken[],
-    col: number,
-): { before: IdToken[]; after: IdToken[] } {
-    const before: IdToken[] = [];
-    const after: IdToken[] = [];
-    let off = 0;
-    for (const tok of tokens) {
-        const tStart = off;
-        const tEnd = off + tok.content.length;
-        if (tEnd <= col) {
-            before.push(tok);
-        } else if (tStart >= col) {
-            after.push(tok);
-        } else {
-            const cut = col - tStart;
-            before.push(makeIdToken(tok.content.slice(0, cut), tok.color));
-            after.push(makeIdToken(tok.content.slice(cut), tok.color));
-        }
-        off = tEnd;
-    }
-    return { before, after };
-}
+import { canHighlight, highlightToTokens, normalizeSource, resolveTheme } from "./highlight";
+import { CodeTheme } from "./style";
+
+// IdToken is our internal wrapper around a highlighter token that gives every
+// token a stable identity across line insertions/removals. All animation state
+// is keyed by `id`, so concurrent edits at different positions don't clobber
+// each other while one is mid-animation.
+export interface IdToken {
+    id: number;
+    content: string;
+    color?: string;
+}
+
+// IdLine wraps a row of tokens with its own stable id, so per-line animations
+// (heightScale during insert/remove) survive line insertions/removals.
+export interface IdLine {
+    id: number;
+    tokens: IdToken[];
+}
+
+// Module-global, monotonic id counters shared across all Code nodes — ids only
+// need to be unique within a node, but a global counter is the simplest way to
+// guarantee that and never collides.
+let nextTokenId = 1;
+let nextLineId = 1;
+
+export function makeIdToken(content: string, color?: string): IdToken {
+    return { id: nextTokenId++, content, color };
+}
+
+export function makeIdLine(tokens: IdToken[]): IdLine {
+    return { id: nextLineId++, tokens };
+}
+
+export function tokenizeCodeToIdLines(code: string, language: string, theme: CodeTheme): IdLine[] {
+    // Until the language parser has loaded (it streams in via the asset loader),
+    // fall back to flat, uncolored lines instead of throwing on an unloaded
+    // grammar. The node re-tokenizes once the load completes.
+    code = normalizeSource(code);
+    if (!canHighlight(language, theme)) {
+        // Resolved for its warning: an unknown theme is reported whether or not
+        // the grammar has landed yet.
+        resolveTheme(theme);
+        return code.split('\n').map(line => makeIdLine([makeIdToken(line, '#d1d5db')]));
+    }
+    return highlightToTokens(code, language, theme).map(line =>
+        makeIdLine(line.map(tok => makeIdToken(tok.content, tok.color))),
+    );
+}
+
+/**
+ * Split `tokens` at character offset `col` (relative to the joined content of
+ * the tokens). If `col` falls inside a token, that token is split into two new
+ * tokens with fresh ids (the original id is discarded — it didn't exist as a
+ * single unit on either side of the cut).
+ */
+export function splitTokensAt(
+    tokens: IdToken[],
+    col: number,
+): { before: IdToken[]; after: IdToken[] } {
+    const before: IdToken[] = [];
+    const after: IdToken[] = [];
+    let off = 0;
+    for (const tok of tokens) {
+        const tStart = off;
+        const tEnd = off + tok.content.length;
+        if (tEnd <= col) {
+            before.push(tok);
+        } else if (tStart >= col) {
+            after.push(tok);
+        } else {
+            const cut = col - tStart;
+            before.push(makeIdToken(tok.content.slice(0, cut), tok.color));
+            after.push(makeIdToken(tok.content.slice(cut), tok.color));
+        }
+        off = tEnd;
+    }
+    return { before, after };
+}

package/src/transitions.ts

@@ -1,184 +1,204 @@
-import type { CodeLayout } from "./layout";
-import { IdLine } from "./tokens";
-
-// A single animated token entry owned by one dim transition. Keyed by stable
-// token id rather than (line, tokenIndex) so concurrent animations don't clobber
-// each other when one shifts the indices of tokens the other is animating.
-export interface AnimToken {
-    id: number;
-    opacity: number[];
-    opacityKeys: number[];
-}
-
-/**
- * A highlight cross-fade: opacity, and nothing else.
- *
- * Structure is untouched, so several of these stack happily and a listing held
- * under a highlight still hits the static-layout cache.
- */
-export interface DimTransition {
-    kind: "dim";
-    tokens: AnimToken[];
-    progress: number;
-}
-
-/**
- * When each part of a structural edit happens, in normalized transition time.
- *
- * The order is what an edit *looks like* being made: what is going away leaves
- * first, what stays reflows into its new place, and only then does what is new
- * appear. Running them together is what made a replacement look like a
- * cross-dissolve of two unrelated listings.
- */
-export interface Phases {
-    /** Removed tokens fade out. Null when the edit removes nothing. */
-    out: [number, number] | null;
-    /** Surviving tokens travel, and the block resizes. Always present. */
-    move: [number, number];
-    /** Added tokens fade (and slide) in. Null when the edit adds nothing. */
-    in: [number, number] | null;
-}
-
-/**
- * One edit in flight: the structure before, the structure after, and who is
- * doing what.
- *
- * Both endpoints are fixed for the transition's whole life, which is why the
- * two resolved layouts hang off it — they are computed once and reused for
- * every frame the edit spans, rather than rebuilt per frame from a structure
- * that is being mutated underneath.
- */
-export interface StructuralTransition {
-    kind: "structural";
-    from: IdLine[];
-    to: IdLine[];
-    removedIds: Set<number>;
-    addedIds: Set<number>;
-    /**
-     * Ids of rows in `to` that did not exist before, and so enter as a whole
-     * row rather than as tokens spliced into one.
-     *
-     * They enter by fading in place, and that is the *only* thing they do. An
-     * earlier version slid each one in from the edge the block had just grown
-     * along — appended rows rising from below, prepended ones descending, ones
-     * spliced into the middle arriving from the left. Every one of those is a
-     * claim about where the line came from, and a listing has no such story to
-     * tell: text is written where it belongs, it does not travel there. Sliding
-     * also puts the row under the neighbours it is meant to sit between for the
-     * length of its entrance, which reads as the listing redrawing itself.
-     */
-    enteringLineIds: Set<number>;
-    fromColorById: Map<number, string | undefined>;
-    phases: Phases;
-    progress: number;
-    /** @internal Layout cache — see {@link StructuralTransition}. */
-    layoutKey: string | null;
-    fromLayout: CodeLayout | null;
-    toLayout: CodeLayout | null;
-}
-
-export type CodeTransition = DimTransition | StructuralTransition;
-
-/**
- * Decides *when* (in normalized transition time) each part of a structural
- * edit happens, given only whether the edit removes/adds anything.
- * `phasesFor` below is the default implementation (exported as
- * `defaultCodePhases`) — pass a `phaseStrategy` of this shape to `<Code>` to
- * replace it with your own timing.
- */
-export type CodePhaseStrategy = (hasRemoved: boolean, hasAdded: boolean) => Phases;
-
-export interface TokenState {
-    opacity: number;
-}
-
-/** Sample a piecewise-linear curve (keys → values) at progress `p` in [0, 1]. */
-export function sampleCurve(keys: number[], values: number[], p: number): number {
-    if (p <= keys[0]) return values[0];
-    if (p >= keys[keys.length - 1]) return values[values.length - 1];
-    for (let i = 0; i < keys.length - 1; i++) {
-        if (p <= keys[i + 1]) {
-            const span = keys[i + 1] - keys[i];
-            const local = span === 0 ? 0 : (p - keys[i]) / span;
-            return values[i] + (values[i + 1] - values[i]) * local;
-        }
-    }
-    return values[values.length - 1];
-}
-
-/** Progress *within* a phase window, clamped to [0, 1]. A null window is complete. */
-export function windowProgress(w: [number, number] | null, p: number): number {
-    if (!w) return 1;
-    const [a, b] = w;
-    if (p <= a) return 0;
-    if (p >= b) return 1;
-    return b === a ? 1 : (p - a) / (b - a);
-}
-
-/** Smooth start and end, so a phase never begins or ends with a velocity step. */
-export function smoothstep(t: number): number {
-    return t * t * (3 - 2 * t);
-}
-
-export function makeAnim(id: number, curve: { keys: number[]; values: number[] }): AnimToken {
-    return { id, opacity: curve.values, opacityKeys: curve.keys };
-}
-
-/**
- * The phase schedule for an edit, shaped by what the edit actually contains.
- *
- * A fixed schedule wastes time it does not need: a pure append has nothing to
- * fade out, so holding the first 40% of the duration empty just makes the
- * animation feel late. Each shape gets the whole duration spent on the parts
- * that exist, with adjacent phases overlapping enough to read as one movement.
- */
-export function phasesFor(hasRemoved: boolean, hasAdded: boolean): Phases {
-    // The overlaps are deliberate and small. Butt-joining the phases leaves the
-    // block sitting empty at its new size for a beat between the old content
-    // leaving and the new content arriving; letting the arrival start while the
-    // reflow's eased tail is still running closes that gap without blurring the
-    // order the edit reads in.
-    if (hasRemoved && hasAdded) return { out: [0, 0.38], move: [0.10, 0.68], in: [0.52, 1] };
-    if (hasRemoved) return { out: [0, 0.45], move: [0.22, 1], in: null };
-    if (hasAdded) return { out: null, move: [0, 0.55], in: [0.38, 1] };
-    return { out: null, move: [0, 1], in: null };
-}
-
-/** {@link phasesFor} under the name a `phaseStrategy` default is looked up by. */
-export const defaultCodePhases: CodePhaseStrategy = phasesFor;
-
-/** How far through the "everything reflows" phase a frame is, eased. A settled frame (no edit) is always fully moved. */
-export function moveProgress(edit: { phases: Phases; progress: number } | null): number {
-    return edit ? smoothstep(windowProgress(edit.phases.move, edit.progress)) : 1;
-}
-
-/**
- * Resolve the per-token opacity multiplier for the current frame from the
- * persistent highlight dim plus every active dim transition.
- */
-export function resolveTokenStates(
-    tokenLines: IdLine[],
-    transitions: CodeTransition[],
-    highlightDimOpacity: number | null,
-    highlightedIds: Set<number>,
-): Map<number, TokenState> {
-    const out = new Map<number, TokenState>();
-
-    if (highlightDimOpacity !== null) {
-        const dim = highlightDimOpacity;
-        for (const line of tokenLines) {
-            for (const tok of line.tokens) {
-                out.set(tok.id, { opacity: highlightedIds.has(tok.id) ? 1 : dim });
-            }
-        }
-    }
-
-    for (const tr of transitions) {
-        if (tr.kind !== "dim") continue;
-        for (const at of tr.tokens) {
-            out.set(at.id, { opacity: sampleCurve(at.opacityKeys, at.opacity, tr.progress) });
-        }
-    }
-
-    return out;
-}
+import type { NormalizedColor } from "@motionscript/sdk";
+import type { CodeLayout } from "./layout";
+import { IdLine } from "./tokens";
+
+// A single animated token entry owned by one dim transition. Keyed by stable
+// token id rather than (line, tokenIndex) so concurrent animations don't clobber
+// each other when one shifts the indices of tokens the other is animating.
+export interface AnimToken {
+    id: number;
+    opacity: number[];
+    opacityKeys: number[];
+}
+
+/**
+ * A highlight cross-fade: opacity, and nothing else.
+ *
+ * Structure is untouched, so several of these stack happily and a listing held
+ * under a highlight still hits the static-layout cache.
+ */
+export interface DimTransition {
+    kind: "dim";
+    tokens: AnimToken[];
+    progress: number;
+}
+
+/**
+ * When each part of a structural edit happens, in normalized transition time.
+ *
+ * The order is what an edit *looks like* being made: what is going away leaves
+ * first, what stays reflows into its new place, and only then does what is new
+ * appear. Running them together is what made a replacement look like a
+ * cross-dissolve of two unrelated listings.
+ */
+export interface Phases {
+    /** Removed tokens fade out. Null when the edit removes nothing. */
+    out: [number, number] | null;
+    /** Surviving tokens travel, and the block resizes. Always present. */
+    move: [number, number];
+    /** Added tokens fade (and slide) in. Null when the edit adds nothing. */
+    in: [number, number] | null;
+}
+
+/**
+ * One edit in flight: the structure before, the structure after, and who is
+ * doing what.
+ *
+ * Both endpoints are fixed for the transition's whole life, which is why the
+ * two resolved layouts hang off it — they are computed once and reused for
+ * every frame the edit spans, rather than rebuilt per frame from a structure
+ * that is being mutated underneath.
+ */
+export interface StructuralTransition {
+    kind: "structural";
+    from: IdLine[];
+    to: IdLine[];
+    removedIds: Set<number>;
+    addedIds: Set<number>;
+    /**
+     * Ids of rows in `to` that did not exist before, and so enter as a whole
+     * row rather than as tokens spliced into one.
+     *
+     * They enter by fading in place, and that is the *only* thing they do. An
+     * earlier version slid each one in from the edge the block had just grown
+     * along — appended rows rising from below, prepended ones descending, ones
+     * spliced into the middle arriving from the left. Every one of those is a
+     * claim about where the line came from, and a listing has no such story to
+     * tell: text is written where it belongs, it does not travel there. Sliding
+     * also puts the row under the neighbours it is meant to sit between for the
+     * length of its entrance, which reads as the listing redrawing itself.
+     */
+    enteringLineIds: Set<number>;
+    fromColorById: Map<number, string | undefined>;
+    phases: Phases;
+    progress: number;
+    /** @internal Layout cache — see {@link StructuralTransition}. */
+    layoutKey: string | null;
+    fromLayout: CodeLayout | null;
+    toLayout: CodeLayout | null;
+}
+
+/** A filled band behind whole rows: the first and last line it covers, by line id so it follows them through an edit, and its paint. */
+export interface RowBand {
+    startId: number;
+    endId: number;
+    color: NormalizedColor;
+    radius: number;
+}
+
+/**
+ * One set of row bands becoming another. Bands at the same position in both
+ * lists travel and recolour; one with no counterpart fades.
+ */
+export interface RowsTransition {
+    kind: "rows";
+    from: RowBand[];
+    to: RowBand[];
+    progress: number;
+}
+
+export type CodeTransition = DimTransition | StructuralTransition | RowsTransition;
+
+/**
+ * Decides *when* (in normalized transition time) each part of a structural
+ * edit happens, given only whether the edit removes/adds anything.
+ * `phasesFor` below is the default implementation (exported as
+ * `defaultCodePhases`) — pass a `phaseStrategy` of this shape to `<Code>` to
+ * replace it with your own timing.
+ */
+export type CodePhaseStrategy = (hasRemoved: boolean, hasAdded: boolean) => Phases;
+
+export interface TokenState {
+    opacity: number;
+}
+
+/** Sample a piecewise-linear curve (keys → values) at progress `p` in [0, 1]. */
+export function sampleCurve(keys: number[], values: number[], p: number): number {
+    if (p <= keys[0]) return values[0];
+    if (p >= keys[keys.length - 1]) return values[values.length - 1];
+    for (let i = 0; i < keys.length - 1; i++) {
+        if (p <= keys[i + 1]) {
+            const span = keys[i + 1] - keys[i];
+            const local = span === 0 ? 0 : (p - keys[i]) / span;
+            return values[i] + (values[i + 1] - values[i]) * local;
+        }
+    }
+    return values[values.length - 1];
+}
+
+/** Progress *within* a phase window, clamped to [0, 1]. A null window is complete. */
+export function windowProgress(w: [number, number] | null, p: number): number {
+    if (!w) return 1;
+    const [a, b] = w;
+    if (p <= a) return 0;
+    if (p >= b) return 1;
+    return b === a ? 1 : (p - a) / (b - a);
+}
+
+/** Smooth start and end, so a phase never begins or ends with a velocity step. */
+export function smoothstep(t: number): number {
+    return t * t * (3 - 2 * t);
+}
+
+export function makeAnim(id: number, curve: { keys: number[]; values: number[] }): AnimToken {
+    return { id, opacity: curve.values, opacityKeys: curve.keys };
+}
+
+/**
+ * The phase schedule for an edit, shaped by what the edit actually contains.
+ *
+ * A fixed schedule wastes time it does not need: a pure append has nothing to
+ * fade out, so holding the first 40% of the duration empty just makes the
+ * animation feel late. Each shape gets the whole duration spent on the parts
+ * that exist, with adjacent phases overlapping enough to read as one movement.
+ */
+export function phasesFor(hasRemoved: boolean, hasAdded: boolean): Phases {
+    // The overlaps are deliberate and small. Butt-joining the phases leaves the
+    // block sitting empty at its new size for a beat between the old content
+    // leaving and the new content arriving; letting the arrival start while the
+    // reflow's eased tail is still running closes that gap without blurring the
+    // order the edit reads in.
+    if (hasRemoved && hasAdded) return { out: [0, 0.38], move: [0.10, 0.68], in: [0.52, 1] };
+    if (hasRemoved) return { out: [0, 0.45], move: [0.22, 1], in: null };
+    if (hasAdded) return { out: null, move: [0, 0.55], in: [0.38, 1] };
+    return { out: null, move: [0, 1], in: null };
+}
+
+/** {@link phasesFor} under the name a `phaseStrategy` default is looked up by. */
+export const defaultCodePhases: CodePhaseStrategy = phasesFor;
+
+/** How far through the "everything reflows" phase a frame is, eased. A settled frame (no edit) is always fully moved. */
+export function moveProgress(edit: { phases: Phases; progress: number } | null): number {
+    return edit ? smoothstep(windowProgress(edit.phases.move, edit.progress)) : 1;
+}
+
+/**
+ * Resolve the per-token opacity multiplier for the current frame from the
+ * persistent highlight dim plus every active dim transition.
+ */
+export function resolveTokenStates(
+    tokenLines: IdLine[],
+    transitions: CodeTransition[],
+    highlightDimOpacity: number | null,
+    highlightedIds: Set<number>,
+): Map<number, TokenState> {
+    const out = new Map<number, TokenState>();
+
+    if (highlightDimOpacity !== null) {
+        const dim = highlightDimOpacity;
+        for (const line of tokenLines) {
+            for (const tok of line.tokens) {
+                out.set(tok.id, { opacity: highlightedIds.has(tok.id) ? 1 : dim });
+            }
+        }
+    }
+
+    for (const tr of transitions) {
+        if (tr.kind !== "dim") continue;
+        for (const at of tr.tokens) {
+            out.set(at.id, { opacity: sampleCurve(at.opacityKeys, at.opacity, tr.progress) });
+        }
+    }
+
+    return out;
+}