@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/dist/internal/DisabledLinkGuardPlugin.js

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DisabledLinkGuardPlugin.tsx
+ * @input The composer's editor, and whether RichTextEditor is disabled
+ * @output DisabledLinkGuardPlugin (internal; not re-exported from index.ts):
+ *   while the editor is disabled, its links add no tab stop and never navigate
+ * @position Rendered by RichTextEditor inside its LexicalExtensionComposer
+ *
+ * A disabled editor is not editable, so the browser treats each link in it as
+ * a live link: a tab stop that navigates on a click or on Enter. A disabled
+ * control must not navigate, and it keeps the focus order it has when enabled,
+ * where its links are not tab stops.
+ */
+import { useEffect } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+
+// Enter on a focused link and a screen reader's activation arrive as a click.
+// A middle click arrives as auxclick.
+function preventLinkActivation(event) {
+  if (event.target instanceof Element && event.target.closest('a[href]')) {
+    event.preventDefault();
+  }
+}
+
+/**
+ * Guards the links under one root element. It records the links it changes,
+ * so it restores only those.
+ */
+function createLinkGuard(root) {
+  const guarded = new Set();
+  const guard = () => {
+    for (const link of root.querySelectorAll('a[href]')) {
+      if (!guarded.has(link)) {
+        guarded.add(link);
+        link.setAttribute('tabindex', '-1');
+        // Assistive technology announces each link as disabled. Only the
+        // link ignores the pointer, so a wide table still scrolls.
+        link.setAttribute('aria-disabled', 'true');
+        if (link instanceof HTMLElement) {
+          link.style.pointerEvents = 'none';
+        }
+      }
+    }
+  };
+  guard();
+  root.addEventListener('click', preventLinkActivation, true);
+  root.addEventListener('auxclick', preventLinkActivation, true);
+  return {
+    guard,
+    release() {
+      for (const link of guarded) {
+        link.removeAttribute('tabindex');
+        link.removeAttribute('aria-disabled');
+        if (link instanceof HTMLElement) {
+          link.style.removeProperty('pointer-events');
+        }
+      }
+      guarded.clear();
+      root.removeEventListener('click', preventLinkActivation, true);
+      root.removeEventListener('auxclick', preventLinkActivation, true);
+    }
+  };
+}
+export function DisabledLinkGuardPlugin({
+  isDisabled
+}) {
+  const [editor] = useLexicalComposerContext();
+  // Synchronizes the editor's link elements, which Lexical renders and owns,
+  // with the disabled state: guarded while disabled, restored when enabled.
+  useEffect(() => {
+    if (!isDisabled) {
+      return undefined;
+    }
+    let linkGuard = null;
+    const unregisterRoot = editor.registerRootListener(next => {
+      linkGuard?.release();
+      linkGuard = next == null ? null : createLinkGuard(next);
+    });
+    // A new or changed document renders new link elements.
+    const unregisterUpdate = editor.registerUpdateListener(() => {
+      linkGuard?.guard();
+    });
+    return () => {
+      unregisterUpdate();
+      unregisterRoot();
+      linkGuard?.release();
+    };
+  }, [editor, isDisabled]);
+  return null;
+}

package/dist/internal/ImageSourceCaretPlugin.d.ts

@@ -0,0 +1,3 @@
+/** Keeps a collapsed caret out of the text holding an image's source. */
+export declare function ImageSourceCaretPlugin(): null;
+//# sourceMappingURL=ImageSourceCaretPlugin.d.ts.map

package/dist/internal/ImageSourceCaretPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageSourceCaretPlugin.d.ts","sourceRoot":"","sources":["../../src/internal/ImageSourceCaretPlugin.tsx"],"names":[],"mappings":"AAyJA,yEAAyE;AACzE,wBAAgB,sBAAsB,IAAI,IAAI,CAI7C"}

