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

package/src/Utils.ts

@@ -0,0 +1,648 @@
+/**
+ * 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 {BaseBinding, Binding, YjsNode} from '.';
+
+import invariant from '@lexical/internal/invariant';
+import {
+  $getNodeByKey,
+  $getRoot,
+  $getWritableNodeState,
+  $isDecoratorNode,
+  $isElementNode,
+  $isLineBreakNode,
+  $isRootNode,
+  $isTextNode,
+  createEditor,
+  DecoratorNode,
+  EditorState,
+  ElementNode,
+  isLexicalEditor,
+  LexicalNode,
+  NodeKey,
+  RangeSelection,
+  TextNode,
+} from 'lexical';
+import {Doc, Map as YMap, XmlElement, XmlText} from 'yjs';
+
+import {isBindingV1} from './Bindings';
+import {
+  $createCollabDecoratorNode,
+  CollabDecoratorNode,
+} from './CollabDecoratorNode';
+import {$createCollabElementNode, CollabElementNode} from './CollabElementNode';
+import {
+  $createCollabLineBreakNode,
+  CollabLineBreakNode,
+} from './CollabLineBreakNode';
+import {$createCollabTextNode, CollabTextNode} from './CollabTextNode';
+
+const baseExcludedProperties = new Set<string>([
+  '__key',
+  '__parent',
+  '__next',
+  '__prev',
+  '__state',
+]);
+const elementExcludedProperties = new Set<string>([
+  '__first',
+  '__last',
+  '__size',
+]);
+const rootExcludedProperties = new Set<string>(['__cachedText']);
+const textExcludedProperties = new Set<string>(['__text']);
+
+function isExcludedProperty(
+  name: string,
+  node: LexicalNode,
+  binding: BaseBinding,
+): boolean {
+  if (
+    baseExcludedProperties.has(name) ||
+    typeof (node as unknown as Record<string, unknown>)[name] === 'function'
+  ) {
+    return true;
+  }
+
+  if ($isTextNode(node)) {
+    if (textExcludedProperties.has(name)) {
+      return true;
+    }
+  } else if ($isElementNode(node)) {
+    if (
+      elementExcludedProperties.has(name) ||
+      ($isRootNode(node) && rootExcludedProperties.has(name))
+    ) {
+      return true;
+    }
+  }
+
+  const nodeKlass = node.constructor;
+  const excludedProperties = binding.excludedProperties.get(nodeKlass);
+  return excludedProperties != null && excludedProperties.has(name);
+}
+
+export function initializeNodeProperties(binding: BaseBinding): void {
+  const {editor, nodeProperties} = binding;
+  editor.update(() => {
+    editor._nodes.forEach(nodeInfo => {
+      const node = new nodeInfo.klass();
+      const defaultProperties: {[property: string]: unknown} = {};
+      for (const [property, value] of Object.entries(node)) {
+        if (!isExcludedProperty(property, node, binding)) {
+          defaultProperties[property] = value;
+        }
+      }
+      nodeProperties.set(node.__type, Object.freeze(defaultProperties));
+    });
+  });
+}
+
+export function getDefaultNodeProperties(
+  node: LexicalNode,
+  binding: BaseBinding,
+): {[property: string]: unknown} {
+  const type = node.__type;
+  const {nodeProperties} = binding;
+  const properties = nodeProperties.get(type);
+  invariant(
+    properties !== undefined,
+    'Node properties for %s not initialized for sync',
+    type,
+  );
+  return properties;
+}
+
+export function getIndexOfYjsNode(
+  yjsParentNode: YjsNode,
+  yjsNode: YjsNode,
+): number {
+  let node = yjsParentNode.firstChild;
+  let i = -1;
+
+  if (node === null) {
+    return -1;
+  }
+
+  do {
+    i++;
+
+    if (node === yjsNode) {
+      return i;
+    }
+
+    // @ts-expect-error Sibling exists but type is not available from YJS.
+    node = node.nextSibling;
+
+    if (node === null) {
+      return -1;
+    }
+  } while (node !== null);
+
+  return i;
+}
+
+export function $createCollabNodeFromLexicalNode(
+  binding: Binding,
+  lexicalNode: LexicalNode,
+  parent: CollabElementNode,
+):
+  | CollabElementNode
+  | CollabTextNode
+  | CollabLineBreakNode
+  | CollabDecoratorNode {
+  const nodeType = lexicalNode.__type;
+  let collabNode;
+
+  if ($isElementNode(lexicalNode)) {
+    const xmlText = new XmlText();
+    collabNode = $createCollabElementNode(xmlText, parent, nodeType);
+    collabNode.syncPropertiesFromLexical(binding, lexicalNode, null);
+    collabNode.syncChildrenFromLexical(binding, lexicalNode, null, null, null);
+  } else if ($isTextNode(lexicalNode)) {
+    // TODO create a token text node for token, segmented nodes.
+    const map = new YMap();
+    collabNode = $createCollabTextNode(
+      map,
+      lexicalNode.__text,
+      parent,
+      nodeType,
+    );
+    collabNode.syncPropertiesAndTextFromLexical(binding, lexicalNode, null);
+  } else if ($isLineBreakNode(lexicalNode)) {
+    const map = new YMap();
+    map.set('__type', 'linebreak');
+    collabNode = $createCollabLineBreakNode(map, parent);
+  } else if ($isDecoratorNode(lexicalNode)) {
+    const xmlElem = new XmlElement();
+    collabNode = $createCollabDecoratorNode(xmlElem, parent, nodeType);
+    collabNode.syncPropertiesFromLexical(binding, lexicalNode, null);
+  } else {
+    invariant(false, 'Expected text, element, decorator, or linebreak node');
+  }
+
+  collabNode._key = lexicalNode.__key;
+  return collabNode;
+}
+
+export function getNodeTypeFromSharedType(
+  sharedType: XmlText | YMap<unknown> | XmlElement,
+): string | undefined {
+  const type = sharedTypeGet(sharedType, '__type');
+  invariant(
+    typeof type === 'string' || typeof type === 'undefined',
+    'Expected shared type to include type attribute',
+  );
+  return type;
+}
+
+export function $getOrInitCollabNodeFromSharedType(
+  binding: Binding,
+  sharedType: XmlText | YMap<unknown> | XmlElement,
+  parent?: CollabElementNode,
+):
+  | CollabElementNode
+  | CollabTextNode
+  | CollabLineBreakNode
+  | CollabDecoratorNode {
+  const collabNode = sharedType._collabNode;
+
+  if (collabNode === undefined) {
+    const registeredNodes = binding.editor._nodes;
+    const type = getNodeTypeFromSharedType(sharedType);
+    invariant(
+      typeof type === 'string',
+      'Expected shared type to include type attribute',
+    );
+    const nodeInfo = registeredNodes.get(type);
+    invariant(nodeInfo !== undefined, 'Node %s is not registered', type);
+
+    const sharedParent = sharedType.parent;
+    const targetParent =
+      parent === undefined && sharedParent !== null
+        ? $getOrInitCollabNodeFromSharedType(
+            binding,
+            sharedParent as XmlText | YMap<unknown> | XmlElement,
+          )
+        : parent || null;
+
+    invariant(
+      targetParent instanceof CollabElementNode,
+      'Expected parent to be a collab element node',
+    );
+
+    if (sharedType instanceof XmlText) {
+      return $createCollabElementNode(sharedType, targetParent, type);
+    } else if (sharedType instanceof YMap) {
+      if (type === 'linebreak') {
+        return $createCollabLineBreakNode(sharedType, targetParent);
+      }
+      return $createCollabTextNode(sharedType, '', targetParent, type);
+    } else if (sharedType instanceof XmlElement) {
+      return $createCollabDecoratorNode(sharedType, targetParent, type);
+    }
+  }
+
+  return collabNode;
+}
+
+export function createLexicalNodeFromCollabNode(
+  binding: Binding,
+  collabNode:
+    | CollabElementNode
+    | CollabTextNode
+    | CollabDecoratorNode
+    | CollabLineBreakNode,
+  parentKey: NodeKey,
+): LexicalNode {
+  const type = collabNode.getType();
+  const registeredNodes = binding.editor._nodes;
+  const nodeInfo = registeredNodes.get(type);
+  invariant(nodeInfo !== undefined, 'Node %s is not registered', type);
+  const lexicalNode:
+    | DecoratorNode<unknown>
+    | TextNode
+    | ElementNode
+    | LexicalNode = new nodeInfo.klass();
+  lexicalNode.__parent = parentKey;
+  collabNode._key = lexicalNode.__key;
+
+  if (collabNode instanceof CollabElementNode) {
+    const xmlText = collabNode._xmlText;
+    collabNode.syncPropertiesFromYjs(binding, null);
+    collabNode.applyChildrenYjsDelta(binding, xmlText.toDelta());
+    collabNode.syncChildrenFromYjs(binding);
+  } else if (collabNode instanceof CollabTextNode) {
+    collabNode.syncPropertiesAndTextFromYjs(binding, null);
+  } else if (collabNode instanceof CollabDecoratorNode) {
+    collabNode.syncPropertiesFromYjs(binding, null);
+  }
+
+  binding.collabNodeMap.set(lexicalNode.__key, collabNode);
+  return lexicalNode;
+}
+
+export function $syncPropertiesFromYjs(
+  binding: BaseBinding,
+  sharedType:
+    | XmlText
+    | YMap<unknown>
+    | XmlElement
+    // v2
+    | Record<string, unknown>,
+  lexicalNode: LexicalNode,
+  keysChanged: null | Set<string>,
+): void {
+  const properties =
+    keysChanged === null
+      ? sharedType instanceof YMap
+        ? Array.from(sharedType.keys())
+        : sharedType instanceof XmlText || sharedType instanceof XmlElement
+          ? Object.keys(sharedType.getAttributes())
+          : Object.keys(sharedType)
+      : Array.from(keysChanged);
+  let writableNode: LexicalNode | undefined;
+
+  for (let i = 0; i < properties.length; i++) {
+    const property = properties[i];
+    if (isExcludedProperty(property, lexicalNode, binding)) {
+      if (property === '__state' && isBindingV1(binding)) {
+        if (!writableNode) {
+          writableNode = lexicalNode.getWritable();
+        }
+        $syncNodeStateToLexical(sharedType, writableNode);
+      }
+      continue;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const prevValue = (lexicalNode as any)[property];
+    let nextValue = sharedTypeGet(sharedType, property);
+
+    if (prevValue !== nextValue) {
+      if (nextValue instanceof Doc) {
+        const yjsDocMap = binding.docMap;
+
+        if (prevValue instanceof Doc) {
+          yjsDocMap.delete(prevValue.guid);
+        }
+
+        const key = nextValue.guid;
+        yjsDocMap.set(key, nextValue);
+
+        // If the node already constructed a nested editor (e.g. via
+        // buildEditorFromExtensions in its constructor), reuse it so its
+        // extensions and LexicalBuilder registration survive the sync.
+        // Otherwise, fall back to a bare editor.
+        if (isLexicalEditor(prevValue)) {
+          prevValue._key = key;
+          nextValue = prevValue;
+        } else {
+          const nestedEditor = createEditor();
+          nestedEditor._key = key;
+          nextValue = nestedEditor;
+        }
+      }
+
+      if (writableNode === undefined) {
+        writableNode = lexicalNode.getWritable();
+      }
+
+      writableNode[property as string & keyof typeof writableNode] =
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        nextValue as any;
+    }
+  }
+}
+
+function sharedTypeGet(
+  sharedType: XmlText | YMap<unknown> | XmlElement | Record<string, unknown>,
+  property: string,
+): unknown {
+  if (sharedType instanceof YMap) {
+    return sharedType.get(property);
+  } else if (
+    sharedType instanceof XmlText ||
+    sharedType instanceof XmlElement
+  ) {
+    return sharedType.getAttribute(property);
+  } else {
+    return sharedType[property];
+  }
+}
+
+function sharedTypeSet(
+  sharedType: XmlText | YMap<unknown> | XmlElement,
+  property: string,
+  nextValue: unknown,
+): void {
+  if (sharedType instanceof YMap) {
+    sharedType.set(property, nextValue);
+  } else {
+    sharedType.setAttribute(property, nextValue as string);
+  }
+}
+
+function $syncNodeStateToLexical(
+  sharedType: XmlText | YMap<unknown> | XmlElement | Record<string, unknown>,
+  lexicalNode: LexicalNode,
+): void {
+  const existingState = sharedTypeGet(sharedType, '__state');
+  if (!(existingState instanceof YMap)) {
+    return;
+  }
+  // This should only called when creating the node initially,
+  // incremental updates to state come in through YMapEvent
+  // with the __state as the target.
+  $getWritableNodeState(lexicalNode).updateFromJSON(existingState.toJSON());
+}
+
+function syncNodeStateFromLexical(
+  binding: Binding,
+  sharedType: XmlText | YMap<unknown> | XmlElement,
+  prevLexicalNode: null | LexicalNode,
+  nextLexicalNode: LexicalNode,
+): void {
+  const nextState = nextLexicalNode.__state;
+  // Reading from a shared type that hasn't been integrated into a doc yet
+  // logs a "premature access" warning in yjs >= 13.6.10. When the shared
+  // type is detached we know there cannot be any existing state.
+  const existingState =
+    sharedType.doc === null ? undefined : sharedTypeGet(sharedType, '__state');
+  if (!nextState) {
+    return;
+  }
+  const [unknown, known] = nextState.getInternalState();
+  const prevState = prevLexicalNode && prevLexicalNode.__state;
+  const stateMap: YMap<unknown> =
+    existingState instanceof YMap ? existingState : new YMap();
+  if (prevState === nextState) {
+    return;
+  }
+  const [prevUnknown, prevKnown] =
+    prevState && stateMap.doc
+      ? prevState.getInternalState()
+      : [undefined, new Map()];
+  if (unknown) {
+    for (const [k, v] of Object.entries(unknown)) {
+      if (prevUnknown && v !== prevUnknown[k]) {
+        stateMap.set(k, v);
+      }
+    }
+  }
+  for (const [stateConfig, v] of known) {
+    if (prevKnown.get(stateConfig) !== v) {
+      stateMap.set(stateConfig.key, stateConfig.unparse(v));
+    }
+  }
+  if (!existingState) {
+    sharedTypeSet(sharedType, '__state', stateMap);
+  }
+}
+
+export function syncPropertiesFromLexical(
+  binding: Binding,
+  sharedType: XmlText | YMap<unknown> | XmlElement,
+  prevLexicalNode: null | LexicalNode,
+  nextLexicalNode: LexicalNode,
+): void {
+  const properties = Object.keys(
+    getDefaultNodeProperties(nextLexicalNode, binding),
+  );
+
+  const EditorClass = binding.editor.constructor;
+
+  syncNodeStateFromLexical(
+    binding,
+    sharedType,
+    prevLexicalNode,
+    nextLexicalNode,
+  );
+  for (let i = 0; i < properties.length; i++) {
+    const property = properties[i];
+    const prevValue =
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      prevLexicalNode === null ? undefined : (prevLexicalNode as any)[property];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let nextValue = (nextLexicalNode as any)[property];
+
+    if (prevValue !== nextValue) {
+      if (nextValue instanceof EditorClass) {
+        const yjsDocMap = binding.docMap;
+        let prevDoc;
+
+        if (prevValue instanceof EditorClass) {
+          const prevKey = prevValue._key;
+          prevDoc = yjsDocMap.get(prevKey);
+          yjsDocMap.delete(prevKey);
+        }
+
+        // If we already have a document, use it.
+        const doc = prevDoc || new Doc();
+        const key = doc.guid;
+        nextValue._key = key;
+        yjsDocMap.set(key, doc);
+        nextValue = doc;
+        // Mark the node dirty as we've assigned a new key to it
+        binding.editor.update(() => {
+          nextLexicalNode.markDirty();
+        });
+      }
+
+      sharedTypeSet(sharedType, property, nextValue);
+    }
+  }
+}
+
+export function spliceString(
+  str: string,
+  index: number,
+  delCount: number,
+  newText: string,
+): string {
+  return str.slice(0, index) + newText + str.slice(index + delCount);
+}
+
+export function getPositionFromElementAndOffset(
+  node: CollabElementNode,
+  offset: number,
+  boundaryIsEdge: boolean,
+): {
+  length: number;
+  node:
+    | CollabElementNode
+    | CollabTextNode
+    | CollabDecoratorNode
+    | CollabLineBreakNode
+    | null;
+  nodeIndex: number;
+  offset: number;
+} {
+  let index = 0;
+  let i = 0;
+  const children = node._children;
+  const childrenLength = children.length;
+
+  for (; i < childrenLength; i++) {
+    const child = children[i];
+    const childOffset = index;
+    const size = child.getSize();
+    index += size;
+    const exceedsBoundary = boundaryIsEdge ? index >= offset : index > offset;
+
+    if (exceedsBoundary && child instanceof CollabTextNode) {
+      let textOffset = offset - childOffset - 1;
+
+      if (textOffset < 0) {
+        textOffset = 0;
+      }
+
+      const diffLength = index - offset;
+      return {
+        length: diffLength,
+        node: child,
+        nodeIndex: i,
+        offset: textOffset,
+      };
+    }
+
+    if (index > offset) {
+      return {
+        length: 0,
+        node: child,
+        nodeIndex: i,
+        offset: childOffset,
+      };
+    } else if (i === childrenLength - 1) {
+      return {
+        length: 0,
+        node: null,
+        nodeIndex: i + 1,
+        offset: childOffset + 1,
+      };
+    }
+  }
+
+  return {
+    length: 0,
+    node: null,
+    nodeIndex: 0,
+    offset: 0,
+  };
+}
+
+export function doesSelectionNeedRecovering(
+  selection: RangeSelection,
+): boolean {
+  const anchor = selection.anchor;
+  const focus = selection.focus;
+  let recoveryNeeded = false;
+
+  try {
+    const anchorNode = anchor.getNode();
+    const focusNode = focus.getNode();
+
+    if (
+      // We might have removed a node that no longer exists
+      !anchorNode.isAttached() ||
+      !focusNode.isAttached() ||
+      // If we've split a node, then the offset might not be right
+      ($isTextNode(anchorNode) &&
+        anchor.offset > anchorNode.getTextContentSize()) ||
+      ($isTextNode(focusNode) && focus.offset > focusNode.getTextContentSize())
+    ) {
+      recoveryNeeded = true;
+    }
+  } catch (_e) {
+    // Sometimes checking nor a node via getNode might trigger
+    // an error, so we need recovery then too.
+    recoveryNeeded = true;
+  }
+
+  return recoveryNeeded;
+}
+
+export function syncWithTransaction(
+  binding: BaseBinding,
+  fn: () => void,
+): void {
+  binding.doc.transact(fn, binding);
+}
+
+export function $moveSelectionToPreviousNode(
+  anchorNodeKey: string,
+  currentEditorState: EditorState,
+) {
+  const anchorNode = currentEditorState._nodeMap.get(anchorNodeKey);
+  if (!anchorNode) {
+    $getRoot().selectStart();
+    return;
+  }
+  // Get previous node
+  const prevNodeKey = anchorNode.__prev;
+  let prevNode: ElementNode | null = null;
+  if (prevNodeKey) {
+    prevNode = $getNodeByKey(prevNodeKey);
+  }
+
+  // If previous node not found, get parent node
+  if (prevNode === null && anchorNode.__parent !== null) {
+    prevNode = $getNodeByKey(anchorNode.__parent);
+  }
+  if (prevNode === null) {
+    $getRoot().selectStart();
+    return;
+  }
+
+  if (prevNode !== null && prevNode.isAttached()) {
+    prevNode.selectEnd();
+    return;
+  } else {
+    // If the found node is also deleted, select the next one
+    $moveSelectionToPreviousNode(prevNode.__key, currentEditorState);
+  }
+}