@lexical/react 0.49.1-nightly.20260901.0 → 0.50.0

package/src/LexicalAutoEmbedPlugin.tsx

@@ -7,10 +7,14 @@
  */
 
 import {$isLinkNode, AutoLinkNode, LinkNode} from '@lexical/link';
+import {
+  type AutoEmbedOption,
+  type EmbedConfig,
+  INSERT_EMBED_COMMAND,
+} from '@lexical/react/LexicalAutoEmbedPluginUtils';
 import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
 import {
   LexicalNodeMenuPlugin,
-  MenuOption,
   type MenuRenderFn,
 } from '@lexical/react/LexicalNodeMenuPlugin';
 import {objectKlassEquals} from '@lexical/utils';
@@ -22,10 +26,6 @@ import {
   COMMAND_PRIORITY_EDITOR,
   COMMAND_PRIORITY_LOW,
   type CommandListenerPriority,
-  createCommand,
-  type LexicalCommand,
-  type LexicalEditor,
-  type LexicalNode,
   mergeRegister,
   type MutationListener,
   type NodeKey,
@@ -35,71 +35,13 @@ import {
 } from 'lexical';
 import {type JSX, useCallback, useEffect, useMemo, useState} from 'react';
 
-/**
- * The result of matching a URL for an embed: the matched `url`, an `id`
- * identifying the embedded resource, and optional provider-specific `data`.
- */
-export type EmbedMatchResult<TEmbedMatchResult = unknown> = {
-  url: string;
-  id: string;
-  data?: TEmbedMatchResult;
-};
-
-/**
- * Describes a kind of embed (for example YouTube, a tweet, or Google Maps) that
- * {@link LexicalAutoEmbedPlugin} can detect and insert. Each config has a `type`
- * identifier, a `parseUrl` function that decides whether a URL matches and
- * extracts its data, and an `insertNode` function that inserts the corresponding
- * Lexical node.
- */
-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;
-}
-
-/**
- * A general-purpose regular expression for detecting URLs, provided as a
- * convenience for implementing an {@link EmbedConfig}'s `parseUrl`.
- */
-export const URL_MATCHER =
-  /((https?:\/\/(www\.)?)|(www\.))[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&//=]*)/;
-
-/**
- * Command dispatched to start inserting an embed. Its payload is the `type` of
- * the {@link EmbedConfig} to use; {@link LexicalAutoEmbedPlugin} listens for it
- * and runs that config's URL detection flow.
- */
-export const INSERT_EMBED_COMMAND: LexicalCommand<EmbedConfig['type']> =
-  createCommand('INSERT_EMBED_COMMAND');
-
-/**
- * A {@link MenuOption} for the auto-embed menu, pairing a display `title` with
- * an `onSelect` callback invoked when the user chooses to embed the detected
- * URL.
- */
-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);
-  }
-}
+export {
+  AutoEmbedOption,
+  type EmbedConfig,
+  type EmbedMatchResult,
+  INSERT_EMBED_COMMAND,
+  URL_MATCHER,
+} from '@lexical/react/LexicalAutoEmbedPluginUtils';
 
 type LexicalAutoEmbedPluginProps<TEmbedConfig extends EmbedConfig> = {
   /**

package/src/LexicalAutoEmbedPluginUtils.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 {MenuOption} from '@lexical/react/LexicalMenuOption';
+import {
+  createCommand,
+  type LexicalCommand,
+  type LexicalEditor,
+  type LexicalNode,
+} from 'lexical';
+
+/**
+ * The result of matching a URL for an embed: the matched `url`, an `id`
+ * identifying the embedded resource, and optional provider-specific `data`.
+ */
+export type EmbedMatchResult<TEmbedMatchResult = unknown> = {
+  url: string;
+  id: string;
+  data?: TEmbedMatchResult;
+};
+
+/**
+ * Describes a kind of embed (for example YouTube, a tweet, or Google Maps) that
+ * {@link LexicalAutoEmbedPlugin} can detect and insert. Each config has a `type`
+ * identifier, a `parseUrl` function that decides whether a URL matches and
+ * extracts its data, and an `insertNode` function that inserts the corresponding
+ * Lexical node.
+ */
+export interface EmbedConfig<
+  TEmbedMatchResultData = unknown,
+  TEmbedMatchResult = EmbedMatchResult<TEmbedMatchResultData>,
+> {
+  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;
+}
+
+/**
+ * A general-purpose regular expression for detecting URLs, provided as a
+ * convenience for implementing an {@link EmbedConfig}'s `parseUrl`.
+ */
+export const URL_MATCHER =
+  /((https?:\/\/(www\.)?)|(www\.))[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&//=]*)/;
+
+/**
+ * Command dispatched to start inserting an embed. Its payload is the `type` of
+ * the {@link EmbedConfig} to use; {@link LexicalAutoEmbedPlugin} listens for it
+ * and runs that config's URL detection flow.
+ */
+export const INSERT_EMBED_COMMAND: LexicalCommand<EmbedConfig['type']> =
+  createCommand('INSERT_EMBED_COMMAND');
+
+/**
+ * A {@link MenuOption} for the auto-embed menu, pairing a display `title` with
+ * an `onSelect` callback invoked when the user chooses to embed the detected
+ * URL.
+ */
+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);
+  }
+}

