@lexical/react 0.44.1-nightly.20260518.0 → 0.45.0

package/src/shared/buildEditorComponent.tsx

@@ -0,0 +1,60 @@
+/**
+ * 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 {
+  LexicalComposerContext,
+  type LexicalComposerContextWithEditor,
+} from '@lexical/react/LexicalComposerContext';
+import {Suspense, useMemo} from 'react';
+
+import {type EditorComponentProps, type ReactConfig} from './types';
+import {useReactDecorators} from './useReactDecorators';
+
+/** @internal */
+export function buildEditorComponent(
+  config: ReactConfig,
+  context: LexicalComposerContextWithEditor,
+) {
+  const [editor] = context;
+  const rawConfigDecorators = config.decorators.map(El =>
+    // eslint-disable-next-line react/jsx-key -- wrapped later
+    typeof El === 'function' ? <El context={context} /> : El,
+  );
+  return function EditorComponent(props: Partial<EditorComponentProps>) {
+    const {
+      EditorChildrenComponent = config.EditorChildrenComponent,
+      ErrorBoundary = config.ErrorBoundary,
+      contentEditable = config.contentEditable,
+      children,
+    } = props;
+    const decorators = useReactDecorators(editor, ErrorBoundary);
+    const configDecorators = useMemo(
+      () =>
+        rawConfigDecorators.map((decorator, i) => (
+          <ErrorBoundary
+            onError={e => {
+              editor._onError(e);
+            }}
+            key={i}>
+            <Suspense fallback={null}>{decorator}</Suspense>
+          </ErrorBoundary>
+        )),
+      [ErrorBoundary],
+    );
+    return (
+      <LexicalComposerContext.Provider value={context}>
+        <EditorChildrenComponent
+          context={context}
+          contentEditable={contentEditable}>
+          {children}
+          {configDecorators}
+          {decorators}
+        </EditorChildrenComponent>
+      </LexicalComposerContext.Provider>
+    );
+  };
+}

package/src/shared/mergeRefs.ts

@@ -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 type {Ref} from 'react';
+
+export function mergeRefs<T>(...refs: Ref<T>[]): (value: null | T) => void {
+  return value => {
+    for (const ref of refs) {
+      if (typeof ref === 'function') {
+        ref(value);
+      } else if (ref != null) {
+        ref.current = value;
+      }
+    }
+  };
+}

package/src/shared/point.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ *
+ */
+export class Point {
+  private readonly _x: number;
+  private readonly _y: number;
+
+  constructor(x: number, y: number) {
+    this._x = x;
+    this._y = y;
+  }
+
+  get x(): number {
+    return this._x;
+  }
+
+  get y(): number {
+    return this._y;
+  }
+
+  public equals({x, y}: Point): boolean {
+    return this.x === x && this.y === y;
+  }
+
+  public calcDeltaXTo({x}: Point): number {
+    return this.x - x;
+  }
+
+  public calcDeltaYTo({y}: Point): number {
+    return this.y - y;
+  }
+
+  public calcHorizontalDistanceTo(point: Point): number {
+    return Math.abs(this.calcDeltaXTo(point));
+  }
+
+  public calcVerticalDistance(point: Point): number {
+    return Math.abs(this.calcDeltaYTo(point));
+  }
+
+  public calcDistanceTo(point: Point): number {
+    return Math.sqrt(
+      Math.pow(this.calcDeltaXTo(point), 2) +
+        Math.pow(this.calcDeltaYTo(point), 2),
+    );
+  }
+}
+
+export function isPoint(x: unknown): x is Point {
+  return x instanceof Point;
+}

package/src/shared/reactPatches.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 React from 'react';
+
+// Webpack + React 17 fails to compile on the usage of `React.startTransition` or
+// `React["startTransition"]` even if it's behind a feature detection of
+// `"startTransition" in React`. Moving this to a constant avoids the issue :/
+const START_TRANSITION = 'startTransition';
+
+export function startTransition(callback: () => void) {
+  if (START_TRANSITION in React) {
+    React[START_TRANSITION](callback);
+  } else {
+    callback();
+  }
+}

