@lexical/react 0.44.1-nightly.20260518.0 → 0.45.0

package/src/ExtensionComponent.tsx

@@ -0,0 +1,59 @@
+/**
+ * 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 {ComponentProps} from 'react';
+
+import {useExtensionComponent} from '@lexical/react/useExtensionComponent';
+import {type AnyLexicalExtension, type LexicalExtensionOutput} from 'lexical';
+
+/**
+ * The lexical:extension prop combined with the props of the given Extension's
+ * output Component.
+ */
+export type ExtensionComponentProps<Extension extends AnyLexicalExtension> = {
+  /** The Extension */ 'lexical:extension': Extension;
+} & ([LexicalExtensionOutput<Extension>] extends [
+  {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- contravariant in props
+    Component: infer OutputComponentType extends React.ComponentType<any>;
+  },
+]
+  ? /** The Props from the Extension output Component */ Omit<
+      ComponentProps<OutputComponentType>,
+      'lexical:extension'
+    >
+  : never);
+
+/**
+ * A convenient way to get an Extension's output Component with {@link useExtensionComponent}
+ * and construct it in one step.
+ *
+ * @example
+ * Usage
+ * ```tsx
+ * return (
+ *   <ExtensionComponent
+ *     lexical:extension={TreeViewExtension}
+ *     viewClassName="tree-view-output" />
+ * );
+ * ```
+ *
+ * @example
+ * Alternative without ExtensionComponent
+ * ```tsx
+ * const TreeViewComponent = useExtensionComponent(TreeViewExtension);
+ * return (<TreeViewComponent viewClassName="tree-view-output" />);
+ * ```
+ */
+export function ExtensionComponent<Extension extends AnyLexicalExtension>({
+  'lexical:extension': extension,
+  ...props
+}: ExtensionComponentProps<Extension>) {
+  const Component = useExtensionComponent(extension);
+  // eslint-disable-next-line react-hooks/static-components
+  return <Component {...props} />;
+}

package/src/LexicalAutoEmbedPlugin.tsx

