@lexical/react 0.44.1-nightly.20260519.0 → 0.45.0

package/src/LexicalNodeMenuPlugin.tsx

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type {MenuRenderFn, MenuResolution} from './shared/LexicalMenu';
+import type {JSX} from 'react';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $getNodeByKey,
+  COMMAND_PRIORITY_LOW,
+  CommandListenerPriority,
+  NodeKey,
+  TextNode,
+} from 'lexical';
+import * as React from 'react';
+import {useCallback, useEffect, useState} from 'react';
+
+import {LexicalMenu, MenuOption, useMenuAnchorRef} from './shared/LexicalMenu';
+import {startTransition} from './shared/reactPatches';
+
+export type NodeMenuPluginProps<TOption extends MenuOption> = {
+  onSelectOption: (
+    option: TOption,
+    textNodeContainingQuery: TextNode | null,
+    closeMenu: () => void,
+    matchingString: string,
+  ) => void;
+  options: Array<TOption>;
+  nodeKey: NodeKey | null;
+  menuRenderFn?: MenuRenderFn<TOption>;
+  onClose?: () => void;
+  onOpen?: (resolution: MenuResolution) => void;
+  anchorClassName?: string;
+  commandPriority?: CommandListenerPriority;
+  parent?: HTMLElement;
+};
+
+export function LexicalNodeMenuPlugin<TOption extends MenuOption>({
+  options,
+  nodeKey,
+  onClose,
+  onOpen,
+  onSelectOption,
+  menuRenderFn,
+  anchorClassName,
+  commandPriority = COMMAND_PRIORITY_LOW,
+  parent,
+}: NodeMenuPluginProps<TOption>): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+  const [resolution, setResolution] = useState<MenuResolution | null>(null);
+  const anchorElementRef = useMenuAnchorRef(
+    resolution,
+    setResolution,
+    anchorClassName,
+    parent,
+  );
+
+  const closeNodeMenu = useCallback(() => {
+    setResolution(null);
+    if (onClose != null && resolution !== null) {
+      onClose();
+    }
+  }, [onClose, resolution]);
+
+  const openNodeMenu = useCallback(
+    (res: MenuResolution) => {
+      setResolution(res);
+      if (onOpen != null && resolution === null) {
+        onOpen(res);
+      }
+    },
+    [onOpen, resolution],
+  );
+
+  const positionOrCloseMenu = useCallback(() => {
+    if (nodeKey) {
+      editor.update(() => {
+        const node = $getNodeByKey(nodeKey);
+        const domElement = editor.getElementByKey(nodeKey);
+        if (node != null && domElement != null) {
+          if (resolution == null) {
+            startTransition(() =>
+              openNodeMenu({
+                getRect: () => domElement.getBoundingClientRect(),
+              }),
+            );
+          }
+        }
+      });
+    } else if (nodeKey == null && resolution != null) {
+      closeNodeMenu();
+    }
+  }, [closeNodeMenu, editor, nodeKey, openNodeMenu, resolution]);
+
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    positionOrCloseMenu();
+  }, [positionOrCloseMenu, nodeKey]);
+
+  useEffect(() => {
+    if (nodeKey != null) {
+      return editor.registerUpdateListener(({dirtyElements}) => {
+        if (dirtyElements.get(nodeKey)) {
+          positionOrCloseMenu();
+        }
+      });
+    }
+  }, [editor, positionOrCloseMenu, nodeKey]);
+
+  return anchorElementRef.current === null ||
+    resolution === null ||
+    editor === null ? null : (
+    <LexicalMenu
+      close={closeNodeMenu}
+      resolution={resolution}
+      editor={editor}
+      anchorElementRef={anchorElementRef}
+      options={options}
+      menuRenderFn={menuRenderFn}
+      onSelectOption={onSelectOption}
+      commandPriority={commandPriority}
+    />
+  );
+}
+
+export {MenuOption, MenuRenderFn, MenuResolution};

package/src/LexicalOnChangePlugin.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type {EditorState, LexicalEditor} from 'lexical';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {HISTORY_MERGE_TAG} from 'lexical';
+
+import useLayoutEffect from './shared/useLayoutEffect';
+
+export function OnChangePlugin({
+  ignoreHistoryMergeTagChange = true,
+  ignoreSelectionChange = false,
+  onChange,
+}: {
+  ignoreHistoryMergeTagChange?: boolean;
+  ignoreSelectionChange?: boolean;
+  onChange: (
+    editorState: EditorState,
+    editor: LexicalEditor,
+    tags: Set<string>,
+  ) => void;
+}): null {
+  const [editor] = useLexicalComposerContext();
+
+  useLayoutEffect(() => {
+    if (onChange) {
+      return editor.registerUpdateListener(
+        ({editorState, dirtyElements, dirtyLeaves, prevEditorState, tags}) => {
+          if (
+            (ignoreSelectionChange &&
+              dirtyElements.size === 0 &&
+              dirtyLeaves.size === 0) ||
+            (ignoreHistoryMergeTagChange && tags.has(HISTORY_MERGE_TAG)) ||
+            prevEditorState.isEmpty()
+          ) {
+            return;
+          }
+
+          onChange(editorState, editor, tags);
+        },
+      );
+    }
+  }, [editor, ignoreHistoryMergeTagChange, ignoreSelectionChange, onChange]);
+
+  return null;
+}