package/src/shared/rect.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 {isPoint, Point} from './point';
+
+type ContainsPointReturn = {
+  result: boolean;
+  reason: {
+    isOnTopSide: boolean;
+    isOnBottomSide: boolean;
+    isOnLeftSide: boolean;
+    isOnRightSide: boolean;
+  };
+};
+
+export class Rectangle {
+  private readonly _left: number;
+  private readonly _top: number;
+  private readonly _right: number;
+  private readonly _bottom: number;
+
+  constructor(left: number, top: number, right: number, bottom: number) {
+    const [physicTop, physicBottom] =
+      top <= bottom ? [top, bottom] : [bottom, top];
+
+    const [physicLeft, physicRight] =
+      left <= right ? [left, right] : [right, left];
+
+    this._top = physicTop;
+    this._right = physicRight;
+    this._left = physicLeft;
+    this._bottom = physicBottom;
+  }
+
+  get top(): number {
+    return this._top;
+  }
+
+  get right(): number {
+    return this._right;
+  }
+
+  get bottom(): number {
+    return this._bottom;
+  }
+
+  get left(): number {
+    return this._left;
+  }
+
+  get width(): number {
+    return Math.abs(this._left - this._right);
+  }
+
+  get height(): number {
+    return Math.abs(this._bottom - this._top);
+  }
+
+  public equals({top, left, bottom, right}: Rectangle): boolean {
+    return (
+      top === this._top &&
+      bottom === this._bottom &&
+      left === this._left &&
+      right === this._right
+    );
+  }
+
+  public contains({x, y}: Point): ContainsPointReturn;
+  public contains({top, left, bottom, right}: Rectangle): boolean;
+  public contains(target: Point | Rectangle): boolean | ContainsPointReturn {
+    if (isPoint(target)) {
+      const {x, y} = target;
+
+      const isOnTopSide = y < this._top;
+      const isOnBottomSide = y > this._bottom;
+      const isOnLeftSide = x < this._left;
+      const isOnRightSide = x > this._right;
+
+      const result =
+        !isOnTopSide && !isOnBottomSide && !isOnLeftSide && !isOnRightSide;
+
+      return {
+        reason: {
+          isOnBottomSide,
+          isOnLeftSide,
+          isOnRightSide,
+          isOnTopSide,
+        },
+        result,
+      };
+    } else {
+      const {top, left, bottom, right} = target;
+
+      return (
+        top >= this._top &&
+        top <= this._bottom &&
+        bottom >= this._top &&
+        bottom <= this._bottom &&
+        left >= this._left &&
+        left <= this._right &&
+        right >= this._left &&
+        right <= this._right
+      );
+    }
+  }
+
+  public intersectsWith(rect: Rectangle): boolean {
+    const {left: x1, top: y1, width: w1, height: h1} = rect;
+    const {left: x2, top: y2, width: w2, height: h2} = this;
+    const maxX = x1 + w1 >= x2 + w2 ? x1 + w1 : x2 + w2;
+    const maxY = y1 + h1 >= y2 + h2 ? y1 + h1 : y2 + h2;
+    const minX = x1 <= x2 ? x1 : x2;
+    const minY = y1 <= y2 ? y1 : y2;
+    return maxX - minX <= w1 + w2 && maxY - minY <= h1 + h2;
+  }
+
+  public generateNewRect({
+    left = this.left,
+    top = this.top,
+    right = this.right,
+    bottom = this.bottom,
+  }): Rectangle {
+    return new Rectangle(left, top, right, bottom);
+  }
+
+  static fromLTRB(
+    left: number,
+    top: number,
+    right: number,
+    bottom: number,
+  ): Rectangle {
+    return new Rectangle(left, top, right, bottom);
+  }
+
+  static fromLWTH(
+    left: number,
+    width: number,
+    top: number,
+    height: number,
+  ): Rectangle {
+    return new Rectangle(left, top, left + width, top + height);
+  }
+
+  static fromPoints(startPoint: Point, endPoint: Point): Rectangle {
+    const {y: top, x: left} = startPoint;
+    const {y: bottom, x: right} = endPoint;
+    return Rectangle.fromLTRB(left, top, right, bottom);
+  }
+
+  static fromDOM(dom: HTMLElement): Rectangle {
+    const {top, width, left, height} = dom.getBoundingClientRect();
+    return Rectangle.fromLWTH(left, width, top, height);
+  }
+}

