@efxlab/motion-canvas-2d 4.0.0

package/src/lib/code/CodeCursor.ts

@@ -0,0 +1,468 @@
+import {
+  clampRemap,
+  Color,
+  map,
+  SerializedVector2,
+  unwrap,
+  Vector2,
+} from '@efxlab/motion-canvas-core';
+import {Code} from '../components';
+import {CodeFragment, parseCodeFragment} from './CodeFragment';
+import {CodeHighlighter} from './CodeHighlighter';
+import {CodeMetrics} from './CodeMetrics';
+import {CodePoint, CodeRange} from './CodeRange';
+import {CodeScope, isCodeScope} from './CodeScope';
+import {isPointInCodeSelection} from './CodeSelection';
+
+export interface CodeFragmentDrawingInfo {
+  text: string;
+  position: Vector2;
+  characterSize: Vector2;
+  cursor: Vector2;
+  fill: string;
+  time: number;
+  alpha: number;
+}
+
+/**
+ * A stateful class for recursively traversing a code scope.
+ *
+ * @internal
+ */
+export class CodeCursor {
+  public cursor = new Vector2();
+  public tweenCursor = new Vector2();
+  public beforeCursor = new Vector2();
+  public afterCursor = new Vector2();
+  public beforeIndex = 0;
+  public afterIndex = 0;
+  private context = {} as CanvasRenderingContext2D;
+  private monoWidth = 0;
+  private maxWidth = 0;
+  private lineHeight = 0;
+  private fallbackFill = new Color('white');
+  private caches: {before: unknown; after: unknown} | null = null;
+  private highlighter: CodeHighlighter | null = null;
+  private selection: CodeRange[] = [];
+  private selectionProgress: number | null = null;
+  private globalProgress: number[] = [];
+  private fragmentDrawingInfo: CodeFragmentDrawingInfo[] = [];
+  private fontHeight = 0;
+  private verticalOffset = 0;
+
+  public constructor(private readonly node: Code) {}
+
+  /**
+   * Prepare the cursor for the next traversal.
+   *
+   * @param context - The context used to measure and draw the code.
+   */
+  public setupMeasure(context: CanvasRenderingContext2D) {
+    const metrics = context.measureText('X');
+    this.monoWidth = metrics.width;
+    this.fontHeight =
+      metrics.fontBoundingBoxDescent + metrics.fontBoundingBoxAscent;
+    this.verticalOffset = metrics.fontBoundingBoxAscent;
+    this.context = context;
+    this.lineHeight = parseFloat(this.node.styles.lineHeight);
+    this.cursor = new Vector2();
+    this.tweenCursor = new Vector2();
+    this.beforeCursor = new Vector2();
+    this.afterCursor = new Vector2();
+    this.beforeIndex = 0;
+    this.afterIndex = 0;
+    this.maxWidth = 0;
+  }
+
+  public setupDraw(context: CanvasRenderingContext2D) {
+    this.setupMeasure(context);
+    const fill = this.node.fill();
+    this.fallbackFill =
+      fill instanceof Color ? (fill as Color) : new Color('white');
+    this.caches = this.node.highlighterCache();
+    this.highlighter = this.node.highlighter();
+    this.selection = this.node.selection();
+    this.selectionProgress = this.node.selectionProgress();
+    this.fragmentDrawingInfo = [];
+    this.globalProgress = [];
+  }
+
+  /**
+   * Measure the desired size of the code scope.
+   *
+   * @remarks
+   * The result can be retrieved with {@link getSize}.
+   *
+   * @param scope - The code scope to measure.
+   */
+  public measureSize(scope: CodeScope) {
+    const progress = unwrap(scope.progress);
+    for (const wrapped of scope.fragments) {
+      const possibleFragment = unwrap(wrapped);
+      if (isCodeScope(possibleFragment)) {
+        this.measureSize(possibleFragment);
+        continue;
+      }
+      if (Array.isArray(possibleFragment)) {
+        this.measureSize({
+          progress: scope.progress,
+          fragments: possibleFragment,
+        });
+        continue;
+      }
+
+      const fragment = parseCodeFragment(
+        possibleFragment,
+        this.context,
+        this.monoWidth,
+      );
+
+      const beforeMaxWidth = this.calculateMaxWidth(fragment.before);
+      const afterMaxWidth = this.calculateMaxWidth(fragment.after);
+
+      const maxWidth = map(beforeMaxWidth, afterMaxWidth, progress);
+      if (maxWidth > this.maxWidth) {
+        this.maxWidth = maxWidth;
+      }
+
+      const beforeEnd = this.calculateWidth(fragment.before);
+      const afterEnd = this.calculateWidth(fragment.after);
+      this.cursor.x = map(beforeEnd, afterEnd, progress);
+
+      if (this.cursor.y === 0) {
+        this.cursor.y = 1;
+      }
+
+      this.cursor.y += map(
+        fragment.before.newRows,
+        fragment.after.newRows,
+        progress,
+      );
+    }
+  }
+
+  /**
+   * Get the size measured by the cursor.
+   */
+  public getSize() {
+    return {
+      x: this.maxWidth * this.monoWidth,
+      y: this.cursor.y * this.lineHeight + this.verticalOffset,
+    };
+  }
+
+  /**
+   * Get the drawing information created by the cursor.
+   */
+  public getDrawingInfo() {
+    return {
+      fragments: this.fragmentDrawingInfo,
+      verticalOffset: this.verticalOffset,
+      fontHeight: this.fontHeight,
+    };
+  }
+
+  /**
+   * Draw the given code scope.
+   *
+   * @param scope - The code scope to draw.
+   */
+  public drawScope(scope: CodeScope) {
+    const progress = unwrap(scope.progress);
+    for (const wrappedFragment of scope.fragments) {
+      const possibleFragment = unwrap(wrappedFragment);
+      if (isCodeScope(possibleFragment)) {
+        this.drawScope(possibleFragment);
+        continue;
+      }
+      if (Array.isArray(possibleFragment)) {
+        this.drawScope({
+          progress: scope.progress,
+          fragments: possibleFragment,
+        });
+        continue;
+      }
+
+      const fragment = parseCodeFragment(
+        possibleFragment,
+        this.context,
+        this.monoWidth,
+      );
+      const timingOffset = 0.8;
+      let alpha = 1;
+      let offsetY = 0;
+      if (fragment.before.content !== fragment.after.content) {
+        const mirrored = Math.abs(progress - 0.5) * 2;
+        alpha = clampRemap(1, 1 - timingOffset, 1, 0, mirrored);
+
+        const isBigger =
+          fragment.after.newRows > fragment.before.newRows ? 1 : -1;
+        const isBefore = progress < 0.5 ? 1 : -1;
+        const scale = isBigger * isBefore * 4;
+        offsetY = map(
+          Math.abs(fragment.after.newRows - fragment.before.newRows) / scale,
+          0,
+          mirrored,
+        );
+      }
+
+      this.drawToken(
+        fragment,
+        scope,
+        this.cursor.addY(offsetY),
+        this.tweenCursor,
+        alpha,
+      );
+
+      this.beforeCursor.x = this.calculateWidth(
+        fragment.before,
+        this.beforeCursor.x,
+      );
+      this.afterCursor.x = this.calculateWidth(
+        fragment.after,
+        this.afterCursor.x,
+      );
+      this.beforeCursor.y += fragment.before.newRows;
+      this.afterCursor.y += fragment.after.newRows;
+
+      this.beforeIndex += fragment.before.content.length;
+      this.afterIndex += fragment.after.content.length;
+
+      this.cursor.y += map(
+        fragment.before.newRows,
+        fragment.after.newRows,
+        progress,
+      );
+
+      const beforeEnd = this.calculateWidth(fragment.before);
+      const afterEnd = this.calculateWidth(fragment.after);
+      this.cursor.x = map(beforeEnd, afterEnd, progress);
+
+      this.tweenCursor.y +=
+        progress > 0.5 ? fragment.after.newRows : fragment.before.newRows;
+      this.tweenCursor.x = progress > 0.5 ? afterEnd : beforeEnd;
+    }
+  }
+
+  private drawToken(
+    fragment: CodeFragment,
+    scope: CodeScope,
+    offset: SerializedVector2,
+    tweenCursor: SerializedVector2,
+    alpha: number,
+  ) {
+    const progress = unwrap(scope.progress);
+    const currentProgress = this.currentProgress();
+    if (progress > 0) {
+      this.globalProgress.push(progress);
+    }
+
+    const code = progress < 0.5 ? fragment.before : fragment.after;
+
+    let hasOffset = true;
+    let width = 0;
+    let stringLength = 0;
+    let y = 0;
+    for (let i = 0; i < code.content.length; i++) {
+      let color = this.fallbackFill.serialize();
+      let char = code.content.charAt(i);
+      const selection: {before: number | null; after: number | null} = {
+        before: null,
+        after: null,
+      };
+
+      if (char === '\n') {
+        y++;
+        hasOffset = false;
+        width = 0;
+        stringLength = 0;
+        selection.before = null;
+        selection.after = null;
+        continue;
+      }
+
+      const beforeHighlight =
+        this.caches &&
+        this.highlighter?.highlight(this.beforeIndex + i, this.caches.before);
+      const afterHighlight =
+        this.caches &&
+        this.highlighter?.highlight(this.afterIndex + i, this.caches.after);
+
+      const highlight = progress < 0.5 ? beforeHighlight : afterHighlight;
+      if (highlight) {
+        // Handle edge cases where the highlight style changes despite the
+        // content being the same. The code doesn't fade in and out so the color
+        // has to be interpolated to avoid jarring changes.
+        if (
+          fragment.before.content === fragment.after.content &&
+          beforeHighlight?.color !== afterHighlight?.color
+        ) {
+          highlight.color = Color.lerp(
+            beforeHighlight?.color ?? this.fallbackFill,
+            afterHighlight?.color ?? this.fallbackFill,
+            progress,
+          ).serialize();
+        }
+
+        if (highlight.color) {
+          color = highlight.color;
+        }
+
+        let skipAhead = 0;
+        do {
+          if (
+            this.processSelection(
+              selection,
+              skipAhead,
+              hasOffset,
+              stringLength,
+              y,
+            )
+          ) {
+            break;
+          }
+
+          skipAhead++;
+        } while (
+          skipAhead < highlight.skipAhead &&
+          code.content.charAt(i + skipAhead) !== '\n'
+        );
+
+        if (skipAhead > 1) {
+          char = code.content.slice(i, i + skipAhead);
+        }
+
+        i += char.length - 1;
+      } else {
+        this.processSelection(selection, 0, hasOffset, stringLength, y);
+        let skipAhead = 1;
+        while (
+          i < code.content.length - 1 &&
+          code.content.charAt(i + 1) !== '\n'
+        ) {
+          if (
+            this.processSelection(
+              selection,
+              skipAhead,
+              hasOffset,
+              stringLength,
+              y,
+            )
+          ) {
+            break;
+          }
+
+          skipAhead++;
+          char += code.content.charAt(++i);
+        }
+      }
+
+      let time: number;
+      const selectionAfter = selection.after ?? 0;
+      const selectionBefore = selection.before ?? 0;
+      if (fragment.before.content === '') {
+        time = selectionAfter;
+      } else if (fragment.after.content === '') {
+        time = selectionBefore;
+      } else {
+        time = map(
+          selectionBefore,
+          selectionAfter,
+          this.selectionProgress ?? currentProgress,
+        );
+      }
+
+      const measure = this.context.measureText(char);
+      this.fragmentDrawingInfo.push({
+        text: char,
+        position: new Vector2(
+          (hasOffset ? offset.x + width : width) * this.monoWidth,
+          (offset.y + y) * this.lineHeight,
+        ),
+        cursor: new Vector2(
+          hasOffset ? tweenCursor.x + stringLength : stringLength,
+          tweenCursor.y + y,
+        ),
+        alpha,
+        characterSize: new Vector2(
+          measure.width / char.length,
+          this.fontHeight,
+        ),
+        fill: color,
+        time,
+      });
+
+      stringLength += char.length;
+      width += Math.round(measure.width / this.monoWidth);
+    }
+  }
+
+  private calculateWidth(metrics: CodeMetrics, x = this.cursor.x): number {
+    return metrics.newRows === 0 ? x + metrics.lastWidth : metrics.lastWidth;
+  }
+
+  private calculateMaxWidth(metrics: CodeMetrics, x = this.cursor.x): number {
+    return Math.max(this.maxWidth, metrics.maxWidth, x + metrics.firstWidth);
+  }
+
+  private currentProgress() {
+    if (this.globalProgress.length === 0) {
+      return 0;
+    }
+
+    let sum = 0;
+    for (const progress of this.globalProgress) {
+      sum += progress;
+    }
+
+    return sum / this.globalProgress.length;
+  }
+
+  private processSelection(
+    selection: {before: number | null; after: number | null},
+    skipAhead: number,
+    hasOffset: boolean,
+    stringLength: number,
+    y: number,
+  ): boolean {
+    let shouldBreak = false;
+    let currentSelected = this.isSelected(
+      (hasOffset ? this.beforeCursor.x + stringLength : stringLength) +
+        skipAhead,
+      this.beforeCursor.y + y,
+    );
+    if (selection.before !== null && selection.before !== currentSelected) {
+      shouldBreak = true;
+    } else {
+      selection.before = currentSelected;
+    }
+
+    currentSelected = this.isSelected(
+      (hasOffset ? this.afterCursor.x + stringLength : stringLength) +
+        skipAhead,
+      this.afterCursor.y + y,
+      true,
+    );
+    if (selection.after !== null && selection.after !== currentSelected) {
+      shouldBreak = true;
+    } else {
+      selection.after = currentSelected;
+    }
+
+    return shouldBreak;
+  }
+
+  private isSelected(x: number, y: number, isAfter?: boolean): number {
+    const point: CodePoint = [y, x];
+    const maxSelection = isPointInCodeSelection(point, this.selection) ? 1 : 0;
+    if (this.node.oldSelection === null || this.selectionProgress === null) {
+      return maxSelection;
+    }
+
+    if (isAfter) {
+      return maxSelection;
+    }
+
+    return isPointInCodeSelection(point, this.node.oldSelection) ? 1 : 0;
+  }
+}

