Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
16.1 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file CodeSyntaxPlugin.tsx
 * @input Uses @lexical/react (composer context), @lexical/code (CodeNode),
 *   lexical, core CodeBlock's highlight styles and token types, and
 *   CodeLineTokens (codeLineTokens.ts), core CodeBlock's tokens kept line by
 *   line.
 * @output Exports CodeSyntaxPlugin, which colors the code in every fenced code
 *   block with core CodeBlock's tokenizer and syntax color tokens; and
 *   CODE_SYNTAX_CLASS, the class the theme gives code blocks for it.
 * @position Rendered by RichTextEditor and RichTextView. A fenced code block
 *   with a language core CodeBlock knows is colored as core Markdown colors
 *   it: the same tokenizer finds the same tokens, and each token type takes
 *   its `--color-syntax-*` token (spec:AST-061 FR1) — no palette of its own.
 *   The colors are CSS Custom Highlight ranges over the text Lexical renders,
 *   the way core CodeBlock colors editable code, so the document and its DOM
 *   are untouched. A block is colored in full when it appears, or when its
 *   language, its element, or its set of text nodes changes. An edit that
 *   only rewrites one text node's text re-tokenizes just the lines
 *   CodeLineTokens says it can change, and replaces only the ranges in that
 *   text node, reading no other. Browsers without the Highlight API show
 *   plain code.
 */

import {useEffect, useState} from 'react';
import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
import {$isCodeNode, CodeNode} from '@lexical/code';
import {
  $getNodeByKey,
  $isTextNode,
  type LexicalEditor,
  type NodeKey,
  type NodeMutation,
} from 'lexical';
import {
  ensureHighlightStyles,
  TOKEN_TYPES,
  type CodeLanguage,
} from '@astryxdesign/core/CodeBlock';
import {listedLanguage, sameLanguages} from './codeLanguages';
import {CodeLineTokens} from './codeLineTokens';

/** The class the theme adds to every code block (editorTheme.ts). */
export const CODE_SYNTAX_CLASS = 'astryx-richtext-code';

let hasInjectedRules = false;

/**
 * The highlight rules for code blocks, injected once: each token type takes
 * the same syntax color token core CodeBlock's rules use.
 */
function ensureRules(): void {
  if (hasInjectedRules || typeof document === 'undefined') {
    return;
  }
  hasInjectedRules = true;
  const style = document.createElement('style');
  style.setAttribute('data-astryx-richtext-code-syntax', '');
  style.textContent = TOKEN_TYPES.map(
    type =>
      `.${CODE_SYNTAX_CLASS}::highlight(astryx-${type}) { color: var(--color-syntax-${type}); }`,
  ).join('\n');
  document.head.append(style);
}

function supportsHighlights(): boolean {
  return (
    typeof CSS !== 'undefined' &&
    'highlights' in CSS &&
    typeof Highlight !== 'undefined'
  );
}

/** A colored token: its range, and the highlight that holds it. */
interface Painted {
  readonly range: Range;
  readonly highlight: Highlight;
}

/**
 * A colored code block, with what an edit needs to recolor part of it.
 * Offsets in the rendered text are offsets in the block's DOM text nodes
 * laid end to end, which is the code itself when its line breaks render as
 * text, and the code without them when each renders as an element (`flat`).
 */
interface Colored {
  readonly element: HTMLElement;
  readonly language: string;
  readonly lines: CodeLineTokens;
  readonly flat: boolean;
  /** The block's DOM text nodes in order. */
  readonly texts: Text[];
  /** Where each DOM text node starts in the rendered text. */
  readonly starts: number[];
  /** Where each leaf's DOM text node starts in the code (NaN for others). */
  readonly codeStarts: number[];
  /** The rendered text's length. */
  length: number;
  /** The Lexical text nodes that render as one DOM text node each, by key:
   *  that node's index in `texts`, and the text last colored. */
  readonly leaves: Map<NodeKey, {readonly index: number; text: string}>;
  /** Each line's colored tokens. */
  ranges: Painted[][];
}