package/src/shared/types.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 {LexicalComposerContextWithEditor} from '@lexical/react/LexicalComposerContext';
+import type {JSX} from 'react';
+
+export interface EditorChildrenComponentProps {
+  context: LexicalComposerContextWithEditor;
+  contentEditable: null | JSX.Element;
+  children?: React.ReactNode;
+}
+
+export type EditorChildrenComponentType = (
+  props: EditorChildrenComponentProps,
+) => JSX.Element | null;
+
+export interface DecoratorComponentProps {
+  context: LexicalComposerContextWithEditor;
+}
+export type DecoratorComponentType =
+  | JSX.Element
+  | ((props: DecoratorComponentProps) => JSX.Element | null);
+
+export interface EditorComponentProps {
+  /**
+   * The EditorChildrenComponent from the config
+   */
+  EditorChildrenComponent: EditorChildrenComponentType;
+  /**
+   * The children to pass to EditorChildrenComponent
+   */
+  children?: React.ReactNode;
+  /**
+   * contentEditable from the config
+   */
+  contentEditable: JSX.Element | null;
+  /**
+   * ErrorBoundary from the config
+   */
+  ErrorBoundary: ErrorBoundaryType;
+}
+
+export type EditorComponentType = (
+  /** Optional overrides to any of the props, typically only children is used */
+  props: Partial<EditorComponentProps>,
+) => JSX.Element;
+
+export interface ReactConfig {
+  /**
+   * The default root element of the editor as JSX. Uses `<ContentEditable />`
+   * from \@lexical/react/ContentEditable by default,
+   * but may be null or another component.
+   *
+   * This component is responsible for calling `editor.setRootElement(elem)`.
+   */
+  contentEditable: JSX.Element | null;
+  /**
+   * The ErrorBoundary used for rendering decorators in the editor. By default
+   * it is `ErrorBoundary` from \@lexical/react/ErrorBoundary.
+   */
+  ErrorBoundary: ErrorBoundaryType;
+  /**
+   * The component that renders the children of the editor context, by default
+   * it is {@link DefaultEditorChildrenComponent} which takes the given props
+   * and renders them in this order:
+   *
+   * - contentEditable
+   * - children
+   */
+  EditorChildrenComponent: EditorChildrenComponentType;
+
+  /**
+   * An array of JSX or components that return JSX that should be rendered
+   * as children of Component. These will be merged by array concatenation.
+   */
+  decorators: readonly DecoratorComponentType[];
+}
+
+export interface ReactOutputs {
+  /**
+   * The editor component, this can be used by Extensions that depend on this to
+   * render the editor such as {@link ReactPluginHostExtension} or internally by
+   * {@link LexicalExtensionComposer}.
+   *
+   * All props have defaults based on the config and editor state, but may be
+   * overridden.
+   */
+  Component: EditorComponentType;
+  /**
+   * This is equivalent to useLexicalComposerContext() from \@lexical/react/LexicalComposerContext.
+   */
+  context: LexicalComposerContextWithEditor;
+}
+
+export interface ErrorBoundaryProps {
+  children: JSX.Element;
+  onError: (error: Error) => void;
+}
+
+export type ErrorBoundaryType =
+  | React.ComponentClass<ErrorBoundaryProps>
+  | React.FC<ErrorBoundaryProps>;

package/src/shared/useCanShowPlaceholder.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 {$canShowPlaceholderCurry} from '@lexical/text';
+import {mergeRegister} from '@lexical/utils';
+import {useState} from 'react';
+
+import useLayoutEffect from './useLayoutEffect';
+
+function canShowPlaceholderFromCurrentEditorState(
+  editor: LexicalEditor,
+): boolean {
+  const currentCanShowPlaceholder = editor
+    .getEditorState()
+    .read($canShowPlaceholderCurry(editor.isComposing()));
+
+  return currentCanShowPlaceholder;
+}
+
+export function useCanShowPlaceholder(editor: LexicalEditor): boolean {
+  const [canShowPlaceholder, setCanShowPlaceholder] = useState(() =>
+    canShowPlaceholderFromCurrentEditorState(editor),
+  );
+
+  useLayoutEffect(() => {
+    function resetCanShowPlaceholder() {
+      const currentCanShowPlaceholder =
+        canShowPlaceholderFromCurrentEditorState(editor);
+      setCanShowPlaceholder(currentCanShowPlaceholder);
+    }
+    resetCanShowPlaceholder();
+    return mergeRegister(
+      editor.registerUpdateListener(() => {
+        resetCanShowPlaceholder();
+      }),
+      editor.registerEditableListener(() => {
+        resetCanShowPlaceholder();
+      }),
+    );
+  }, [editor]);
+
+  return canShowPlaceholder;
+}