zurfyx-lexical-react 0.39.1-nightly.20251225.0

package/src/LexicalCollaborationContext.tsx

@@ -0,0 +1,89 @@
+/**
+ * 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 {Doc} from 'yjs';
+
+import {createContext, useContext, useMemo} from 'react';
+import devInvariant from 'shared/devInvariant';
+
+export type CollaborationContextType = {
+  color: string;
+  isCollabActive: boolean;
+  name: string;
+  yjsDocMap: Map<string, Doc>;
+};
+
+const entries = [
+  ['Cat', 'rgb(125, 50, 0)'],
+  ['Dog', 'rgb(100, 0, 0)'],
+  ['Rabbit', 'rgb(150, 0, 0)'],
+  ['Frog', 'rgb(200, 0, 0)'],
+  ['Fox', 'rgb(200, 75, 0)'],
+  ['Hedgehog', 'rgb(0, 75, 0)'],
+  ['Pigeon', 'rgb(0, 125, 0)'],
+  ['Squirrel', 'rgb(75, 100, 0)'],
+  ['Bear', 'rgb(125, 100, 0)'],
+  ['Tiger', 'rgb(0, 0, 150)'],
+  ['Leopard', 'rgb(0, 0, 200)'],
+  ['Zebra', 'rgb(0, 0, 250)'],
+  ['Wolf', 'rgb(0, 100, 150)'],
+  ['Owl', 'rgb(0, 100, 100)'],
+  ['Gull', 'rgb(100, 0, 100)'],
+  ['Squid', 'rgb(150, 0, 150)'],
+];
+
+const randomEntry = entries[Math.floor(Math.random() * entries.length)];
+
+export const CollaborationContext =
+  createContext<CollaborationContextType | null>(null);
+
+function newContext() {
+  return {
+    color: randomEntry[1],
+    isCollabActive: false,
+    name: randomEntry[0],
+    yjsDocMap: new Map(),
+  };
+}
+
+// This is here to help the transition post-#7818, however should be removed in a future release as
+// a shared context across editors is likely to lead to bugs.
+const UNSAFE_GLOBAL_CONTEXT = newContext();
+
+export function LexicalCollaboration({children}: {children: React.ReactNode}) {
+  const collabContext = useMemo(() => newContext(), []);
+
+  return (
+    <CollaborationContext.Provider value={collabContext}>
+      {children}
+    </CollaborationContext.Provider>
+  );
+}
+
+export function useCollaborationContext(
+  username?: string,
+  color?: string,
+): CollaborationContextType {
+  let collabContext = useContext(CollaborationContext);
+  devInvariant(
+    collabContext != null,
+    'useCollaborationContext: no context provider found',
+  );
+
+  collabContext = collabContext ?? UNSAFE_GLOBAL_CONTEXT;
+
+  if (username != null) {
+    collabContext.name = username;
+  }
+
+  if (color != null) {
+    collabContext.color = color;
+  }
+
+  return collabContext;
+}

package/src/LexicalCollaborationPlugin.tsx

@@ -0,0 +1,265 @@
+/**
+ * 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 {
+  type CollaborationContextType,
+  useCollaborationContext,
+} from '@lexical/react/LexicalCollaborationContext';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {
+  Binding,
+  createBinding,
+  ExcludedProperties,
+  Provider,
+  SyncCursorPositionsFn,
+} from '@lexical/yjs';
+import {LexicalEditor} from 'lexical';
+import {useEffect, useRef, useState} from 'react';
+import {Doc} from 'yjs';
+
+import {InitialEditorStateType} from './LexicalComposer';
+import {
+  CursorsContainerRef,
+  useYjsCollaboration,
+  useYjsCollaborationV2__EXPERIMENTAL,
+  useYjsCursors,
+  useYjsFocusTracking,
+  useYjsHistory,
+  useYjsHistoryV2,
+} from './shared/useYjsCollaboration';
+
+type ProviderFactory = (id: string, yjsDocMap: Map<string, Doc>) => Provider;
+
+type CollaborationPluginProps = {
+  id: string;
+  providerFactory: ProviderFactory;
+  shouldBootstrap: boolean;
+  username?: string;
+  cursorColor?: string;
+  cursorsContainerRef?: CursorsContainerRef;
+  initialEditorState?: InitialEditorStateType;
+  excludedProperties?: ExcludedProperties;
+  // `awarenessData` parameter allows arbitrary data to be added to the awareness.
+  awarenessData?: object;
+  syncCursorPositionsFn?: SyncCursorPositionsFn;
+};
+
+export function CollaborationPlugin({
+  id,
+  providerFactory,
+  shouldBootstrap,
+  username,
+  cursorColor,
+  cursorsContainerRef,
+  initialEditorState,
+  excludedProperties,
+  awarenessData,
+  syncCursorPositionsFn,
+}: CollaborationPluginProps): JSX.Element {
+  const isBindingInitialized = useRef(false);
+  const isProviderInitialized = useRef(false);
+
+  const collabContext = useCollaborationContext(username, cursorColor);
+  const {yjsDocMap, name, color} = collabContext;
+
+  const [editor] = useLexicalComposerContext();
+
+  useCollabActive(collabContext, editor);
+
+  const [provider, setProvider] = useState<Provider>();
+  const [doc, setDoc] = useState<Doc>();
+
+  useEffect(() => {
+    if (isProviderInitialized.current) {
+      return;
+    }
+
+    isProviderInitialized.current = true;
+
+    const newProvider = providerFactory(id, yjsDocMap);
+    setProvider(newProvider);
+    setDoc(yjsDocMap.get(id));
+
+    return () => {
+      newProvider.disconnect();
+    };
+  }, [id, providerFactory, yjsDocMap]);
+
+  const [binding, setBinding] = useState<Binding>();
+
+  useEffect(() => {
+    if (!provider) {
+      return;
+    }
+
+    if (isBindingInitialized.current) {
+      return;
+    }
+
+    isBindingInitialized.current = true;
+
+    const newBinding = createBinding(
+      editor,
+      provider,
+      id,
+      doc || yjsDocMap.get(id),
+      yjsDocMap,
+      excludedProperties,
+    );
+    setBinding(newBinding);
+
+    return () => {
+      newBinding.root.destroy(newBinding);
+    };
+  }, [editor, provider, id, yjsDocMap, doc, excludedProperties]);
+
+  if (!provider || !binding) {
+    return <></>;
+  }
+
+  return (
+    <YjsCollaborationCursors
+      awarenessData={awarenessData}
+      binding={binding}
+      collabContext={collabContext}
+      color={color}
+      cursorsContainerRef={cursorsContainerRef}
+      editor={editor}
+      id={id}
+      initialEditorState={initialEditorState}
+      name={name}
+      provider={provider}
+      setDoc={setDoc}
+      shouldBootstrap={shouldBootstrap}
+      yjsDocMap={yjsDocMap}
+      syncCursorPositionsFn={syncCursorPositionsFn}
+    />
+  );
+}
+
+function YjsCollaborationCursors({
+  editor,
+  id,
+  provider,
+  yjsDocMap,
+  name,
+  color,
+  shouldBootstrap,
+  cursorsContainerRef,
+  initialEditorState,
+  awarenessData,
+  collabContext,
+  binding,
+  setDoc,
+  syncCursorPositionsFn,
+}: {
+  editor: LexicalEditor;
+  id: string;
+  provider: Provider;
+  yjsDocMap: Map<string, Doc>;
+  name: string;
+  color: string;
+  shouldBootstrap: boolean;
+  binding: Binding;
+  setDoc: React.Dispatch<React.SetStateAction<Doc | undefined>>;
+  cursorsContainerRef?: CursorsContainerRef | undefined;
+  initialEditorState?: InitialEditorStateType | undefined;
+  awarenessData?: object;
+  collabContext: CollaborationContextType;
+  syncCursorPositionsFn?: SyncCursorPositionsFn;
+}) {
+  const cursors = useYjsCollaboration(
+    editor,
+    id,
+    provider,
+    yjsDocMap,
+    name,
+    color,
+    shouldBootstrap,
+    binding,
+    setDoc,
+    cursorsContainerRef,
+    initialEditorState,
+    awarenessData,
+    syncCursorPositionsFn,
+  );
+
+  useYjsHistory(editor, binding);
+  useYjsFocusTracking(editor, provider, name, color, awarenessData);
+
+  return cursors;
+}
+
+type CollaborationPluginV2Props = {
+  id: string;
+  doc: Doc;
+  provider: Provider;
+  __shouldBootstrapUnsafe?: boolean;
+  username?: string;
+  cursorColor?: string;
+  cursorsContainerRef?: CursorsContainerRef;
+  excludedProperties?: ExcludedProperties;
+  // `awarenessData` parameter allows arbitrary data to be added to the awareness.
+  awarenessData?: object;
+};
+
+export function CollaborationPluginV2__EXPERIMENTAL({
+  id,
+  doc,
+  provider,
+  __shouldBootstrapUnsafe,
+  username,
+  cursorColor,
+  cursorsContainerRef,
+  excludedProperties,
+  awarenessData,
+}: CollaborationPluginV2Props): JSX.Element {
+  const collabContext = useCollaborationContext(username, cursorColor);
+  const {yjsDocMap, name, color} = collabContext;
+
+  const [editor] = useLexicalComposerContext();
+  useCollabActive(collabContext, editor);
+
+  const binding = useYjsCollaborationV2__EXPERIMENTAL(
+    editor,
+    id,
+    doc,
+    provider,
+    yjsDocMap,
+    name,
+    color,
+    {
+      __shouldBootstrapUnsafe,
+      awarenessData,
+      excludedProperties,
+    },
+  );
+
+  useYjsHistoryV2(editor, binding);
+  useYjsFocusTracking(editor, provider, name, color, awarenessData);
+  return useYjsCursors(binding, cursorsContainerRef);
+}
+
+const useCollabActive = (
+  collabContext: CollaborationContextType,
+  editor: LexicalEditor,
+) => {
+  useEffect(() => {
+    collabContext.isCollabActive = true;
+
+    return () => {
+      // Resetting flag only when unmount top level editor collab plugin. Nested
+      // editors (e.g. image caption) should unmount without affecting it
+      if (editor._parentEditor == null) {
+        collabContext.isCollabActive = false;
+      }
+    };
+  }, [collabContext, editor]);
+};

package/src/LexicalComposer.tsx

@@ -0,0 +1,151 @@
+/**
+ * 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 {LexicalComposerContextType} from '@lexical/react/LexicalComposerContext';
+import type {JSX} from 'react';
+
+import {
+  createLexicalComposerContext,
+  LexicalComposerContext,
+} from '@lexical/react/LexicalComposerContext';
+import {
+  $createParagraphNode,
+  $getRoot,
+  $getSelection,
+  createEditor,
+  EditorState,
+  EditorThemeClasses,
+  HISTORY_MERGE_TAG,
+  HTMLConfig,
+  Klass,
+  LexicalEditor,
+  LexicalNode,
+  LexicalNodeReplacement,
+} from 'lexical';
+import {useMemo} from 'react';
+import * as React from 'react';
+import {CAN_USE_DOM} from 'shared/canUseDOM';
+import useLayoutEffect from 'shared/useLayoutEffect';
+
+const HISTORY_MERGE_OPTIONS = {tag: HISTORY_MERGE_TAG};
+
+export type InitialEditorStateType =
+  | null
+  | string
+  | EditorState
+  | ((editor: LexicalEditor) => void);
+
+export type InitialConfigType = Readonly<{
+  namespace: string;
+  nodes?: ReadonlyArray<Klass<LexicalNode> | LexicalNodeReplacement>;
+  onError: (error: Error, editor: LexicalEditor) => void;
+  editable?: boolean;
+  theme?: EditorThemeClasses;
+  editorState?: InitialEditorStateType;
+  html?: HTMLConfig;
+}>;
+
+type Props = React.PropsWithChildren<{
+  initialConfig: InitialConfigType;
+}>;
+
+export function LexicalComposer({initialConfig, children}: Props): JSX.Element {
+  const composerContext: [LexicalEditor, LexicalComposerContextType] = useMemo(
+    () => {
+      const {
+        theme,
+        namespace,
+        nodes,
+        onError,
+        editorState: initialEditorState,
+        html,
+      } = initialConfig;
+
+      const context: LexicalComposerContextType = createLexicalComposerContext(
+        null,
+        theme,
+      );
+
+      const editor = createEditor({
+        editable: initialConfig.editable,
+        html,
+        namespace,
+        nodes,
+        onError: (error) => onError(error, editor),
+        theme,
+      });
+      initializeEditor(editor, initialEditorState);
+
+      return [editor, context];
+    },
+
+    // We only do this for init
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  useLayoutEffect(() => {
+    const isEditable = initialConfig.editable;
+    const [editor] = composerContext;
+    editor.setEditable(isEditable !== undefined ? isEditable : true);
+
+    // We only do this for init
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <LexicalComposerContext.Provider value={composerContext}>
+      {children}
+    </LexicalComposerContext.Provider>
+  );
+}
+
+function initializeEditor(
+  editor: LexicalEditor,
+  initialEditorState?: InitialEditorStateType,
+): void {
+  if (initialEditorState === null) {
+    return;
+  } else if (initialEditorState === undefined) {
+    editor.update(() => {
+      const root = $getRoot();
+      if (root.isEmpty()) {
+        const paragraph = $createParagraphNode();
+        root.append(paragraph);
+        const activeElement = CAN_USE_DOM ? document.activeElement : null;
+        if (
+          $getSelection() !== null ||
+          (activeElement !== null && activeElement === editor.getRootElement())
+        ) {
+          paragraph.select();
+        }
+      }
+    }, HISTORY_MERGE_OPTIONS);
+  } else if (initialEditorState !== null) {
+    switch (typeof initialEditorState) {
+      case 'string': {
+        const parsedEditorState = editor.parseEditorState(initialEditorState);
+        editor.setEditorState(parsedEditorState, HISTORY_MERGE_OPTIONS);
+        break;
+      }
+      case 'object': {
+        editor.setEditorState(initialEditorState, HISTORY_MERGE_OPTIONS);
+        break;
+      }
+      case 'function': {
+        editor.update(() => {
+          const root = $getRoot();
+          if (root.isEmpty()) {
+            initialEditorState(editor);
+          }
+        }, HISTORY_MERGE_OPTIONS);
+        break;
+      }
+    }
+  }
+}

package/src/LexicalComposerContext.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 {EditorThemeClasses, LexicalEditor} from 'lexical';
+
+import {createContext as createReactContext, useContext} from 'react';
+import invariant from 'shared/invariant';
+
+export type LexicalComposerContextType = {
+  getTheme: () => EditorThemeClasses | null | undefined;
+};
+
+export type LexicalComposerContextWithEditor = [
+  LexicalEditor,
+  LexicalComposerContextType,
+];
+
+export const LexicalComposerContext: React.Context<
+  LexicalComposerContextWithEditor | null | undefined
+> = createReactContext<LexicalComposerContextWithEditor | null | undefined>(
+  null,
+);
+
+export function createLexicalComposerContext(
+  parent: LexicalComposerContextWithEditor | null | undefined,
+  theme: EditorThemeClasses | null | undefined,
+): LexicalComposerContextType {
+  let parentContext: LexicalComposerContextType | null = null;
+
+  if (parent != null) {
+    parentContext = parent[1];
+  }
+
+  function getTheme() {
+    if (theme != null) {
+      return theme;
+    }
+
+    return parentContext != null ? parentContext.getTheme() : null;
+  }
+
+  return {
+    getTheme,
+  };
+}
+
+export function useLexicalComposerContext(): LexicalComposerContextWithEditor {
+  const composerContext = useContext(LexicalComposerContext);
+
+  if (composerContext == null) {
+    invariant(
+      false,
+      'LexicalComposerContext.useLexicalComposerContext: cannot find a LexicalComposerContext',
+    );
+  }
+
+  return composerContext;
+}

package/src/LexicalContentEditable.tsx

@@ -0,0 +1,97 @@
+/**
+ * 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 {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {forwardRef, Ref, useLayoutEffect, useState} from 'react';
+
+import {
+  ContentEditableElement,
+  type ContentEditableElementProps,
+} from './shared/LexicalContentEditableElement';
+import {useCanShowPlaceholder} from './shared/useCanShowPlaceholder';
+
+export {ContentEditableElement, type ContentEditableElementProps};
+
+export type ContentEditableProps = Omit<ContentEditableElementProps, 'editor'> &
+  (
+    | {
+        'aria-placeholder'?: void;
+        placeholder?: null;
+      }
+    | {
+        'aria-placeholder': string;
+        placeholder:
+          | ((isEditable: boolean) => null | JSX.Element)
+          | JSX.Element;
+      }
+  );
+
+/**
+ * @deprecated This type has been renamed to `ContentEditableProps` to provide a clearer and more descriptive name.
+ * For backward compatibility, this type is still exported as `Props`, but it is recommended to migrate to using `ContentEditableProps` instead.
+ *
+ * This alias is maintained for compatibility purposes but may be removed in future versions.
+ * Please update your codebase to use `ContentEditableProps` to ensure long-term maintainability.
+ */
+export type Props = ContentEditableProps;
+
+export const ContentEditable = forwardRef(ContentEditableImpl);
+
+function ContentEditableImpl(
+  props: ContentEditableProps,
+  ref: Ref<HTMLDivElement>,
+): JSX.Element {
+  const {placeholder, ...rest} = props;
+  const [editor] = useLexicalComposerContext();
+
+  return (
+    <>
+      <ContentEditableElement editor={editor} {...rest} ref={ref} />
+      {placeholder != null && (
+        <Placeholder editor={editor} content={placeholder} />
+      )}
+    </>
+  );
+}
+
+function Placeholder({
+  content,
+  editor,
+}: {
+  editor: LexicalEditor;
+  content: ((isEditable: boolean) => null | JSX.Element) | JSX.Element;
+}): null | JSX.Element {
+  const showPlaceholder = useCanShowPlaceholder(editor);
+
+  const [isEditable, setEditable] = useState(editor.isEditable());
+  useLayoutEffect(() => {
+    setEditable(editor.isEditable());
+    return editor.registerEditableListener((currentIsEditable) => {
+      setEditable(currentIsEditable);
+    });
+  }, [editor]);
+
+  if (!showPlaceholder) {
+    return null;
+  }
+
+  let placeholder = null;
+  if (typeof content === 'function') {
+    placeholder = content(isEditable);
+  } else if (content !== null) {
+    placeholder = content;
+  }
+
+  if (placeholder === null) {
+    return null;
+  }
+  return <div aria-hidden={true}>{placeholder}</div>;
+}