@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/src/internal/CodeBackspacePlugin.tsx

@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file CodeBackspacePlugin.tsx
+ * @input Uses @lexical/react (composer context), @lexical/code (CodeNode), and
+ *   lexical.
+ * @output Exports CodeBackspacePlugin, which makes Backspace at the very start
+ *   of a code block turn the block into a paragraph holding its lines.
+ * @position Rendered by RichTextEditor; always on, not exported. Lexical's
+ *   own Backspace there merges the code into the block above, and a heading
+ *   above reads back as a longer heading and a stray paragraph.
+ */
+
+import {useEffect} from 'react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$isCodeNode, type CodeNode} from '@lexical/code';
+import {
+  $createLineBreakNode,
+  $createParagraphNode,
+  $createTextNode,
+  $getSelection,
+  $isRangeSelection,
+  COMMAND_PRIORITY_LOW,
+  DELETE_CHARACTER_COMMAND,
+  type ParagraphNode,
+} from 'lexical';
+
+/** Start is offset 0 of the block or of its first child, not the start of a later line. */
+function $codeBlockAtCaretStart(): CodeNode | null {
+  const selection = $getSelection();
+  if (
+    !$isRangeSelection(selection) ||
+    !selection.isCollapsed() ||
+    selection.anchor.offset !== 0
+  ) {
+    return null;
+  }
+  const node = selection.anchor.getNode();
+  const code = $isCodeNode(node) ? node : node.getParent();
+  if (!$isCodeNode(code)) {
+    return null;
+  }
+  return node.is(code) || node.is(code.getFirstChild()) ? code : null;
+}
+
+/**
+ * A newline inside text exports as a soft break, and the lines read back as
+ * one. A line break node exports as a hard break. Empty lines at the end of
+ * the code are dropped: a hard break that ends a paragraph reads back as a
+ * literal backslash.
+ */
+function $paragraphOfLines(code: CodeNode): ParagraphNode {
+  const paragraph = $createParagraphNode();
+  code
+    .getTextContent()
+    .replace(/\n+$/, '')
+    .split('\n')
+    .forEach((line, index) => {
+      if (index > 0) {
+        paragraph.append($createLineBreakNode());
+      }
+      if (line !== '') {
+        paragraph.append($createTextNode(line));
+      }
+    });
+  return paragraph;
+}
+
+export function CodeBackspacePlugin(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(
+    () =>
+      editor.registerCommand(
+        DELETE_CHARACTER_COMMAND,
+        isBackward => {
+          if (!isBackward || !editor.isEditable()) {
+            return false;
+          }
+          const code = $codeBlockAtCaretStart();
+          if (code == null) {
+            return false;
+          }
+          const paragraph = $paragraphOfLines(code);
+          code.replace(paragraph);
+          paragraph.selectStart();
+          return true;
+        },
+        // Ahead of the rich-text deletion, which would do the merge.
+        COMMAND_PRIORITY_LOW,
+      ),
+    [editor],
+  );
+  return null;
+}

package/src/internal/CodeBlockHeaderPlugin.tsx

