@lexical/react 0.44.1-nightly.20260519.0 → 0.45.1-dev.0

package/src/LexicalExtensionComposer.tsx

@@ -0,0 +1,117 @@
+/**
+ * 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 {
+  getExtensionDependencyFromEditor,
+  LexicalBuilder,
+} from '@lexical/extension';
+import {ReactConfig, ReactExtension} from '@lexical/react/ReactExtension';
+import {ReactProviderExtension} from '@lexical/react/ReactProviderExtension';
+import {type AnyLexicalExtensionArgument, configExtension} from 'lexical';
+import {useEffect, useMemo} from 'react';
+
+export interface LexicalExtensionComposerProps {
+  /**
+   * Your root extension, typically defined with {@link defineExtension}
+   */
+  extension: AnyLexicalExtensionArgument;
+  /**
+   * Any children will have access to useLexicalComposerContext (e.g. for React plug-ins or UX)
+   */
+  children?: React.ReactNode;
+  /**
+   * Override the default ContentEditable that is rendered as the first child of the
+   * composer. If this is null, then it is your responsibility to render a ContentEditable
+   * elsewhere in the tree. This is equivalent to
+   * `configExtension(ReactExtension, {contentEditable})` in your extension dependencies.
+   */
+  contentEditable?: ReactConfig['contentEditable'];
+}
+
+/**
+ * The equivalent of LexicalComposer for an extension. Make sure that your extension
+ * argument is stable (e.g. using module scope or useMemo) so
+ * that you are not re-creating the editor on every render!
+ *
+ * @example
+ * Module scoped extension
+ * ```tsx
+ * const extension = defineExtension({
+ *   name: "[root]",
+ *   dependencies: [RichTextExtension, HistoryExtension, EmojiExtension]
+ * });
+ * function MyEditor({ children }) {
+ *   return (<LexicalExtensionComposer extension={extension}>{children}</LexicalExtensionComposer>);
+ * }
+ * ```
+ *
+ * @example
+ * useMemo extension
+ * ```tsx
+ * function MyEditor({ emojiBaseUrl, children }) {
+ *   const extension = useMemo(() => {
+ *     return defineExtension({
+ *       name: "[root]",
+ *       dependencies: [
+ *         RichTextExtension,
+ *         HistoryExtension,
+ *         configExtension(EmojiExtension, { emojiBaseUrl }),
+ *       ],
+ *     });
+ *   }, [emojiBaseUrl]);
+ *   return (<LexicalExtensionComposer extension={extension}>{children}</LexicalExtensionComposer>);
+ * }
+ * ```
+ *
+ * @example
+ * Incorrect usage with unstable extension
+ * ```tsx
+ * function MyBrokenEditor({ emojiBaseUrl }) {
+ *   // This argument is not stable, the editor is re-created every render and
+ *   // all state is lost!
+ *   const extension = defineExtension({
+ *     name: "[root]",
+ *     dependencies: [RichTextExtension, HistoryExtension, EmojiExtension]
+ *   });
+ *   return (<LexicalExtensionComposer extension={extension}>{children}</LexicalExtensionComposer>);
+ * }
+ * ```
+ */
+export function LexicalExtensionComposer({
+  extension,
+  children,
+  contentEditable,
+}: LexicalExtensionComposerProps) {
+  const editor = useMemo(() => {
+    const builder = LexicalBuilder.fromExtensions([
+      ReactProviderExtension,
+      configExtension(
+        ReactExtension,
+        contentEditable === undefined ? {} : {contentEditable},
+      ),
+      extension,
+    ]);
+    return builder.buildEditor();
+  }, [contentEditable, extension]);
+  useEffect(() => {
+    // Strict mode workaround
+    let didMount = false;
+    queueMicrotask(() => {
+      didMount = true;
+    });
+    return () => {
+      if (didMount) {
+        editor.dispose();
+      }
+    };
+  }, [editor]);
+  const {Component} = getExtensionDependencyFromEditor(
+    editor,
+    ReactExtension,
+  ).output;
+  return <Component>{children}</Component>;
+}

