zurfyx-lexical-react 0.39.1-nightly.20251225.0

package/src/__tests__/unit/useLexicalIsTextContentEmpty.test.tsx

@@ -0,0 +1,96 @@
+/**
+ * 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 {useLexicalIsTextContentEmpty} from '@lexical/react/useLexicalIsTextContentEmpty';
+import {
+  $createParagraphNode,
+  $createTextNode,
+  $getRoot,
+  createEditor,
+  LexicalEditor,
+  ParagraphNode,
+} from 'lexical';
+import * as React from 'react';
+import {createRef} from 'react';
+import {createRoot, Root} from 'react-dom/client';
+import * as ReactTestUtils from 'shared/react-test-utils';
+import {afterEach, beforeEach, describe, expect, test, vi} from 'vitest';
+
+describe('useLexicalIsTextContentEmpty', () => {
+  let container: HTMLDivElement | null = null;
+  let reactRoot: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    reactRoot = createRoot(container);
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.removeChild(container!);
+    container = null;
+
+    vi.restoreAllMocks();
+  });
+
+  function useLexicalEditor(
+    rootElementRef: React.RefObject<null | HTMLDivElement>,
+  ) {
+    const editor = React.useMemo(
+      () =>
+        createEditor({
+          namespace: '',
+          nodes: [ParagraphNode],
+          onError: (err) => {
+            throw err;
+          },
+        }),
+      [],
+    );
+
+    React.useEffect(() => {
+      const rootElement = rootElementRef.current;
+      editor.setRootElement(rootElement);
+    }, [rootElementRef, editor]);
+
+    return editor;
+  }
+
+  test('hook works', async () => {
+    const ref = createRef<null | HTMLDivElement>();
+    let editor: LexicalEditor;
+    let hasText = false;
+
+    function TestBase() {
+      editor = useLexicalEditor(ref);
+      const isBlank = useLexicalIsTextContentEmpty(editor);
+
+      expect(isBlank).toBe(!hasText);
+
+      return <div ref={ref} contentEditable={true} />;
+    }
+
+    ReactTestUtils.act(() => {
+      reactRoot.render(<TestBase />);
+    });
+
+    await ReactTestUtils.act(async () => {
+      await editor.update(() => {
+        const root = $getRoot();
+
+        const paragraph = $createParagraphNode();
+        const text = $createTextNode('foo');
+
+        root.append(paragraph);
+        paragraph.append(text);
+
+        hasText = true;
+      });
+    });
+  });
+});

package/src/__tests__/unit/useMenuAnchorRef.test.tsx

@@ -0,0 +1,65 @@
+/**
+ * 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 {createTestEditor} from 'lexical/src/__tests__/utils';
+import * as React from 'react';
+import {createRoot, Root} from 'react-dom/client';
+import * as ReactTestUtils from 'shared/react-test-utils';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {useMenuAnchorRef} from '../../shared/LexicalMenu';
+
+describe('useMenuAnchorRef', () => {
+  let container: HTMLDivElement | null = null;
+  let reactRoot: Root;
+
+  beforeEach(() => {
+    vi.mock('@lexical/react/LexicalComposerContext', () => ({
+      useLexicalComposerContext: () => [createTestEditor()],
+    }));
+
+    vi.mock('shared/canUseDOM', () => ({
+      CAN_USE_DOM: false,
+    }));
+
+    container = document.createElement('div');
+    reactRoot = createRoot(container);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should return null if CAN_USE_DOM is false', async () => {
+    let anchorElementRef;
+
+    function App() {
+      const resolution = null;
+      const setResolution = vi.fn();
+      const anchorClassName = 'some-class';
+      const parent = undefined;
+      const shouldIncludePageYOffset__EXPERIMENTAL = true;
+
+      anchorElementRef = useMenuAnchorRef(
+        resolution,
+        setResolution,
+        anchorClassName,
+        parent,
+        shouldIncludePageYOffset__EXPERIMENTAL,
+      );
+
+      return null;
+    }
+
+    await ReactTestUtils.act(async () => {
+      reactRoot.render(<App />);
+    });
+
+    expect(anchorElementRef!.current).toBeNull();
+  });
+});

package/src/__tests__/unit/utils.tsx

@@ -0,0 +1,356 @@
+/**
+ * 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 {
+  LexicalCollaboration,
+  useCollaborationContext,
+} from '@lexical/react/LexicalCollaborationContext';
+import {
+  CollaborationPlugin,
+  CollaborationPluginV2__EXPERIMENTAL,
+} from '@lexical/react/LexicalCollaborationPlugin';
+import {LexicalComposer} from '@lexical/react/LexicalComposer';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {ContentEditable} from '@lexical/react/LexicalContentEditable';
+import {LexicalErrorBoundary} from '@lexical/react/LexicalErrorBoundary';
+import {RichTextPlugin} from '@lexical/react/LexicalRichTextPlugin';
+import {Provider, UserState} from '@lexical/yjs';
+import {LexicalEditor} from 'lexical';
+import * as React from 'react';
+import {type Container, createRoot, type Root} from 'react-dom/client';
+import * as ReactTestUtils from 'shared/react-test-utils';
+import {expect} from 'vitest';
+import * as Y from 'yjs';
+
+function Editor({
+  doc,
+  provider,
+  setEditor,
+  awarenessData,
+  shouldBootstrapEditor = true,
+  useCollabV2 = false,
+}: {
+  doc: Y.Doc;
+  provider: Provider;
+  setEditor: (editor: LexicalEditor) => void;
+  awarenessData?: object | undefined;
+  shouldBootstrapEditor?: boolean;
+  useCollabV2?: boolean;
+}) {
+  const context = useCollaborationContext();
+
+  const [editor] = useLexicalComposerContext();
+
+  const {yjsDocMap} = context;
+  context.isCollabActive = true;
+  yjsDocMap.set('main', doc);
+
+  setEditor(editor);
+
+  return (
+    <>
+      {useCollabV2 ? (
+        <CollaborationPluginV2__EXPERIMENTAL
+          id="main"
+          doc={doc}
+          provider={provider}
+          awarenessData={awarenessData}
+          __shouldBootstrapUnsafe={shouldBootstrapEditor}
+        />
+      ) : (
+        <CollaborationPlugin
+          id="main"
+          providerFactory={() => provider}
+          shouldBootstrap={shouldBootstrapEditor}
+          awarenessData={awarenessData}
+        />
+      )}
+      <RichTextPlugin
+        contentEditable={<ContentEditable />}
+        placeholder={<></>}
+        ErrorBoundary={LexicalErrorBoundary}
+      />
+    </>
+  );
+}
+
+export class Client implements Provider {
+  _id: string;
+  _reactRoot: Root | null = null;
+  _container: HTMLDivElement | null = null;
+  _editor: LexicalEditor | null = null;
+  _connection: {
+    _clients: Map<string, Client>;
+    _useCollabV2: boolean;
+  };
+  _connected: boolean = false;
+  _doc: Y.Doc = new Y.Doc({gc: false});
+
+  _listeners = new Map<string, Set<(data: unknown) => void>>();
+  _updates: Uint8Array[] = [];
+  _awarenessState: UserState | null = null;
+  awareness: {
+    getLocalState: () => UserState | null;
+    getStates: () => Map<number, UserState>;
+    off(): void;
+    on(): void;
+    setLocalState: (state: UserState) => void;
+    setLocalStateField: (field: string, value: unknown) => void;
+  };
+
+  constructor(id: Client['_id'], connection: Client['_connection']) {
+    this._id = id;
+    this._connection = connection;
+    this._onUpdate = this._onUpdate.bind(this);
+
+    this._doc.on('update', this._onUpdate);
+
+    this.awareness = {
+      getLocalState: () => this._awarenessState,
+      getStates: () => new Map([[0, this._awarenessState!]]),
+      off: () => {
+        // TODO
+      },
+
+      on: () => {
+        // TODO
+      },
+
+      setLocalState: (state) => {
+        this._awarenessState = state;
+      },
+      setLocalStateField: (field: string, value: unknown) => {
+        // TODO
+      },
+    };
+  }
+
+  _onUpdate(update: Uint8Array, origin: unknown, transaction: unknown) {
+    if (origin !== this._connection && this._connected) {
+      this._broadcastUpdate(update);
+    }
+  }
+
+  _broadcastUpdate(update: Uint8Array) {
+    this._connection._clients.forEach((client) => {
+      if (client !== this) {
+        if (client._connected) {
+          Y.applyUpdate(client._doc, update, this._connection);
+        } else {
+          client._updates.push(update);
+        }
+      }
+    });
+  }
+
+  connect() {
+    if (!this._connected) {
+      this._connected = true;
+      const update = Y.encodeStateAsUpdate(this._doc);
+
+      if (this._updates.length > 0) {
+        Y.applyUpdate(
+          this._doc,
+          Y.mergeUpdates(this._updates),
+          this._connection,
+        );
+        this._updates = [];
+      }
+
+      this._broadcastUpdate(update);
+
+      this._dispatch('sync', true);
+    }
+  }
+
+  disconnect() {
+    this._connected = false;
+  }
+
+  /**
+   * @param options
+   *  - shouldBootstrapEditor: Whether to initialize the editor with an empty paragraph
+   */
+  start(
+    rootContainer: Container,
+    awarenessData?: object,
+    options: {shouldBootstrapEditor?: boolean} = {},
+  ) {
+    const container = document.createElement('div');
+    const reactRoot = createRoot(container);
+    this._container = container;
+    this._reactRoot = reactRoot;
+
+    rootContainer.appendChild(container);
+
+    ReactTestUtils.act(() => {
+      reactRoot.render(
+        <LexicalCollaboration>
+          <LexicalComposer
+            initialConfig={{
+              editorState: null,
+              namespace: '',
+              onError: (e) => {
+                throw e;
+              },
+            }}>
+            <Editor
+              provider={this}
+              doc={this._doc}
+              setEditor={(editor) => (this._editor = editor)}
+              awarenessData={awarenessData}
+              shouldBootstrapEditor={options.shouldBootstrapEditor}
+              useCollabV2={this._connection._useCollabV2}
+            />
+          </LexicalComposer>
+        </LexicalCollaboration>,
+      );
+    });
+  }
+
+  stop() {
+    ReactTestUtils.act(() => {
+      this._reactRoot!.render(null);
+    });
+
+    this.getContainer().parentNode!.removeChild(this.getContainer());
+
+    this._container = null;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  on(type: string, callback: (arg: any) => void) {
+    let listenerSet = this._listeners.get(type);
+
+    if (listenerSet === undefined) {
+      listenerSet = new Set();
+
+      this._listeners.set(type, listenerSet);
+    }
+
+    listenerSet.add(callback);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  off(type: string, callback: (arg: any) => void) {
+    const listenerSet = this._listeners.get(type);
+
+    if (listenerSet !== undefined) {
+      listenerSet.delete(callback);
+    }
+  }
+
+  _dispatch(type: string, data: unknown) {
+    const listenerSet = this._listeners.get(type);
+
+    if (listenerSet !== undefined) {
+      listenerSet.forEach((callback) => callback(data));
+    }
+  }
+
+  getHTML() {
+    return (this.getContainer().firstChild as HTMLElement).innerHTML;
+  }
+
+  getDoc() {
+    return this._doc;
+  }
+
+  getDocJSON() {
+    return this._doc.toJSON();
+  }
+
+  getEditorState() {
+    return this.getEditor().getEditorState();
+  }
+
+  getEditor() {
+    return this._editor!;
+  }
+
+  getContainer() {
+    return this._container!;
+  }
+
+  async focus() {
+    this.getContainer().focus();
+
+    await Promise.resolve().then();
+  }
+
+  update(cb: () => void) {
+    this.getEditor().update(cb);
+  }
+}
+
+export class TestConnection {
+  _clients = new Map<string, Client>();
+
+  constructor(readonly _useCollabV2: boolean) {}
+
+  createClient(id: string) {
+    const client = new Client(id, this);
+
+    this._clients.set(id, client);
+
+    return client;
+  }
+}
+
+export function createTestConnection(useCollabV2: boolean) {
+  return new TestConnection(useCollabV2);
+}
+
+export async function waitForReact(cb: () => void) {
+  await ReactTestUtils.act(async () => {
+    cb();
+    await Promise.resolve().then();
+  });
+}
+
+export function createAndStartClients(
+  connector: TestConnection,
+  aContainer: HTMLDivElement,
+  count: number,
+): Array<Client> {
+  const result = [];
+
+  for (let i = 0; i < count; ++i) {
+    const id = `${i}`;
+    const client = connector.createClient(id);
+    client.start(aContainer);
+    result.push(client);
+  }
+
+  return result;
+}
+
+export function disconnectClients(clients: Array<Client>) {
+  for (let i = 0; i < clients.length; ++i) {
+    clients[i].disconnect();
+  }
+}
+
+export function connectClients(clients: Array<Client>) {
+  for (let i = 0; i < clients.length; ++i) {
+    clients[i].connect();
+  }
+}
+
+export function stopClients(clients: Array<Client>) {
+  for (let i = 0; i < clients.length; ++i) {
+    clients[i].stop();
+  }
+}
+
+export function testClientsForEquality(clients: Array<Client>) {
+  for (let i = 1; i < clients.length; ++i) {
+    expect(clients[0].getHTML()).toEqual(clients[i].getHTML());
+    expect(clients[0].getDocJSON()).toEqual(clients[i].getDocJSON());
+  }
+}

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 {ReactProviderExtension} from '@lexical/react/ReactProviderExtension';
+import {type LexicalEditor} from 'lexical';
+import invariant from 'shared/invariant';
+
+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 useLayoutEffect from 'shared/useLayoutEffect';
+
+import {mergeRefs} from './mergeRefs';
+
+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);