package/src/LexicalPlainTextPlugin.tsx

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type {JSX} from 'react';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useLexicalEditable} from '@lexical/react/useLexicalEditable';
+
+import {
+  type ErrorBoundaryType,
+  LegacyDecorators,
+} from './shared/LegacyDecorators';
+import {useCanShowPlaceholder} from './shared/useCanShowPlaceholder';
+import {usePlainTextSetup} from './shared/usePlainTextSetup';
+
+export function PlainTextPlugin({
+  contentEditable,
+  // TODO Remove. This property is now part of ContentEditable
+  placeholder = null,
+  ErrorBoundary,
+}: {
+  contentEditable: JSX.Element;
+  placeholder?:
+    | ((isEditable: boolean) => null | JSX.Element)
+    | null
+    | JSX.Element;
+  ErrorBoundary: ErrorBoundaryType;
+}): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  usePlainTextSetup(editor);
+
+  return (
+    <>
+      {contentEditable}
+      <Placeholder content={placeholder} />
+      <LegacyDecorators editor={editor} ErrorBoundary={ErrorBoundary} />
+    </>
+  );
+}
+
+// TODO Remove
+function Placeholder({
+  content,
+}: {
+  content: ((isEditable: boolean) => null | JSX.Element) | null | JSX.Element;
+}): null | JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  const showPlaceholder = useCanShowPlaceholder(editor);
+  const editable = useLexicalEditable();
+
+  if (!showPlaceholder) {
+    return null;
+  }
+
+  if (typeof content === 'function') {
+    return content(editable);
+  } else {
+    return content;
+  }
+}

package/src/LexicalRichTextPlugin.tsx

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type {JSX} from 'react';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useLexicalEditable} from '@lexical/react/useLexicalEditable';
+
+import {
+  type ErrorBoundaryType,
+  LegacyDecorators,
+} from './shared/LegacyDecorators';
+import {useCanShowPlaceholder} from './shared/useCanShowPlaceholder';
+import {useRichTextSetup} from './shared/useRichTextSetup';
+
+export function RichTextPlugin({
+  contentEditable,
+  // TODO Remove. This property is now part of ContentEditable
+  placeholder = null,
+  ErrorBoundary,
+}: {
+  contentEditable: JSX.Element;
+  placeholder?:
+    | ((isEditable: boolean) => null | JSX.Element)
+    | null
+    | JSX.Element;
+  ErrorBoundary: ErrorBoundaryType;
+}): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  useRichTextSetup(editor);
+
+  return (
+    <>
+      {contentEditable}
+      <Placeholder content={placeholder} />
+      <LegacyDecorators editor={editor} ErrorBoundary={ErrorBoundary} />
+    </>
+  );
+}
+
+// TODO remove
+function Placeholder({
+  content,
+}: {
+  content: ((isEditable: boolean) => null | JSX.Element) | null | JSX.Element;
+}): null | JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  const showPlaceholder = useCanShowPlaceholder(editor);
+  const editable = useLexicalEditable();
+
+  if (!showPlaceholder) {
+    return null;
+  }
+
+  if (typeof content === 'function') {
+    return content(editable);
+  } else {
+    return content;
+  }
+}

package/src/LexicalSelectionAlwaysOnDisplay.tsx

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {selectionAlwaysOnDisplay} from '@lexical/utils';
+import {useEffect} from 'react';
+
+type Props = Readonly<{
+  onReposition?: (node: readonly HTMLElement[]) => void;
+}>;
+
+export function SelectionAlwaysOnDisplay({onReposition}: Props): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    return selectionAlwaysOnDisplay(editor, onReposition);
+  }, [editor, onReposition]);
+
+  return null;
+}

