@lexical/react 0.44.1-nightly.20260518.0 → 0.45.0

package/src/ReactExtension.tsx

@@ -0,0 +1,113 @@
+/**
+ * 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 {
+  EditorChildrenComponentProps,
+  ReactConfig,
+  ReactOutputs,
+} from './shared/types';
+import type {LexicalComposerContextWithEditor} from '@lexical/react/LexicalComposerContext';
+
+import invariant from '@lexical/internal/invariant';
+import {ContentEditable} from '@lexical/react/LexicalContentEditable';
+import {LexicalErrorBoundary} from '@lexical/react/LexicalErrorBoundary';
+import {ReactProviderExtension} from '@lexical/react/ReactProviderExtension';
+import {
+  declarePeerDependency,
+  defineExtension,
+  shallowMergeConfig,
+} from 'lexical';
+
+import {buildEditorComponent} from './shared/buildEditorComponent';
+
+export type {EditorChildrenComponentProps, ReactConfig, ReactOutputs};
+
+/**
+ * @example
+ * The default EditorChildrenComponent implementation
+ * ```jsx
+ * return (
+ *   <>
+ *     {contentEditable}
+ *     {children}
+ *   </>
+ * );
+ * ```
+ */
+export function DefaultEditorChildrenComponent({
+  contentEditable,
+  children,
+}: EditorChildrenComponentProps) {
+  return (
+    <>
+      {contentEditable}
+      {children}
+    </>
+  );
+}
+
+const initialConfig: ReactConfig = {
+  EditorChildrenComponent: DefaultEditorChildrenComponent,
+  ErrorBoundary: LexicalErrorBoundary,
+  contentEditable: <ContentEditable />,
+  decorators: [],
+};
+
+/**
+ * An extension to use or configure React for use with Lexical. In an editor, you
+ * would typically use {@link LexicalExtensionComposer} (for React projects) or
+ * {@link ReactPluginHostExtension} (to use React Extensions and plug-ins in a non-React
+ * project).
+ *
+ * See {@link ReactConfig} for more detailed exextensionations of how to use
+ * the config for this Extension.
+ *
+ * For an Extension developer, you can defineConfig() override the extension with
+ * decorators to add JSX inside the editor context that is not
+ * location-dependent (e.g. floating UI that does not need to be mounted in
+ * some specific location, or effects that return null).
+ */
+export const ReactExtension = defineExtension({
+  build(editor, config, state) {
+    const providerPeer = state.getPeer<typeof ReactProviderExtension>(
+      ReactProviderExtension.name,
+    );
+    if (!providerPeer) {
+      invariant(
+        false,
+        'No ReactProviderExtension detected. You must use ReactPluginHostExtension or LexicalExtensionComposer to host React extensions. The following extensions depend on ReactExtension: %s',
+        [...state.getDirectDependentNames()].join(' '),
+      );
+    }
+    const context: LexicalComposerContextWithEditor = [
+      editor,
+      {getTheme: () => editor._config.theme},
+    ];
+    const Component = buildEditorComponent(config, context);
+    return {Component, context};
+  },
+  config: initialConfig,
+  mergeConfig(a, b) {
+    const config = shallowMergeConfig(a, b);
+    if (b.decorators) {
+      config.decorators =
+        b.decorators.length > 0
+          ? [...a.decorators, ...b.decorators]
+          : a.decorators;
+    }
+    return config;
+  },
+  name: '@lexical/react/React',
+  peerDependencies: [
+    // We are not trying to avoid the import, just the direct dependency,
+    // so using the extension directly is fine.
+    declarePeerDependency<typeof ReactProviderExtension>(
+      ReactProviderExtension.name,
+    ),
+  ],
+});

package/src/ReactPluginHostExtension.tsx