@@ -0,0 +1,300 @@
+/**
+ * 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 {
+  CommandListenerPriority,
+  LexicalNode,
+  MutationListener,
+} from 'lexical';
+import type {JSX} from 'react';
+
+import {$isLinkNode, AutoLinkNode, LinkNode} from '@lexical/link';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  LexicalNodeMenuPlugin,
+  MenuOption,
+  type MenuRenderFn,
+} from '@lexical/react/LexicalNodeMenuPlugin';
+import {mergeRegister} from '@lexical/utils';
+import {
+  $getNodeByKey,
+  $getSelection,
+  COMMAND_PRIORITY_EDITOR,
+  COMMAND_PRIORITY_LOW,
+  createCommand,
+  LexicalCommand,
+  LexicalEditor,
+  NodeKey,
+  PASTE_TAG,
+  TextNode,
+} from 'lexical';
+import {useCallback, useEffect, useMemo, useState} from 'react';
+
+export type EmbedMatchResult<TEmbedMatchResult = unknown> = {
+  url: string;
+  id: string;
+  data?: TEmbedMatchResult;
+};
+
+export interface EmbedConfig<
+  TEmbedMatchResultData = unknown,
+  TEmbedMatchResult = EmbedMatchResult<TEmbedMatchResultData>,
+> {
+  // Used to identify this config e.g. youtube, tweet, google-maps.
+  type: string;
+  // Determine if a given URL is a match and return url data.
+  parseUrl: (
+    text: string,
+  ) => Promise<TEmbedMatchResult | null> | TEmbedMatchResult | null;
+  // Create the Lexical embed node from the url data.
+  insertNode: (editor: LexicalEditor, result: TEmbedMatchResult) => void;
+}
+
+export const URL_MATCHER =
+  /((https?:\/\/(www\.)?)|(www\.))[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&//=]*)/;
+
+export const INSERT_EMBED_COMMAND: LexicalCommand<EmbedConfig['type']> =
+  createCommand('INSERT_EMBED_COMMAND');
+
+export class AutoEmbedOption extends MenuOption {
+  title: string;
+  onSelect: (targetNode: LexicalNode | null) => void;
+  constructor(
+    title: string,
+    options: {
+      onSelect: (targetNode: LexicalNode | null) => void;
+    },
+  ) {
+    super(title);
+    this.title = title;
+    this.onSelect = options.onSelect.bind(this);
+  }
+}
+
+type LexicalAutoEmbedPluginProps<TEmbedConfig extends EmbedConfig> = {
+  /**
+   * An array of configurations used to insert Embed elements
+   */
+  embedConfigs: TEmbedConfig[];
+  /**
+   * Callback for handling the {@link INSERT_EMBED_COMMAND} command.
+   * If no function is passed, the command is not registered
+   * @param embedConfig - the config corresponding to the {@link EmbedConfig.type} of the inserted Embed
+   * @returns
+   */
+  onOpenEmbedModalForConfig?: (embedConfig: TEmbedConfig) => void;
+  /**
+   * A function that links a specific configuration to a set of options.
+   * Each option can be handling by click or press the Enter or Tab key
+   * when the cursor hovers over it.
+   * Pass the necessary callbacks to {@link AutoEmbedOption.onSelect}
+   * @param activeEmbedConfig - the current active config is determined by a match
+   * from the {@link EmbedConfig.parseUrl} of the inserted AutoLinkNode
+   * @param embedFn - callback for handling option selection.
+   * Calling the callback will invoke the {@link EmbedConfig.insertNode} method
+   * and remove the inserted AutoLinkNode
+   * @param dismissFn - сallback to deselect. Calling the callback will hide the options menu
+   * @returns array of options from {@link AutoEmbedOption} instances
+   */
+  getMenuOptions: (
+    activeEmbedConfig: TEmbedConfig,
+    embedFn: () => void,
+    dismissFn: () => void,
+  ) => AutoEmbedOption[];
+  /**
+   * A function for rendering button menu.
+   * By default, it displays a plain list with the option titles
+   */
+  menuRenderFn?: MenuRenderFn<AutoEmbedOption>;
+  /**
+   * Priority for key handling in the menu. The default is `COMMAND_PRIORITY_LOW`
+   */
+  menuCommandPriority?: CommandListenerPriority;
+};
+
+/**
+ * Watches for pasted AutoLink nodes that match any of the provided embed configurations (e.g., YouTube, Twitter URLs).
+ * When a match is found, it shows a menu offering to replace the link with an embedded node.
+ *
+ * You can pass a generic type to the plugin to extend {@link EmbedConfig}
+ * with additional data in {@link EmbedMatchResult} that will be passed to the callbacks
+ *
+ * @example
+ * Usage
+ * ```tsx
+ * interface CustomEmbedConfig extends EmbedConfig<{
+ *   domain: string;
+ *   oid?: string;
+ * }> {
+ *   // Icon for display.
+ *   icon?: JSX.Element;
+ *   // Embed a Figma Project.
+ *   description?: string;
+ * };
+ *
+ * return (
+ *  <LexicalAutoEmbedPlugin<CustomEmbedConfig>
+ *    embedConfigs={EmbedConfigs}
+ *    getMenuOptions={getMenuOptions}
+ *  />
+ * );
+ * ```
+ */
+export function LexicalAutoEmbedPlugin<TEmbedConfig extends EmbedConfig>({
+  embedConfigs,
+  onOpenEmbedModalForConfig,
+  getMenuOptions,
+  menuRenderFn,
+  menuCommandPriority = COMMAND_PRIORITY_LOW,
+}: LexicalAutoEmbedPluginProps<TEmbedConfig>): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+
+  const [nodeKey, setNodeKey] = useState<NodeKey | null>(null);
+  const [activeEmbedConfig, setActiveEmbedConfig] =
+    useState<TEmbedConfig | null>(null);
+
+  const reset = useCallback(() => {
+    setNodeKey(null);
+    setActiveEmbedConfig(null);
+  }, []);
+
+  const checkIfLinkNodeIsEmbeddable = useCallback(
+    async (key: NodeKey) => {
+      const url = editor.getEditorState().read(function () {
+        const linkNode = $getNodeByKey(key);
+        if ($isLinkNode(linkNode)) {
+          return linkNode.getURL();
+        }
+      });
+      if (url === undefined) {
+        return;
+      }
+      for (const embedConfig of embedConfigs) {
+        const urlMatch = await Promise.resolve(embedConfig.parseUrl(url));
+        if (urlMatch != null) {
+          setActiveEmbedConfig(embedConfig);
+          setNodeKey(key);
+        }
+      }
+    },
+    [editor, embedConfigs],
+  );
+
+  useEffect(() => {
+    const listener: MutationListener = (
+      nodeMutations,
+      {updateTags, dirtyLeaves},
+    ) => {
+      for (const [key, mutation] of nodeMutations) {
+        if (
+          mutation === 'created' &&
+          updateTags.has(PASTE_TAG) &&
+          dirtyLeaves.size <= 3
+        ) {
+          checkIfLinkNodeIsEmbeddable(key);
+        } else if (key === nodeKey) {
+          reset();
+        }
+      }
+    };
+    return mergeRegister(
+      ...[LinkNode, AutoLinkNode].map(Klass =>
+        editor.registerMutationListener(Klass, (...args) => listener(...args), {
+          skipInitialization: true,
+        }),
+      ),
+    );
+  }, [checkIfLinkNodeIsEmbeddable, editor, nodeKey, reset]);
+
+  useEffect(() => {
+    if (!onOpenEmbedModalForConfig) return;
+
+    return editor.registerCommand(
+      INSERT_EMBED_COMMAND,
+      (embedConfigType: TEmbedConfig['type']) => {
+        const embedConfig = embedConfigs.find(
+          ({type}) => type === embedConfigType,
+        );
+        if (embedConfig) {
+          onOpenEmbedModalForConfig(embedConfig);
+          return true;
+        }
+        return false;
+      },
+      COMMAND_PRIORITY_EDITOR,
+    );
+  }, [editor, embedConfigs, onOpenEmbedModalForConfig]);
+
+  const embedLinkViaActiveEmbedConfig = useCallback(
+    async function () {
+      if (activeEmbedConfig != null && nodeKey != null) {
+        const linkNode = editor.getEditorState().read(() => {
+          const node = $getNodeByKey(nodeKey);
+          if ($isLinkNode(node)) {
+            return node;
+          }
+          return null;
+        });
+
+        if ($isLinkNode(linkNode)) {
+          const result = await Promise.resolve(
+            activeEmbedConfig.parseUrl(linkNode.__url),
+          );
+          if (result != null) {
+            editor.update(() => {
+              if (!$getSelection()) {
+                linkNode.selectEnd();
+              }
+              activeEmbedConfig.insertNode(editor, result);
+              if (linkNode.isAttached()) {
+                linkNode.remove();
+              }
+            });
+          }
+        }
+      }
+    },
+    [activeEmbedConfig, editor, nodeKey],
+  );
+
+  const options = useMemo(() => {
+    return activeEmbedConfig != null && nodeKey != null
+      ? getMenuOptions(activeEmbedConfig, embedLinkViaActiveEmbedConfig, reset)
+      : [];
+  }, [
+    activeEmbedConfig,
+    embedLinkViaActiveEmbedConfig,
+    getMenuOptions,
+    nodeKey,
+    reset,
+  ]);
+
+  const onSelectOption = useCallback(
+    (
+      selectedOption: AutoEmbedOption,
+      targetNode: TextNode | null,
+      closeMenu: () => void,
+    ) => {
+      editor.update(() => {
+        selectedOption.onSelect(targetNode);
+        closeMenu();
+      });
+    },
+    [editor],
+  );
+
+  return nodeKey != null ? (
+    <LexicalNodeMenuPlugin<AutoEmbedOption>
+      nodeKey={nodeKey}
+      onClose={reset}
+      onSelectOption={onSelectOption}
+      options={options}
+      menuRenderFn={menuRenderFn}
+      commandPriority={menuCommandPriority}
+    />
+  ) : null;
+}