package/src/LexicalCollaborationContext.tsx

@@ -6,64 +6,17 @@
  *
  */
 
-import type {Doc} from 'yjs';
-
-import devInvariant from '@lexical/internal/devInvariant';
-import {createContext, useContext, useMemo} from 'react';
-
-/**
- * The value stored in the {@link CollaborationContext}: the local user's
- * display `name` and cursor `color`, whether collaboration is currently active,
- * and the map of Yjs documents shared by the editors under this provider.
- */
-export type CollaborationContextType = {
-  color: string;
-  isCollabActive: boolean;
-  name: string;
-  yjsDocMap: Map<string, Doc>;
-};
-
-const entries = [
-  ['Cat', 'rgb(125, 50, 0)'],
-  ['Dog', 'rgb(100, 0, 0)'],
-  ['Rabbit', 'rgb(150, 0, 0)'],
-  ['Frog', 'rgb(200, 0, 0)'],
-  ['Fox', 'rgb(200, 75, 0)'],
-  ['Hedgehog', 'rgb(0, 75, 0)'],
-  ['Pigeon', 'rgb(0, 125, 0)'],
-  ['Squirrel', 'rgb(75, 100, 0)'],
-  ['Bear', 'rgb(125, 100, 0)'],
-  ['Tiger', 'rgb(0, 0, 150)'],
-  ['Leopard', 'rgb(0, 0, 200)'],
-  ['Zebra', 'rgb(0, 0, 250)'],
-  ['Wolf', 'rgb(0, 100, 150)'],
-  ['Owl', 'rgb(0, 100, 100)'],
-  ['Gull', 'rgb(100, 0, 100)'],
-  ['Squid', 'rgb(150, 0, 150)'],
-];
-
-const randomEntry = entries[Math.floor(Math.random() * entries.length)];
-
-/**
- * The React context that holds the shared {@link CollaborationContextType} for
- * collaborative editors. Provide it with {@link LexicalCollaboration} and read
- * it with {@link useCollaborationContext}.
- */
-export const CollaborationContext =
-  createContext<CollaborationContextType | null>(null);
-
-function newContext() {
-  return {
-    color: randomEntry[1],
-    isCollabActive: false,
-    name: randomEntry[0],
-    yjsDocMap: new Map(),
-  };
-}
-
-// This is here to help the transition post-#7818, however should be removed in a future release as
-// a shared context across editors is likely to lead to bugs.
-const UNSAFE_GLOBAL_CONTEXT = newContext();
+import {
+  CollaborationContext,
+  newContext,
+} from '@lexical/react/LexicalCollaborationContextUtils';
+import {useMemo} from 'react';
+
+export {
+  CollaborationContext,
+  type CollaborationContextType,
+  useCollaborationContext,
+} from '@lexical/react/LexicalCollaborationContextUtils';
 
 /**
  * A provider component that creates a fresh {@link CollaborationContextType}
@@ -82,35 +35,3 @@ export function LexicalCollaboration({children}: {children: React.ReactNode}) {
     </CollaborationContext.Provider>
   );
 }
-
-/**
- * Reads the current {@link CollaborationContextType} from the nearest
- * {@link LexicalCollaboration} provider. Optionally pass `username` and `color`
- * to set the local user's display name and cursor color.
- *
- * @returns The active collaboration context.
- */
-export function useCollaborationContext(
-  username?: string,
-  color?: string,
-): CollaborationContextType {
-  let collabContext = useContext(CollaborationContext);
-  devInvariant(
-    collabContext != null,
-    'useCollaborationContext: no context provider found',
-  );
-
-  collabContext = collabContext ?? UNSAFE_GLOBAL_CONTEXT;
-
-  if (username != null) {
-    // eslint-disable-next-line react-hooks/immutability
-    collabContext.name = username;
-  }
-
-  if (color != null) {
-    // eslint-disable-next-line react-hooks/immutability
-    collabContext.color = color;
-  }
-
-  return collabContext;
-}