package/src/lib/code/CodeDiffer.ts

@@ -0,0 +1,77 @@
+import {CodeScope, CodeTag, resolveScope} from './CodeScope';
+import {CodeTokenizer} from './CodeTokenizer';
+import {patienceDiff} from './diff';
+
+/**
+ * A function that compares two code snippets and returns a list of
+ * {@link CodeTag}s describing a transition between them.
+ */
+export type CodeDiffer = (
+  /**
+   * The original code scope.
+   */
+  from: CodeScope,
+  /**
+   * The new code scope.
+   */
+  to: CodeScope,
+  /**
+   * The inherited tokenizer to use.
+   */
+  tokenize: CodeTokenizer,
+) => CodeTag[];
+
+/**
+ * Default diffing function utilizing {@link code.patienceDiff}.
+ *
+ * @param from - The original code scope.
+ * @param to - The new code scope.
+ * @param tokenize - The inherited tokenizer to use.
+ */
+export function defaultDiffer(
+  from: CodeScope,
+  to: CodeScope,
+  tokenize: CodeTokenizer,
+) {
+  const fromString = resolveScope(from, false);
+  const toString = resolveScope(to, true);
+
+  const diff = patienceDiff(tokenize(fromString), tokenize(toString));
+
+  const fragments: CodeTag[] = [];
+  let before = '';
+  let after = '';
+  let lastAdded = false;
+  const flush = () => {
+    if (before !== '' || after !== '') {
+      fragments.push({
+        before,
+        after,
+      });
+      before = '';
+      after = '';
+    }
+  };
+
+  for (const line of diff.lines) {
+    if (line.aIndex === -1) {
+      if (after !== '' && !lastAdded) {
+        flush();
+      }
+      lastAdded = true;
+      after += line.line;
+    } else if (line.bIndex === -1) {
+      if (before !== '' && lastAdded) {
+        flush();
+      }
+      lastAdded = false;
+      before += line.line;
+    } else {
+      flush();
+      fragments.push(line.line);
+    }
+  }
+  flush();
+
+  return fragments;
+}

