@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/src/internal/SelectAllScopePlugin.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file SelectAllScopePlugin.tsx
+ * @input Uses @lexical/react (composer context), @lexical/code (CodeNode),
+ *   @lexical/table (TableCellNode), and lexical (the select-all command and
+ *   selection).
+ * @output Exports SelectAllScopePlugin, which makes Cmd+A (Ctrl+A off Apple
+ *   platforms) select the content of the code block or table cell holding the
+ *   caret first, and the whole document on the next press.
+ * @position Rendered by RichTextEditor, always on; a read-only or disabled
+ *   editor keeps the browser's and Lexical's select all. Elsewhere, and when
+ *   the selection already covers its code block or cell or runs outside it,
+ *   the press falls through to Lexical's own select all, which takes the
+ *   whole document.
+ */
+
+import {useEffect} from 'react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$isCodeNode} from '@lexical/code';
+import {$isTableCellNode} from '@lexical/table';
+import {
+  $getSelection,
+  $isBlockFullySelected,
+  $isRangeSelection,
+  COMMAND_PRIORITY_NORMAL,
+  SELECT_ALL_COMMAND,
+  type ElementNode,
+  type LexicalEditor,
+  type LexicalNode,
+} from 'lexical';
+
+/** Whether select all stops at `node` before taking the whole document. */
+function $isScope(node: LexicalNode): node is ElementNode {
+  return $isCodeNode(node) || $isTableCellNode(node);
+}
+
+/** The scopes holding `node`, innermost first. */
+function $scopesOf(node: LexicalNode): Array<ElementNode> {
+  const scopes: Array<ElementNode> = [];
+  for (let at: LexicalNode | null = node; at !== null; at = at.getParent()) {
+    if ($isScope(at)) {
+      scopes.push(at);
+    }
+  }
+  return scopes;
+}
+
+/**
+ * Selects the content of the innermost scope that holds the whole selection
+ * and is not yet fully selected; false, to let the document be selected,
+ * when there is none.
+ */
+function $selectScope(): boolean {
+  const selection = $getSelection();
+  if (!$isRangeSelection(selection)) {
+    return false;
+  }
+  const focusScopes = $scopesOf(selection.focus.getNode());
+  for (const scope of $scopesOf(selection.anchor.getNode())) {
+    if (
+      focusScopes.some(each => each.is(scope)) &&
+      !$isBlockFullySelected(scope, selection)
+    ) {
+      scope.select(0, scope.getChildrenSize());
+      return true;
+    }
+  }
+  return false;
+}
+
+function registerSelectAllScope(editor: LexicalEditor): () => void {
+  return editor.registerCommand(
+    SELECT_ALL_COMMAND,
+    () => editor.isEditable() && $selectScope(),
+    COMMAND_PRIORITY_NORMAL,
+  );
+}
+
+export function SelectAllScopePlugin(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => registerSelectAllScope(editor), [editor]);
+  return null;
+}

