zurfyx-lexical-react 0.39.1-nightly.20251225.0

package/src/LexicalTypeaheadMenuPlugin.tsx

@@ -0,0 +1,354 @@
+/**
+ * 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 {
+  MenuRenderFn,
+  MenuResolution,
+  MenuTextMatch,
+  TriggerFn,
+} from './shared/LexicalMenu';
+import type {JSX} from 'react';
+
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  $getSelection,
+  $isRangeSelection,
+  $isTextNode,
+  COMMAND_PRIORITY_LOW,
+  CommandListenerPriority,
+  createCommand,
+  getDOMSelection,
+  LexicalCommand,
+  LexicalEditor,
+  RangeSelection,
+  TextNode,
+} from 'lexical';
+import {useCallback, useEffect, useState} from 'react';
+import {startTransition} from 'shared/reactPatches';
+
+import {LexicalMenu, MenuOption, useMenuAnchorRef} from './shared/LexicalMenu';
+
+export const PUNCTUATION =
+  '\\.,\\+\\*\\?\\$\\@\\|#{}\\(\\)\\^\\-\\[\\]\\\\/!%\'"~=<>_:;';
+
+function getTextUpToAnchor(selection: RangeSelection): string | null {
+  const anchor = selection.anchor;
+  if (anchor.type !== 'text') {
+    return null;
+  }
+  const anchorNode = anchor.getNode();
+  if (!anchorNode.isSimpleText()) {
+    return null;
+  }
+  const anchorOffset = anchor.offset;
+  return anchorNode.getTextContent().slice(0, anchorOffset);
+}
+
+function tryToPositionRange(
+  leadOffset: number,
+  range: Range,
+  editorWindow: Window,
+): boolean {
+  const domSelection = getDOMSelection(editorWindow);
+  if (domSelection === null || !domSelection.isCollapsed) {
+    return false;
+  }
+  const anchorNode = domSelection.anchorNode;
+  const startOffset = leadOffset;
+  const endOffset = domSelection.anchorOffset;
+
+  if (anchorNode == null || endOffset == null) {
+    return false;
+  }
+
+  try {
+    range.setStart(anchorNode, startOffset);
+    range.setEnd(anchorNode, endOffset);
+  } catch (_error) {
+    return false;
+  }
+
+  return true;
+}
+
+function getQueryTextForSearch(editor: LexicalEditor): string | null {
+  let text = null;
+  editor.getEditorState().read(() => {
+    const selection = $getSelection();
+    if (!$isRangeSelection(selection)) {
+      return;
+    }
+    text = getTextUpToAnchor(selection);
+  });
+  return text;
+}
+
+function isSelectionOnEntityBoundary(
+  editor: LexicalEditor,
+  offset: number,
+): boolean {
+  if (offset !== 0) {
+    return false;
+  }
+  return editor.getEditorState().read(() => {
+    const selection = $getSelection();
+    if ($isRangeSelection(selection)) {
+      const anchor = selection.anchor;
+      const anchorNode = anchor.getNode();
+      const prevSibling = anchorNode.getPreviousSibling();
+      return $isTextNode(prevSibling) && prevSibling.isTextEntity();
+    }
+    return false;
+  });
+}
+
+// Got from https://stackoverflow.com/a/42543908/2013580
+export function getScrollParent(
+  element: HTMLElement,
+  includeHidden: boolean,
+): HTMLElement | HTMLBodyElement {
+  let style = getComputedStyle(element);
+  const excludeStaticParent = style.position === 'absolute';
+  const overflowRegex = includeHidden
+    ? /(auto|scroll|hidden)/
+    : /(auto|scroll)/;
+  if (style.position === 'fixed') {
+    return document.body;
+  }
+  for (
+    let parent: HTMLElement | null = element;
+    (parent = parent.parentElement);
+
+  ) {
+    style = getComputedStyle(parent);
+    if (excludeStaticParent && style.position === 'static') {
+      continue;
+    }
+    if (
+      overflowRegex.test(style.overflow + style.overflowY + style.overflowX)
+    ) {
+      return parent;
+    }
+  }
+  return document.body;
+}
+
+export {useDynamicPositioning} from './shared/LexicalMenu';
+
+export const SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND: LexicalCommand<{
+  index: number;
+  option: MenuOption;
+}> = createCommand('SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND');
+
+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 type TypeaheadMenuPluginProps<TOption extends MenuOption> = {
+  onQueryChange: (matchingString: string | null) => void;
+  onSelectOption: (
+    option: TOption,
+    textNodeContainingQuery: TextNode | null,
+    closeMenu: () => void,
+    matchingString: string,
+  ) => void;
+  options: Array<TOption>;
+  menuRenderFn: MenuRenderFn<TOption>;
+  triggerFn: TriggerFn;
+  onOpen?: (resolution: MenuResolution) => void;
+  onClose?: () => void;
+  anchorClassName?: string;
+  commandPriority?: CommandListenerPriority;
+  parent?: HTMLElement;
+  preselectFirstItem?: boolean;
+  ignoreEntityBoundary?: boolean;
+};
+
+export function LexicalTypeaheadMenuPlugin<TOption extends MenuOption>({
+  options,
+  onQueryChange,
+  onSelectOption,
+  onOpen,
+  onClose,
+  menuRenderFn,
+  triggerFn,
+  anchorClassName,
+  commandPriority = COMMAND_PRIORITY_LOW,
+  parent,
+  preselectFirstItem = true,
+  ignoreEntityBoundary = false,
+}: TypeaheadMenuPluginProps<TOption>): JSX.Element | null {
+  const [editor] = useLexicalComposerContext();
+  const [resolution, setResolution] = useState<MenuResolution | null>(null);
+  const anchorElementRef = useMenuAnchorRef(
+    resolution,
+    setResolution,
+    anchorClassName,
+    parent,
+  );
+
+  const closeTypeahead = useCallback(() => {
+    setResolution(null);
+    if (onClose != null && resolution !== null) {
+      onClose();
+    }
+  }, [onClose, resolution]);
+
+  const openTypeahead = useCallback(
+    (res: MenuResolution) => {
+      setResolution(res);
+      if (onOpen != null && resolution === null) {
+        onOpen(res);
+      }
+    },
+    [onOpen, resolution],
+  );
+
+  useEffect(() => {
+    const updateListener = () => {
+      editor.getEditorState().read(() => {
+        // Check if editor is in read-only mode
+        if (!editor.isEditable()) {
+          closeTypeahead();
+          return;
+        }
+
+        if (editor.isComposing()) {
+          return;
+        }
+
+        const editorWindow = editor._window || window;
+        const range = editorWindow.document.createRange();
+        const selection = $getSelection();
+        const text = getQueryTextForSearch(editor);
+
+        if (
+          !$isRangeSelection(selection) ||
+          !selection.isCollapsed() ||
+          text === null ||
+          range === null
+        ) {
+          closeTypeahead();
+          return;
+        }
+
+        const match = triggerFn(text, editor);
+        onQueryChange(match ? match.matchingString : null);
+
+        if (
+          match !== null &&
+          (ignoreEntityBoundary ||
+            !isSelectionOnEntityBoundary(editor, match.leadOffset))
+        ) {
+          const isRangePositioned = tryToPositionRange(
+            match.leadOffset,
+            range,
+            editorWindow,
+          );
+          if (isRangePositioned !== null) {
+            startTransition(() =>
+              openTypeahead({
+                getRect: () => range.getBoundingClientRect(),
+                match,
+              }),
+            );
+            return;
+          }
+        }
+        closeTypeahead();
+      });
+    };
+
+    const removeUpdateListener = editor.registerUpdateListener(updateListener);
+
+    return () => {
+      removeUpdateListener();
+    };
+  }, [
+    editor,
+    triggerFn,
+    onQueryChange,
+    resolution,
+    closeTypeahead,
+    openTypeahead,
+    ignoreEntityBoundary,
+  ]);
+
+  useEffect(
+    () =>
+      editor.registerEditableListener((isEditable) => {
+        if (!isEditable) {
+          closeTypeahead();
+        }
+      }),
+    [editor, closeTypeahead],
+  );
+
+  return resolution === null ||
+    editor === null ||
+    anchorElementRef.current === null ? null : (
+    <LexicalMenu
+      close={closeTypeahead}
+      resolution={resolution}
+      editor={editor}
+      anchorElementRef={anchorElementRef}
+      options={options}
+      menuRenderFn={menuRenderFn}
+      shouldSplitNodeWithQuery={true}
+      onSelectOption={onSelectOption}
+      commandPriority={commandPriority}
+      preselectFirstItem={preselectFirstItem}
+    />
+  );
+}
+
+export {MenuOption, MenuRenderFn, MenuResolution, MenuTextMatch, TriggerFn};

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 {ContentEditable} from '@lexical/react/LexicalContentEditable';
+import {LexicalErrorBoundary} from '@lexical/react/LexicalErrorBoundary';
+import {ReactProviderExtension} from '@lexical/react/ReactProviderExtension';
+import {
+  declarePeerDependency,
+  defineExtension,
+  shallowMergeConfig,
+} from 'lexical';
+import invariant from 'shared/invariant';
+
+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 {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 {Suspense, useEffect, useState} from 'react';
+import * as React from 'react';
+import {createPortal} from 'react-dom';
+import {type Container, createRoot, type Root} from 'react-dom/client';
+import invariant from 'shared/invariant';
+
+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: infer OutputComponentType extends React.ComponentType;
+      },
+    ]
+      ? /** The Props from the Extension output Component */ React.ComponentProps<OutputComponentType> | 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',
+});