package/src/LexicalTabIndentationPlugin.tsx

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import {
+  type CanIndentPredicate,
+  registerTabIndentation,
+} from '@lexical/extension';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useEffect} from 'react';
+
+export {registerTabIndentation};
+
+/**
+ * This plugin adds the ability to indent content using the tab key. Generally, we don't
+ * recommend using this plugin as it could negatively affect accessibility for keyboard
+ * users, causing focus to become trapped within the editor.
+ */
+export function TabIndentationPlugin({
+  maxIndent,
+  $canIndent,
+}: {
+  maxIndent?: number;
+  /**
+   * By default, indents are set on all elements for which the {@link ElementNode.canIndent} returns true.
+   * This option allows you to set indents for specific nodes without overriding the method for others.
+   */
+  $canIndent?: CanIndentPredicate;
+}): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    return registerTabIndentation(editor, maxIndent, $canIndent);
+  }, [editor, maxIndent, $canIndent]);
+
+  return null;
+}

package/src/LexicalTableOfContentsPlugin.tsx

@@ -0,0 +1,277 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type {JSX} from 'react';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$isHeadingNode, HeadingNode, HeadingTagType} from '@lexical/rich-text';
+import {$getNextRightPreorderNode} from '@lexical/utils';
+import {
+  $getNodeByKey,
+  $getRoot,
+  $isElementNode,
+  ElementNode,
+  LexicalEditor,
+  NodeKey,
+  NodeMutation,
+  TextNode,
+} from 'lexical';
+import {useEffect, useState} from 'react';
+
+export type TableOfContentsEntry = [
+  key: NodeKey,
+  text: string,
+  tag: HeadingTagType,
+];
+
+function toEntry(heading: HeadingNode): TableOfContentsEntry {
+  return [heading.getKey(), heading.getTextContent(), heading.getTag()];
+}
+
+function $insertHeadingIntoTableOfContents(
+  prevHeading: HeadingNode | null,
+  newHeading: HeadingNode | null,
+  currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
+  if (newHeading === null) {
+    return currentTableOfContents;
+  }
+  const newEntry: TableOfContentsEntry = toEntry(newHeading);
+  let newTableOfContents: Array<TableOfContentsEntry> = [];
+  if (prevHeading === null) {
+    // check if key already exists
+    if (
+      currentTableOfContents.length > 0 &&
+      currentTableOfContents[0][0] === newHeading.__key
+    ) {
+      return currentTableOfContents;
+    }
+    newTableOfContents = [newEntry, ...currentTableOfContents];
+  } else {
+    for (let i = 0; i < currentTableOfContents.length; i++) {
+      const key = currentTableOfContents[i][0];
+      newTableOfContents.push(currentTableOfContents[i]);
+      if (key === prevHeading.getKey() && key !== newHeading.getKey()) {
+        // check if key already exists
+        if (
+          i + 1 < currentTableOfContents.length &&
+          currentTableOfContents[i + 1][0] === newHeading.__key
+        ) {
+          return currentTableOfContents;
+        }
+        newTableOfContents.push(newEntry);
+      }
+    }
+  }
+  return newTableOfContents;
+}
+
+function $deleteHeadingFromTableOfContents(
+  key: NodeKey,
+  currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
+  const newTableOfContents = [];
+  for (const heading of currentTableOfContents) {
+    if (heading[0] !== key) {
+      newTableOfContents.push(heading);
+    }
+  }
+  return newTableOfContents;
+}
+
+function $updateHeadingInTableOfContents(
+  heading: HeadingNode,
+  currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
+  const newTableOfContents: Array<TableOfContentsEntry> = [];
+  for (const oldHeading of currentTableOfContents) {
+    if (oldHeading[0] === heading.getKey()) {
+      newTableOfContents.push(toEntry(heading));
+    } else {
+      newTableOfContents.push(oldHeading);
+    }
+  }
+  return newTableOfContents;
+}
+
+/**
+ * Returns the updated table of contents, placing the given `heading` before the given `prevHeading`. If `prevHeading`
+ * is undefined, `heading` is placed at the start of table of contents
+ */
+function $updateHeadingPosition(
+  prevHeading: HeadingNode | null,
+  heading: HeadingNode,
+  currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
+  const newTableOfContents: Array<TableOfContentsEntry> = [];
+  const newEntry: TableOfContentsEntry = toEntry(heading);
+
+  if (!prevHeading) {
+    newTableOfContents.push(newEntry);
+  }
+  for (const oldHeading of currentTableOfContents) {
+    if (oldHeading[0] === heading.getKey()) {
+      continue;
+    }
+    newTableOfContents.push(oldHeading);
+    if (prevHeading && oldHeading[0] === prevHeading.getKey()) {
+      newTableOfContents.push(newEntry);
+    }
+  }
+
+  return newTableOfContents;
+}
+
+function $getPreviousHeading(node: HeadingNode): HeadingNode | null {
+  let prevHeading = $getNextRightPreorderNode(node);
+  while (prevHeading !== null && !$isHeadingNode(prevHeading)) {
+    prevHeading = $getNextRightPreorderNode(prevHeading);
+  }
+  return prevHeading;
+}
+
+type Props = {
+  children: (
+    values: Array<TableOfContentsEntry>,
+    editor: LexicalEditor,
+  ) => JSX.Element;
+};
+
+export function TableOfContentsPlugin({children}: Props): JSX.Element {
+  const [tableOfContents, setTableOfContents] = useState<
+    Array<TableOfContentsEntry>
+  >([]);
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    // Set table of contents initial state
+    let currentTableOfContents: Array<TableOfContentsEntry> = [];
+    editor.getEditorState().read(() => {
+      const updateCurrentTableOfContents = (node: ElementNode) => {
+        for (const child of node.getChildren()) {
+          if ($isHeadingNode(child)) {
+            currentTableOfContents.push([
+              child.getKey(),
+              child.getTextContent(),
+              child.getTag(),
+            ]);
+          } else if ($isElementNode(child)) {
+            updateCurrentTableOfContents(child);
+          }
+        }
+      };
+
+      updateCurrentTableOfContents($getRoot());
+      setTableOfContents(currentTableOfContents);
+    });
+
+    const removeRootUpdateListener = editor.registerUpdateListener(
+      ({editorState, dirtyElements}) => {
+        editorState.read(() => {
+          const updateChildHeadings = (node: ElementNode) => {
+            for (const child of node.getChildren()) {
+              if ($isHeadingNode(child)) {
+                const prevHeading = $getPreviousHeading(child);
+                currentTableOfContents = $updateHeadingPosition(
+                  prevHeading,
+                  child,
+                  currentTableOfContents,
+                );
+                setTableOfContents(currentTableOfContents);
+              } else if ($isElementNode(child)) {
+                updateChildHeadings(child);
+              }
+            }
+          };
+
+          // If a node is changes, all child heading positions need to be updated
+          $getRoot()
+            .getChildren()
+            .forEach(node => {
+              if ($isElementNode(node) && dirtyElements.get(node.__key)) {
+                updateChildHeadings(node);
+              }
+            });
+        });
+      },
+    );
+
+    // Listen to updates to heading mutations and update state
+    const removeHeaderMutationListener = editor.registerMutationListener(
+      HeadingNode,
+      (mutatedNodes: Map<string, NodeMutation>) => {
+        editor.getEditorState().read(() => {
+          for (const [nodeKey, mutation] of mutatedNodes) {
+            if (mutation === 'created') {
+              const newHeading = $getNodeByKey<HeadingNode>(nodeKey);
+              if (newHeading !== null) {
+                const prevHeading = $getPreviousHeading(newHeading);
+                currentTableOfContents = $insertHeadingIntoTableOfContents(
+                  prevHeading,
+                  newHeading,
+                  currentTableOfContents,
+                );
+              }
+            } else if (mutation === 'destroyed') {
+              currentTableOfContents = $deleteHeadingFromTableOfContents(
+                nodeKey,
+                currentTableOfContents,
+              );
+            } else if (mutation === 'updated') {
+              const newHeading = $getNodeByKey<HeadingNode>(nodeKey);
+              if (newHeading !== null) {
+                const prevHeading = $getPreviousHeading(newHeading);
+                currentTableOfContents = $updateHeadingPosition(
+                  prevHeading,
+                  newHeading,
+                  currentTableOfContents,
+                );
+              }
+            }
+          }
+          setTableOfContents(currentTableOfContents);
+        });
+      },
+      // Initialization is handled separately
+      {skipInitialization: true},
+    );
+
+    // Listen to text node mutation updates
+    const removeTextNodeMutationListener = editor.registerMutationListener(
+      TextNode,
+      (mutatedNodes: Map<string, NodeMutation>) => {
+        editor.getEditorState().read(() => {
+          for (const [nodeKey, mutation] of mutatedNodes) {
+            if (mutation === 'updated') {
+              const currNode = $getNodeByKey(nodeKey);
+              if (currNode !== null) {
+                const parentNode = currNode.getParentOrThrow();
+                if ($isHeadingNode(parentNode)) {
+                  currentTableOfContents = $updateHeadingInTableOfContents(
+                    parentNode,
+                    currentTableOfContents,
+                  );
+                  setTableOfContents(currentTableOfContents);
+                }
+              }
+            }
+          }
+        });
+      },
+      // Initialization is handled separately
+      {skipInitialization: true},
+    );
+
+    return () => {
+      removeHeaderMutationListener();
+      removeTextNodeMutationListener();
+      removeRootUpdateListener();
+    };
+  }, [editor]);
+
+  return children(tableOfContents, editor);
+}