package/src/LexicalCollaborationContextUtils.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 {Doc} from 'yjs';
+
+import devInvariant from '@lexical/internal/devInvariant';
+import {createContext, useContext} from 'react';
+
+/**
+ * The value stored in the {@link CollaborationContext}: the local user's
+ * display `name` and cursor `color`, whether collaboration is currently active,
+ * and the map of Yjs documents shared by the editors under this provider.
+ */
+export type CollaborationContextType = {
+  color: string;
+  isCollabActive: boolean;
+  name: string;
+  yjsDocMap: Map<string, Doc>;
+};
+
+const entries = [
+  ['Cat', 'rgb(125, 50, 0)'],
+  ['Dog', 'rgb(100, 0, 0)'],
+  ['Rabbit', 'rgb(150, 0, 0)'],
+  ['Frog', 'rgb(200, 0, 0)'],
+  ['Fox', 'rgb(200, 75, 0)'],
+  ['Hedgehog', 'rgb(0, 75, 0)'],
+  ['Pigeon', 'rgb(0, 125, 0)'],
+  ['Squirrel', 'rgb(75, 100, 0)'],
+  ['Bear', 'rgb(125, 100, 0)'],
+  ['Tiger', 'rgb(0, 0, 150)'],
+  ['Leopard', 'rgb(0, 0, 200)'],
+  ['Zebra', 'rgb(0, 0, 250)'],
+  ['Wolf', 'rgb(0, 100, 150)'],
+  ['Owl', 'rgb(0, 100, 100)'],
+  ['Gull', 'rgb(100, 0, 100)'],
+  ['Squid', 'rgb(150, 0, 150)'],
+];
+
+const randomEntry = entries[Math.floor(Math.random() * entries.length)];
+
+/**
+ * The React context that holds the shared {@link CollaborationContextType} for
+ * collaborative editors. Provide it with {@link LexicalCollaboration} and read
+ * it with {@link useCollaborationContext}.
+ */
+export const CollaborationContext =
+  createContext<CollaborationContextType | null>(null);
+
+/** @internal */
+export function newContext(): CollaborationContextType {
+  return {
+    color: randomEntry[1],
+    isCollabActive: false,
+    name: randomEntry[0],
+    yjsDocMap: new Map(),
+  };
+}
+
+// This is here to help the transition post-#7818, however should be removed in a future release as
+// a shared context across editors is likely to lead to bugs.
+const UNSAFE_GLOBAL_CONTEXT = newContext();
+
+/**
+ * Reads the current {@link CollaborationContextType} from the nearest
+ * {@link LexicalCollaboration} provider. Optionally pass `username` and `color`
+ * to set the local user's display name and cursor color.
+ *
+ * @returns The active collaboration context.
+ */
+export function useCollaborationContext(
+  username?: string,
+  color?: string,
+): CollaborationContextType {
+  let collabContext = useContext(CollaborationContext);
+  devInvariant(
+    collabContext != null,
+    'useCollaborationContext: no context provider found',
+  );
+
+  collabContext = collabContext ?? UNSAFE_GLOBAL_CONTEXT;
+
+  if (username != null) {
+    // eslint-disable-next-line react-hooks/immutability
+    collabContext.name = username;
+  }
+
+  if (color != null) {
+    // eslint-disable-next-line react-hooks/immutability
+    collabContext.color = color;
+  }
+
+  return collabContext;
+}

package/src/LexicalMenuOption.ts

@@ -0,0 +1,39 @@
+/**
+ * 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, RefObject} from 'react';
+
+/**
+ * The base class for an item shown in a {@link LexicalTypeaheadMenuPlugin} or
+ * {@link LexicalNodeMenuPlugin} menu. Each option has a unique `key` and a `ref`
+ * to its rendered element (used for scrolling and keyboard navigation).
+ * Subclass it to attach your own data such as a label or callback.
+ *
+ * Its own module, and not `shared/LexicalMenu`, because that module is not an
+ * entry point: it is inlined into every entry that reaches it, which would give
+ * each of them a different `MenuOption` class. Its own module rather than one
+ * of the plugin entry points, because those export React components — anything
+ * importing this from one of them sits behind that component's Fast Refresh
+ * boundary and is invalidated whenever the component changes.
+ */
+export class MenuOption {
+  key: string;
+  ref?: RefObject<HTMLElement | null>;
+  icon?: JSX.Element;
+  title?: JSX.Element | string;
+
+  constructor(key: string) {
+    this.key = key;
+    this.ref = {current: null};
+    this.setRefElement = this.setRefElement.bind(this);
+  }
+
+  setRefElement(element: HTMLElement | null) {
+    this.ref = {current: element};
+  }
+}

