@lexical/react 0.44.1-nightly.20260518.0 → 0.45.0

package/src/LexicalNestedComposer.tsx

@@ -0,0 +1,221 @@
+/**
+ * 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 {LexicalComposerContextType} from '@lexical/react/LexicalComposerContext';
+import type {EditableListener} from 'lexical';
+import type {JSX} from 'react';
+
+import invariant from '@lexical/internal/invariant';
+import warnOnlyOnce from '@lexical/internal/warnOnlyOnce';
+import {CollaborationContext} from '@lexical/react/LexicalCollaborationContext';
+import {
+  createLexicalComposerContext,
+  LexicalComposerContext,
+} from '@lexical/react/LexicalComposerContext';
+import {
+  createSharedNodeState,
+  EditorThemeClasses,
+  getRegisteredNode,
+  getTransformSetFromKlass,
+  Klass,
+  LexicalEditor,
+  LexicalNode,
+  LexicalNodeReplacement,
+} from 'lexical';
+import * as React from 'react';
+import {ReactNode, useContext, useEffect, useMemo, useRef} from 'react';
+
+export interface LexicalNestedComposerProps {
+  /**
+   * Any children (e.g. plug-ins) for this editor. Note that the nested editor
+   * does not inherit any plug-ins or registrations from those plug-ins (such
+   * as transforms and command listeners that may be necessary for correct
+   * operation of those nodes) from the parent editor. If you are using nodes
+   * that require plug-ins they must also be instantiated here.
+   */
+  children?: ReactNode;
+  /**
+   * The nested editor, created outside of this component (typically in the
+   * implementation of a LexicalNode) with {@link createEditor}
+   */
+  initialEditor: LexicalEditor;
+  /**
+   * Optionally overwrite the theme of the initialEditor
+   */
+  initialTheme?: EditorThemeClasses;
+  /**
+   * @deprecated This feature is not safe or correctly implemented and will be
+   * removed in v0.32.0. The only correct time to configure the nodes is when
+   * creating the initialEditor.
+   *
+   * @example
+   * ```ts
+   * // This is normally in the implementation of a LexicalNode that
+   * // owns the nested editor
+   * editor = createEditor({nodes: [], parentEditor: $getEditor()});
+   * ```
+   */
+  initialNodes?: ReadonlyArray<Klass<LexicalNode> | LexicalNodeReplacement>;
+  /**
+   * If this is not explicitly set to true, and the collab plugin is active,
+   * rendering the children of this component will not happen until collab is ready.
+   */
+  skipCollabChecks?: undefined | true;
+  /**
+   * If this is not explicitly set to true, the editable state of the nested
+   * editor will automatically follow the parent editor's editable state.
+   * When set to true, the nested editor is responsible for managing its own
+   * editable state.
+   *
+   * Available since v0.29.0
+   */
+  skipEditableListener?: undefined | true;
+}
+
+const initialNodesWarning = warnOnlyOnce(
+  `LexicalNestedComposer initialNodes is deprecated and will be removed in v0.32.0, it has never worked correctly.\nYou can configure your editor's nodes with createEditor({nodes: [], parentEditor: $getEditor()})`,
+);
+const explicitNamespaceWarning = warnOnlyOnce(
+  `LexicalNestedComposer initialEditor should explicitly initialize its namespace when the node configuration differs from the parentEditor. For backwards compatibility, the namespace will be initialized from parentEditor until v0.32.0, but this has always had incorrect copy/paste behavior when the configuration differed.\nYou can configure your editor's namespace with createEditor({namespace: 'nested-editor-namespace', nodes: [], parentEditor: $getEditor()}).`,
+);
+
+export function LexicalNestedComposer({
+  initialEditor,
+  children,
+  initialNodes,
+  initialTheme,
+  skipCollabChecks,
+  skipEditableListener,
+}: LexicalNestedComposerProps): JSX.Element {
+  const wasCollabPreviouslyReadyRef = useRef(false);
+  const parentContext = useContext(LexicalComposerContext);
+
+  if (parentContext == null) {
+    invariant(false, 'Unexpected parent context null on a nested composer');
+  }
+
+  const [parentEditor, {getTheme: getParentTheme}] = parentContext;
+
+  const composerContext: [LexicalEditor, LexicalComposerContextType] = useMemo(
+    () => {
+      const composerTheme: EditorThemeClasses | undefined =
+        initialTheme || getParentTheme() || undefined;
+
+      const context: LexicalComposerContextType = createLexicalComposerContext(
+        parentContext,
+        composerTheme,
+      );
+
+      if (composerTheme !== undefined) {
+        // eslint-disable-next-line react-hooks/immutability
+        initialEditor._config.theme = composerTheme;
+      }
+
+      // eslint-disable-next-line react-hooks/immutability
+      initialEditor._parentEditor = initialEditor._parentEditor || parentEditor;
+      const createEditorArgs = initialEditor._createEditorArgs;
+      const explicitNamespace = createEditorArgs && createEditorArgs.namespace;
+
+      if (!initialNodes) {
+        if (!(createEditorArgs && createEditorArgs.nodes)) {
+          // eslint-disable-next-line react-hooks/immutability
+          const parentNodes = (initialEditor._nodes = new Map(
+            parentEditor._nodes,
+          ));
+          if (!explicitNamespace) {
+            // This is the only safe situation to inherit the parent's namespace
+            // eslint-disable-next-line react-hooks/immutability
+            initialEditor._config.namespace = parentEditor._config.namespace;
+          }
+          for (const [type, entry] of parentNodes) {
+            initialEditor._nodes.set(type, {
+              exportDOM: entry.exportDOM,
+              klass: entry.klass,
+              replace: entry.replace,
+              replaceWithKlass: entry.replaceWithKlass,
+              sharedNodeState: createSharedNodeState(entry.klass),
+              transforms: getTransformSetFromKlass(entry.klass),
+            });
+          }
+        } else if (!explicitNamespace) {
+          explicitNamespaceWarning();
+          // eslint-disable-next-line react-hooks/immutability
+          initialEditor._config.namespace = parentEditor._config.namespace;
+        }
+      } else {
+        initialNodesWarning();
+        if (!explicitNamespace) {
+          explicitNamespaceWarning();
+          // eslint-disable-next-line react-hooks/immutability
+          initialEditor._config.namespace = parentEditor._config.namespace;
+        }
+        for (let klass of initialNodes) {
+          let replace = null;
+          let replaceWithKlass = null;
+
+          if (typeof klass !== 'function') {
+            const options = klass;
+            klass = options.replace;
+            replace = options.with;
+            replaceWithKlass = options.withKlass || null;
+          }
+          const registeredKlass = getRegisteredNode(
+            initialEditor,
+            klass.getType(),
+          );
+
+          initialEditor._nodes.set(klass.getType(), {
+            exportDOM: registeredKlass ? registeredKlass.exportDOM : undefined,
+            klass,
+            replace,
+            replaceWithKlass,
+            sharedNodeState: createSharedNodeState(klass),
+            transforms: getTransformSetFromKlass(klass),
+          });
+        }
+      }
+
+      return [initialEditor, context];
+    },
+
+    // We only do this for init
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  // If collaboration is enabled, make sure we don't render the children until the collaboration subdocument is ready.
+  const collabContext = useContext(CollaborationContext);
+  const {isCollabActive, yjsDocMap} = collabContext ?? {};
+
+  const isCollabReady =
+    skipCollabChecks ||
+    wasCollabPreviouslyReadyRef.current ||
+    (yjsDocMap && yjsDocMap.has(initialEditor.getKey()));
+
+  useEffect(() => {
+    if (isCollabReady) {
+      wasCollabPreviouslyReadyRef.current = true;
+    }
+  }, [isCollabReady]);
+
+  // Update `isEditable` state of nested editor in response to the same change on parent editor.
+  useEffect(() => {
+    if (!skipEditableListener) {
+      const editableListener: EditableListener = editable =>
+        initialEditor.setEditable(editable);
+      editableListener(parentEditor.isEditable());
+      return parentEditor.registerEditableListener(editableListener);
+    }
+  }, [initialEditor, parentEditor, skipEditableListener]);
+
+  return (
+    <LexicalComposerContext.Provider value={composerContext}>
+      {!isCollabActive || isCollabReady ? children : null}
+    </LexicalComposerContext.Provider>
+  );
+}

package/src/LexicalNodeContextMenuPlugin.tsx

@@ -0,0 +1,316 @@
+/**
+ * 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 {
+  autoUpdate,
+  flip,
+  FloatingFocusManager,
+  FloatingOverlay,
+  FloatingPortal,
+  offset,
+  shift,
+  useDismiss,
+  useFloating,
+  useInteractions,
+  useListNavigation,
+  useRole,
+  useTypeahead,
+} from '@floating-ui/react';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$getNearestNodeFromDOMNode, $getRoot, LexicalNode} from 'lexical';
+import {forwardRef, JSX, RefObject, useEffect, useRef, useState} from 'react';
+
+class MenuOption {
+  key: string;
+  ref?: RefObject<HTMLElement | null>;
+
+  constructor(key: string) {
+    this.key = key;
+    this.ref = {current: null};
+    this.setRefElement = this.setRefElement.bind(this);
+  }
+
+  setRefElement(element: HTMLElement | null) {
+    this.ref = {current: element};
+  }
+}
+
+class NodeContextMenuOption extends MenuOption {
+  type: string;
+  title: string;
+  icon: JSX.Element | null;
+  disabled: boolean;
+  $onSelect: () => void;
+  $showOn?: (node: LexicalNode) => boolean;
+
+  constructor(
+    title: string,
+    options: {
+      disabled?: boolean;
+      icon?: JSX.Element;
+      $onSelect: () => void;
+      $showOn?: (node: LexicalNode) => boolean;
+    },
+  ) {
+    super(title);
+    this.type = 'item';
+    this.title = title;
+    this.disabled = options.disabled ?? false;
+    this.icon = options.icon ?? null;
+    this.$onSelect = options.$onSelect;
+    if (options.$showOn) {
+      this.$showOn = options.$showOn;
+    }
+  }
+}
+
+class NodeContextMenuSeparator extends MenuOption {
+  type: string;
+  $showOn?: (node: LexicalNode) => boolean;
+
+  constructor(options?: {$showOn?: (node: LexicalNode) => boolean}) {
+    super('_separator');
+    this.type = 'separator';
+    if (options && options.$showOn) {
+      this.$showOn = options.$showOn;
+    }
+  }
+}
+
+const ContextMenuSeparatorItem = forwardRef<
+  HTMLButtonElement,
+  React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    disabled?: boolean;
+  }
+>(({className, disabled, ...props}, ref) => {
+  return <hr className={className} />;
+});
+
+const ContextMenuItem = forwardRef<
+  HTMLButtonElement,
+  React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    label?: string;
+    disabled?: boolean;
+    icon?: JSX.Element | null;
+  }
+>(({className, label, disabled, icon, ...props}, ref) => {
+  return (
+    <button
+      {...props}
+      className={className}
+      ref={ref}
+      role="menuitem"
+      disabled={disabled}>
+      {icon}
+      {label}
+    </button>
+  );
+});
+
+type ContextMenuType = NodeContextMenuOption | NodeContextMenuSeparator;
+
+interface MenuSeparatorType {
+  className: string;
+  key: string;
+  type: string;
+}
+
+interface MenuItemType extends MenuSeparatorType {
+  disabled: boolean;
+  label: string;
+  onClick: () => void;
+  title: string;
+}
+
+type MenuType = MenuItemType | MenuSeparatorType;
+
+interface Props {
+  label?: string;
+  nested?: boolean;
+  itemClassName?: string;
+  separatorClassName?: string;
+  items: ContextMenuType[];
+}
+
+const NodeContextMenuPlugin = forwardRef<
+  HTMLButtonElement,
+  Props & React.HTMLProps<HTMLButtonElement>
+>(({items, className, itemClassName, separatorClassName}, forwardedRef) => {
+  const [editor] = useLexicalComposerContext();
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const [isOpen, setIsOpen] = useState(false);
+
+  const listItemsRef = useRef<Array<HTMLButtonElement | null>>([]);
+  const listContentRef = useRef<Array<string | null>>([]);
+
+  const {refs, floatingStyles, context} = useFloating({
+    middleware: [
+      offset({alignmentAxis: 4, mainAxis: 5}),
+      flip({
+        fallbackPlacements: ['left-start'],
+      }),
+      shift({padding: 10}),
+    ],
+    onOpenChange: setIsOpen,
+    open: isOpen,
+    placement: 'right-start',
+    strategy: 'fixed',
+    whileElementsMounted: autoUpdate,
+  });
+
+  const role = useRole(context, {role: 'menu'});
+  const dismiss = useDismiss(context);
+  const listNavigation = useListNavigation(context, {
+    activeIndex,
+    listRef: listItemsRef,
+    onNavigate: setActiveIndex,
+  });
+  const typeahead = useTypeahead(context, {
+    activeIndex,
+    enabled: isOpen,
+    listRef: listContentRef,
+    onMatch: setActiveIndex,
+  });
+
+  const {getFloatingProps, getItemProps} = useInteractions([
+    role,
+    dismiss,
+    listNavigation,
+    typeahead,
+  ]);
+
+  const [renderItems, setRenderItems] = useState<MenuType[]>([]);
+
+  useEffect(() => {
+    function onContextMenu(e: MouseEvent) {
+      e.preventDefault();
+
+      refs.setPositionReference({
+        getBoundingClientRect() {
+          return {
+            bottom: e.clientY,
+            height: 0,
+            left: e.clientX,
+            right: e.clientX,
+            top: e.clientY,
+            width: 0,
+            x: e.clientX,
+            y: e.clientY,
+          };
+        },
+      });
+
+      let visibleItems: ContextMenuType[] = [];
+      if (items) {
+        editor.read(() => {
+          const node =
+            $getNearestNodeFromDOMNode(e.target as Element) ?? $getRoot();
+          if (node) {
+            visibleItems = items!.filter(option =>
+              option.$showOn ? option.$showOn(node) : true,
+            );
+          }
+        });
+      }
+
+      const renderableItems = visibleItems.map((option, index) => {
+        if (option.type === 'separator') {
+          return {
+            className: separatorClassName,
+            key: option.key + '-' + index,
+            type: option.type,
+          };
+        } else {
+          return {
+            className: itemClassName,
+            disabled: (option as NodeContextMenuOption).disabled,
+            icon: (option as NodeContextMenuOption).icon,
+            key: option.key,
+            label: (option as NodeContextMenuOption).title,
+            onClick: () =>
+              editor.update(() =>
+                (option as NodeContextMenuOption).$onSelect(),
+              ),
+            title: (option as NodeContextMenuOption).title,
+            type: option.type,
+          };
+        }
+      }) as MenuType[];
+
+      listContentRef.current = renderableItems.map(item => item.key);
+
+      setRenderItems(renderableItems);
+
+      setIsOpen(true);
+    }
+
+    return editor.registerRootListener(rootElement => {
+      if (rootElement !== null) {
+        rootElement.addEventListener('contextmenu', onContextMenu);
+        return () =>
+          rootElement.removeEventListener('contextmenu', onContextMenu);
+      }
+    });
+  }, [items, itemClassName, separatorClassName, refs, editor]);
+
+  return (
+    <FloatingPortal>
+      {isOpen && (
+        <FloatingOverlay lockScroll={true}>
+          <FloatingFocusManager context={context} initialFocus={refs.floating}>
+            <div
+              className={className}
+              ref={refs.setFloating}
+              style={floatingStyles}
+              {...getFloatingProps()}>
+              {renderItems.map((item, index) => {
+                if (item.type === 'item') {
+                  return (
+                    <ContextMenuItem
+                      {...getItemProps({
+                        ...item,
+                        onClick() {
+                          (item as MenuItemType).onClick();
+                          setIsOpen(false);
+                        },
+                        onMouseUp() {
+                          (item as MenuItemType).onClick();
+                          setIsOpen(false);
+                        },
+                        ref(node: HTMLButtonElement) {
+                          listItemsRef.current[index] = node;
+                        },
+                        tabIndex: activeIndex === index ? 0 : -1,
+                      })}
+                      key={item.key}
+                    />
+                  );
+                } else if (item.type === 'separator') {
+                  return (
+                    <ContextMenuSeparatorItem
+                      {...getItemProps({
+                        ...item,
+                        ref(node: HTMLButtonElement) {
+                          listItemsRef.current[index] = node;
+                        },
+                        tabIndex: activeIndex === index ? 0 : -1,
+                      })}
+                      key={item.key}
+                    />
+                  );
+                }
+              })}
+            </div>
+          </FloatingFocusManager>
+        </FloatingOverlay>
+      )}
+    </FloatingPortal>
+  );
+});
+
+export {NodeContextMenuOption, NodeContextMenuPlugin, NodeContextMenuSeparator};

package/src/LexicalNodeEventPlugin.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 {Klass, LexicalEditor, LexicalNode, NodeKey} from 'lexical';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$findMatchingParent} from '@lexical/utils';
+import {$getNearestNodeFromDOMNode} from 'lexical';
+import {useEffect, useRef} from 'react';
+
+const capturedEvents = new Set<string>(['mouseenter', 'mouseleave']);
+
+export function NodeEventPlugin({
+  nodeType,
+  eventType,
+  eventListener,
+}: {
+  nodeType: Klass<LexicalNode>;
+  eventType: string;
+  eventListener: (
+    event: Event,
+    editor: LexicalEditor,
+    nodeKey: NodeKey,
+  ) => void;
+}): null {
+  const [editor] = useLexicalComposerContext();
+  const listenerRef = useRef(eventListener);
+
+  listenerRef.current = eventListener;
+
+  useEffect(() => {
+    const isCaptured = capturedEvents.has(eventType);
+
+    const onEvent = (event: Event) => {
+      editor.update(() => {
+        const nearestNode = $getNearestNodeFromDOMNode(event.target as Element);
+        if (nearestNode !== null) {
+          const targetNode = isCaptured
+            ? nearestNode instanceof nodeType
+              ? nearestNode
+              : null
+            : $findMatchingParent(
+                nearestNode,
+                node => node instanceof nodeType,
+              );
+          if (targetNode !== null) {
+            listenerRef.current(event, editor, targetNode.getKey());
+            return;
+          }
+        }
+      });
+    };
+
+    return editor.registerRootListener(rootElement => {
+      if (rootElement) {
+        rootElement.addEventListener(eventType, onEvent, isCaptured);
+        return () =>
+          rootElement.removeEventListener(eventType, onEvent, isCaptured);
+      }
+    });
+    // We intentionally don't respect changes to eventType.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor, nodeType]);
+
+  return null;
+}