package/dist/internal/ImageSourceCaretPlugin.js

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ImageSourceCaretPlugin.tsx
+ * @input Uses @lexical/react (composer context), lexical (selection, the
+ *   selection-change and text-insertion commands, the root element), and
+ *   $isImageSource from markdownCharacterReferences.ts.
+ * @output Exports ImageSourceCaretPlugin.
+ * @position Rendered by RichTextEditor, always on. Lexical replaces a whole
+ *   token with text typed inside it. So a caret inside an image's source
+ *   moves to an edge: past the image for an arrow key, to the nearer edge
+ *   for a click or any other move.
+ */
+import { useEffect } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { mergeRegister } from '@lexical/utils';
+import { $getNodeByKey, $getSelection, $isRangeSelection, COMMAND_PRIORITY_CRITICAL, CONTROLLED_TEXT_INSERTION_COMMAND, SELECTION_CHANGE_COMMAND } from 'lexical';
+import { $isImageSource } from "../markdownCharacterReferences.js";
+/** The collapsed caret, when it is in text. */
+function $caretPoint() {
+  const selection = $getSelection();
+  return $isRangeSelection(selection) && selection.isCollapsed() && selection.anchor.type === 'text' ? {
+    key: selection.anchor.key,
+    offset: selection.anchor.offset
+  } : null;
+}
+
+/**
+ * The edge of `token` a caret at `offset` inside it moves to. An arrow key
+ * that moved the caret in from one edge, or from the text beside it, moves
+ * it on to the other edge.
+ */
+function $edgeFor(token, offset, arrowFrom) {
+  const size = token.getTextContentSize();
+  const nearer = offset < size / 2 ? 0 : size;
+  if (arrowFrom == null) {
+    return nearer;
+  }
+  if (arrowFrom.key === token.getKey()) {
+    return arrowFrom.offset === 0 ? size : arrowFrom.offset === size ? 0 : nearer;
+  }
+  const before = token.getPreviousSibling();
+  if (before != null && before.getKey() === arrowFrom.key && arrowFrom.offset === before.getTextContentSize()) {
+    return size;
+  }
+  const after = token.getNextSibling();
+  if (after != null && after.getKey() === arrowFrom.key && arrowFrom.offset === 0) {
+    return 0;
+  }
+  return nearer;
+}
+
+/** Moves a collapsed caret inside an image's source to an edge of it. */
+function $moveCaretOutOfImage(arrowFrom) {
+  const caret = $caretPoint();
+  if (caret == null) {
+    return;
+  }
+  const node = $getNodeByKey(caret.key);
+  if (node == null || !$isImageSource(node) || caret.offset === 0 || caret.offset === node.getTextContentSize()) {
+    return;
+  }
+  const edge = $edgeFor(node, caret.offset, arrowFrom);
+  const selection = $getSelection();
+  if ($isRangeSelection(selection)) {
+    selection.anchor.set(caret.key, edge, 'text');
+    selection.focus.set(caret.key, edge, 'text');
+  }
+}
+function registerImageSourceCaret(editor) {
+  // Where the caret was when an arrow key went down; the next selection
+  // change reads it once. A press is a click, never an arrow key.
+  let arrowFrom = null;
+  const onKeyDown = event => {
+    arrowFrom = event.key === 'ArrowLeft' || event.key === 'ArrowRight' ? editor.getEditorState().read($caretPoint) : null;
+  };
+  const onPointerDown = () => {
+    arrowFrom = null;
+  };
+  return mergeRegister(editor.registerRootListener((root, previousRoot) => {
+    previousRoot?.removeEventListener('keydown', onKeyDown, true);
+    previousRoot?.removeEventListener('pointerdown', onPointerDown, true);
+    root?.addEventListener('keydown', onKeyDown, true);
+    root?.addEventListener('pointerdown', onPointerDown, true);
+  }), editor.registerCommand(SELECTION_CHANGE_COMMAND, () => {
+    $moveCaretOutOfImage(arrowFrom);
+    arrowFrom = null;
+    return false;
+  }, COMMAND_PRIORITY_CRITICAL),
+  // A key typed before the browser reports a caret move reaches the editor
+  // with the caret still inside the source.
+  editor.registerCommand(CONTROLLED_TEXT_INSERTION_COMMAND, () => {
+    $moveCaretOutOfImage(null);
+    return false;
+  }, COMMAND_PRIORITY_CRITICAL));
+}
+
+/** Keeps a collapsed caret out of the text holding an image's source. */
+export function ImageSourceCaretPlugin() {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => registerImageSourceCaret(editor), [editor]);
+  return null;
+}