package/src/lib/code/CodeFragment.ts

@@ -0,0 +1,96 @@
+import {CodeMetrics, isCodeMetrics, measureString} from './CodeMetrics';
+
+export interface CodeFragment {
+  before: CodeMetrics;
+  after: CodeMetrics;
+}
+export interface RawCodeFragment {
+  before: string;
+  after: string;
+}
+
+export type PossibleCodeFragment =
+  | CodeFragment
+  | CodeMetrics
+  | RawCodeFragment
+  | string;
+
+export function metricsToFragment(value: CodeMetrics): CodeFragment {
+  return {
+    before: value,
+    after: value,
+  };
+}
+
+export function parseCodeFragment(
+  value: PossibleCodeFragment,
+  context: CanvasRenderingContext2D,
+  monoWidth: number,
+): CodeFragment {
+  let fragment: CodeFragment;
+  if (typeof value === 'string') {
+    fragment = metricsToFragment(measureString(context, monoWidth, value));
+  } else if (isCodeMetrics(value)) {
+    fragment = metricsToFragment(value);
+  } else {
+    fragment = {
+      before:
+        typeof value.before === 'string'
+          ? measureString(context, monoWidth, value.before)
+          : value.before,
+      after:
+        typeof value.after === 'string'
+          ? measureString(context, monoWidth, value.after)
+          : value.after,
+    };
+  }
+
+  return fragment;
+}
+
+/**
+ * Create a code fragment that represents an insertion of code.
+ *
+ * @remarks
+ * Can be used in conjunction with {@link code.CodeSignalHelpers.edit}.
+ *
+ * @param code - The code to insert.
+ */
+export function insert(code: string): RawCodeFragment {
+  return {
+    before: '',
+    after: code,
+  };
+}
+
+/**
+ * Create a code fragment that represents a change from one piece of code to
+ * another.
+ *
+ * @remarks
+ * Can be used in conjunction with {@link code.CodeSignalHelpers.edit}.
+ *
+ * @param before - The code to change from.
+ * @param after - The code to change to.
+ */
+export function replace(before: string, after: string): RawCodeFragment {
+  return {
+    before,
+    after,
+  };
+}
+
+/**
+ * Create a code fragment that represents a removal of code.
+ *
+ * @remarks
+ * Can be used in conjunction with {@link code.CodeSignalHelpers.edit}.
+ *
+ * @param code - The code to remove.
+ */
+export function remove(code: string): RawCodeFragment {
+  return {
+    before: code,
+    after: '',
+  };
+}