package/src/LexicalTypeaheadMenuPlugin.tsx

@@ -7,17 +7,14 @@
  */
 
 import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
-import {getScrollParent as getScrollParent_} from '@lexical/utils';
 import {
   $getSelection,
   $isRangeSelection,
   $isTextNode,
   COMMAND_PRIORITY_LOW,
   type CommandListenerPriority,
-  createCommand,
   getDOMSelection,
   getDOMSelectionPoints,
-  type LexicalCommand,
   type LexicalEditor,
   type RangeSelection,
   type TextNode,
@@ -40,14 +37,6 @@ import {
   useMenuAnchorRef,
 } from './shared/LexicalMenu';
 
-/**
- * The default set of punctuation characters (as a character-class fragment)
- * that terminate a typeahead query. Used as the default `punctuation` option of
- * {@link useBasicTypeaheadTriggerMatch}.
- */
-export const PUNCTUATION =
-  '\\.,\\+\\*\\?\\$\\@\\|#{}\\(\\)\\^\\-\\[\\]\\\\/!%\'"~=<>_:;';
-
 function getTextUpToAnchor(selection: RangeSelection): string | null {
   const anchor = selection.anchor;
   if (anchor.type !== 'text') {
@@ -122,75 +111,12 @@ function isSelectionOnEntityBoundary(
 }
 
 export {useDynamicPositioning} from './shared/LexicalMenu';
-/** @deprecated Moved to `@lexical/utils`. Import `getScrollParent` from there. */
-export const getScrollParent = getScrollParent_;
-
-/**
- * Command dispatched while the typeahead menu is open to scroll the option at
- * the given `index` into view. The default menu renderer listens for it; custom
- * {@link MenuRenderFn}s can handle it to implement their own scrolling.
- */
-export const SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND: LexicalCommand<{
-  index: number;
-  option: MenuOption;
-}> = createCommand('SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND');
-
-/**
- * Builds a {@link TriggerFn} for the common case of a single-character
- * `trigger` (such as `@` or `#`) followed by a query. The returned function
- * matches when the trigger is preceded by whitespace or the start of the line
- * and is followed by between `minLength` and `maxLength` non-`punctuation`
- * characters (optionally allowing whitespace).
- *
- * @returns A memoized trigger function for {@link LexicalTypeaheadMenuPlugin}.
- */
-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 {
+  getScrollParent,
+  PUNCTUATION,
+  SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND,
+  useBasicTypeaheadTriggerMatch,
+} from '@lexical/react/LexicalTypeaheadMenuPluginUtils';
 
 /**
  * Props for the {@link LexicalTypeaheadMenuPlugin} component.

package/src/LexicalTypeaheadMenuPluginUtils.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 {MenuOption, TriggerFn} from './shared/LexicalMenu';
+
+import {getScrollParent as getScrollParent_} from '@lexical/utils';
+import {createCommand, type LexicalCommand} from 'lexical';
+import {useCallback} from 'react';
+
+/**
+ * The default set of punctuation characters (as a character-class fragment)
+ * that terminate a typeahead query. Used as the default `punctuation` option of
+ * {@link useBasicTypeaheadTriggerMatch}.
+ */
+export const PUNCTUATION =
+  '\\.,\\+\\*\\?\\$\\@\\|#{}\\(\\)\\^\\-\\[\\]\\\\/!%\'"~=<>_:;';
+
+/**
+ * Command dispatched while the typeahead menu is open to scroll the option at
+ * the given `index` into view. The built-in menu hook registers a default
+ * handler; custom implementations can register their own handler at a higher
+ * priority to override the scrolling behavior.
+ */
+export const SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND: LexicalCommand<{
+  index: number;
+  option: MenuOption;
+}> = createCommand('SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND');
+
+/** @deprecated Moved to `@lexical/utils`. Import `getScrollParent` from there. */
+export const getScrollParent = getScrollParent_;
+
+/**
+ * Builds a {@link TriggerFn} for the common case of a single-character
+ * `trigger` (such as `@` or `#`) followed by a query. The returned function
+ * matches when the trigger is preceded by whitespace, an open parenthesis,
+ * or the start of the line
+ * and is followed by between `minLength` and `maxLength` non-`punctuation`
+ * characters (optionally allowing whitespace).
+ *
+ * @returns A memoized trigger function for {@link LexicalTypeaheadMenuPlugin}.
+ */
+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],
+  );
+}