@@ -0,0 +1,228 @@
+/**
+ * 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 {DecoratorComponentProps} from './shared/types';
+import type {JSX} from 'react';
+
+import {
+  effect,
+  getExtensionDependencyFromEditor,
+  signal,
+  untracked,
+} from '@lexical/extension';
+import invariant from '@lexical/internal/invariant';
+import {ReactExtension} from '@lexical/react/ReactExtension';
+import {ReactProviderExtension} from '@lexical/react/ReactProviderExtension';
+import {mergeRegister} from '@lexical/utils';
+import {
+  type AnyLexicalExtension,
+  COMMAND_PRIORITY_CRITICAL,
+  COMMAND_PRIORITY_EDITOR,
+  configExtension,
+  createCommand,
+  defineExtension,
+  type LexicalEditor,
+  type LexicalExtensionOutput,
+} from 'lexical';
+import * as React from 'react';
+import {Suspense, useEffect, useState} from 'react';
+import {createPortal} from 'react-dom';
+import {type Container, createRoot, type Root} from 'react-dom/client';
+
+export type {DecoratorComponentProps};
+
+export interface HostMountCommandArg {
+  root: Root;
+}
+
+export interface MountPluginCommandArg {
+  key: string;
+  element: JSX.Element | null;
+  domNode?: Element | DocumentFragment | null;
+}
+
+export function mountReactExtensionComponent<
+  Extension extends AnyLexicalExtension,
+>(
+  editor: LexicalEditor,
+  opts: {
+    extension: Extension;
+    props: [LexicalExtensionOutput<Extension>] extends [
+      {
+        Component: React.ComponentType<infer OutputComponentProps>;
+      },
+    ]
+      ? /** The Props from the Extension output Component */ OutputComponentProps | null
+      : never;
+  } & Omit<MountPluginCommandArg, 'element'>,
+): void {
+  const {props, extension, ...rest} = opts;
+  const {Component} = getExtensionDependencyFromEditor(
+    editor,
+    extension,
+  ).output;
+  const element = props ? <Component {...props} /> : null;
+  mountReactPluginElement(editor, {
+    ...rest,
+    element,
+  });
+}
+
+export function mountReactPluginComponent<
+  P extends Record<never, never> = Record<never, never>,
+>(
+  editor: LexicalEditor,
+  opts: {
+    Component: React.ComponentType<P>;
+    props: (P & React.Attributes) | null;
+  } & Omit<MountPluginCommandArg, 'element'>,
+): void {
+  const {Component, props, ...rest} = opts;
+  mountReactPluginElement(editor, {
+    ...rest,
+    element: props ? <Component {...props} /> : null,
+  });
+}
+
+export function mountReactPluginElement(
+  editor: LexicalEditor,
+  opts: MountPluginCommandArg,
+): void {
+  getExtensionDependencyFromEditor(
+    editor,
+    ReactPluginHostExtension,
+  ).output.mountReactPlugin(opts);
+}
+
+export function mountReactPluginHost(
+  editor: LexicalEditor,
+  container: Container,
+): void {
+  getExtensionDependencyFromEditor(
+    editor,
+    ReactPluginHostExtension,
+  ).output.mountReactPluginHost(container);
+}
+
+export const REACT_PLUGIN_HOST_MOUNT_ROOT_COMMAND =
+  createCommand<HostMountCommandArg>('REACT_PLUGIN_HOST_MOUNT_ROOT_COMMAND');
+export const REACT_PLUGIN_HOST_MOUNT_PLUGIN_COMMAND =
+  createCommand<MountPluginCommandArg>(
+    'REACT_PLUGIN_HOST_MOUNT_PLUGIN_COMMAND',
+  );
+
+function PluginHostDecorator({
+  context: [editor],
+}: DecoratorComponentProps): JSX.Element | null {
+  const {mountedPluginsStore} = getExtensionDependencyFromEditor(
+    editor,
+    ReactPluginHostExtension,
+  ).output;
+  const {ErrorBoundary} = getExtensionDependencyFromEditor(
+    editor,
+    ReactExtension,
+  ).config;
+  const onError = editor._onError.bind(editor);
+  const [{plugins}, setMountedPlugins] = useState(() =>
+    mountedPluginsStore.peek(),
+  );
+  useEffect(
+    () => effect(() => setMountedPlugins(mountedPluginsStore.value)),
+    [mountedPluginsStore],
+  );
+  const children: JSX.Element[] = [];
+  for (const {key, element, domNode} of plugins.values()) {
+    if (!element) {
+      continue;
+    }
+    const wrapped = (
+      <ErrorBoundary onError={onError} key={key}>
+        <Suspense fallback={null}>{element}</Suspense>
+      </ErrorBoundary>
+    );
+    children.push(domNode ? createPortal(wrapped, domNode, key) : wrapped);
+  }
+  return children.length > 0 ? <>{children}</> : null;
+}
+
+/**
+ * This extension provides a React host for editors that are not built
+ * with LexicalExtensionComposer (e.g. you are using Vanilla JS or some
+ * other framework).
+ *
+ * You must use {@link mountReactPluginHost} for any React content to work.
+ * Afterwards, you may use {@link mountReactExtensionComponent} to
+ * render UI for a specific React Extension.
+ * {@link mountReactPluginComponent} and
+ * {@link mountReactPluginElement} can be used to render
+ * legacy React plug-ins (or any React content).
+ */
+export const ReactPluginHostExtension = defineExtension({
+  build(editor, config, state) {
+    const mountedPluginsStore = signal({
+      plugins: new Map<MountPluginCommandArg['key'], MountPluginCommandArg>(),
+    });
+    return {
+      mountReactPlugin: (arg: MountPluginCommandArg) => {
+        editor.dispatchCommand(REACT_PLUGIN_HOST_MOUNT_PLUGIN_COMMAND, arg);
+      },
+      // Using outputs to wrap commands will give us better error messages
+      // if the mount functions are called on an editor without this extension
+      mountReactPluginHost: (container: Container) =>
+        editor.dispatchCommand(REACT_PLUGIN_HOST_MOUNT_ROOT_COMMAND, {
+          root: createRoot(container),
+        }),
+      mountedPluginsStore,
+    };
+  },
+  dependencies: [
+    ReactProviderExtension,
+    configExtension(ReactExtension, {decorators: [PluginHostDecorator]}),
+  ],
+  name: '@lexical/react/ReactPluginHost',
+  register(editor, _config, state) {
+    let root: Root | undefined;
+    const {mountedPluginsStore} = state.getOutput();
+    const {Component} = state.getDependency(ReactExtension).output;
+    return mergeRegister(
+      () => {
+        if (root) {
+          root.unmount();
+        }
+        untracked(() => {
+          mountedPluginsStore.value.plugins.clear();
+        });
+      },
+      editor.registerCommand(
+        REACT_PLUGIN_HOST_MOUNT_PLUGIN_COMMAND,
+        arg => {
+          // This runs before the PluginHost version
+          untracked(() => {
+            const {plugins} = mountedPluginsStore.value;
+            plugins.set(arg.key, arg);
+            mountedPluginsStore.value = {plugins};
+          });
+          return false;
+        },
+        COMMAND_PRIORITY_CRITICAL,
+      ),
+      editor.registerCommand(
+        REACT_PLUGIN_HOST_MOUNT_ROOT_COMMAND,
+        arg => {
+          invariant(
+            root === undefined,
+            'ReactPluginHostExtension: Root is already mounted',
+          );
+          root = arg.root;
+          root.render(<Component contentEditable={null} />);
+          return true;
+        },
+        COMMAND_PRIORITY_EDITOR,
+      ),
+    );
+  },
+});