package/dist/internal/ListItemShortcutsPlugin.d.ts

@@ -0,0 +1,6 @@
+import { type Transformer } from '@lexical/markdown';
+export declare function ListItemShortcutsPlugin({ transformers, }: {
+    /** The editor's Markdown transformers; markers they do not make are left. */
+    readonly transformers: ReadonlyArray<Transformer>;
+}): null;
+//# sourceMappingURL=ListItemShortcutsPlugin.d.ts.map

package/dist/internal/ListItemShortcutsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListItemShortcutsPlugin.d.ts","sourceRoot":"","sources":["../../src/internal/ListItemShortcutsPlugin.tsx"],"names":[],"mappings":"AA8BA,OAAO,EAAa,KAAK,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAyW/D,wBAAgB,uBAAuB,CAAC,EACtC,YAAY,GACb,EAAE;IACD,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;CACnD,GAAG,IAAI,CAOP"}

package/dist/internal/ListItemShortcutsPlugin.js

@@ -0,0 +1,314 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ListItemShortcutsPlugin.tsx
+ * @input Uses @lexical/react (composer context), @lexical/list,
+ *   @lexical/rich-text, @lexical/markdown (Transformer), lexical, and the task
+ *   state in markdownTaskList.ts.
+ * @output Exports ListItemShortcutsPlugin, which re-marks a list item when a
+ *   Markdown block marker is typed at its start, keeping the item's text:
+ *   `- `, `1. `, or `[ ] ` switches the item's list between bullets, numbers,
+ *   and tasks, and `# ` or `> ` takes a top-level item out of its list as a
+ *   heading or a quote, the rest of the list continuing after it.
+ * @position Rendered by RichTextEditor beside MarkdownShortcutPlugin, only
+ *   when `hasMarkdownShortcuts` is on. Lexical's shortcuts never look inside a
+ *   list. A marker counts only when the editor's `transformers` make that
+ *   block from it, and a task takes the shape of the transformer that matched.
+ *   Each re-mark is one undo step.
+ */
+import { useEffect } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { $createListNode, $isListItemNode, $isListNode } from '@lexical/list';
+import { CHECK_LIST } from '@lexical/markdown';
+import { $createHeadingNode, $createQuoteNode } from '@lexical/rich-text';
+import { $addUpdateTag, $getNodeByKey, $getSelection, $isRangeSelection, $isRootOrShadowRoot, $isTextNode, COLLABORATION_TAG, HISTORIC_TAG, HISTORY_PUSH_TAG } from 'lexical';
+import { $getTaskState, $setTaskState } from "../markdownTaskList.js";
+
+/** What a marker typed at the start of a list item makes of it. */
+
+/** Whether `marker` takes an item out of its list, rather than switching it. */
+function isBlockMarker(marker) {
+  return marker.kind === 'heading' || marker.kind === 'quote';
+}
+
+/**
+ * The marker `prefix` is (the text before the caret, ending in the space
+ * just typed), and the line that would make the same block at the start of a
+ * paragraph. A task marker needs a bullet there, as GFM task items do.
+ */
+function markerOf(prefix) {
+  const heading = /^(#{1,6}) $/.exec(prefix);
+  if (heading != null) {
+    return {
+      marker: {
+        kind: 'heading',
+        tag: `h${heading[1].length}`
+      },
+      line: prefix
+    };
+  }
+  if (prefix === '> ') {
+    return {
+      marker: {
+        kind: 'quote'
+      },
+      line: prefix
+    };
+  }
+  if (/^[-*+] $/.test(prefix)) {
+    return {
+      marker: {
+        kind: 'bullet'
+      },
+      line: prefix
+    };
+  }
+  const number = /^(\d{1,9})\. $/.exec(prefix);
+  if (number != null) {
+    return {
+      marker: {
+        kind: 'number',
+        start: Number(number[1])
+      },
+      line: prefix
+    };
+  }
+  const task = /^([-*+] )?\[([ xX])\] $/.exec(prefix);
+  if (task != null) {
+    return {
+      marker: {
+        kind: 'task',
+        checked: task[2] !== ' '
+      },
+      line: task[1] == null ? `- ${prefix}` : prefix
+    };
+  }
+  return null;
+}
+
+/** The first of `transformers` that makes a block from `line`, all of it. */
+function transformerFor(line, transformers) {
+  return transformers.find(transformer => transformer.type === 'element' && line.match(transformer.regExp)?.[0] === line);
+}
+
+/** Whether `node` is the item Lexical nests a list in, not an item itself. */
+function $holdsNestedList(node) {
+  return $isListItemNode(node) && node.getChildrenSize() === 1 && $isListNode(node.getFirstChild());
+}
+
+/** The items of `list` that have content of their own. */
+function $itemsOf(list) {
+  return list.getChildren().filter(child => $isListItemNode(child) && !$holdsNestedList(child));
+}
+
+/**
+ * Switches the list holding `item` to bullets, numbers, or tasks. Tasks take
+ * the shape the matching transformer reads and writes: Lexical's `check`
+ * list for CHECK_LIST, or else RichText's bulleted items with task state
+ * (markdownTaskList.ts). Switching to tasks makes every item a task, keeping
+ * the state of those that already were, and `item` takes the marker's;
+ * switching to bullets or numbers makes every item a plain one. A numbered
+ * list starts at the marker's number when `item` is its first item.
+ */
+function $switchList(list, item, marker, isCheckList) {
+  const items = $itemsOf(list);
+  if (marker.kind === 'task' && isCheckList) {
+    // A check list already keeps each item's state; only another list is
+    // converted, carrying over RichText's task state.
+    if (list.getListType() !== 'check') {
+      const states = items.map(each => $getTaskState(each));
+      for (const each of items) {
+        $setTaskState(each, null);
+      }
+      list.setListType('check');
+      items.forEach((each, index) => {
+        each.setChecked(states[index] === 'checked');
+      });
+    }
+    item.setChecked(marker.checked);
+    return;
+  }
+  if (marker.kind === 'task') {
+    // Read a check list's states first: Lexical reports no checked state
+    // once the list is no longer a check list.
+    const checkStates = list.getListType() === 'check' ? items.map(each => each.getChecked() === true) : null;
+    if (list.getListType() !== 'bullet') {
+      list.setListType('bullet');
+    }
+    items.forEach((each, index) => {
+      if (checkStates != null) {
+        each.setChecked(undefined);
+        $setTaskState(each, checkStates[index] ? 'checked' : 'unchecked');
+      } else if ($getTaskState(each) == null) {
+        $setTaskState(each, 'unchecked');
+      }
+    });
+    $setTaskState(item, marker.checked ? 'checked' : 'unchecked');
+    return;
+  }
+  for (const each of items) {
+    if ($getTaskState(each) != null) {
+      $setTaskState(each, null);
+    }
+    if (each.getChecked() !== undefined) {
+      each.setChecked(undefined);
+    }
+  }
+  const wasNumbered = list.getListType() === 'number';
+  list.setListType(marker.kind);
+  if (marker.kind === 'number') {
+    if (items[0]?.is(item) === true) {
+      list.setStart(marker.start);
+    } else if (!wasNumbered) {
+      list.setStart(1);
+    }
+  }
+}
+
+/**
+ * Takes `item` out of `list` as `block`, holding the item's content. The
+ * items before it stay in `list`; the lists nested under it follow `block`
+ * at the top level, since a heading or a quote cannot hold them; and the
+ * items after it continue in a list of the same kind, numbered on from where
+ * they were. When the last of those nested lists has the same type, Lexical
+ * merges the items after it into that list, which numbers them on from its
+ * own items.
+ */
+function $takeOutOfList(list, item, block) {
+  const nested = [];
+  let next = item.getNextSibling();
+  while ($holdsNestedList(next)) {
+    nested.push(next);
+    next = next.getNextSibling();
+  }
+  const after = next == null ? [] : [next, ...next.getNextSiblings()];
+  const before = $itemsOf(list).findIndex(each => each.is(item));
+  block.append(...item.getChildren());
+  list.insertAfter(block);
+  let last = block;
+  for (const holder of nested) {
+    const child = holder.getFirstChild();
+    if ($isListNode(child)) {
+      last.insertAfter(child);
+      last = child;
+    }
+    holder.remove();
+  }
+  if (after.length > 0) {
+    const type = list.getListType();
+    const rest = $createListNode(type, type === 'number' ? list.getStart() + before + 1 : 1);
+    rest.append(...after);
+    last.insertAfter(rest);
+  }
+  item.remove();
+  if (list.getChildrenSize() === 0) {
+    list.remove();
+  }
+}
+
+/** Re-marks the item whose first text, `key`, starts with `prefix`. */
+function $remark(key, prefix, marker, isCheckList) {
+  const text = $getNodeByKey(key);
+  const item = text?.getParent();
+  const list = item?.getParent();
+  if (!$isTextNode(text) || !text.getTextContent().startsWith(prefix) || !$isListItemNode(item) || !text.is(item.getFirstChild()) || !$isListNode(list) || isBlockMarker(marker) && !$isRootOrShadowRoot(list.getParent())) {
+    return;
+  }
+  const rest = text.getTextContent().slice(prefix.length);
+  if (rest === '') {
+    text.remove();
+  } else {
+    text.setTextContent(rest);
+  }
+  if (isBlockMarker(marker)) {
+    const block = marker.kind === 'heading' ? $createHeadingNode(marker.tag) : $createQuoteNode();
+    $takeOutOfList(list, item, block);
+    block.selectStart();
+  } else {
+    $switchList(list, item, marker, isCheckList);
+    // Lexical merges a dirty list with a list of the same type after it, but
+    // not with one before it. Marking the list before it joins the two, as
+    // the Markdown reads back.
+    const previous = list.getPreviousSibling();
+    if ($isListNode(previous) && previous.getListType() === list.getListType()) {
+      previous.markDirty();
+    }
+    item.selectStart();
+  }
+  // Its own undo step, so undo returns to the marker as typed.
+  $addUpdateTag(HISTORY_PUSH_TAG);
+}
+
+/**
+ * Watches for a marker completed by a typed space at the start of a list
+ * item's text, and re-marks the item in an update of its own, as Lexical's
+ * Markdown shortcuts do for blocks in the root.
+ */
+function registerListItemShortcuts(editor, transformers) {
+  return editor.registerUpdateListener(({
+    tags,
+    dirtyLeaves,
+    editorState,
+    prevEditorState
+  }) => {
+    if (tags.has(COLLABORATION_TAG) || tags.has(HISTORIC_TAG) || dirtyLeaves.size === 0 || editor.isComposing() || !editor.isEditable()) {
+      return;
+    }
+    const previous = prevEditorState.read(() => {
+      const selection = $getSelection();
+      return $isRangeSelection(selection) && selection.isCollapsed() ? selection.anchor : null;
+    });
+    if (previous == null) {
+      return;
+    }
+    const found = editorState.read(() => {
+      const selection = $getSelection();
+      if (!$isRangeSelection(selection) || !selection.isCollapsed()) {
+        return null;
+      }
+      const {
+        key,
+        offset
+      } = selection.anchor;
+      // One character typed, just now, in the same text.
+      if (!dirtyLeaves.has(key) || previous.key !== key || previous.offset !== offset - 1) {
+        return null;
+      }
+      const text = selection.anchor.getNode();
+      if (!$isTextNode(text) || text.hasFormat('code')) {
+        return null;
+      }
+      const prefix = text.getTextContent().slice(0, offset);
+      const match = markerOf(prefix);
+      const item = text.getParent();
+      const list = item?.getParent();
+      const transformer = match == null ? undefined : transformerFor(match.line, transformers);
+      if (match == null || transformer == null || !$isListItemNode(item) || !text.is(item.getFirstChild()) || !$isListNode(list)) {
+        return null;
+      }
+      // A heading or a quote can only stand where a top-level block does;
+      // in a nested list the marker stays as typed.
+      if (isBlockMarker(match.marker) && !$isRootOrShadowRoot(list.getParent())) {
+        return null;
+      }
+      return {
+        key,
+        prefix,
+        marker: match.marker,
+        isCheckList: transformer === CHECK_LIST
+      };
+    });
+    if (found != null) {
+      editor.update(() => $remark(found.key, found.prefix, found.marker, found.isCheckList));
+    }
+  });
+}
+export function ListItemShortcutsPlugin({
+  transformers
+}) {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => registerListItemShortcuts(editor, transformers), [editor, transformers]);
+  return null;
+}