package/src/internal/TableColumnFloorPlugin.tsx

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TableColumnFloorPlugin.tsx
+ * @input Uses @lexical/react (composer context), @lexical/table, and lexical.
+ * @output Exports TableColumnFloorPlugin, which gives each table column core
+ *   Markdown's readable width floor, and tableColumnFloors, the rule itself.
+ * @position Rendered by RichTextEditor and RichTextView. Matches core
+ *   Markdown's table column floors (spec:AST-061 FR4): automatic table layout
+ *   already keeps every column at least as wide as its longest word, but a
+ *   prose column's longest word is short, so a narrow table still wraps one
+ *   word per line. The floor lets a column's longest cell wrap to about two
+ *   lines instead, keeps a header label on one line up to a cap, and stays
+ *   bounded so a table of short columns still fits; a wider table scrolls
+ *   inside its wrapper. The floors are `ch` on content-box cells, so they
+ *   follow the reader's font size and cell padding does not eat into them.
+ */
+
+import {useEffect} from 'react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$isTableCellNode, $isTableNode, $isTableRowNode} from '@lexical/table';
+import {$getRoot} from 'lexical';
+
+const TABLE_COLUMN_MIN_CH = 4;
+const TABLE_COLUMN_MAX_CH = 24;
+const TABLE_COLUMN_TARGET_LINES = 2;
+const TABLE_HEADER_ONE_LINE_MAX_CH = 20;
+
+/**
+ * Each column's floor in `ch`, from the text length of every cell, header row
+ * first: the longest cell wraps to about two lines, the header reads on one
+ * line up to its cap, and every floor stays between the bounds.
+ */
+export function tableColumnFloors(
+  rows: ReadonlyArray<ReadonlyArray<number>>,
+): Array<number> {
+  const [header, ...body] = rows;
+  if (header == null) {
+    return [];
+  }
+  return header.map((headerLength, column) => {
+    const longest = Math.max(
+      headerLength,
+      ...body.map(row => row[column] ?? 0),
+    );
+    const bodyFloor = Math.ceil(longest / TABLE_COLUMN_TARGET_LINES);
+    const headerFloor = Math.min(headerLength, TABLE_HEADER_ONE_LINE_MAX_CH);
+    return Math.min(
+      TABLE_COLUMN_MAX_CH,
+      Math.max(TABLE_COLUMN_MIN_CH, bodyFloor, headerFloor),
+    );
+  });
+}
+
+/**
+ * Sets each top-level table's header cells to their column's floor after
+ * every update, so the floors follow edits.
+ */
+export function TableColumnFloorPlugin(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    let frame = 0;
+    const apply = () => {
+      frame = 0;
+      editor.getEditorState().read(() => {
+        for (const table of $getRoot().getChildren().filter($isTableNode)) {
+          const rows = table
+            .getChildren()
+            .filter($isTableRowNode)
+            .map(row => row.getChildren().filter($isTableCellNode));
+          const floors = tableColumnFloors(
+            rows.map(cells => cells.map(cell => cell.getTextContentSize())),
+          );
+          rows[0]?.forEach((cell, column) => {
+            const element = editor.getElementByKey(cell.getKey());
+            const floor = `${floors[column]}ch`;
+            if (element != null && element.style.minWidth !== floor) {
+              element.style.minWidth = floor;
+            }
+          });
+        }
+      });
+    };
+    const schedule = () => {
+      if (frame === 0) {
+        frame = requestAnimationFrame(apply);
+      }
+    };
+    const unregister = editor.registerUpdateListener(schedule);
+    schedule();
+    return () => {
+      cancelAnimationFrame(frame);
+      unregister();
+    };
+  }, [editor]);
+  return null;
+}

package/src/internal/TablePastePlugin.tsx