function highlightFor(type: string): Highlight {
  const name = `astryx-${type}`;
  let highlight = CSS.highlights.get(name);
  if (highlight == null) {
    highlight = new Highlight();
    CSS.highlights.set(name, highlight);
  }
  return highlight;
}

/**
 * The DOM position of `offset` in a block's rendered text: in the text node
 * that holds the character there when `inside`, else in the first text node
 * that reaches it. Null past the end of the text.
 */
function pointAt(
  block: Colored,
  offset: number,
  inside: boolean,
): [Text, number] | null {
  const {texts, starts, length} = block;
  if (texts.length === 0 || offset > length) {
    return null;
  }
  let low = 0;
  let high = texts.length - 1;
  while (low < high) {
    const mid = (low + high) >>> 1;
    const end = mid + 1 < texts.length ? starts[mid + 1] : length;
    if (inside ? end > offset : end >= offset) {
      high = mid;
    } else {
      low = mid + 1;
    }
  }
  return [texts[low], offset - starts[low]];
}

/** Colors one line's tokens. */
function paintLine(block: Colored, line: number): void {
  // A flat block's rendered text has no line breaks before this line.
  const base = block.lines.starts[line] - (block.flat ? line : 0);
  const painted: Painted[] = [];
  for (const token of block.lines.tokens[line] ?? []) {
    const start = base + token.start;
    const end = base + token.end;
    const from = pointAt(block, start, start < end);
    const to = pointAt(block, end, false);
    if (from == null || to == null) {
      continue;
    }
    const highlight = highlightFor(token.type);
    try {
      const range = new Range();
      range.setStart(...from);
      range.setEnd(...to);
      highlight.add(range);
      painted.push({range, highlight});
    } catch {
      // A range the DOM refuses colors nothing.
    }
  }
  block.ranges[line] = painted;
}

function unpaintLine(block: Colored, line: number): void {
  for (const {range, highlight} of block.ranges[line] ?? []) {
    highlight.delete(range);
  }
  block.ranges[line] = [];
}

function unpaintAll(block: Colored): void {
  for (let line = 0; line < block.ranges.length; line++) {
    unpaintLine(block, line);
  }
  block.ranges = [];
}

function repaintAll(block: Colored): void {
  unpaintAll(block);
  for (let line = 0; line < block.lines.tokens.length; line++) {
    paintLine(block, line);
  }
}

/**
 * Lists a block's DOM text nodes in order with their offsets, and the
 * Lexical text nodes that render as exactly one of them.
 */
function $indexText(
  editor: LexicalEditor,
  node: CodeNode,
  block: Colored,
): void {
  const walker = document.createTreeWalker(block.element, NodeFilter.SHOW_TEXT);
  while (walker.nextNode() != null) {
    const text = walker.currentNode as Text;
    block.texts.push(text);
    block.starts.push(block.length);
    block.codeStarts.push(NaN);
    block.length += text.length;
  }
  const indexes = new Map(block.texts.map((text, index) => [text, index]));
  let codeStart = 0;
  for (const child of node.getChildren()) {
    const dom = $isTextNode(child)
      ? editor.getElementByKey(child.getKey())
      : null;
    const index =
      dom?.childNodes.length === 1
        ? indexes.get(dom.firstChild as Text)
        : undefined;
    if (index != null) {
      block.leaves.set(child.getKey(), {index, text: child.getTextContent()});
      block.codeStarts[index] = codeStart;
    }
    codeStart += child.getTextContentSize();
  }
}

/** The key of the code block that holds the node `key`, if any. */
function $codeBlockOf(key: NodeKey): NodeKey | null {
  let node = $getNodeByKey(key)?.getParent() ?? null;
  while (node != null && !$isCodeNode(node)) {
    node = node.getParent();
  }
  return node?.getKey() ?? null;
}