package/src/LexicalAutoFocusPlugin.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 {useEffect} from 'react';
+
+type Props = {
+  defaultSelection?: 'rootStart' | 'rootEnd';
+};
+
+export function AutoFocusPlugin({defaultSelection}: Props): null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    editor.focus(
+      () => {
+        // If we try and move selection to the same point with setBaseAndExtent, it won't
+        // trigger a re-focus on the element. So in the case this occurs, we'll need to correct it.
+        // Normally this is fine, Selection API !== Focus API, but fore the intents of the naming
+        // of this plugin, which should preserve focus too.
+        const activeElement = document.activeElement;
+        const rootElement = editor.getRootElement() as HTMLDivElement;
+        if (
+          rootElement !== null &&
+          (activeElement === null || !rootElement.contains(activeElement))
+        ) {
+          // Note: preventScroll won't work in Webkit.
+          rootElement.focus({preventScroll: true});
+        }
+      },
+      {defaultSelection},
+    );
+  }, [defaultSelection, editor]);
+
+  return null;
+}

package/src/LexicalAutoLinkPlugin.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 {ChangeHandler, LinkMatcher} from '@lexical/link';
+import type {ElementNode, LexicalEditor} from 'lexical';
+import type {JSX} from 'react';
+
+import invariant from '@lexical/internal/invariant';
+import {AutoLinkNode, registerAutoLink} from '@lexical/link';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useEffect} from 'react';
+
+export {
+  type ChangeHandler,
+  createLinkMatcherWithRegExp,
+  type LinkMatcher,
+} from '@lexical/link';
+
+function useAutoLink(
+  editor: LexicalEditor,
+  matchers: Array<LinkMatcher>,
+  onChange?: ChangeHandler,
+  excludeParents?: Array<(parent: ElementNode) => boolean>,
+): void {
+  useEffect(() => {
+    if (!editor.hasNodes([AutoLinkNode])) {
+      invariant(
+        false,
+        'LexicalAutoLinkPlugin: AutoLinkNode not registered on editor',
+      );
+    }
+  });
+  useEffect(() => {
+    return registerAutoLink(editor, {
+      changeHandlers: onChange ? [onChange] : [],
+      excludeParents: excludeParents ?? [],
+      matchers,
+    });
+  }, [editor, matchers, onChange, excludeParents]);
+}
+
+export function AutoLinkPlugin({
+  matchers,
+  onChange,
+  excludeParents,
+}: {
+  matchers: Array<LinkMatcher>;
+  onChange?: ChangeHandler;
+  excludeParents?: Array<(parent: ElementNode) => boolean>;
+}): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+
+  useAutoLink(editor, matchers, onChange, excludeParents);
+
+  return null;
+}