package/src/ReactProviderExtension.tsx

@@ -0,0 +1,20 @@
+/**
+ * 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 {defineExtension} from 'lexical';
+
+/**
+ * An extension used to declare that there is a LexicalExtensionComposer or
+ * ReactPluginHostExtension available so that we can issue runtime warnings
+ * when plugins that depend on React are hosted in an environment
+ * where it is not ever going to be rendered.
+ *
+ * It is a separate extension so it can be used as a peer dependency.
+ */
+export const ReactProviderExtension = defineExtension({
+  name: '@lexical/react/ReactProvider',
+});

package/src/TreeViewExtension.tsx

@@ -0,0 +1,48 @@
+/**
+ * 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 {TreeView} from '@lexical/react/LexicalTreeView';
+import {ReactExtension} from '@lexical/react/ReactExtension';
+import {useExtensionDependency} from '@lexical/react/useExtensionComponent';
+import {defineExtension} from 'lexical';
+
+export type TreeViewConfig = Omit<Parameters<typeof TreeView>[0], 'editor'>;
+export function TreeViewExtensionComponent(
+  props: Partial<TreeViewConfig>,
+): JSX.Element {
+  const [editor] = useLexicalComposerContext();
+  return (
+    <TreeView
+      editor={editor}
+      {...useExtensionDependency(TreeViewExtension).config}
+      {...props}
+    />
+  );
+}
+
+const config: TreeViewConfig = {
+  timeTravelButtonClassName: 'debug-timetravel-button',
+  timeTravelPanelButtonClassName: 'debug-timetravel-panel-button',
+  timeTravelPanelClassName: 'debug-timetravel-panel',
+  timeTravelPanelSliderClassName: 'debug-timetravel-panel-slider',
+  treeTypeButtonClassName: 'debug-treetype-button',
+  viewClassName: 'tree-view-output',
+};
+
+/**
+ * Provides a configured TreeView debugging tool (React dependent)
+ * as an output component with configurable class names.
+ */
+export const TreeViewExtension = defineExtension({
+  build: () => ({Component: TreeViewExtensionComponent}),
+  config,
+  dependencies: [ReactExtension],
+  name: '@lexical/react/TreeView',
+});

