zurfyx-lexical-react 0.39.1-nightly.20251225.0

package/src/LexicalSelectionAlwaysOnDisplay.tsx

@@ -0,0 +1,20 @@
+/**
+ * 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';
+
+export function SelectionAlwaysOnDisplay(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    return selectionAlwaysOnDisplay(editor);
+  }, [editor]);
+
+  return null;
+}

package/src/LexicalTabIndentationPlugin.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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 {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}: {maxIndent?: number}): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    return registerTabIndentation(editor, maxIndent);
+  }, [editor, maxIndent]);
+
+  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);
+}

package/src/LexicalTablePlugin.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 {signal} from '@lexical/extension';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $isScrollableTablesActive,
+  registerTableCellUnmergeTransform,
+  registerTablePlugin,
+  registerTableSelectionObserver,
+  setScrollableTablesActive,
+  TableCellNode,
+  TableNode,
+} from '@lexical/table';
+import {useEffect, useMemo} from 'react';
+
+export interface TablePluginProps {
+  /**
+   * When `false` (default `true`), merged cell support (colspan and rowspan) will be disabled and all
+   * tables will be forced into a regular grid with 1x1 table cells.
+   */
+  hasCellMerge?: boolean;
+  /**
+   * When `false` (default `true`), the background color of TableCellNode will always be removed.
+   */
+  hasCellBackgroundColor?: boolean;
+  /**
+   * When `true` (default `true`), the tab key can be used to navigate table cells.
+   */
+  hasTabHandler?: boolean;
+  /**
+   * When `true` (default `false`), tables will be wrapped in a `<div>` to enable horizontal scrolling
+   */
+  hasHorizontalScroll?: boolean;
+  /**
+   * When `true` (default `false`), nested tables will be allowed.
+   *
+   * @experimental Nested tables are not officially supported.
+   */
+  hasNestedTables?: boolean;
+}
+
+/**
+ * A plugin to enable all of the features of Lexical's TableNode.
+ *
+ * @param props - See type for documentation
+ * @returns An element to render in your LexicalComposer
+ */
+export function TablePlugin({
+  hasCellMerge = true,
+  hasCellBackgroundColor = true,
+  hasTabHandler = true,
+  hasHorizontalScroll = false,
+  hasNestedTables = false,
+}: TablePluginProps): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    const hadHorizontalScroll = $isScrollableTablesActive(editor);
+    if (hadHorizontalScroll !== hasHorizontalScroll) {
+      setScrollableTablesActive(editor, hasHorizontalScroll);
+      // Registering the transform has the side-effect of marking all existing
+      // TableNodes as dirty. The handler is immediately unregistered.
+      editor.registerNodeTransform(TableNode, () => {})();
+    }
+  }, [editor, hasHorizontalScroll]);
+
+  const hasNestedTablesSignal = useMemo(() => signal(false), []);
+  if (hasNestedTablesSignal.peek() !== hasNestedTables) {
+    hasNestedTablesSignal.value = hasNestedTables;
+  }
+
+  useEffect(
+    () => registerTablePlugin(editor, {hasNestedTables: hasNestedTablesSignal}),
+    [editor, hasNestedTablesSignal],
+  );
+
+  useEffect(
+    () => registerTableSelectionObserver(editor, hasTabHandler),
+    [editor, hasTabHandler],
+  );
+
+  // Unmerge cells when the feature isn't enabled
+  useEffect(() => {
+    if (!hasCellMerge) {
+      return registerTableCellUnmergeTransform(editor);
+    }
+  }, [editor, hasCellMerge]);
+
+  // Remove cell background color when feature is disabled
+  useEffect(() => {
+    if (hasCellBackgroundColor) {
+      return;
+    }
+    return editor.registerNodeTransform(TableCellNode, (node) => {
+      if (node.getBackgroundColor() !== null) {
+        node.setBackgroundColor(null);
+      }
+    });
+  }, [editor, hasCellBackgroundColor, hasCellMerge]);
+
+  return null;
+}

package/src/LexicalTreeView.tsx