package/src/LexicalExtensionEditorComposer.tsx

@@ -0,0 +1,46 @@
+/**
+ * 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 {getExtensionDependencyFromEditor} from '@lexical/extension';
+import {ReactExtension} from '@lexical/react/ReactExtension';
+import {LexicalEditorWithDispose} from 'lexical';
+
+export interface LexicalExtensionEditorComposerProps {
+  /**
+   * Your root extension, typically defined with {@link defineExtension}.
+   * The lifecycle of this editor is not owned by this component,
+   * you are responsible for calling `initialEditor.dispose()` if needed.
+   * Note also that any LexicalEditor can only be rendered to one root
+   * element, so if you try and use it from multiple components
+   * simultaneously then it will only be managed correctly by the last one
+   * to render.
+   */
+  initialEditor: LexicalEditorWithDispose;
+  /**
+   * Any children will have access to useLexicalComposerContext (e.g. for React plug-ins or UX)
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * The equivalent of LexicalComposer for an editor that was already built for
+ * extensions, typically used with nested editors.
+ *
+ * Make sure that your initialEditor argument is stable (e.g. using module scope or useMemo) so
+ * that you are not re-creating the editor on every render! The editor should be built with
+ * ReactProviderExtension and ReactExtension dependencies.
+ */
+export function LexicalExtensionEditorComposer({
+  initialEditor: editor,
+  children,
+}: LexicalExtensionEditorComposerProps) {
+  const {Component} = getExtensionDependencyFromEditor(
+    editor,
+    ReactExtension,
+  ).output;
+  return <Component>{children}</Component>;
+}

package/src/LexicalHashtagPlugin.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 {HashtagNode, registerLexicalHashtag} from '@lexical/hashtag';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useEffect} from 'react';
+
+export function HashtagPlugin(): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    if (!editor.hasNodes([HashtagNode])) {
+      throw new Error('HashtagPlugin: HashtagNode not registered on editor');
+    }
+    return registerLexicalHashtag(editor);
+  }, [editor]);
+
+  return null;
+}

package/src/LexicalHistoryPlugin.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 {HistoryState} from '@lexical/history';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+
+import {useHistory} from './shared/useHistory';
+
+export {createEmptyHistoryState} from '@lexical/history';
+
+export type {HistoryState};
+
+export function HistoryPlugin({
+  delay,
+  externalHistoryState,
+}: {
+  delay?: number;
+  externalHistoryState?: HistoryState;
+}): null {
+  const [editor] = useLexicalComposerContext();
+
+  useHistory(editor, externalHistoryState, delay);
+
+  return null;
+}

package/src/LexicalHorizontalRuleNode.tsx