@@ -0,0 +1,223 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TablePastePlugin.tsx
+ * @input Uses @lexical/react (composer context), @lexical/table,
+ *   @lexical/utils, and lexical.
+ * @output Exports TablePastePlugin, which pastes into a table's cells without
+ *   dropping any of the paste or emptying a cell.
+ * @position Rendered by RichTextEditor beside TablePlugin. It answers a paste
+ *   that holds a table, made with the selection in one table's cells, ahead of
+ *   TablePlugin's own handler. That handler refuses a table that comes with
+ *   other content, and fits a pasted merged cell by merging the cells under
+ *   it, which drops their text.
+ */
+
+import {useEffect} from 'react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $computeTableCellRectBoundary,
+  $computeTableMap,
+  $computeTableMapSkipCellCheck,
+  $insertTableColumnAtNode,
+  $insertTableRowAtNode,
+  $isTableCellNode,
+  $isTableNode,
+  $isTableSelection,
+  type TableCellNode,
+  type TableNode,
+  type TableSelection,
+} from '@lexical/table';
+import {$dfs, $findMatchingParent} from '@lexical/utils';
+import {$startsInCodeBlock} from './CodePastePlugin';
+import {
+  $createParagraphNode,
+  $createTabNode,
+  $createTextNode,
+  $isRangeSelection,
+  COMMAND_PRIORITY_LOW,
+  SELECTION_INSERT_CLIPBOARD_NODES_COMMAND,
+  type BaseSelection,
+  type LexicalNode,
+  type ParagraphNode,
+  type RangeSelection,
+} from 'lexical';
+
+/** A selection that starts and ends in cells of one table. */
+interface CellSelection {
+  readonly selection: RangeSelection | TableSelection;
+  readonly table: TableNode;
+  readonly anchorCell: TableCellNode;
+  readonly focusCell: TableCellNode;
+}
+
+function $cellSelection(selection: BaseSelection): CellSelection | null {
+  if (!$isRangeSelection(selection) && !$isTableSelection(selection)) {
+    return null;
+  }
+  const points = selection.getStartEndPoints();
+  if (points == null) {
+    return null;
+  }
+  const anchorCell = $findMatchingParent(points[0].getNode(), $isTableCellNode);
+  const focusCell = $findMatchingParent(points[1].getNode(), $isTableCellNode);
+  if (anchorCell == null || focusCell == null) {
+    return null;
+  }
+  const table = $findMatchingParent(anchorCell, $isTableNode);
+  if (table == null || !table.isParentOf(focusCell)) {
+    return null;
+  }
+  return {selection, table, anchorCell, focusCell};
+}
+
+/**
+ * Writes a pasted table into the table cell by cell, starting at the
+ * top-left selected cell and adding the rows and columns it reaches past the
+ * table's edge; selected cells bound it instead. Each pasted cell replaces
+ * what its cell held. A merged pasted cell fills only the cell where it
+ * starts: the rest of its span, like the missing end of a short row, leaves
+ * the cells under it as they were, so no cell is merged or emptied.
+ */
+function $pasteTableIntoCells(
+  pasted: TableNode,
+  {selection, table, anchorCell, focusCell}: CellSelection,
+): void {
+  const [grid, anchorEntry, focusEntry] = $computeTableMap(
+    table,
+    anchorCell,
+    focusCell,
+  );
+  const {minRow, minColumn, maxRow, maxColumn} = $computeTableCellRectBoundary(
+    grid,
+    anchorEntry,
+    focusEntry,
+  );
+  const [source] = $computeTableMapSkipCellCheck(pasted, null, null);
+  // Pasted rows can differ in length, so the widest one sets the width.
+  let rows = source.length;
+  let columns = Math.max(0, ...source.map(row => row.length));
+  if ($isTableSelection(selection)) {
+    rows = Math.min(rows, maxRow - minRow + 1);
+    columns = Math.min(columns, maxColumn - minColumn + 1);
+  }
+  for (let count = grid.length; count < minRow + rows; count++) {
+    const [current] = $computeTableMapSkipCellCheck(table, null, null);
+    $insertTableRowAtNode(current[current.length - 1][0].cell);
+  }
+  for (let count = grid[0].length; count < minColumn + columns; count++) {
+    const [current] = $computeTableMapSkipCellCheck(table, null, null);
+    $insertTableColumnAtNode(
+      current[0][current[0].length - 1].cell,
+      true,
+      false,
+    );
+  }
+  const [target] = $computeTableMapSkipCellCheck(table, null, null);
+  for (let row = 0; row < rows; row++) {
+    for (let column = 0; column < columns; column++) {
+      const entry = source[row][column];
+      if (
+        entry == null ||
+        entry.startRow !== row ||
+        entry.startColumn !== column
+      ) {
+        continue;
+      }
+      const cell = target[minRow + row][minColumn + column].cell;
+      const replaced = cell.getChildren();
+      cell.append(...entry.cell.getChildren());
+      for (const node of replaced) {
+        node.remove();
+      }
+    }
+  }
+  target[minRow][minColumn].cell.selectEnd();
+}
+
+/**
+ * A table as text a cell can hold: a paragraph per row, with the text of the
+ * row's cells between tabs. A merged cell's text appears once, where the
+ * cell starts.
+ */
+function $tableAsParagraphs(table: TableNode): Array<ParagraphNode> {
+  const [grid] = $computeTableMapSkipCellCheck(table, null, null);
+  return grid.map((row, rowIndex) => {
+    const paragraph = $createParagraphNode();
+    row.forEach((entry, column) => {
+      if (column > 0) {
+        paragraph.append($createTabNode());
+      }
+      if (entry.startRow !== rowIndex || entry.startColumn !== column) {
+        return;
+      }
+      const text = entry.cell.getTextContent().replace(/\s+/g, ' ').trim();
+      if (text !== '') {
+        paragraph.append($createTextNode(text));
+      }
+    });
+    return paragraph;
+  });
+}
+
+/** `node` with every table in it, or the node itself if a table, as text. */
+function $withTablesAsText(node: LexicalNode): Array<LexicalNode> {
+  if ($isTableNode(node)) {
+    return $tableAsParagraphs(node);
+  }
+  for (const {node: inner} of $dfs(node)) {
+    if ($isTableNode(inner)) {
+      for (const paragraph of $tableAsParagraphs(inner)) {
+        inner.insertBefore(paragraph);
+      }
+      inner.remove();
+    }
+  }
+  return [node];
+}
+
+/**
+ * Pastes a table into a table's cells. A table alone goes in cell by cell
+ * (`$pasteTableIntoCells`). A table that comes with other content, such as
+ * the paragraph and table a web page copies, goes into the cell with each
+ * table as text, since a cell holds no table. Any other paste is left to
+ * the editor's own handlers.
+ */
+export function TablePastePlugin(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(
+    () =>
+      editor.registerCommand(
+        SELECTION_INSERT_CLIPBOARD_NODES_COMMAND,
+        ({nodes, selection}, dispatchEditor) => {
+          // A paste into a code block, even one in a cell, belongs to
+          // CodePastePlugin, which adds plain code lines.
+          if (
+            dispatchEditor !== editor ||
+            $startsInCodeBlock(selection) ||
+            !nodes.some(node =>
+              $dfs(node).some(({node: inner}) => $isTableNode(inner)),
+            )
+          ) {
+            return false;
+          }
+          const cells = $cellSelection(selection);
+          if (cells == null) {
+            return false;
+          }
+          if (nodes.length === 1 && $isTableNode(nodes[0])) {
+            $pasteTableIntoCells(nodes[0], cells);
+          } else {
+            cells.selection.insertNodes(nodes.flatMap($withTablesAsText));
+          }
+          return true;
+        },
+        // Ahead of TablePlugin's handler, which runs at the editor priority.
+        COMMAND_PRIORITY_LOW,
+      ),
+    [editor],
+  );
+  return null;
+}