@@ -0,0 +1,282 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file CodeBlockHeaderPlugin.tsx
+ * @input Uses @lexical/react (composer context), @lexical/code (CodeNode),
+ *   lexical, and core IconButton, Icon, useClipboard, and useTranslator.
+ * @output Exports CodeBlockHeaderPlugin, which draws core CodeBlock's header
+ *   over every fenced code block: the language label and a copy button, or
+ *   just the copy button in the corner when the block names no language.
+ * @position Rendered by RichTextEditor and RichTextView inside the positioned
+ *   element that holds the content editable. The headers are siblings of the
+ *   editable text, never inside it, so they are not part of the document and
+ *   cannot be edited (spec:AST-061 FR8, DEC-4). The code block's theme class
+ *   reserves the header's height, so the code sits where core Markdown's does.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {useEffect, useState, type JSX} from 'react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$isCodeNode} from '@lexical/code';
+import {$getNodeByKey, $getRoot} from 'lexical';
+import {Icon} from '@blue-patterns/core/Icon';
+import {IconButton} from '@blue-patterns/core/IconButton';
+import {useClipboard} from '@blue-patterns/core/hooks';
+import {useTranslator} from '@blue-patterns/core/i18n';
+import type {CodeLanguage} from '@blue-patterns/core/CodeBlock';
+import {listedLanguage} from '../codeLanguages';
+import {
+  fontWeightVars,
+  spacingVars,
+  typeScaleVars,
+  typographyVars,
+} from '@blue-patterns/core/theme/tokens.stylex';
+
+/** Where one code block's header goes, in the container's coordinates. */
+interface HeaderPlacement {
+  readonly key: string;
+  readonly language: string | null;
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+}
+
+const styles = stylex.create({
+  // Core CodeBlock's compact header row: 8px above and below a small control,
+  // 16px at the sides.
+  header: {
+    position: 'absolute',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingBlock: spacingVars['--spacing-2'],
+    paddingInline: spacingVars['--spacing-4'],
+    boxSizing: 'border-box',
+  },
+  // No language: the copy button alone, 8px from the top end corner.
+  corner: {
+    position: 'absolute',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    padding: spacingVars['--spacing-2'],
+    boxSizing: 'border-box',
+    pointerEvents: 'none',
+  },
+  cornerButton: {
+    pointerEvents: 'auto',
+  },
+  title: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+    fontFamily: typographyVars['--font-family-code'],
+    fontWeight: fontWeightVars['--font-weight-medium'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    color: 'var(--color-syntax-comment)',
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  copyButton: {
+    color: 'var(--color-syntax-comment)',
+  },
+  placement: (top: number, left: number, width: number) => ({
+    top,
+    // eslint-disable-next-line @astryx/no-physical-properties -- intentional: `left` is a measured viewport coordinate (`box.left - origin.left + element.clientLeft`), not an authored edge. `insetInlineStart` would resolve to the right edge in RTL and place the header off the block.
+    left,
+    width,
+  }),
+});
+
+/**
+ * The language a header names, as core CodeBlock decides it: none for a fence
+ * without one, and none for exactly `plaintext`, which core Markdown gives a
+ * fence with no info string.
+ */
+function displayLanguageOf(language: string | null | undefined): string | null {
+  return language == null || language === '' || language === PLAIN_TEXT
+    ? null
+    : language;
+}
+
+const PLAIN_TEXT = 'plaintext';
+
+function samePlacements(
+  a: ReadonlyArray<HeaderPlacement>,
+  b: ReadonlyArray<HeaderPlacement>,
+): boolean {
+  return (
+    a.length === b.length &&
+    a.every(
+      (placement, index) =>
+        placement.key === b[index].key &&
+        placement.language === b[index].language &&
+        placement.top === b[index].top &&
+        placement.left === b[index].left &&
+        placement.width === b[index].width,
+    )
+  );
+}
+
+function CodeBlockHeader({
+  placement,
+  label,
+}: {
+  readonly placement: HeaderPlacement;
+  /** The matched language value's name, when a listed value claims the fence. */
+  readonly label?: string;
+}): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  const t = useTranslator();
+  const {copy, isCopied} = useClipboard({
+    announce: t('@astryx.codeBlock.copied'),
+  });
+  const copyButton = (
+    <IconButton
+      variant="ghost"
+      size="sm"
+      icon={
+        <Icon icon={isCopied ? 'check' : 'copy'} size="sm" color="inherit" />
+      }
+      tooltip={t('@astryx.codeBlock.copyCode')}
+      label={
+        isCopied
+          ? t('@astryx.codeBlock.copied')
+          : t('@astryx.codeBlock.copyCode')
+      }
+      onClick={() => {
+        const code = editor
+          .getEditorState()
+          .read(() => $getNodeByKey(placement.key)?.getTextContent() ?? '');
+        void copy(code);
+      }}
+      xstyle={[
+        styles.copyButton,
+        placement.language == null && styles.cornerButton,
+      ]}
+    />
+  );
+  const position = styles.placement(
+    placement.top,
+    placement.left,
+    placement.width,
+  );
+  if (placement.language == null) {
+    return (
+      <div
+        data-richtext-code-header=""
+        {...stylex.props(styles.corner, position)}>
+        {copyButton}
+      </div>
+    );
+  }
+  return (
+    <div
+      data-richtext-code-header=""
+      {...stylex.props(styles.header, position)}>
+      <span {...stylex.props(styles.title)}>{label ?? placement.language}</span>
+      {copyButton}
+    </div>
+  );
+}
+
+/**
+ * Draws a header over each top-level code block and keeps it there as the
+ * document, the editor's size, or the window changes.
+ */
+export function CodeBlockHeaderPlugin({
+  codeLanguages,
+}: {
+  /** Language values a fence may name; a matched fence shows the value's name. */
+  codeLanguages?: ReadonlyArray<CodeLanguage>;
+} = {}): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  const [placements, setPlacements] = useState<ReadonlyArray<HeaderPlacement>>(
+    [],
+  );
+
+  useEffect(() => {
+    let frame = 0;
+    const measure = () => {
+      frame = 0;
+      const root = editor.getRootElement();
+      const container = root?.parentElement;
+      if (root == null || container == null) {
+        setPlacements(current => (current.length === 0 ? current : []));
+        return;
+      }
+      const origin = container.getBoundingClientRect();
+      const next = editor.getEditorState().read(() =>
+        $getRoot()
+          .getChildren()
+          .filter($isCodeNode)
+          .flatMap(node => {
+            const element = editor.getElementByKey(node.getKey());
+            if (element == null) {
+              return [];
+            }
+            const box = element.getBoundingClientRect();
+            // Inside the block's border, so the header lines up with the
+            // padding the theme reserves for it.
+            return [
+              {
+                key: node.getKey(),
+                language: displayLanguageOf(node.getLanguage()),
+                top: box.top - origin.top + element.clientTop,
+                left: box.left - origin.left + element.clientLeft,
+                width: element.clientWidth,
+              },
+            ];
+          }),
+      );
+      setPlacements(current =>
+        samePlacements(current, next) ? current : next,
+      );
+    };
+    const schedule = () => {
+      if (frame === 0) {
+        frame = requestAnimationFrame(measure);
+      }
+    };
+    const observer =
+      typeof ResizeObserver === 'undefined'
+        ? null
+        : new ResizeObserver(schedule);
+    const unregisterRoot = editor.registerRootListener(root => {
+      observer?.disconnect();
+      if (root != null) {
+        observer?.observe(root);
+      }
+      schedule();
+    });
+    const unregisterUpdate = editor.registerUpdateListener(schedule);
+    window.addEventListener('resize', schedule);
+    schedule();
+    return () => {
+      cancelAnimationFrame(frame);
+      observer?.disconnect();
+      unregisterRoot();
+      unregisterUpdate();
+      window.removeEventListener('resize', schedule);
+    };
+  }, [editor]);
+
+  return (
+    <>
+      {placements.map(placement => (
+        <CodeBlockHeader
+          key={placement.key}
+          placement={placement}
+          // A fence matched in `codeLanguages` shows the value's name, as
+          // Markdown does (spec:AST-061).
+          label={
+            placement.language == null
+              ? undefined
+              : listedLanguage(codeLanguages, placement.language)?.name
+          }
+        />
+      ))}
+    </>
+  );
+}