@@ -0,0 +1,123 @@
+/**
+ * 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 {DOMConversionMap, DOMConversionOutput, NodeKey} from 'lexical';
+import type {JSX} from 'react';
+
+import {
+  $isHorizontalRuleNode,
+  HorizontalRuleNode as BaseHorizontalRuleNode,
+  INSERT_HORIZONTAL_RULE_COMMAND,
+  type SerializedHorizontalRuleNode,
+} from '@lexical/extension';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useLexicalNodeSelection} from '@lexical/react/useLexicalNodeSelection';
+import {
+  addClassNamesToElement,
+  mergeRegister,
+  removeClassNamesFromElement,
+} from '@lexical/utils';
+import {
+  $applyNodeReplacement,
+  CLICK_COMMAND,
+  COMMAND_PRIORITY_LOW,
+} from 'lexical';
+import * as React from 'react';
+import {useEffect} from 'react';
+
+export {
+  $isHorizontalRuleNode,
+  INSERT_HORIZONTAL_RULE_COMMAND,
+  type SerializedHorizontalRuleNode,
+};
+
+function HorizontalRuleComponent({nodeKey}: {nodeKey: NodeKey}) {
+  const [editor] = useLexicalComposerContext();
+  const [isSelected, setSelected, clearSelection] =
+    useLexicalNodeSelection(nodeKey);
+
+  useEffect(() => {
+    return mergeRegister(
+      editor.registerCommand(
+        CLICK_COMMAND,
+        (event: MouseEvent) => {
+          const hrElem = editor.getElementByKey(nodeKey);
+
+          if (event.target === hrElem) {
+            if (!event.shiftKey) {
+              clearSelection();
+            }
+            setSelected(!isSelected);
+            return true;
+          }
+
+          return false;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+    );
+  }, [clearSelection, editor, isSelected, nodeKey, setSelected]);
+
+  useEffect(() => {
+    const hrElem = editor.getElementByKey(nodeKey);
+    const isSelectedClassName = editor._config.theme.hrSelected ?? 'selected';
+
+    if (hrElem !== null) {
+      if (isSelected) {
+        addClassNamesToElement(hrElem, isSelectedClassName);
+      } else {
+        removeClassNamesFromElement(hrElem, isSelectedClassName);
+      }
+    }
+  }, [editor, isSelected, nodeKey]);
+
+  return null;
+}
+
+/**
+ * @deprecated A pure Lexical implementation is available in `@lexical/extension` as HorizontalRuleExtension
+ */
+export class HorizontalRuleNode extends BaseHorizontalRuleNode {
+  static getType(): string {
+    return 'horizontalrule';
+  }
+
+  static clone(node: HorizontalRuleNode): HorizontalRuleNode {
+    return new HorizontalRuleNode(node.__key);
+  }
+
+  static importJSON(
+    serializedNode: SerializedHorizontalRuleNode,
+  ): HorizontalRuleNode {
+    return $createHorizontalRuleNode().updateFromJSON(serializedNode);
+  }
+
+  static importDOM(): DOMConversionMap | null {
+    return {
+      hr: () => ({
+        conversion: $convertHorizontalRuleElement,
+        priority: 0,
+      }),
+    };
+  }
+
+  decorate(): JSX.Element {
+    return <HorizontalRuleComponent nodeKey={this.__key} />;
+  }
+}
+
+function $convertHorizontalRuleElement(): DOMConversionOutput {
+  return {node: $createHorizontalRuleNode()};
+}
+
+/**
+ * @deprecated A pure Lexical implementation is available in `@lexical/extension` as HorizontalRuleExtension
+ */
+export function $createHorizontalRuleNode(): HorizontalRuleNode {
+  return $applyNodeReplacement(new HorizontalRuleNode());
+}

package/src/LexicalHorizontalRulePlugin.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 {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $createHorizontalRuleNode,
+  INSERT_HORIZONTAL_RULE_COMMAND,
+} from '@lexical/react/LexicalHorizontalRuleNode';
+import {$insertNodeToNearestRoot} from '@lexical/utils';
+import {
+  $getSelection,
+  $isRangeSelection,
+  COMMAND_PRIORITY_EDITOR,
+} from 'lexical';
+import {useEffect} from 'react';
+
+/**
+ * @deprecated A pure Lexical implementation is available in `@lexical/extension` as HorizontalRuleExtension
+ */
+export function HorizontalRulePlugin(): null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    return editor.registerCommand(
+      INSERT_HORIZONTAL_RULE_COMMAND,
+      type => {
+        const selection = $getSelection();
+
+        if (!$isRangeSelection(selection)) {
+          return false;
+        }
+
+        const focusNode = selection.focus.getNode();
+
+        if (focusNode !== null) {
+          const horizontalRuleNode = $createHorizontalRuleNode();
+          $insertNodeToNearestRoot(horizontalRuleNode);
+        }
+
+        return true;
+      },
+      COMMAND_PRIORITY_EDITOR,
+    );
+  }, [editor]);
+
+  return null;
+}