package/src/shared/LegacyDecorators.tsx

@@ -0,0 +1,62 @@
+/**
+ * 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 {LexicalBuilder} from '@lexical/extension';
+import invariant from '@lexical/internal/invariant';
+import {ReactProviderExtension} from '@lexical/react/ReactProviderExtension';
+import {type LexicalEditor} from 'lexical';
+
+import {type ErrorBoundaryType, useDecorators} from './useDecorators';
+
+export {type ErrorBoundaryType};
+
+function isUsingReactExtension(editor: LexicalEditor): boolean {
+  const builder = LexicalBuilder.maybeFromEditor(editor);
+  if (builder && builder.hasExtensionByName(ReactProviderExtension.name)) {
+    for (const name of ['@lexical/plain-text', '@lexical/rich-text']) {
+      invariant(
+        !builder.hasExtensionByName(name),
+        'LexicalBuilder: @lexical/react legacy text plugins conflict with the %s extension. Remove the legacy <RichTextPlugin/> or <PlainTextPlugin/> component.',
+        name,
+      );
+    }
+    return true;
+  }
+  return false;
+}
+
+function Decorators({
+  editor,
+  ErrorBoundary,
+}: {
+  editor: LexicalEditor;
+  ErrorBoundary: ErrorBoundaryType;
+}) {
+  return useDecorators(editor, ErrorBoundary);
+}
+
+/**
+ * @internal
+ *
+ * When using @lexical/extension, the ReactProvider is expected to handle
+ * rendering decorators. This component allows RichTextPlugin and
+ * PlainTextPlugin to be used in extension projects that have not yet
+ * migrated to use RichTextExtension or PlainTextExtension.
+ **/
+export function LegacyDecorators({
+  editor,
+  ErrorBoundary,
+}: {
+  editor: LexicalEditor;
+  ErrorBoundary: ErrorBoundaryType;
+}): JSX.Element | null {
+  return isUsingReactExtension(editor) ? null : (
+    <Decorators editor={editor} ErrorBoundary={ErrorBoundary} />
+  );
+}

package/src/shared/LexicalContentEditableElement.tsx