package/src/lib/code/CodeHighlighter.ts

@@ -0,0 +1,73 @@
+/**
+ * Describes the result of a highlight operation.
+ */
+export interface HighlightResult {
+  /**
+   * The color of the code at the given index.
+   */
+  color: string | null;
+
+  /**
+   * The number of characters to skip ahead.
+   *
+   * @remarks
+   * This should be used to skip to the end of the currently highlighted token.
+   * The returned style will be used for the skipped characters, and they will
+   * be drawn as one continuous string keeping emojis and ligatures intact.
+   *
+   * The returned value is the number of characters to skip ahead, not the
+   * index of the end of the token.
+   */
+  skipAhead: number;
+}
+
+/**
+ * Describes custom highlighters used by the Code node.
+ *
+ * @typeParam T - The type of the cache used by the highlighter.
+ */
+export interface CodeHighlighter<T = unknown> {
+  /**
+   * Initializes the highlighter.
+   *
+   * @remarks
+   * This method is called when collecting async resources for the node.
+   * It can be called multiple times so caching the initialization is
+   * recommended.
+   *
+   * If initialization is asynchronous, a promise should be registered using
+   * {@link DependencyContext.collectPromise} and the value of `false` should
+   * be returned. The hook will be called again when the promise resolves.
+   * This process can be repeated until the value of `true` is returned which
+   * will mark the highlighter as ready.
+   */
+  initialize(): boolean;
+
+  /**
+   * Prepares the code for highlighting.
+   *
+   * @remarks
+   * This method is called each time the code changes. It can be used to do
+   * any preprocessing of the code before highlighting. The result of this
+   * method is cached and passed to {@link highlight} when the code is
+   * highlighted.
+   *
+   * @param code - The code to prepare.
+   */
+  prepare(code: string): T;
+
+  /**
+   * Highlights the code at the given index.
+   *
+   * @param index - The index of the code to highlight.
+   * @param cache - The result of {@link prepare}.
+   */
+  highlight(index: number, cache: T): HighlightResult;
+
+  /**
+   * Tokenize the code.
+   *
+   * @param code - The code to tokenize.
+   */
+  tokenize(code: string): string[];
+}