@lexical/react 0.44.1-nightly.20260518.0 → 0.45.0

package/src/LexicalTablePlugin.ts

@@ -0,0 +1,118 @@
+/**
+ * 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, signal} from '@lexical/extension';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $isScrollableTablesActive,
+  registerTableCellUnmergeTransform,
+  registerTablePlugin,
+  registerTableSelectionObserver,
+  setScrollableTablesActive,
+  TableCellNode,
+} from '@lexical/table';
+import {$fullReconcile} from 'lexical';
+import {useEffect, useState} 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);
+      // Re-render existing tables through the new scroll-wrapper config without
+      // cloning every TableNode the way marking them dirty would. A full
+      // reconcile marks no nodes dirty, so it's deferred (no synchronous render
+      // from this effect) and produces no history entry.
+      editor.update($fullReconcile);
+    }
+  }, [editor, hasHorizontalScroll]);
+
+  const hasNestedTablesSignal = usePropSignal(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;
+}
+
+function usePropSignal<T>(value: T): Signal<T> {
+  const [configSignal] = useState(() => signal(value));
+  if (configSignal.peek() !== value) {
+    // eslint-disable-next-line react-hooks/immutability
+    configSignal.value = value;
+  }
+  return configSignal;
+}

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}
+    />
+  );
+}

package/src/LexicalTypeaheadMenuPlugin.tsx

@@ -0,0 +1,365 @@
+/**
+ * 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,
+  MenuTextMatch,
+  TriggerFn,
+} from './shared/LexicalMenu';
+import type {JSX} from 'react';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $getSelection,
+  $isRangeSelection,
+  $isTextNode,
+  COMMAND_PRIORITY_LOW,
+  CommandListenerPriority,
+  createCommand,
+  getDOMSelection,
+  LexicalCommand,
+  LexicalEditor,
+  RangeSelection,
+  TextNode,
+} from 'lexical';
+import {useCallback, useEffect, useState} from 'react';
+
+import {LexicalMenu, MenuOption, useMenuAnchorRef} from './shared/LexicalMenu';
+import {startTransition} from './shared/reactPatches';
+
+export const PUNCTUATION =
+  '\\.,\\+\\*\\?\\$\\@\\|#{}\\(\\)\\^\\-\\[\\]\\\\/!%\'"~=<>_:;';
+
+function getTextUpToAnchor(selection: RangeSelection): string | null {
+  const anchor = selection.anchor;
+  if (anchor.type !== 'text') {
+    return null;
+  }
+  const anchorNode = anchor.getNode();
+  if (!anchorNode.isSimpleText()) {
+    return null;
+  }
+  const anchorOffset = anchor.offset;
+  return anchorNode.getTextContent().slice(0, anchorOffset);
+}
+
+function tryToPositionRange(
+  leadOffset: number,
+  range: Range,
+  editorWindow: Window,
+): boolean {
+  const domSelection = getDOMSelection(editorWindow);
+  if (domSelection === null || !domSelection.isCollapsed) {
+    return false;
+  }
+  const anchorNode = domSelection.anchorNode;
+  const startOffset = leadOffset;
+  const endOffset = domSelection.anchorOffset;
+
+  if (anchorNode == null || endOffset == null) {
+    return false;
+  }
+
+  try {
+    range.setStart(anchorNode, startOffset);
+    range.setEnd(anchorNode, endOffset);
+  } catch (_error) {
+    return false;
+  }
+
+  return true;
+}
+
+function getQueryTextForSearch(editor: LexicalEditor): string | null {
+  let text = null;
+  editor.getEditorState().read(() => {
+    const selection = $getSelection();
+    if (!$isRangeSelection(selection)) {
+      return;
+    }
+    text = getTextUpToAnchor(selection);
+  });
+  return text;
+}
+
+function isSelectionOnEntityBoundary(
+  editor: LexicalEditor,
+  offset: number,
+): boolean {
+  if (offset !== 0) {
+    return false;
+  }
+  return editor.getEditorState().read(() => {
+    const selection = $getSelection();
+    if ($isRangeSelection(selection)) {
+      const anchor = selection.anchor;
+      const anchorNode = anchor.getNode();
+      const prevSibling = anchorNode.getPreviousSibling();
+      return $isTextNode(prevSibling) && prevSibling.isTextEntity();
+    }
+    return false;
+  });
+}
+
+// Got from https://stackoverflow.com/a/42543908/2013580
+export function getScrollParent(
+  element: HTMLElement,
+  includeHidden: boolean,
+): HTMLElement | HTMLBodyElement {
+  let style = getComputedStyle(element);
+  const excludeStaticParent = style.position === 'absolute';
+  const overflowRegex = includeHidden
+    ? /(auto|scroll|hidden)/
+    : /(auto|scroll)/;
+  if (style.position === 'fixed') {
+    return document.body;
+  }
+  for (
+    let parent: HTMLElement | null = element;
+    (parent = parent.parentElement);
+  ) {
+    style = getComputedStyle(parent);
+    if (excludeStaticParent && style.position === 'static') {
+      continue;
+    }
+    if (
+      overflowRegex.test(style.overflow + style.overflowY + style.overflowX)
+    ) {
+      return parent;
+    }
+  }
+  return document.body;
+}
+
+export {useDynamicPositioning} from './shared/LexicalMenu';
+
+export const SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND: LexicalCommand<{
+  index: number;
+  option: MenuOption;
+}> = createCommand('SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND');
+
+export function useBasicTypeaheadTriggerMatch(
+  trigger: string,
+  {
+    minLength = 1,
+    maxLength = 75,
+    punctuation = PUNCTUATION,
+    allowWhitespace = false,
+  }: {
+    minLength?: number;
+    maxLength?: number;
+    punctuation?: string;
+    allowWhitespace?: boolean;
+  },
+): TriggerFn {
+  return useCallback(
+    (text: string) => {
+      const validCharsSuffix = allowWhitespace ? '' : '\\s';
+      const validChars = '[^' + trigger + punctuation + validCharsSuffix + ']';
+      const TypeaheadTriggerRegex = new RegExp(
+        '(^|\\s|\\()(' +
+          '[' +
+          trigger +
+          ']' +
+          '((?:' +
+          validChars +
+          '){0,' +
+          maxLength +
+          '})' +
+          ')$',
+      );
+      const match = TypeaheadTriggerRegex.exec(text);
+      if (match !== null) {
+        const maybeLeadingWhitespace = match[1];
+        const matchingString = match[3];
+        if (matchingString.length >= minLength) {
+          return {
+            leadOffset: match.index + maybeLeadingWhitespace.length,
+            matchingString,
+            replaceableString: match[2],
+          };
+        }
+      }
+      return null;
+    },
+    [allowWhitespace, trigger, punctuation, maxLength, minLength],
+  );
+}
+
+export type TypeaheadMenuPluginProps<TOption extends MenuOption> = {
+  onQueryChange: (matchingString: string | null) => void;
+  onSelectOption: (
+    option: TOption,
+    textNodeContainingQuery: TextNode | null,
+    closeMenu: () => void,
+    matchingString: string,
+  ) => void;
+  options: Array<TOption>;
+  triggerFn: TriggerFn;
+  menuRenderFn?: MenuRenderFn<TOption>;
+  onOpen?: (resolution: MenuResolution) => void;
+  onClose?: () => void | PromiseLike<void>;
+  anchorClassName?: string;
+  commandPriority?: CommandListenerPriority;
+  parent?: HTMLElement;
+  preselectFirstItem?: boolean;
+  ignoreEntityBoundary?: boolean;
+};
+
+export function LexicalTypeaheadMenuPlugin<TOption extends MenuOption>({
+  options,
+  onQueryChange,
+  onSelectOption,
+  onOpen,
+  onClose,
+  menuRenderFn,
+  triggerFn,
+  anchorClassName,
+  commandPriority = COMMAND_PRIORITY_LOW,
+  parent,
+  preselectFirstItem = true,
+  ignoreEntityBoundary = false,
+}: TypeaheadMenuPluginProps<TOption>): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+  const [resolution, setResolution] = useState<MenuResolution | null>(null);
+  const anchorElementRef = useMenuAnchorRef(
+    resolution,
+    setResolution,
+    anchorClassName,
+    parent,
+  );
+
+  const closeTypeahead = useCallback(() => {
+    if (resolution === null) {
+      return;
+    }
+    const finish = () => {
+      setResolution(null);
+    };
+    let result;
+    try {
+      result = onClose && onClose();
+    } finally {
+      if (result) {
+        result.then(finish, finish);
+      } else {
+        finish();
+      }
+    }
+  }, [onClose, resolution]);
+
+  const openTypeahead = useCallback(
+    (res: MenuResolution) => {
+      setResolution(res);
+      if (onOpen != null && resolution === null) {
+        onOpen(res);
+      }
+    },
+    [onOpen, resolution],
+  );
+
+  useEffect(() => {
+    const updateListener = () => {
+      editor.getEditorState().read(() => {
+        // Check if editor is in read-only mode
+        if (!editor.isEditable()) {
+          closeTypeahead();
+          return;
+        }
+
+        if (editor.isComposing()) {
+          return;
+        }
+
+        const editorWindow = editor._window || window;
+        const range = editorWindow.document.createRange();
+        const selection = $getSelection();
+        const text = getQueryTextForSearch(editor);
+
+        if (
+          !$isRangeSelection(selection) ||
+          !selection.isCollapsed() ||
+          text === null ||
+          range === null
+        ) {
+          closeTypeahead();
+          return;
+        }
+
+        const match = triggerFn(text, editor);
+        onQueryChange(match ? match.matchingString : null);
+
+        if (
+          match !== null &&
+          (ignoreEntityBoundary ||
+            !isSelectionOnEntityBoundary(editor, match.leadOffset))
+        ) {
+          const isRangePositioned = tryToPositionRange(
+            match.leadOffset,
+            range,
+            editorWindow,
+          );
+          if (isRangePositioned !== null) {
+            startTransition(() =>
+              openTypeahead({
+                getRect: () => range.getBoundingClientRect(),
+                match,
+              }),
+            );
+            return;
+          }
+        }
+        closeTypeahead();
+      });
+    };
+
+    const removeUpdateListener = editor.registerUpdateListener(updateListener);
+
+    return () => {
+      removeUpdateListener();
+    };
+  }, [
+    editor,
+    triggerFn,
+    onQueryChange,
+    resolution,
+    closeTypeahead,
+    openTypeahead,
+    ignoreEntityBoundary,
+  ]);
+
+  useEffect(
+    () =>
+      editor.registerEditableListener(isEditable => {
+        if (!isEditable) {
+          closeTypeahead();
+        }
+      }),
+    [editor, closeTypeahead],
+  );
+
+  return resolution === null ||
+    editor === null ||
+    anchorElementRef.current === null ? null : (
+    <LexicalMenu
+      close={closeTypeahead}
+      resolution={resolution}
+      editor={editor}
+      anchorElementRef={anchorElementRef}
+      options={options}
+      menuRenderFn={menuRenderFn}
+      shouldSplitNodeWithQuery={true}
+      onSelectOption={onSelectOption}
+      commandPriority={commandPriority}
+      preselectFirstItem={preselectFirstItem}
+    />
+  );
+}
+
+export {MenuOption, MenuRenderFn, MenuResolution, MenuTextMatch, TriggerFn};