@lexical/react 0.44.1-nightly.20260519.0 → 0.45.0

package/src/LexicalClearEditorPlugin.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 {registerClearEditor} from '@lexical/extension';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+
+import useLayoutEffect from './shared/useLayoutEffect';
+
+type Props = Readonly<{
+  onClear?: () => void;
+}>;
+
+export function ClearEditorPlugin({onClear}: Props): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+  useLayoutEffect(
+    () => registerClearEditor(editor, onClear),
+    [editor, onClear],
+  );
+  return null;
+}

package/src/LexicalClickableLinkPlugin.tsx

@@ -0,0 +1,28 @@
+/**
+ * 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 {registerClickableLink} from '@lexical/link';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {useEffect} from 'react';
+
+export function ClickableLinkPlugin({
+  newTab = true,
+  disabled = false,
+}: {
+  newTab?: boolean;
+  disabled?: boolean;
+}): null {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    return registerClickableLink(editor, namedSignals({disabled, newTab}));
+  }, [editor, newTab, disabled]);
+
+  return null;
+}

package/src/LexicalCollaborationContext.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 {Doc} from 'yjs';
+
+import devInvariant from '@lexical/internal/devInvariant';
+import {createContext, useContext, useMemo} from 'react';
+
+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)];
+
+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();
+
+export function LexicalCollaboration({children}: {children: React.ReactNode}) {
+  const collabContext = useMemo(() => newContext(), []);
+
+  return (
+    <CollaborationContext.Provider value={collabContext}>
+      {children}
+    </CollaborationContext.Provider>
+  );
+}
+
+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/LexicalCollaborationPlugin.tsx

@@ -0,0 +1,266 @@
+/**
+ * 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 {
+  type CollaborationContextType,
+  useCollaborationContext,
+} from '@lexical/react/LexicalCollaborationContext';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  Binding,
+  createBinding,
+  ExcludedProperties,
+  Provider,
+  SyncCursorPositionsFn,
+} from '@lexical/yjs';
+import {LexicalEditor} from 'lexical';
+import {useEffect, useRef, useState} from 'react';
+import {Doc} from 'yjs';
+
+import {InitialEditorStateType} from './LexicalComposer';
+import {
+  CursorsContainerRef,
+  useYjsCollaboration,
+  useYjsCollaborationV2__EXPERIMENTAL,
+  useYjsCursors,
+  useYjsFocusTracking,
+  useYjsHistory,
+  useYjsHistoryV2,
+} from './shared/useYjsCollaboration';
+
+type ProviderFactory = (id: string, yjsDocMap: Map<string, Doc>) => Provider;
+
+type CollaborationPluginProps = {
+  id: string;
+  providerFactory: ProviderFactory;
+  shouldBootstrap: boolean;
+  username?: string;
+  cursorColor?: string;
+  cursorsContainerRef?: CursorsContainerRef;
+  initialEditorState?: InitialEditorStateType;
+  excludedProperties?: ExcludedProperties;
+  // `awarenessData` parameter allows arbitrary data to be added to the awareness.
+  awarenessData?: object;
+  syncCursorPositionsFn?: SyncCursorPositionsFn;
+};
+
+export function CollaborationPlugin({
+  id,
+  providerFactory,
+  shouldBootstrap,
+  username,
+  cursorColor,
+  cursorsContainerRef,
+  initialEditorState,
+  excludedProperties,
+  awarenessData,
+  syncCursorPositionsFn,
+}: CollaborationPluginProps): JSX.Element {
+  const isBindingInitialized = useRef(false);
+  const isProviderInitialized = useRef(false);
+
+  const collabContext = useCollaborationContext(username, cursorColor);
+  const {yjsDocMap, name, color} = collabContext;
+
+  const [editor] = useLexicalComposerContext();
+
+  useCollabActive(collabContext, editor);
+
+  const [provider, setProvider] = useState<Provider>();
+  const [doc, setDoc] = useState<Doc>();
+
+  useEffect(() => {
+    if (isProviderInitialized.current) {
+      return;
+    }
+
+    isProviderInitialized.current = true;
+
+    const newProvider = providerFactory(id, yjsDocMap);
+    setProvider(newProvider);
+    setDoc(yjsDocMap.get(id));
+
+    return () => {
+      newProvider.disconnect();
+    };
+  }, [id, providerFactory, yjsDocMap]);
+
+  const [binding, setBinding] = useState<Binding>();
+
+  useEffect(() => {
+    if (!provider) {
+      return;
+    }
+
+    if (isBindingInitialized.current) {
+      return;
+    }
+
+    isBindingInitialized.current = true;
+
+    const newBinding = createBinding(
+      editor,
+      provider,
+      id,
+      doc || yjsDocMap.get(id),
+      yjsDocMap,
+      excludedProperties,
+    );
+    setBinding(newBinding);
+
+    return () => {
+      newBinding.root.destroy(newBinding);
+    };
+  }, [editor, provider, id, yjsDocMap, doc, excludedProperties]);
+
+  if (!provider || !binding) {
+    return <></>;
+  }
+
+  return (
+    <YjsCollaborationCursors
+      awarenessData={awarenessData}
+      binding={binding}
+      collabContext={collabContext}
+      color={color}
+      cursorsContainerRef={cursorsContainerRef}
+      editor={editor}
+      id={id}
+      initialEditorState={initialEditorState}
+      name={name}
+      provider={provider}
+      setDoc={setDoc}
+      shouldBootstrap={shouldBootstrap}
+      yjsDocMap={yjsDocMap}
+      syncCursorPositionsFn={syncCursorPositionsFn}
+    />
+  );
+}
+
+function YjsCollaborationCursors({
+  editor,
+  id,
+  provider,
+  yjsDocMap,
+  name,
+  color,
+  shouldBootstrap,
+  cursorsContainerRef,
+  initialEditorState,
+  awarenessData,
+  collabContext,
+  binding,
+  setDoc,
+  syncCursorPositionsFn,
+}: {
+  editor: LexicalEditor;
+  id: string;
+  provider: Provider;
+  yjsDocMap: Map<string, Doc>;
+  name: string;
+  color: string;
+  shouldBootstrap: boolean;
+  binding: Binding;
+  setDoc: React.Dispatch<React.SetStateAction<Doc | undefined>>;
+  cursorsContainerRef?: CursorsContainerRef | undefined;
+  initialEditorState?: InitialEditorStateType | undefined;
+  awarenessData?: object;
+  collabContext: CollaborationContextType;
+  syncCursorPositionsFn?: SyncCursorPositionsFn;
+}) {
+  const cursors = useYjsCollaboration(
+    editor,
+    id,
+    provider,
+    yjsDocMap,
+    name,
+    color,
+    shouldBootstrap,
+    binding,
+    setDoc,
+    cursorsContainerRef,
+    initialEditorState,
+    awarenessData,
+    syncCursorPositionsFn,
+  );
+
+  useYjsHistory(editor, binding);
+  useYjsFocusTracking(editor, provider, name, color, awarenessData);
+
+  return cursors;
+}
+
+type CollaborationPluginV2Props = {
+  id: string;
+  doc: Doc;
+  provider: Provider;
+  __shouldBootstrapUnsafe?: boolean;
+  username?: string;
+  cursorColor?: string;
+  cursorsContainerRef?: CursorsContainerRef;
+  excludedProperties?: ExcludedProperties;
+  // `awarenessData` parameter allows arbitrary data to be added to the awareness.
+  awarenessData?: object;
+};
+
+export function CollaborationPluginV2__EXPERIMENTAL({
+  id,
+  doc,
+  provider,
+  __shouldBootstrapUnsafe,
+  username,
+  cursorColor,
+  cursorsContainerRef,
+  excludedProperties,
+  awarenessData,
+}: CollaborationPluginV2Props): JSX.Element {
+  const collabContext = useCollaborationContext(username, cursorColor);
+  const {yjsDocMap, name, color} = collabContext;
+
+  const [editor] = useLexicalComposerContext();
+  useCollabActive(collabContext, editor);
+
+  const binding = useYjsCollaborationV2__EXPERIMENTAL(
+    editor,
+    id,
+    doc,
+    provider,
+    yjsDocMap,
+    name,
+    color,
+    {
+      __shouldBootstrapUnsafe,
+      awarenessData,
+      excludedProperties,
+    },
+  );
+
+  useYjsHistoryV2(editor, binding);
+  useYjsFocusTracking(editor, provider, name, color, awarenessData);
+  return useYjsCursors(binding, cursorsContainerRef);
+}
+
+const useCollabActive = (
+  collabContext: CollaborationContextType,
+  editor: LexicalEditor,
+) => {
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/immutability
+    collabContext.isCollabActive = true;
+
+    return () => {
+      // Resetting flag only when unmount top level editor collab plugin. Nested
+      // editors (e.g. image caption) should unmount without affecting it
+      if (editor._parentEditor == null) {
+        collabContext.isCollabActive = false;
+      }
+    };
+  }, [collabContext, editor]);
+};

package/src/LexicalComposer.tsx

@@ -0,0 +1,185 @@
+/**
+ * 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 {JSX} from 'react';
+
+import {
+  createLexicalComposerContext,
+  LexicalComposerContext,
+} from '@lexical/react/LexicalComposerContext';
+import {
+  $createParagraphNode,
+  $getRoot,
+  $getSelection,
+  CAN_USE_DOM,
+  createEditor,
+  EditorState,
+  EditorThemeClasses,
+  HISTORY_MERGE_TAG,
+  HTMLConfig,
+  Klass,
+  LexicalEditor,
+  LexicalNode,
+  LexicalNodeReplacement,
+} from 'lexical';
+import * as React from 'react';
+import {useMemo} from 'react';
+
+import useLayoutEffect from './shared/useLayoutEffect';
+
+const HISTORY_MERGE_OPTIONS = {tag: HISTORY_MERGE_TAG};
+
+/**
+ * The initial editor state accepted by {@link LexicalComposer} via
+ * `initialConfig.editorState`. Each variant is handled differently:
+ *
+ * - `null` — skip default initialization entirely. The root is left with no
+ *   children for an external owner (typically the
+ *   [collaboration plugin](/docs/collaboration/react) and its Yjs document)
+ *   to populate.
+ * - `string` — a JSON string produced by serializing an `EditorState`. Parsed
+ *   with {@link LexicalEditor.parseEditorState} and applied via
+ *   {@link LexicalEditor.setEditorState}.
+ * - `EditorState` — applied directly via {@link LexicalEditor.setEditorState}.
+ * - `(editor) => void` — an updater run inside `editor.update(...)`. Invoked
+ *   only when the root is still empty, so it will not overwrite content
+ *   bootstrapped by another mechanism, and is silently skipped if the root
+ *   already has children.
+ *
+ * Note that `string` and `EditorState` inputs go through `setEditorState`,
+ * which throws when the parsed state satisfies `EditorState.isEmpty()` (root
+ * with no children and no selection). The empty serialization produced by
+ * initializing with `null` and never modifying the editor falls into this
+ * category, so it cannot be re-applied via `setEditorState` after a round-trip.
+ */
+export type InitialEditorStateType =
+  | null
+  | string
+  | EditorState
+  | ((editor: LexicalEditor) => void);
+
+export type InitialConfigType = Readonly<{
+  namespace: string;
+  nodes?: ReadonlyArray<Klass<LexicalNode> | LexicalNodeReplacement>;
+  onError: (error: Error, editor: LexicalEditor) => void;
+  editable?: boolean;
+  theme?: EditorThemeClasses;
+  /**
+   * The initial state of the editor. Read once on mount; changes after the
+   * first render are ignored.
+   *
+   * Omitting the field (or passing `undefined`) seeds the root with a default
+   * empty `ParagraphNode`. Pass `null` to skip that default — required when
+   * pairing with the collaboration plugin so that the Yjs document, not
+   * Lexical, owns the initial content. See {@link InitialEditorStateType}
+   * for the full set of accepted shapes.
+   */
+  editorState?: InitialEditorStateType;
+  html?: HTMLConfig;
+}>;
+
+type Props = React.PropsWithChildren<{
+  initialConfig: InitialConfigType;
+}>;
+
+export function LexicalComposer({initialConfig, children}: Props): JSX.Element {
+  const composerContext: [LexicalEditor, LexicalComposerContextType] = useMemo(
+    () => {
+      const {
+        theme,
+        namespace,
+        nodes,
+        onError,
+        editorState: initialEditorState,
+        html,
+      } = initialConfig;
+
+      const context: LexicalComposerContextType = createLexicalComposerContext(
+        null,
+        theme,
+      );
+
+      const editor = createEditor({
+        editable: initialConfig.editable,
+        html,
+        namespace,
+        nodes,
+        onError: error => onError(error, editor),
+        theme,
+      });
+      initializeEditor(editor, initialEditorState);
+
+      return [editor, context];
+    },
+
+    // We only do this for init
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  useLayoutEffect(() => {
+    const isEditable = initialConfig.editable;
+    const [editor] = composerContext;
+    editor.setEditable(isEditable !== undefined ? isEditable : true);
+
+    // We only do this for init
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <LexicalComposerContext.Provider value={composerContext}>
+      {children}
+    </LexicalComposerContext.Provider>
+  );
+}
+
+function initializeEditor(
+  editor: LexicalEditor,
+  initialEditorState?: InitialEditorStateType,
+): void {
+  if (initialEditorState === null) {
+    return;
+  } else if (initialEditorState === undefined) {
+    editor.update(() => {
+      const root = $getRoot();
+      if (root.isEmpty()) {
+        const paragraph = $createParagraphNode();
+        root.append(paragraph);
+        const activeElement = CAN_USE_DOM ? document.activeElement : null;
+        if (
+          $getSelection() !== null ||
+          (activeElement !== null && activeElement === editor.getRootElement())
+        ) {
+          paragraph.select();
+        }
+      }
+    }, HISTORY_MERGE_OPTIONS);
+  } else if (initialEditorState !== null) {
+    switch (typeof initialEditorState) {
+      case 'string': {
+        const parsedEditorState = editor.parseEditorState(initialEditorState);
+        editor.setEditorState(parsedEditorState, HISTORY_MERGE_OPTIONS);
+        break;
+      }
+      case 'object': {
+        editor.setEditorState(initialEditorState, HISTORY_MERGE_OPTIONS);
+        break;
+      }
+      case 'function': {
+        editor.update(() => {
+          const root = $getRoot();
+          if (root.isEmpty()) {
+            initialEditorState(editor);
+          }
+        }, HISTORY_MERGE_OPTIONS);
+        break;
+      }
+    }
+  }
+}

package/src/LexicalComposerContext.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 {EditorThemeClasses, LexicalEditor} from 'lexical';
+
+import invariant from '@lexical/internal/invariant';
+import {createContext as createReactContext, useContext} from 'react';
+
+export type LexicalComposerContextType = {
+  getTheme: () => EditorThemeClasses | null | undefined;
+};
+
+export type LexicalComposerContextWithEditor = [
+  LexicalEditor,
+  LexicalComposerContextType,
+];
+
+export const LexicalComposerContext: React.Context<
+  LexicalComposerContextWithEditor | null | undefined
+> = createReactContext<LexicalComposerContextWithEditor | null | undefined>(
+  null,
+);
+
+export function createLexicalComposerContext(
+  parent: LexicalComposerContextWithEditor | null | undefined,
+  theme: EditorThemeClasses | null | undefined,
+): LexicalComposerContextType {
+  let parentContext: LexicalComposerContextType | null = null;
+
+  if (parent != null) {
+    parentContext = parent[1];
+  }
+
+  function getTheme() {
+    if (theme != null) {
+      return theme;
+    }
+
+    return parentContext != null ? parentContext.getTheme() : null;
+  }
+
+  return {
+    getTheme,
+  };
+}
+
+export function useLexicalComposerContext(): LexicalComposerContextWithEditor {
+  const composerContext = useContext(LexicalComposerContext);
+
+  if (composerContext == null) {
+    invariant(
+      false,
+      'LexicalComposerContext.useLexicalComposerContext: cannot find a LexicalComposerContext',
+    );
+  }
+
+  return composerContext;
+}