package/src/LexicalLinkPlugin.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 {namedSignals} from '@lexical/extension';
+import {type LinkAttributes, LinkNode, registerLink} from '@lexical/link';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useEffect} from 'react';
+
+type Props = {
+  validateUrl?: (url: string) => boolean;
+  attributes?: LinkAttributes;
+};
+
+export function LinkPlugin({validateUrl, attributes}: Props): null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    if (!editor.hasNodes([LinkNode])) {
+      throw new Error('LinkPlugin: LinkNode not registered on editor');
+    }
+  });
+  useEffect(() => {
+    return registerLink(editor, namedSignals({attributes, validateUrl}));
+  }, [editor, validateUrl, attributes]);
+
+  return null;
+}

package/src/LexicalListPlugin.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 {
+  ListItemNode,
+  ListNode,
+  registerList,
+  registerListStrictIndentTransform,
+} from '@lexical/list';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {mergeRegister} from 'lexical';
+import {useEffect} from 'react';
+
+import {useList} from './shared/useList';
+
+export interface ListPluginProps {
+  /**
+   * When `true`, enforces strict indentation rules for list items, ensuring consistent structure.
+   * When `false` (default), indentation is more flexible.
+   */
+  hasStrictIndent?: boolean;
+  /**
+   * When `true`, splitting a numbered list will preserve the numbering continuity.
+   * When `false` (default), the new split list resets to 1.
+   */
+  shouldPreserveNumbering?: boolean;
+}
+
+export function ListPlugin({
+  hasStrictIndent = false,
+  shouldPreserveNumbering = false,
+}: ListPluginProps): null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    if (!editor.hasNodes([ListNode, ListItemNode])) {
+      throw new Error(
+        'ListPlugin: ListNode and/or ListItemNode not registered on editor',
+      );
+    }
+  }, [editor]);
+
+  useEffect(() => {
+    return mergeRegister(
+      registerList(editor, {
+        restoreNumbering: shouldPreserveNumbering,
+      }),
+      hasStrictIndent ? registerListStrictIndentTransform(editor) : () => {},
+    );
+  }, [editor, hasStrictIndent, shouldPreserveNumbering]);
+
+  useList(editor);
+
+  return null;
+}

package/src/LexicalMarkdownShortcutPlugin.tsx

@@ -0,0 +1,56 @@
+/**
+ * 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 {ElementTransformer, Transformer} from '@lexical/markdown';
+import type {LexicalNode} from 'lexical';
+
+import {
+  $createHorizontalRuleNode,
+  $isHorizontalRuleNode,
+  HorizontalRuleNode,
+} from '@lexical/extension';
+import {registerMarkdownShortcuts, TRANSFORMERS} from '@lexical/markdown';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useEffect} from 'react';
+
+const HR: ElementTransformer = {
+  dependencies: [HorizontalRuleNode],
+  export: (node: LexicalNode) => {
+    return $isHorizontalRuleNode(node) ? '***' : null;
+  },
+  regExp: /^(---|\*\*\*|___)\s?$/,
+  replace: (parentNode, _1, _2, isImport) => {
+    const line = $createHorizontalRuleNode();
+
+    // TODO: Get rid of isImport flag
+    if (isImport || parentNode.getNextSibling() != null) {
+      parentNode.replace(line);
+    } else {
+      parentNode.insertBefore(line);
+    }
+
+    line.selectNext();
+  },
+  triggerOnEnter: true,
+  type: 'element',
+};
+export const DEFAULT_TRANSFORMERS = [HR, ...TRANSFORMERS];
+
+export function MarkdownShortcutPlugin({
+  transformers = DEFAULT_TRANSFORMERS,
+}: Readonly<{
+  transformers?: Array<Transformer>;
+}>): null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    return registerMarkdownShortcuts(editor, transformers);
+  }, [editor, transformers]);
+
+  return null;
+}