export function CodeSyntaxPlugin({
  codeLanguages,
}: {
  /** Language values a fence may name (component:Markdown FR30). */
  codeLanguages?: ReadonlyArray<CodeLanguage>;
} = {}): null {
  const [editor] = useLexicalComposerContext();
  // Keep one list while it names the same values, so an inline
  // `codeLanguages={[…]}` does not re-colour every block on each parent
  // render (adjusting state during render, not in an Effect).
  const [languages, setLanguages] = useState(codeLanguages);
  if (!sameLanguages(languages, codeLanguages)) {
    setLanguages(codeLanguages);
  }

  // Synchronizes the editor's code blocks with the CSS highlight registry:
  // Lexical mutation and update listeners colour each block, and the cleanup
  // removes the listeners and every highlight range they added.
  useEffect(() => {
    if (!supportsHighlights()) {
      return undefined;
    }
    ensureRules();
    // Every code block in the editor, the ones colored, and the ones colored
    // in full during the current update.
    const blocks = new Set<NodeKey>();
    const colored = new Map<NodeKey, Colored>();
    const repainted = new Set<NodeKey>();
    const uncolor = (key: NodeKey) => {
      const block = colored.get(key);
      if (block != null) {
        unpaintAll(block);
        colored.delete(key);
      }
    };
    // Colors a block in full, unless `force` is false and its element,
    // language, and code are as last colored.
    const $color = (key: NodeKey, force: boolean) => {
      const node = $getNodeByKey(key);
      const element = editor.getElementByKey(key);
      if (!$isCodeNode(node) || element == null) {
        uncolor(key);
        return;
      }
      const code = node.getTextContent();
      const language = node.getLanguage() ?? '';
      const previous = colored.get(key);
      if (
        !force &&
        previous != null &&
        previous.element === element &&
        previous.language === language &&
        previous.lines.text === code
      ) {
        return;
      }
      uncolor(key);
      const rendered = element.textContent ?? '';
      if (rendered !== code && rendered !== code.replaceAll('\n', '')) {
        // Not rendered yet; the block's next change tries again.
        return;
      }
      ensureHighlightStyles();
      const block: Colored = {
        element,
        language,
        lines: new CodeLineTokens(
          code,
          listedLanguage(languages, language) ?? language,
        ),
        flat: rendered !== code,
        texts: [],
        starts: [],
        codeStarts: [],
        length: 0,
        leaves: new Map(),
        ranges: [],
      };
      $indexText(editor, node, block);
      repaintAll(block);
      colored.set(key, block);
      repainted.add(key);
    };
    // Recolors a block after an update that rewrote the text of its leaf
    // `leafKey` and changed nothing else in it. False when the block must
    // be colored in full instead.
    const $recolorLeaf = (key: NodeKey, leafKey: NodeKey): boolean => {
      const block = colored.get(key);
      const leaf = block?.leaves.get(leafKey);
      const node = $getNodeByKey(leafKey);
      const parent = node?.getParent();
      if (
        block == null ||
        leaf == null ||
        !$isTextNode(node) ||
        !$isCodeNode(parent) ||
        parent.getKey() !== key ||
        (parent.getLanguage() ?? '') !== block.language ||
        editor.getElementByKey(key) !== block.element
      ) {
        return false;
      }
      const text = block.texts[leaf.index];
      const dom = editor.getElementByKey(leafKey);
      const after = node.getTextContent();
      if (
        dom?.childNodes.length !== 1 ||
        dom.firstChild !== text ||
        text.data !== after
      ) {
        return false;
      }
      const before = leaf.text;
      if (after === before) {
        return true;
      }
      let first = 0;
      while (
        first < before.length &&
        first < after.length &&
        before[first] === after[first]
      ) {
        first++;
      }
      let beforeEnd = before.length;
      let afterEnd = after.length;
      while (
        beforeEnd > first &&
        afterEnd > first &&
        before[beforeEnd - 1] === after[afterEnd - 1]
      ) {
        beforeEnd--;
        afterEnd--;
      }
      const inserted = after.slice(first, afterEnd);
      // A flat block's text holds no line breaks; one typed in would no
      // longer lay the code over its rendered text.
      if (block.flat && inserted.includes('\n')) {
        return false;
      }
      const leafStart = block.codeStarts[leaf.index];
      const lines = block.lines.replace(
        leafStart + first,
        beforeEnd - first,
        inserted,
      );
      const delta = after.length - before.length;
      for (let i = leaf.index + 1; i < block.texts.length; i++) {
        block.starts[i] += delta;
        block.codeStarts[i] += delta;
      }
      block.length += delta;
      leaf.text = after;
      if (lines == null) {
        repaintAll(block);
        return true;
      }
      // Lexical rewrites a changed DOM text node whole, which leaves every
      // range in it stale: recolor each line the node holds, and any other
      // line the edit re-tokenized. Every other range sits in a text node of
      // its own line and is still right.
      const recolor = new Set(lines);
      const last = block.lines.lineAt(
        leafStart + Math.max(after.length - 1, 0),
      );
      for (let i = block.lines.lineAt(leafStart); i <= last; i++) {
        recolor.add(i);
      }
      for (const i of recolor) {
        unpaintLine(block, i);
        paintLine(block, i);
      }
      return true;
    };
    const unregisterMutations = editor.registerMutationListener(
      CodeNode,
      mutations => {
        editor.getEditorState().read(() => {
          for (const [key, mutation] of mutations) {
            if (mutation === 'destroyed') {
              blocks.delete(key);
              uncolor(key);
            } else {
              blocks.add(key);
              $color(key, false);
            }
          }
        });
      },
      {skipInitialization: false},
    );
    repainted.clear();
    // Typing in a block changes its text nodes, not the block itself: after
    // each update, recolor the blocks whose text nodes changed. A block whose
    // only change is one leaf's text takes the partial path; any other
    // change colors it in full, unless the block listener just did.
    const unregisterUpdates = editor.registerUpdateListener(
      ({editorState, mutatedNodes, prevEditorState}) => {
        if (mutatedNodes != null && blocks.size > 0) {
          const mutations: Array<[NodeKey, NodeMutation]> = [];
          for (const nodes of mutatedNodes.values()) {
            for (const mutation of nodes) {
              mutations.push(mutation);
            }
          }
          const before = prevEditorState.read(() =>
            mutations.map(([key, mutation]) =>
              mutation === 'created' ? null : $codeBlockOf(key),
            ),
          );
          editorState.read(() => {
            // Each changed block, with the one leaf whose text an update
            // rewrote, or null when anything else in it changed.
            const changed = new Map<NodeKey, NodeKey | null>();
            const note = (key: NodeKey | null, leafKey: NodeKey | null) => {
              if (key != null && blocks.has(key)) {
                changed.set(key, changed.has(key) ? null : leafKey);
              }
            };
            mutations.forEach(([key, mutation], i) => {
              const after = mutation === 'destroyed' ? null : $codeBlockOf(key);
              const rewritten =
                mutation === 'updated' &&
                after === before[i] &&
                $isTextNode($getNodeByKey(key));
              note(after, rewritten ? key : null);
              if (before[i] !== after) {
                note(before[i], null);
              }
            });
            for (const [key, leafKey] of changed) {
              if (
                !repainted.has(key) &&
                (leafKey == null || !$recolorLeaf(key, leafKey))
              ) {
                $color(key, true);
              }
            }
          });
        }
        repainted.clear();
      },
    );
    return () => {
      unregisterMutations();
      unregisterUpdates();
      for (const key of [...colored.keys()]) {
        uncolor(key);
      }
      blocks.clear();
    };
  }, [editor, languages]);

  return null;
}