@@ -0,0 +1,126 @@
+/**
+ * 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 {LexicalEditor} from 'lexical';
+import type {ForwardedRef, JSX, RefCallback} from 'react';
+
+import * as React from 'react';
+import {forwardRef, useCallback, useMemo, useState} from 'react';
+
+import {mergeRefs} from './mergeRefs';
+import useLayoutEffect from './useLayoutEffect';
+
+export type ContentEditableElementProps = {
+  editor: LexicalEditor;
+  ariaActiveDescendant?: React.AriaAttributes['aria-activedescendant'];
+  ariaAutoComplete?: React.AriaAttributes['aria-autocomplete'];
+  ariaControls?: React.AriaAttributes['aria-controls'];
+  ariaDescribedBy?: React.AriaAttributes['aria-describedby'];
+  ariaErrorMessage?: React.AriaAttributes['aria-errormessage'];
+  ariaExpanded?: React.AriaAttributes['aria-expanded'];
+  ariaInvalid?: React.AriaAttributes['aria-invalid'];
+  ariaLabel?: React.AriaAttributes['aria-label'];
+  ariaLabelledBy?: React.AriaAttributes['aria-labelledby'];
+  ariaMultiline?: React.AriaAttributes['aria-multiline'];
+  ariaOwns?: React.AriaAttributes['aria-owns'];
+  ariaRequired?: React.AriaAttributes['aria-required'];
+  autoCapitalize?: HTMLDivElement['autocapitalize'];
+  'data-testid'?: string | null | undefined;
+} & Omit<React.AllHTMLAttributes<HTMLDivElement>, 'placeholder'>;
+
+function ContentEditableElementImpl(
+  {
+    editor,
+    ariaActiveDescendant,
+    ariaAutoComplete,
+    ariaControls,
+    ariaDescribedBy,
+    ariaErrorMessage,
+    ariaExpanded,
+    ariaInvalid,
+    ariaLabel,
+    ariaLabelledBy,
+    ariaMultiline,
+    ariaOwns,
+    ariaRequired,
+    autoCapitalize,
+    className,
+    id,
+    role = 'textbox',
+    spellCheck = true,
+    style,
+    tabIndex,
+    'data-testid': testid,
+    ...rest
+  }: ContentEditableElementProps,
+  ref: ForwardedRef<HTMLDivElement>,
+): JSX.Element {
+  const [isEditable, setEditable] = useState(editor.isEditable());
+
+  const handleRef = useCallback<RefCallback<HTMLDivElement>>(
+    rootElement => {
+      // defaultView is required for a root element.
+      // In multi-window setups, the defaultView may not exist at certain points.
+      if (
+        rootElement &&
+        rootElement.ownerDocument &&
+        rootElement.ownerDocument.defaultView
+      ) {
+        editor.setRootElement(rootElement);
+      } else {
+        editor.setRootElement(null);
+      }
+    },
+    [editor],
+  );
+  const mergedRefs = useMemo(() => mergeRefs(ref, handleRef), [handleRef, ref]);
+
+  useLayoutEffect(() => {
+    setEditable(editor.isEditable());
+    return editor.registerEditableListener(currentIsEditable => {
+      setEditable(currentIsEditable);
+    });
+  }, [editor]);
+
+  return (
+    <div
+      aria-activedescendant={isEditable ? ariaActiveDescendant : undefined}
+      aria-autocomplete={isEditable ? ariaAutoComplete : 'none'}
+      aria-controls={isEditable ? ariaControls : undefined}
+      aria-describedby={ariaDescribedBy}
+      // for compat, only override aria-errormessage if ariaErrorMessage is defined
+      {...(ariaErrorMessage != null
+        ? {'aria-errormessage': ariaErrorMessage}
+        : {})}
+      aria-expanded={
+        isEditable && role === 'combobox' ? !!ariaExpanded : undefined
+      }
+      // for compat, only override aria-invalid if ariaInvalid is defined
+      {...(ariaInvalid != null ? {'aria-invalid': ariaInvalid} : {})}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-multiline={ariaMultiline}
+      aria-owns={isEditable ? ariaOwns : undefined}
+      aria-readonly={isEditable ? undefined : true}
+      aria-required={ariaRequired}
+      autoCapitalize={autoCapitalize}
+      className={className}
+      contentEditable={isEditable}
+      data-testid={testid}
+      id={id}
+      ref={mergedRefs}
+      role={role}
+      spellCheck={spellCheck}
+      style={style}
+      tabIndex={tabIndex}
+      {...rest}
+    />
+  );
+}
+
+export const ContentEditableElement = forwardRef(ContentEditableElementImpl);