package/src/LexicalBlockWithAlignableContents.tsx

@@ -0,0 +1,119 @@
+/**
+ * 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 {ElementFormatType, NodeKey} from 'lexical';
+import type {JSX} from 'react';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {$isDecoratorBlockNode} from '@lexical/react/LexicalDecoratorBlockNode';
+import {useLexicalNodeSelection} from '@lexical/react/useLexicalNodeSelection';
+import {
+  $getNearestBlockElementAncestorOrThrow,
+  mergeRegister,
+} from '@lexical/utils';
+import {
+  $getNodeByKey,
+  $getSelection,
+  $isNodeSelection,
+  $isRangeSelection,
+  CLICK_COMMAND,
+  COMMAND_PRIORITY_LOW,
+  FORMAT_ELEMENT_COMMAND,
+} from 'lexical';
+import * as React from 'react';
+import {ReactNode, useEffect, useRef} from 'react';
+
+type Props = Readonly<{
+  children: ReactNode;
+  format?: ElementFormatType | null;
+  nodeKey: NodeKey;
+  className: Readonly<{
+    base: string;
+    focus: string;
+  }>;
+}>;
+
+export function BlockWithAlignableContents({
+  children,
+  format,
+  nodeKey,
+  className,
+}: Props): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+
+  const [isSelected, setSelected, clearSelection] =
+    useLexicalNodeSelection(nodeKey);
+  const ref = useRef(null);
+
+  useEffect(() => {
+    return mergeRegister(
+      editor.registerCommand<ElementFormatType>(
+        FORMAT_ELEMENT_COMMAND,
+        formatType => {
+          if (isSelected) {
+            const selection = $getSelection();
+
+            if ($isNodeSelection(selection)) {
+              const node = $getNodeByKey(nodeKey);
+
+              if ($isDecoratorBlockNode(node)) {
+                node.setFormat(formatType);
+              }
+            } else if ($isRangeSelection(selection)) {
+              const nodes = selection.getNodes();
+
+              for (const node of nodes) {
+                if ($isDecoratorBlockNode(node)) {
+                  node.setFormat(formatType);
+                } else {
+                  const element = $getNearestBlockElementAncestorOrThrow(node);
+                  element.setFormat(formatType);
+                }
+              }
+            }
+
+            return true;
+          }
+
+          return false;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+      editor.registerCommand<MouseEvent>(
+        CLICK_COMMAND,
+        event => {
+          if (event.target === ref.current) {
+            event.preventDefault();
+            if (!event.shiftKey) {
+              clearSelection();
+            }
+
+            setSelected(!isSelected);
+            return true;
+          }
+
+          return false;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+    );
+  }, [clearSelection, editor, isSelected, nodeKey, setSelected]);
+
+  return (
+    <div
+      className={[className.base, isSelected ? className.focus : null]
+        .filter(Boolean)
+        .join(' ')}
+      ref={ref}
+      style={{
+        textAlign: format ? format : undefined,
+      }}>
+      {children}
+    </div>
+  );
+}

package/src/LexicalCharacterLimitPlugin.tsx

@@ -0,0 +1,91 @@
+/**
+ * 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 * as React from 'react';
+import {useMemo, useState} from 'react';
+
+import {useCharacterLimit} from './shared/useCharacterLimit';
+
+const CHARACTER_LIMIT = 5;
+let textEncoderInstance: null | TextEncoder = null;
+
+function textEncoder(): null | TextEncoder {
+  if (window.TextEncoder === undefined) {
+    return null;
+  }
+
+  if (textEncoderInstance === null) {
+    textEncoderInstance = new window.TextEncoder();
+  }
+
+  return textEncoderInstance;
+}
+
+function utf8Length(text: string) {
+  const currentTextEncoder = textEncoder();
+
+  if (currentTextEncoder === null) {
+    // http://stackoverflow.com/a/5515960/210370
+    const m = encodeURIComponent(text).match(/%[89ABab]/g);
+    return text.length + (m ? m.length : 0);
+  }
+
+  return currentTextEncoder.encode(text).length;
+}
+
+function DefaultRenderer({remainingCharacters}: {remainingCharacters: number}) {
+  return (
+    <span
+      className={`characters-limit ${
+        remainingCharacters < 0 ? 'characters-limit-exceeded' : ''
+      }`}>
+      {remainingCharacters}
+    </span>
+  );
+}
+
+export function CharacterLimitPlugin({
+  charset = 'UTF-16',
+  maxLength = CHARACTER_LIMIT,
+  renderer = DefaultRenderer,
+}: {
+  charset: 'UTF-8' | 'UTF-16';
+  maxLength: number;
+  renderer?: ({
+    remainingCharacters,
+  }: {
+    remainingCharacters: number;
+  }) => JSX.Element;
+}): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+
+  const [remainingCharacters, setRemainingCharacters] = useState(maxLength);
+
+  const characterLimitProps = useMemo(
+    () => ({
+      remainingCharacters: setRemainingCharacters,
+      strlen: (text: string) => {
+        if (charset === 'UTF-8') {
+          return utf8Length(text);
+        } else if (charset === 'UTF-16') {
+          return text.length;
+        } else {
+          throw new Error('Unrecognized charset');
+        }
+      },
+    }),
+    [charset],
+  );
+
+  useCharacterLimit(editor, maxLength, characterLimitProps);
+
+  return renderer({remainingCharacters});
+}

package/src/LexicalCheckListPlugin.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 {registerCheckList} from '@lexical/list';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useEffect} from 'react';
+
+export function CheckListPlugin({
+  disableTakeFocusOnClick = false,
+}: {
+  disableTakeFocusOnClick?: boolean;
+}): null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    return registerCheckList(editor, {disableTakeFocusOnClick});
+  }, [editor, disableTakeFocusOnClick]);
+  return null;
+}