@@ -0,0 +1,128 @@
+/**
+ * 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 type {JSX} from 'react';
+
+import {
+  CustomPrintNodeFn,
+  generateContent,
+  TreeView as TreeViewCore,
+  useLexicalCommandsLog,
+} from '@lexical/devtools-core';
+import {mergeRegister} from '@lexical/utils';
+import * as React from 'react';
+import {useEffect, useState} from 'react';
+
+/**
+ * TreeView is a React component that provides a visual representation of
+ * the Lexical editor's state and enables debugging features like time travel
+ * and custom tree node rendering.
+ *
+ * @param {Object} props - The properties passed to the TreeView component.
+ * @param {LexicalEditor} props.editor - The Lexical editor instance to be visualized and debugged.
+ * @param {string} [props.treeTypeButtonClassName] - Custom class name for the tree type toggle button.
+ * @param {string} [props.timeTravelButtonClassName] - Custom class name for the time travel toggle button.
+ * @param {string} [props.timeTravelPanelButtonClassName] - Custom class name for buttons inside the time travel panel.
+ * @param {string} [props.timeTravelPanelClassName] - Custom class name for the overall time travel panel container.
+ * @param {string} [props.timeTravelPanelSliderClassName] - Custom class name for the time travel slider in the panel.
+ * @param {string} [props.viewClassName] - Custom class name for the tree view container.
+ * @param {CustomPrintNodeFn} [props.customPrintNode] - A function for customizing the display of nodes in the tree.
+ *
+ * @returns {JSX.Element} - A React element that visualizes the editor's state and supports debugging interactions.
+ */
+
+export function TreeView({
+  treeTypeButtonClassName,
+  timeTravelButtonClassName,
+  timeTravelPanelSliderClassName,
+  timeTravelPanelButtonClassName,
+  timeTravelPanelClassName,
+  viewClassName,
+  editor,
+  customPrintNode,
+}: {
+  editor: LexicalEditor;
+  treeTypeButtonClassName?: string;
+  timeTravelButtonClassName?: string;
+  timeTravelPanelButtonClassName?: string;
+  timeTravelPanelClassName?: string;
+  timeTravelPanelSliderClassName?: string;
+  viewClassName?: string;
+  customPrintNode?: CustomPrintNodeFn;
+}): JSX.Element {
+  const treeElementRef = React.createRef<HTMLPreElement>();
+
+  const [editorCurrentState, setEditorCurrentState] = useState<EditorState>(
+    editor.getEditorState(),
+  );
+
+  const commandsLog = useLexicalCommandsLog(editor);
+
+  useEffect(() => {
+    // Registers listeners to update the tree view when the editor state changes
+    return mergeRegister(
+      editor.registerUpdateListener(({editorState}) => {
+        setEditorCurrentState(editorState);
+      }),
+      editor.registerEditableListener(() => {
+        setEditorCurrentState(editor.getEditorState());
+      }),
+    );
+  }, [editor]);
+
+  useEffect(() => {
+    const element = treeElementRef.current;
+
+    if (element !== null) {
+      // Assigns the editor instance to the tree view DOM element for internal tracking
+      // @ts-ignore Internal field used by Lexical
+      element.__lexicalEditor = editor;
+
+      return () => {
+        // Cleans up the reference when the component is unmounted
+        // @ts-ignore Internal field used by Lexical
+        element.__lexicalEditor = null;
+      };
+    }
+  }, [editor, treeElementRef]);
+
+  /**
+   * Handles toggling the readonly state of the editor.
+   *
+   * @param {boolean} isReadonly - Whether the editor should be set to readonly.
+   */
+  const handleEditorReadOnly = (isReadonly: boolean) => {
+    const rootElement = editor.getRootElement();
+    if (rootElement == null) {
+      return;
+    }
+
+    rootElement.contentEditable = isReadonly ? 'false' : 'true';
+  };
+
+  return (
+    <TreeViewCore
+      treeTypeButtonClassName={treeTypeButtonClassName}
+      timeTravelButtonClassName={timeTravelButtonClassName}
+      timeTravelPanelSliderClassName={timeTravelPanelSliderClassName}
+      timeTravelPanelButtonClassName={timeTravelPanelButtonClassName}
+      viewClassName={viewClassName}
+      timeTravelPanelClassName={timeTravelPanelClassName}
+      setEditorReadOnly={handleEditorReadOnly}
+      editorState={editorCurrentState}
+      setEditorState={(state) => editor.setEditorState(state)}
+      generateContent={async function (exportDOM) {
+        // Generates the content for the tree view, allowing customization with exportDOM and customPrintNode
+        return generateContent(editor, commandsLog, exportDOM, customPrintNode);
+      }}
+      ref={treeElementRef}
+      commandsLog={commandsLog}
+    />
+  );
+}