@lexical/react 0.44.1-nightly.20260519.0 → 0.45.1-dev.0

package/src/shared/useCharacterLimit.ts

@@ -0,0 +1,314 @@
+/**
+ * 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, LexicalNode} from 'lexical';
+
+import invariant from '@lexical/internal/invariant';
+import {
+  $createOverflowNode,
+  $isOverflowNode,
+  OverflowNode,
+} from '@lexical/overflow';
+import {$rootTextContent} from '@lexical/text';
+import {
+  $dfs,
+  $findMatchingParent,
+  $unwrapNode,
+  mergeRegister,
+} from '@lexical/utils';
+import {
+  $getSelection,
+  $isElementNode,
+  $isLeafNode,
+  $isRangeSelection,
+  $isTextNode,
+  $setSelection,
+  COMMAND_PRIORITY_LOW,
+  DELETE_CHARACTER_COMMAND,
+  HISTORY_MERGE_TAG,
+} from 'lexical';
+import {useEffect} from 'react';
+
+type OptionalProps = {
+  remainingCharacters?: (characters: number) => void;
+  strlen?: (input: string) => number;
+};
+
+export function useCharacterLimit(
+  editor: LexicalEditor,
+  maxCharacters: number,
+  optional: OptionalProps = Object.freeze({}),
+): void {
+  const {
+    strlen = input => input.length,
+    // UTF-16
+    remainingCharacters = () => {
+      return;
+    },
+  } = optional;
+
+  useEffect(() => {
+    if (!editor.hasNodes([OverflowNode])) {
+      invariant(
+        false,
+        'useCharacterLimit: OverflowNode not registered on editor',
+      );
+    }
+  }, [editor]);
+
+  useEffect(() => {
+    let text = editor.getEditorState().read($rootTextContent, {editor});
+    let lastComputedTextLength = 0;
+
+    return mergeRegister(
+      editor.registerTextContentListener((currentText: string) => {
+        text = currentText;
+      }),
+      editor.registerUpdateListener(({dirtyLeaves, dirtyElements}) => {
+        const isComposing = editor.isComposing();
+        const hasContentChanges =
+          dirtyLeaves.size > 0 || dirtyElements.size > 0;
+
+        if (isComposing || !hasContentChanges) {
+          return;
+        }
+
+        const textLength = strlen(text);
+        const textLengthAboveThreshold =
+          textLength > maxCharacters ||
+          (lastComputedTextLength !== null &&
+            lastComputedTextLength > maxCharacters);
+        const diff = maxCharacters - textLength;
+
+        remainingCharacters(diff);
+
+        if (lastComputedTextLength === null || textLengthAboveThreshold) {
+          const offset = findOffset(text, maxCharacters, strlen);
+          editor.update(
+            () => {
+              $wrapOverflowedNodes(offset);
+            },
+            {
+              tag: HISTORY_MERGE_TAG,
+            },
+          );
+        }
+
+        lastComputedTextLength = textLength;
+      }),
+      editor.registerCommand(
+        DELETE_CHARACTER_COMMAND,
+        isBackward => {
+          const selection = $getSelection();
+          if (!$isRangeSelection(selection)) {
+            return false;
+          }
+          const anchorNode = selection.anchor.getNode();
+          const overflow = anchorNode.getParent();
+          const overflowParent = overflow ? overflow.getParent() : null;
+          const parentNext = overflowParent
+            ? overflowParent.getNextSibling()
+            : null;
+          selection.deleteCharacter(isBackward);
+          if (overflowParent && overflowParent.isEmpty()) {
+            overflowParent.remove();
+          } else if ($isElementNode(parentNext) && parentNext.isEmpty()) {
+            parentNext.remove();
+          }
+          return true;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+    );
+  }, [editor, maxCharacters, remainingCharacters, strlen]);
+}
+
+function findOffset(
+  text: string,
+  maxCharacters: number,
+  strlen: (input: string) => number,
+): number {
+  let offsetUtf16 = 0;
+  let offset = 0;
+
+  if (typeof Intl.Segmenter === 'function') {
+    const segmenter = new Intl.Segmenter();
+    const graphemes = segmenter.segment(text);
+
+    for (const {segment: grapheme} of graphemes) {
+      const nextOffset = offset + strlen(grapheme);
+
+      if (nextOffset > maxCharacters) {
+        break;
+      }
+
+      offset = nextOffset;
+      offsetUtf16 += grapheme.length;
+    }
+  } else {
+    const codepoints = Array.from(text);
+    const codepointsLength = codepoints.length;
+
+    for (let i = 0; i < codepointsLength; i++) {
+      const codepoint = codepoints[i];
+      const nextOffset = offset + strlen(codepoint);
+
+      if (nextOffset > maxCharacters) {
+        break;
+      }
+
+      offset = nextOffset;
+      offsetUtf16 += codepoint.length;
+    }
+  }
+
+  return offsetUtf16;
+}
+
+function $wrapOverflowedNodes(offset: number): void {
+  const dfsNodes = $dfs();
+  const dfsNodesLength = dfsNodes.length;
+  let accumulatedLength = 0;
+
+  for (let i = 0; i < dfsNodesLength; i += 1) {
+    const {node} = dfsNodes[i];
+
+    const needsOverflowParent =
+      $isLeafNode(node) && !$findMatchingParent(node, $isOverflowNode);
+
+    if ($isOverflowNode(node)) {
+      const previousLength = accumulatedLength;
+      const nextLength = accumulatedLength + node.getTextContentSize();
+
+      if (nextLength <= offset) {
+        const parent = node.getParent();
+        const previousSibling = node.getPreviousSibling();
+        const nextSibling = node.getNextSibling();
+        $unwrapNode(node);
+        const selection = $getSelection();
+
+        // Restore selection when the overflow children are removed
+        if (
+          $isRangeSelection(selection) &&
+          (!selection.anchor.getNode().isAttached() ||
+            !selection.focus.getNode().isAttached())
+        ) {
+          if ($isTextNode(previousSibling)) {
+            previousSibling.select();
+          } else if ($isTextNode(nextSibling)) {
+            nextSibling.select();
+          } else if (parent !== null) {
+            parent.select();
+          }
+        }
+      } else if (previousLength < offset) {
+        const descendant = node.getFirstDescendant();
+        const descendantLength =
+          descendant !== null ? descendant.getTextContentSize() : 0;
+        const previousPlusDescendantLength = previousLength + descendantLength;
+        // For simple text we can redimension the overflow into a smaller and more accurate
+        // container
+        const firstDescendantIsSimpleText =
+          $isTextNode(descendant) && descendant.isSimpleText();
+        const firstDescendantDoesNotOverflow =
+          previousPlusDescendantLength <= offset;
+
+        if (firstDescendantIsSimpleText || firstDescendantDoesNotOverflow) {
+          $unwrapNode(node);
+        }
+      }
+    } else if (needsOverflowParent) {
+      const previousAccumulatedLength = accumulatedLength;
+      accumulatedLength += node.getTextContentSize();
+
+      if (accumulatedLength > offset && !$isOverflowNode(node.getParent())) {
+        const previousSelection = $getSelection();
+        let overflowNode;
+
+        // For simple text we can improve the limit accuracy by splitting the TextNode
+        // on the split point
+        if (
+          previousAccumulatedLength < offset &&
+          $isTextNode(node) &&
+          node.isSimpleText()
+        ) {
+          const [, overflowedText] = node.splitText(
+            offset - previousAccumulatedLength,
+          );
+          overflowNode = $wrapNode(overflowedText);
+        } else {
+          overflowNode = $wrapNode(node);
+        }
+
+        if (previousSelection !== null) {
+          $setSelection(previousSelection);
+        }
+
+        $mergePrevious(overflowNode);
+      }
+    }
+  }
+}
+
+function $wrapNode(node: LexicalNode): OverflowNode {
+  const overflowNode = $createOverflowNode();
+  node.replace(overflowNode);
+  overflowNode.append(node);
+  return overflowNode;
+}
+
+export function $mergePrevious(overflowNode: OverflowNode): void {
+  const previousNode = overflowNode.getPreviousSibling();
+
+  if (!$isOverflowNode(previousNode)) {
+    return;
+  }
+
+  const firstChild = overflowNode.getFirstChild();
+  const previousNodeChildren = previousNode.getChildren();
+  const previousNodeChildrenLength = previousNodeChildren.length;
+
+  if (firstChild === null) {
+    overflowNode.append(...previousNodeChildren);
+  } else {
+    for (let i = 0; i < previousNodeChildrenLength; i++) {
+      firstChild.insertBefore(previousNodeChildren[i]);
+    }
+  }
+
+  const selection = $getSelection();
+
+  if ($isRangeSelection(selection)) {
+    const anchor = selection.anchor;
+    const anchorNode = anchor.getNode();
+    const focus = selection.focus;
+    const focusNode = anchor.getNode();
+
+    if (anchorNode.is(previousNode)) {
+      anchor.set(overflowNode.getKey(), anchor.offset, 'element');
+    } else if (anchorNode.is(overflowNode)) {
+      anchor.set(
+        overflowNode.getKey(),
+        previousNodeChildrenLength + anchor.offset,
+        'element',
+      );
+    }
+
+    if (focusNode.is(previousNode)) {
+      focus.set(overflowNode.getKey(), focus.offset, 'element');
+    } else if (focusNode.is(overflowNode)) {
+      focus.set(
+        overflowNode.getKey(),
+        previousNodeChildrenLength + focus.offset,
+        'element',
+      );
+    }
+  }
+
+  previousNode.remove();
+}

package/src/shared/useDecorators.tsx

@@ -0,0 +1,73 @@
+/**
+ * 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, NodeKey} from 'lexical';
+import type {JSX} from 'react';
+
+import * as React from 'react';
+import {Suspense, useEffect, useMemo, useState} from 'react';
+import {createPortal, flushSync} from 'react-dom';
+
+import useLayoutEffect from './useLayoutEffect';
+
+type ErrorBoundaryProps = {
+  children: JSX.Element;
+  onError: (error: Error) => void;
+};
+
+export type ErrorBoundaryType =
+  | React.ComponentClass<ErrorBoundaryProps>
+  | React.FC<ErrorBoundaryProps>;
+
+export function useDecorators(
+  editor: LexicalEditor,
+  ErrorBoundary: ErrorBoundaryType,
+): Array<JSX.Element> {
+  const [decorators, setDecorators] = useState<Record<NodeKey, JSX.Element>>(
+    () => editor.getDecorators<JSX.Element>(),
+  );
+
+  // Subscribe to changes
+  useLayoutEffect(() => {
+    return editor.registerDecoratorListener<JSX.Element>(nextDecorators => {
+      flushSync(() => {
+        setDecorators(nextDecorators);
+      });
+    });
+  }, [editor]);
+
+  useEffect(() => {
+    // If the content editable mounts before the subscription is added, then
+    // nothing will be rendered on initial pass. We can get around that by
+    // ensuring that we set the value.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setDecorators(editor.getDecorators());
+  }, [editor]);
+
+  // Return decorators defined as React Portals
+  return useMemo(() => {
+    const decoratedPortals = [];
+    const decoratorKeys = Object.keys(decorators);
+
+    for (let i = 0; i < decoratorKeys.length; i++) {
+      const nodeKey = decoratorKeys[i];
+      const reactDecorator = (
+        <ErrorBoundary onError={e => editor._onError(e)}>
+          <Suspense fallback={null}>{decorators[nodeKey]}</Suspense>
+        </ErrorBoundary>
+      );
+      const element = editor.getElementByKey(nodeKey);
+
+      if (element !== null) {
+        decoratedPortals.push(createPortal(reactDecorator, element, nodeKey));
+      }
+    }
+
+    return decoratedPortals;
+  }, [ErrorBoundary, decorators, editor]);
+}

package/src/shared/useHistory.ts

@@ -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 type {HistoryState} from '@lexical/history';
+import type {LexicalEditor} from 'lexical';
+
+import {createEmptyHistoryState, registerHistory} from '@lexical/history';
+import {useEffect, useMemo} from 'react';
+
+export function useHistory(
+  editor: LexicalEditor,
+  externalHistoryState?: HistoryState,
+  delay = 1000,
+): void {
+  const historyState: HistoryState = useMemo(
+    () => externalHistoryState || createEmptyHistoryState(),
+    [externalHistoryState],
+  );
+
+  useEffect(() => {
+    return registerHistory(editor, historyState, delay);
+  }, [delay, editor, historyState]);
+}

package/src/shared/useLayoutEffect.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 {CAN_USE_DOM} from 'lexical';
+import {useEffect, useLayoutEffect} from 'react';
+
+// This workaround is no longer necessary in React 19,
+// but we currently support React >=17.x
+// https://github.com/facebook/react/pull/26395
+const useLayoutEffectImpl: typeof useLayoutEffect = CAN_USE_DOM
+  ? useLayoutEffect
+  : useEffect;
+
+export default useLayoutEffectImpl;

package/src/shared/useList.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 {registerList} from '@lexical/list';
+import {useEffect} from 'react';
+
+export function useList(editor: LexicalEditor): void {
+  useEffect(() => {
+    return registerList(editor);
+  }, [editor]);
+}

package/src/shared/usePlainTextSetup.ts

@@ -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 type {LexicalEditor} from 'lexical';
+
+import {registerDragonSupport} from '@lexical/dragon';
+import {registerPlainText} from '@lexical/plain-text';
+import {mergeRegister} from '@lexical/utils';
+
+import useLayoutEffect from './useLayoutEffect';
+
+export function usePlainTextSetup(editor: LexicalEditor): void {
+  useLayoutEffect(() => {
+    return mergeRegister(
+      registerPlainText(editor),
+      registerDragonSupport(editor),
+    );
+  }, [editor]);
+}

package/src/shared/useReactDecorators.tsx

@@ -0,0 +1,53 @@
+/**
+ * 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 {JSX} from 'react';
+
+import {Suspense, useMemo, useSyncExternalStore} from 'react';
+import {createPortal} from 'react-dom';
+
+import {type ErrorBoundaryType} from './types';
+
+/** @internal */
+export function useReactDecorators(
+  editor: LexicalEditor,
+  ErrorBoundary: ErrorBoundaryType,
+): JSX.Element[] {
+  const [subscribe, getSnapshot] = useMemo(
+    () =>
+      [
+        (cb: () => void) => editor.registerDecoratorListener(cb),
+        () => editor.getDecorators<JSX.Element>(),
+      ] as const,
+    [editor],
+  );
+  const decorators = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  // Return decorators defined as React Portals
+  return useMemo(() => {
+    const decoratedPortals = [];
+    for (const nodeKey in decorators) {
+      const element = editor.getElementByKey(nodeKey);
+
+      if (element !== null) {
+        const reactDecorator = (
+          <ErrorBoundary
+            onError={e => {
+              editor._onError(e);
+            }}>
+            <Suspense fallback={null}>{decorators[nodeKey]}</Suspense>
+          </ErrorBoundary>
+        );
+        decoratedPortals.push(createPortal(reactDecorator, element, nodeKey));
+      }
+    }
+
+    return decoratedPortals;
+  }, [ErrorBoundary, decorators, editor]);
+}

package/src/shared/useRichTextSetup.ts

@@ -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 type {LexicalEditor} from 'lexical';
+
+import {registerDragonSupport} from '@lexical/dragon';
+import {registerRichText} from '@lexical/rich-text';
+import {mergeRegister} from '@lexical/utils';
+
+import useLayoutEffect from './useLayoutEffect';
+
+export function useRichTextSetup(editor: LexicalEditor): void {
+  useLayoutEffect(() => {
+    return mergeRegister(
+      registerRichText(editor),
+      registerDragonSupport(editor),
+    );
+  }, [editor]);
+}