package/dist/internal/MarkdownExtensionsPlugin.d.ts

@@ -0,0 +1,17 @@
+import type { Transformer } from '@lexical/markdown';
+import type { MarkdownExtensionNode, MarkdownPluginEntry } from '@blue-patterns/core/Markdown/plugins';
+import { type RichTextMarkdownExtension } from '../markdownExtensions.js';
+import { type RichTextExtensionNodeFacts } from '../markdownExtensionNode.js';
+/**
+ * The node core derives from a stored node's source with `plugins`, or null
+ * when no adopted plugin of the same protocol version reads that exact source
+ * as that node.
+ */
+export declare function deriveExtensionNode(facts: RichTextExtensionNodeFacts, plugins: ReadonlyArray<MarkdownPluginEntry>): MarkdownExtensionNode | null;
+export interface MarkdownExtensionsPluginProps {
+    extensions: ReadonlyArray<RichTextMarkdownExtension>;
+    /** The surface's Markdown transformers, checked against the extensions. */
+    transformers: ReadonlyArray<Transformer>;
+}
+export declare function MarkdownExtensionsPlugin({ extensions, transformers, }: MarkdownExtensionsPluginProps): null;
+//# sourceMappingURL=MarkdownExtensionsPlugin.d.ts.map

package/dist/internal/MarkdownExtensionsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownExtensionsPlugin.d.ts","sourceRoot":"","sources":["../../src/internal/MarkdownExtensionsPlugin.tsx"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAwBnD,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAY,KAAK,yBAAyB,EAAC,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAKL,KAAK,0BAA0B,EAChC,MAAM,0BAA0B,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,0BAA0B,EACjC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC1C,qBAAqB,GAAG,IAAI,CAoB9B;AAyHD,MAAM,WAAW,6BAA6B;IAC5C,UAAU,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAC;IACrD,2EAA2E;IAC3E,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;CAC1C;AAED,wBAAgB,wBAAwB,CAAC,EACvC,UAAU,EACV,YAAY,GACb,EAAE,6BAA6B,GAAG,IAAI,CAoEtC"}