@efxlab/motion-canvas-2d 4.0.0

package/src/lib/components/Code.ts

@@ -0,0 +1,532 @@
+import {
+  BBox,
+  createSignal,
+  experimentalLog,
+  map,
+  SerializedVector2,
+  Signal,
+  SignalValue,
+  SimpleSignal,
+  ThreadGenerator,
+  TimingFunction,
+  unwrap,
+  useLogger,
+  useScene,
+  Vector2,
+} from '@efxlab/motion-canvas-core';
+import {
+  CodeCursor,
+  CodeFragmentDrawingInfo,
+  CodeHighlighter,
+  CodePoint,
+  CodeRange,
+  CodeSelection,
+  CodeSignal,
+  codeSignal,
+  CodeSignalContext,
+  findAllCodeRanges,
+  isPointInCodeSelection,
+  lines,
+  parseCodeSelection,
+  PossibleCodeScope,
+  PossibleCodeSelection,
+  resolveScope,
+} from '../code';
+import {computed, initial, nodeName, parser, signal} from '../decorators';
+import {DesiredLength} from '../partials';
+import {Shape, ShapeProps} from './Shape';
+
+/**
+ * @experimental
+ */
+export interface DrawTokenHook {
+  (
+    ctx: CanvasRenderingContext2D,
+    text: string,
+    position: Vector2,
+    color: string,
+    selection: number,
+  ): void;
+}
+
+/**
+ * Describes custom drawing logic used by the Code node.
+ *
+ * @experimental
+ */
+export interface DrawHooks {
+  /**
+   * Custom drawing logic for individual code tokens.
+   *
+   * @example
+   * ```ts
+   * token(ctx, text, position, color, selection) {
+   *   const blur = map(3, 0, selection);
+   *   const alpha = map(0.5, 1, selection);
+   *   ctx.globalAlpha *= alpha;
+   *   ctx.filter = `blur(${blur}px)`;
+   *   ctx.fillStyle = color;
+   *   ctx.fillText(text, position.x, position.y);
+   * }
+   * ```
+   */
+  token: DrawTokenHook;
+}
+
+export interface CodeProps extends ShapeProps {
+  /**
+   * {@inheritDoc Code.highlighter}
+   */
+  highlighter?: SignalValue<CodeHighlighter | null>;
+  /**
+   * {@inheritDoc Code.code}
+   */
+  code?: SignalValue<PossibleCodeScope>;
+  /**
+   * {@inheritDoc Code.selection}
+   */
+  selection?: SignalValue<PossibleCodeSelection>;
+  /**
+   * {@inheritDoc Code.drawHooks}
+   */
+  drawHooks?: SignalValue<DrawHooks>;
+}
+
+/**
+ * A node for displaying and animating code.
+ *
+ * @preview
+ * ```tsx editor
+ * import {Code, makeScene2D} from '@efxlab/motion-canvas-2d';
+ * import {createRef} from '@efxlab/motion-canvas-core';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const code = createRef<Code>();
+ *
+ *   view.add(
+ *     <Code
+ *       ref={code}
+ *       offset={-1}
+ *       position={view.size().scale(-0.5).add(60)}
+ *       fontFamily={'JetBrains Mono, monospace'}
+ *       fontSize={36}
+ *       code={`\
+ * function hello() {
+ *   console.log('Hello');
+ * }`}
+ *     />,
+ *   );
+ *
+ *   yield* code()
+ *     .code(
+ *       `\
+ * function hello() {
+ *   console.warn('Hello World');
+ * }`,
+ *       1,
+ *     )
+ *     .wait(0.5)
+ *     .back(1)
+ *     .wait(0.5);
+ * });
+ * ```
+ */
+@nodeName('CodeBlock')
+export class Code extends Shape {
+  /**
+   * Create a standalone code signal.
+   *
+   * @param initial - The initial code.
+   * @param highlighter - Custom highlighter to use.
+   */
+  public static createSignal(
+    initial: SignalValue<PossibleCodeScope>,
+    highlighter?: SignalValue<CodeHighlighter>,
+  ): CodeSignal<void> {
+    return new CodeSignalContext<void>(
+      initial,
+      undefined,
+      highlighter,
+    ).toSignal();
+  }
+
+  public static defaultHighlighter: CodeHighlighter | null = null;
+
+  /**
+   * The code highlighter to use for this code node.
+   *
+   * @remarks
+   * Defaults to a shared {@link code.LezerHighlighter}.
+   */
+  @initial(() => Code.defaultHighlighter)
+  @signal()
+  declare public readonly highlighter: SimpleSignal<
+    CodeHighlighter | null,
+    this
+  >;
+
+  /**
+   * The code to display.
+   */
+  @codeSignal()
+  declare public readonly code: CodeSignal<this>;
+
+  /**
+   * Custom drawing logic for the code.
+   *
+   * @remarks
+   * Check out {@link DrawHooks} for available render hooks.
+   *
+   * @experimental
+   *
+   * @example
+   * Make the unselected code blurry and transparent:
+   * ```tsx
+   * <Code
+   *   drawHooks={{
+   *     token(ctx, text, position, color, selection) {
+   *       const blur = map(3, 0, selection);
+   *       const alpha = map(0.5, 1, selection);
+   *       ctx.globalAlpha *= alpha;
+   *       ctx.filter = `blur(${blur}px)`;
+   *       ctx.fillStyle = color;
+   *       ctx.fillText(text, position.x, position.y);
+   *     },
+   *   }}
+   *   // ...
+   * />
+   * ```
+   */
+  @initial<DrawHooks>({
+    token(ctx, text, position, color, selection) {
+      ctx.fillStyle = color;
+      ctx.globalAlpha *= map(0.2, 1, selection);
+      ctx.fillText(text, position.x, position.y);
+    },
+  })
+  @signal()
+  declare public readonly drawHooks: SimpleSignal<DrawHooks, this>;
+
+  protected setDrawHooks(value: DrawHooks) {
+    if (
+      !useScene().experimentalFeatures &&
+      value !== this.drawHooks.context.getInitial()
+    ) {
+      useLogger().log({
+        ...experimentalLog(`Code uses experimental draw hooks.`),
+        inspect: this.key,
+      });
+    } else {
+      this.drawHooks.context.setter(value);
+    }
+  }
+
+  /**
+   * The currently selected code range.
+   *
+   * @remarks
+   * Either a single {@link code.CodeRange} or an array of them
+   * describing which parts of the code should be visually emphasized.
+   *
+   * You can use {@link code.word} and
+   * {@link code.lines} to quickly create ranges.
+   *
+   * @example
+   * The following will select the word "console" in the code.
+   * Both lines and columns are 0-based. So it will select a 7-character-long
+   * (`7`) word in the second line (`1`) starting at the third character (`2`).
+   * ```tsx
+   * <Code
+   *   selection={word(1, 2, 7)}
+   *   code={`\
+   * function hello() => {
+   *   console.log('Hello');
+   * }`}
+   *   // ...
+   * />
+   * ```
+   */
+  @initial(lines(0, Infinity))
+  @parser(parseCodeSelection)
+  @signal()
+  declare public readonly selection: Signal<
+    PossibleCodeSelection,
+    CodeSelection,
+    this
+  >;
+  public oldSelection: CodeSelection | null = null;
+  public selectionProgress = createSignal<number | null>(null);
+  protected *tweenSelection(
+    value: CodeRange[],
+    duration: number,
+    timingFunction: TimingFunction,
+  ): ThreadGenerator {
+    this.oldSelection = this.selection();
+    this.selection(value);
+    this.selectionProgress(0);
+    yield* this.selectionProgress(1, duration, timingFunction);
+    this.selectionProgress(null);
+    this.oldSelection = null;
+  }
+
+  /**
+   * Get the currently displayed code as a string.
+   */
+  @computed()
+  public parsed(): string {
+    return resolveScope(this.code(), scope => unwrap(scope.progress) > 0.5);
+  }
+
+  @computed()
+  public highlighterCache() {
+    const highlighter = this.highlighter();
+    if (!highlighter || !highlighter.initialize()) return null;
+    const code = this.code();
+    const before = resolveScope(code, false);
+    const after = resolveScope(code, true);
+
+    return {
+      before: highlighter.prepare(before),
+      after: highlighter.prepare(after),
+    };
+  }
+
+  private cursorCache: CodeCursor | undefined;
+  private get cursor() {
+    this.cursorCache ??= new CodeCursor(this);
+    return this.cursorCache;
+  }
+
+  public constructor(props: CodeProps) {
+    super({
+      fontFamily: 'monospace',
+      highlighter: Code.defaultHighlighter,
+      ...props,
+    });
+  }
+
+  /**
+   * Create a child code signal.
+   *
+   * @param initial - The initial code.
+   */
+  public createSignal(
+    initial: SignalValue<PossibleCodeScope>,
+  ): CodeSignal<this> {
+    return new CodeSignalContext<this>(
+      initial,
+      this,
+      this.highlighter,
+    ).toSignal();
+  }
+
+  /**
+   * Find all code ranges that match the given pattern.
+   *
+   * @param pattern - Either a string or a regular expression to search for.
+   *                  When a string is passed, it looks for **exact matches**.
+   *                  When a RegExp object is passed, it will match against it.
+   */
+  public findAllRanges(pattern: string | RegExp): CodeRange[] {
+    return findAllCodeRanges(this.parsed(), pattern);
+  }
+
+  /**
+   * Find the first code range that matches the given pattern.
+   *
+   * @param pattern - Either a string or a regular expression to search for.
+   *                  When a string is passed, it looks for **exact matches**.
+   *                  When a RegExp object is passed, it will match against it.
+   */
+  public findFirstRange(pattern: string | RegExp): CodeRange {
+    return (
+      findAllCodeRanges(this.parsed(), pattern, 1)[0] ?? [
+        [0, 0],
+        [0, 0],
+      ]
+    );
+  }
+
+  /**
+   * Find the last code range that matches the given pattern.
+   *
+   * @param pattern - Either a string or a regular expression to search for.
+   *                  When a string is passed, it looks for **exact matches**.
+   *                  When a RegExp object is passed, it will match against it.
+   */
+  public findLastRange(pattern: string | RegExp): CodeRange {
+    return (
+      findAllCodeRanges(this.parsed(), pattern).at(-1) ?? [
+        [0, 0],
+        [0, 0],
+      ]
+    );
+  }
+
+  /**
+   * Return the bounding box of the given point (character) in the code.
+   *
+   * @remarks
+   * The returned bound box is in local space of the `Code` node.
+   *
+   * @param point - The point to get the bounding box for.
+   */
+  public getPointBBox(point: CodePoint): BBox {
+    const [line, column] = point;
+    const drawingInfo = this.drawingInfo();
+    let match: CodeFragmentDrawingInfo | undefined;
+    for (const info of drawingInfo.fragments) {
+      if (info.cursor.y < line) {
+        match = info;
+        continue;
+      }
+
+      if (info.cursor.y === line && info.cursor.x < column) {
+        match = info;
+        continue;
+      }
+
+      break;
+    }
+
+    if (!match) return new BBox();
+
+    const size = this.computedSize();
+    return new BBox(
+      match.position
+        .sub(size.scale(0.5))
+        .addX(match.characterSize.x * (column - match.cursor.x)),
+      match.characterSize,
+    );
+  }
+
+  /**
+   * Return bounding boxes of all characters in the selection.
+   *
+   * @remarks
+   * The returned bounding boxes are in local space of the `Code` node.
+   * Each line of code has a separate bounding box.
+   *
+   * @param selection - The selection to get the bounding boxes for.
+   */
+  public getSelectionBBox(selection: PossibleCodeSelection): BBox[] {
+    const size = this.computedSize();
+    const range = parseCodeSelection(selection);
+    const drawingInfo = this.drawingInfo();
+    const bboxes: BBox[] = [];
+
+    let current: BBox | null = null;
+    let line = 0;
+    let column = 0;
+    for (const info of drawingInfo.fragments) {
+      if (info.cursor.y !== line) {
+        line = info.cursor.y;
+        if (current) {
+          bboxes.push(current);
+          current = null;
+        }
+      }
+
+      column = info.cursor.x;
+      for (let i = 0; i < info.text.length; i++) {
+        if (isPointInCodeSelection([line, column], range)) {
+          const bbox = new BBox(
+            info.position
+              .sub(size.scale(0.5))
+              .addX(info.characterSize.x * (column - info.cursor.x)),
+            info.characterSize,
+          );
+          if (!current) {
+            current = bbox;
+          } else {
+            current = current.union(bbox);
+          }
+        } else if (current) {
+          bboxes.push(current);
+          current = null;
+        }
+
+        column++;
+      }
+    }
+
+    if (current) {
+      bboxes.push(current);
+    }
+
+    return bboxes;
+  }
+
+  @computed()
+  protected drawingInfo() {
+    this.requestFontUpdate();
+    const context = this.cacheCanvas();
+    const code = this.code();
+
+    context.save();
+    this.applyStyle(context);
+    this.applyText(context);
+    this.cursor.setupDraw(context);
+    this.cursor.drawScope(code);
+    const info = this.cursor.getDrawingInfo();
+    context.restore();
+
+    return info;
+  }
+
+  protected override desiredSize(): SerializedVector2<DesiredLength> {
+    this.requestFontUpdate();
+    const context = this.cacheCanvas();
+    const code = this.code();
+
+    context.save();
+    this.applyStyle(context);
+    this.applyText(context);
+    this.cursor.setupMeasure(context);
+    this.cursor.measureSize(code);
+    const size = this.cursor.getSize();
+    context.restore();
+
+    return size;
+  }
+
+  protected override draw(context: CanvasRenderingContext2D): void {
+    this.requestFontUpdate();
+    this.applyStyle(context);
+    this.applyText(context);
+    const size = this.computedSize();
+    const drawingInfo = this.drawingInfo();
+
+    context.save();
+    context.translate(
+      -size.width / 2,
+      -size.height / 2 + drawingInfo.verticalOffset,
+    );
+
+    const drawHooks = this.drawHooks();
+    for (const info of drawingInfo.fragments) {
+      context.save();
+      context.globalAlpha *= info.alpha;
+      drawHooks.token(context, info.text, info.position, info.fill, info.time);
+      context.restore();
+    }
+
+    context.restore();
+
+    this.drawChildren(context);
+  }
+
+  protected override applyText(context: CanvasRenderingContext2D) {
+    super.applyText(context);
+    context.font = this.styles.font;
+    context.textBaseline = 'top';
+    if ('letterSpacing' in context) {
+      context.letterSpacing = this.styles.letterSpacing;
+    }
+  }
+
+  protected override collectAsyncResources(): void {
+    super.collectAsyncResources();
+    this.highlighter()?.initialize();
+  }
+}