Skip to content

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

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

'use client';

/**
 * @file CodeTabPlugin.tsx
 * @input Uses @lexical/react (composer context), @lexical/code (CodeNode), and
 *   lexical.
 * @output Exports CodeTabPlugin, which makes Tab and Shift+Tab in a code block
 *   indent and outdent every line the selection touches, by the indent the
 *   block's own lines use.
 * @position Rendered by RichTextEditor; always on, and not exported from the
 *   package. A press indents by the block's own indent, so edited code keeps
 *   the indentation its author chose; the selection stays on the same
 *   characters, and each press is one undo step. It replaces only what Tab
 *   did in a code block before: TabIndentationPlugin put a tab character in
 *   place of the selection. Its listener sits at the front of the
 *   editor-priority queue, ahead of TabIndentationPlugin and behind every
 *   low-priority listener, so Escape then Tab still moves focus out of the
 *   editor (TabFocusEscapePlugin, WCAG 2.1.2). A selection that reaches
 *   outside the code block keeps TabIndentationPlugin's meaning. Read-only
 *   and disabled editors are unchanged.
 */

import {useEffect} from 'react';
import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
import {$isCodeNode, type CodeNode} from '@lexical/code';
import {
  $addUpdateTag,
  $createTextNode,
  $getSelection,
  $isRangeSelection,
  $isTabNode,
  $isTextNode,
  COMMAND_PRIORITY_BEFORE_EDITOR,
  HISTORY_PUSH_TAG,
  KEY_TAB_COMMAND,
  type LexicalNode,
  type PointType,
  type RangeSelection,
  type TextNode,
} from 'lexical';

/** The narrowest space indent a block uses, and the widest. */
const MIN_SPACE_INDENT = 2;
const MAX_SPACE_INDENT = 8;

function leadingSpaces(line: string): number {
  return /^ */.exec(line)?.[0].length ?? 0;
}

/**
 * The indent a code block's lines use: a tab when any line starts with one;
 * otherwise the fewest spaces an indented line starts with, kept between two
 * and eight; otherwise two spaces.
 */
function codeIndentUnit(lines: ReadonlyArray<string>): string {
  if (lines.some(line => line.startsWith('\t'))) {
    return '\t';
  }
  const widths = lines.map(leadingSpaces).filter(width => width > 0);
  const width = widths.length === 0 ? MIN_SPACE_INDENT : Math.min(...widths);
  return ' '.repeat(
    Math.min(MAX_SPACE_INDENT, Math.max(MIN_SPACE_INDENT, width)),
  );
}

/**
 * A code block's children, the offset in the block's text where each one
 * starts, and that text. A line ends at a line break node or at a newline
 * inside a text node: imported code holds newlines, and Enter adds line
 * break nodes.
 */
interface CodeLayout {
  readonly children: ReadonlyArray<LexicalNode>;
  readonly starts: ReadonlyArray<number>;
  readonly text: string;
}

function $layoutOf(code: CodeNode): CodeLayout {
  const children = code.getChildren();
  const starts: number[] = [];
  let text = '';
  for (const child of children) {
    starts.push(text.length);
    text += child.getTextContent();
  }
  return {children, starts, text};
}

/** A text node that can take a caret and grow: any but a tab node. */
function $isPlainText(node: LexicalNode): node is TextNode {
  return $isTextNode(node) && !$isTabNode(node);
}

/** The code block that holds both ends of the selection, or null. */
function $selectionCodeBlock(selection: RangeSelection): CodeNode | null {
  const blockOf = (point: PointType) => {
    const node = point.getNode();
    return $isCodeNode(node) ? node : node.getParent();
  };
  const block = blockOf(selection.anchor);
  return $isCodeNode(block) && block.is(blockOf(selection.focus))
    ? block
    : null;
}

/** Where a point of the block's selection falls in the block's text. */
function $offsetOf(
  code: CodeNode,
  layout: CodeLayout,
  point: PointType,
): number {
  if (point.key === code.getKey()) {
    return point.offset < layout.children.length
      ? layout.starts[point.offset]
      : layout.text.length;
  }
  const index = layout.children.findIndex(
    child => child.getKey() === point.key,
  );
  return index < 0 ? 0 : layout.starts[index] + point.offset;
}

/**
 * Moves a selection point to an offset in the block's text: into the text
 * node there, or between children where none holds it (beside a tab or a
 * line break, or on an empty line).
 */
function $placePoint(code: CodeNode, point: PointType, offset: number): void {
  const children = code.getChildren();
  let start = 0;
  for (let index = 0; index < children.length; index++) {
    const child = children[index];
    const size = child.getTextContentSize();
    if ($isPlainText(child) && offset >= start && offset <= start + size) {
      point.set(child.getKey(), offset - start, 'text');
      return;
    }
    if (offset <= start) {
      point.set(code.getKey(), index, 'element');
      return;
    }
    start += size;
  }
  point.set(code.getKey(), children.length, 'element');
}