package/src/internal/CodePastePlugin.tsx

@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file CodePastePlugin.tsx
+ * @input Uses @lexical/react (composer context), @lexical/code (CodeNode), and
+ *   lexical.
+ * @output Exports CodePastePlugin, which makes rich content pasted or dropped
+ *   into a code block go in as plain lines of code, and $startsInCodeBlock,
+ *   which TablePastePlugin uses to leave such a paste to it.
+ * @position Rendered by RichTextEditor; always on; not exported. A paste
+ *   whose selection starts in a code block goes in as plain text: the
+ *   clipboard's plain text, or else one line per pasted block.
+ */
+
+import {useEffect} from 'react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$isCodeNode} from '@lexical/code';
+import {
+  $addUpdateTag,
+  $findMatchingParent,
+  $getSelection,
+  $isElementNode,
+  $isRangeSelection,
+  $isSelectionCapturedInDecoratorInput,
+  COMMAND_PRIORITY_LOW,
+  isDOMNode,
+  mergeRegister,
+  PASTE_COMMAND,
+  PASTE_TAG,
+  SELECTION_INSERT_CLIPBOARD_NODES_COMMAND,
+  type BaseSelection,
+  type LexicalNode,
+  type RangeSelection,
+} from 'lexical';
+
+/** Clipboard types that carry more than plain text. */
+const RICH_TYPES = ['text/html', 'application/x-lexical-editor'];
+
+/** Whether content inserted at the selection lands in a code block. */
+export function $startsInCodeBlock(
+  selection: BaseSelection | null,
+): selection is RangeSelection {
+  if (!$isRangeSelection(selection)) {
+    return false;
+  }
+  const start = selection.isBackward() ? selection.focus : selection.anchor;
+  const node = start.getNode();
+  // A link (an autolinked URL) can sit between the text and its code block.
+  return $findMatchingParent(node, $isCodeNode) !== null;
+}
+
+/**
+ * Clipboard nodes as plain lines: each block's text on a line of its own (a
+ * paragraph, a heading, a list item, a table cell), and inline content
+ * between blocks on one line.
+ */
+function $plainLinesOf(nodes: ReadonlyArray<LexicalNode>): string {
+  const lines: string[] = [];
+  let inline: string | null = null;
+  const endInline = () => {
+    if (inline != null) {
+      lines.push(inline);
+      inline = null;
+    }
+  };
+  const visit = (node: LexicalNode) => {
+    if (node.isInline()) {
+      inline = (inline ?? '') + node.getTextContent();
+      return;
+    }
+    endInline();
+    if (
+      $isElementNode(node) &&
+      node.getChildren().some(child => !child.isInline())
+    ) {
+      node.getChildren().forEach(visit);
+      endInline();
+    } else {
+      lines.push(node.getTextContent());
+    }
+  };
+  nodes.forEach(visit);
+  endInline();
+  return lines.join('\n');
+}
+
+export function CodePastePlugin(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(
+    () =>
+      mergeRegister(
+        // Ahead of the rich-text paste, which inserts the clipboard's rich
+        // content when there is any.
+        editor.registerCommand(
+          PASTE_COMMAND,
+          event => {
+            // A paste into an input a decorator node renders is that input's.
+            if (
+              isDOMNode(event.target) &&
+              $isSelectionCapturedInDecoratorInput(event.target)
+            ) {
+              return false;
+            }
+            const data = 'clipboardData' in event ? event.clipboardData : null;
+            if (
+              !editor.isEditable() ||
+              data == null ||
+              !RICH_TYPES.some(type => data.types.includes(type))
+            ) {
+              return false;
+            }
+            const text = data.getData('text/plain');
+            const selection = $getSelection();
+            if (text === '' || !$startsInCodeBlock(selection)) {
+              return false;
+            }
+            event.preventDefault();
+            // Its own undo step, as every paste is.
+            $addUpdateTag(PASTE_TAG);
+            selection.insertRawText(text);
+            return true;
+          },
+          COMMAND_PRIORITY_LOW,
+        ),
+        // Every insertion of clipboard nodes, a paste with no plain text or a
+        // drop, comes through here; ahead of the table's own handler.
+        editor.registerCommand(
+          SELECTION_INSERT_CLIPBOARD_NODES_COMMAND,
+          ({nodes, selection}) => {
+            if (!$startsInCodeBlock(selection)) {
+              return false;
+            }
+            selection.insertRawText($plainLinesOf(nodes));
+            return true;
+          },
+          COMMAND_PRIORITY_LOW,
+        ),
+      ),
+    [editor],
+  );
+  return null;
+}