package/src/internal/TableScrollRegionPlugin.tsx

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TableScrollRegionPlugin.tsx
+ * @input Lexical's TableNode mutations, the scroll wrapper that TablePlugin's
+ *   horizontal-scroll mode renders around each table, and core's translator
+ *   for the region's name.
+ * @output TableScrollRegionPlugin: gives each table's scroll wrapper the
+ *   semantics of core Table's scroll region.
+ * @position Internal to @blue-patterns/richtext; rendered by RichTextView only.
+ *   The editor needs none of this: its caret scrolls a wide table, and a tab
+ *   stop inside the editable surface would break Escape-then-Tab.
+ */
+
+import {useEffect} from 'react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {TableNode} from '@lexical/table';
+import {useTranslator} from '@blue-patterns/core/i18n';
+
+interface TrackedRegion {
+  readonly wrapper: HTMLElement;
+  readonly observer: ResizeObserver | null;
+}
+
+/** A tab stop only while the table is wider than its wrapper. */
+function syncTabStop(wrapper: HTMLElement): void {
+  if (wrapper.scrollWidth > wrapper.clientWidth) {
+    wrapper.tabIndex = 0;
+  } else {
+    wrapper.removeAttribute('tabindex');
+  }
+}
+
+/**
+ * A read-only view has no caret, so nothing inside a wide table can scroll it
+ * from the keyboard. Like core Table's scroll region, each table's wrapper is
+ * a group named "Table" that takes a tab stop only while the table overflows
+ * it; a table that fits adds no stop. The tab stop is explicit, so browsers
+ * that do not make scroll containers focusable on their own still reach it.
+ */
+export function TableScrollRegionPlugin(): null {
+  const [editor] = useLexicalComposerContext();
+  const t = useTranslator();
+  const label = t('@astryx.table.label');
+
+  useEffect(() => {
+    const regions = new Map<string, TrackedRegion>();
+
+    const release = (key: string) => {
+      regions.get(key)?.observer?.disconnect();
+      regions.delete(key);
+    };
+
+    const track = (key: string) => {
+      // With horizontal scroll active, a table node's DOM is its wrapper.
+      const wrapper = editor.getElementByKey(key);
+      if (!(wrapper instanceof HTMLDivElement)) {
+        release(key);
+        return;
+      }
+      if (regions.get(key)?.wrapper === wrapper) {
+        syncTabStop(wrapper);
+        return;
+      }
+      release(key);
+      wrapper.setAttribute('role', 'group');
+      wrapper.setAttribute('aria-label', label);
+      let observer: ResizeObserver | null = null;
+      if (typeof ResizeObserver !== 'undefined') {
+        observer = new ResizeObserver(() => syncTabStop(wrapper));
+        // The wrapper resizes with its container, the table with its content.
+        observer.observe(wrapper);
+        const table = wrapper.querySelector(':scope > table');
+        if (table != null) {
+          observer.observe(table);
+        }
+      }
+      regions.set(key, {wrapper, observer});
+      syncTabStop(wrapper);
+    };
+
+    const unregister = editor.registerMutationListener(
+      TableNode,
+      mutations => {
+        for (const [key, mutation] of mutations) {
+          if (mutation === 'destroyed') {
+            release(key);
+          } else {
+            track(key);
+          }
+        }
+      },
+      {skipInitialization: false},
+    );
+
+    return () => {
+      unregister();
+      for (const key of [...regions.keys()]) {
+        release(key);
+      }
+    };
+  }, [editor, label]);
+
+  return null;
+}