/** Inserts text at an offset in the block's text. */
function $insertAt(code: CodeNode, offset: number, text: string): void {
  const {children, starts} = $layoutOf(code);
  for (let index = 0; index < children.length; index++) {
    const child = children[index];
    const start = starts[index];
    if (
      $isPlainText(child) &&
      offset >= start &&
      offset <= start + child.getTextContentSize()
    ) {
      const content = child.getTextContent();
      const at = offset - start;
      child.setTextContent(content.slice(0, at) + text + content.slice(at));
      return;
    }
    if (offset <= start) {
      child.insertBefore($createTextNode(text));
      return;
    }
  }
  code.append($createTextNode(text));
}

/** Removes `count` characters at an offset in the block's text. */
function $removeAt(code: CodeNode, offset: number, count: number): void {
  const {children, starts} = $layoutOf(code);
  let left = count;
  for (let index = 0; index < children.length && left > 0; index++) {
    const child = children[index];
    const size = child.getTextContentSize();
    if (!$isTextNode(child) || starts[index] + size <= offset) {
      continue;
    }
    const from = Math.max(0, offset - starts[index]);
    const removed = Math.min(left, size - from);
    const content = child.getTextContent();
    const rest = content.slice(0, from) + content.slice(from + removed);
    if (rest === '') {
      child.remove();
    } else {
      child.setTextContent(rest);
    }
    left -= removed;
  }
}

/**
 * Indents, or outdents, every line the selection touches by the block's own
 * indent, and puts the selection back on the characters it held.
 */
function $shiftLines(
  code: CodeNode,
  selection: RangeSelection,
  isOutdent: boolean,
): void {
  const layout = $layoutOf(code);
  const lines = layout.text.split('\n');
  const lineStarts: number[] = [];
  let lineStart = 0;
  for (const line of lines) {
    lineStarts.push(lineStart);
    lineStart += line.length + 1;
  }
  const lineAt = (offset: number) => {
    let line = 0;
    while (line + 1 < lineStarts.length && lineStarts[line + 1] <= offset) {
      line++;
    }
    return line;
  };
  const unit = codeIndentUnit(lines);
  // A tab-indented block outdents a space-indented line by the narrowest
  // space indent.
  const spaceUnit = unit === '\t' ? MIN_SPACE_INDENT : unit.length;
  const anchor = $offsetOf(code, layout, selection.anchor);
  const focus = $offsetOf(code, layout, selection.focus);
  const start = Math.min(anchor, focus);
  const end = Math.max(anchor, focus);
  const first = lineAt(start);
  let last = lineAt(end);
  // A selection that ends where a line begins does not reach into that line.
  if (last > first && lineStarts[last] === end) {
    last--;
  }
  // Each edit as [offset, characters added (negative when removed)], made
  // from the last line up so the offsets of the lines above stay true.
  const edits: Array<readonly [number, number]> = [];
  for (let line = last; line >= first; line--) {
    const at = lineStarts[line];
    if (!isOutdent) {
      $insertAt(code, at, unit);
      edits.push([at, unit.length]);
      continue;
    }
    const removed = lines[line].startsWith('\t')
      ? 1
      : Math.min(leadingSpaces(lines[line]), spaceUnit);
    if (removed > 0) {
      $removeAt(code, at, removed);
      edits.push([at, -removed]);
    }
  }
  // A point keeps its character: text added at or before it pushes it on,
  // and a point inside removed indentation moves to its line's start.
  const shifted = (offset: number) =>
    edits.reduce((moved, [at, delta]) => {
      if (delta > 0) {
        return offset >= at ? moved + delta : moved;
      }
      return offset > at ? moved - Math.min(-delta, offset - at) : moved;
    }, offset);
  $placePoint(code, selection.anchor, shifted(anchor));
  $placePoint(code, selection.focus, shifted(focus));
}

export function CodeTabPlugin(): null {
  const [editor] = useLexicalComposerContext();
  useEffect(
    () =>
      editor.registerCommand(
        KEY_TAB_COMMAND,
        event => {
          const selection = $getSelection();
          if (!editor.isEditable() || !$isRangeSelection(selection)) {
            return false;
          }
          const code = $selectionCodeBlock(selection);
          if (code == null) {
            return false;
          }
          event.preventDefault();
          // One undo step per press, even when a press adds or removes a
          // single character beside the caret. The push tag starts a step
          // before the press. A dirty block makes history class the press
          // as its own change, so typing after it starts another step.
          $addUpdateTag(HISTORY_PUSH_TAG);
          $shiftLines(code, selection, event.shiftKey);
          code.markDirty();
          return true;
        },
        // After TabFocusEscapePlugin's low-priority listener, which lets an
        // armed Tab move focus, and before TabIndentationPlugin's; see the
        // file header.
        COMMAND_PRIORITY_BEFORE_EDITOR,
      ),
    [editor],
  );
  return null;
}