@lexical/utils 0.12.1 → 0.12.3

package/LexicalUtils.dev.js

@@ -9,8 +9,299 @@
 var selection = require('@lexical/selection');
 var lexical = require('lexical');
 
-/** @module @lexical/utils */
+/**
+ * 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.
+ *
+ */
+
+/**
+ * Returns a function that will execute all functions passed when called. It is generally used
+ * to register multiple lexical listeners and then tear them down with a single function call, such
+ * as React's useEffect hook.
+ * @example
+ * ```ts
+ * useEffect(() => {
+ *   return mergeRegister(
+ *     editor.registerCommand(...registerCommand1 logic),
+ *     editor.registerCommand(...registerCommand2 logic),
+ *     editor.registerCommand(...registerCommand3 logic)
+ *   )
+ * }, [editor])
+ * ```
+ * In this case, useEffect is returning the function returned by mergeRegister as a cleanup
+ * function to be executed after either the useEffect runs again (due to one of its dependencies
+ * updating) or the component it resides in unmounts.
+ * Note the functions don't neccesarily need to be in an array as all arguements
+ * are considered to be the func argument and spread from there.
+ * @param func - An array of functions meant to be executed by the returned function.
+ * @returns the function which executes all the passed register command functions.
+ */
+function mergeRegister(...func) {
+  return () => {
+    func.forEach(f => f());
+  };
+}
+
+/**
+ * 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.
+ *
+ */
+
+function px(value) {
+  return `${value}px`;
+}
 
+/**
+ * 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.
+ *
+ */
+const mutationObserverConfig = {
+  attributes: true,
+  characterData: true,
+  childList: true,
+  subtree: true
+};
+function positionNodeOnRange(editor, range, onReposition) {
+  let rootDOMNode = null;
+  let parentDOMNode = null;
+  let observer = null;
+  let lastNodes = [];
+  const wrapperNode = document.createElement('div');
+  function position() {
+    if (!(rootDOMNode !== null)) {
+      throw Error(`Unexpected null rootDOMNode`);
+    }
+    if (!(parentDOMNode !== null)) {
+      throw Error(`Unexpected null parentDOMNode`);
+    }
+    const {
+      left: rootLeft,
+      top: rootTop
+    } = rootDOMNode.getBoundingClientRect();
+    const parentDOMNode_ = parentDOMNode;
+    const rects = selection.createRectsFromDOMRange(editor, range);
+    if (!wrapperNode.isConnected) {
+      parentDOMNode_.append(wrapperNode);
+    }
+    let hasRepositioned = false;
+    for (let i = 0; i < rects.length; i++) {
+      const rect = rects[i];
+      // Try to reuse the previously created Node when possible, no need to
+      // remove/create on the most common case reposition case
+      const rectNode = lastNodes[i] || document.createElement('div');
+      const rectNodeStyle = rectNode.style;
+      if (rectNodeStyle.position !== 'absolute') {
+        rectNodeStyle.position = 'absolute';
+        hasRepositioned = true;
+      }
+      const left = px(rect.left - rootLeft);
+      if (rectNodeStyle.left !== left) {
+        rectNodeStyle.left = left;
+        hasRepositioned = true;
+      }
+      const top = px(rect.top - rootTop);
+      if (rectNodeStyle.top !== top) {
+        rectNode.style.top = top;
+        hasRepositioned = true;
+      }
+      const width = px(rect.width);
+      if (rectNodeStyle.width !== width) {
+        rectNode.style.width = width;
+        hasRepositioned = true;
+      }
+      const height = px(rect.height);
+      if (rectNodeStyle.height !== height) {
+        rectNode.style.height = height;
+        hasRepositioned = true;
+      }
+      if (rectNode.parentNode !== wrapperNode) {
+        wrapperNode.append(rectNode);
+        hasRepositioned = true;
+      }
+      lastNodes[i] = rectNode;
+    }
+    while (lastNodes.length > rects.length) {
+      lastNodes.pop();
+    }
+    if (hasRepositioned) {
+      onReposition(lastNodes);
+    }
+  }
+  function stop() {
+    parentDOMNode = null;
+    rootDOMNode = null;
+    if (observer !== null) {
+      observer.disconnect();
+    }
+    observer = null;
+    wrapperNode.remove();
+    for (const node of lastNodes) {
+      node.remove();
+    }
+    lastNodes = [];
+  }
+  function restart() {
+    const currentRootDOMNode = editor.getRootElement();
+    if (currentRootDOMNode === null) {
+      return stop();
+    }
+    const currentParentDOMNode = currentRootDOMNode.parentElement;
+    if (!(currentParentDOMNode instanceof HTMLElement)) {
+      return stop();
+    }
+    stop();
+    rootDOMNode = currentRootDOMNode;
+    parentDOMNode = currentParentDOMNode;
+    observer = new MutationObserver(mutations => {
+      const nextRootDOMNode = editor.getRootElement();
+      const nextParentDOMNode = nextRootDOMNode && nextRootDOMNode.parentElement;
+      if (nextRootDOMNode !== rootDOMNode || nextParentDOMNode !== parentDOMNode) {
+        return restart();
+      }
+      for (const mutation of mutations) {
+        if (!wrapperNode.contains(mutation.target)) {
+          // TODO throttle
+          return position();
+        }
+      }
+    });
+    observer.observe(currentParentDOMNode, mutationObserverConfig);
+    position();
+  }
+  const removeRootListener = editor.registerRootListener(restart);
+  return () => {
+    removeRootListener();
+    stop();
+  };
+}
+
+/**
+ * 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.
+ *
+ */
+function markSelection(editor, onReposition) {
+  let previousAnchorNode = null;
+  let previousAnchorOffset = null;
+  let previousFocusNode = null;
+  let previousFocusOffset = null;
+  let removeRangeListener = () => {};
+  function compute(editorState) {
+    editorState.read(() => {
+      const selection = lexical.$getSelection();
+      if (!lexical.$isRangeSelection(selection)) {
+        // TODO
+        previousAnchorNode = null;
+        previousAnchorOffset = null;
+        previousFocusNode = null;
+        previousFocusOffset = null;
+        removeRangeListener();
+        removeRangeListener = () => {};
+        return;
+      }
+      const {
+        anchor,
+        focus
+      } = selection;
+      const currentAnchorNode = anchor.getNode();
+      const currentAnchorNodeKey = currentAnchorNode.getKey();
+      const currentAnchorOffset = anchor.offset;
+      const currentFocusNode = focus.getNode();
+      const currentFocusNodeKey = currentFocusNode.getKey();
+      const currentFocusOffset = focus.offset;
+      const currentAnchorNodeDOM = editor.getElementByKey(currentAnchorNodeKey);
+      const currentFocusNodeDOM = editor.getElementByKey(currentFocusNodeKey);
+      const differentAnchorDOM = previousAnchorNode === null || currentAnchorNodeDOM === null || currentAnchorOffset !== previousAnchorOffset || currentAnchorNodeKey !== previousAnchorNode.getKey() || currentAnchorNode !== previousAnchorNode && (!(previousAnchorNode instanceof lexical.TextNode) || currentAnchorNode.updateDOM(previousAnchorNode, currentAnchorNodeDOM, editor._config));
+      const differentFocusDOM = previousFocusNode === null || currentFocusNodeDOM === null || currentFocusOffset !== previousFocusOffset || currentFocusNodeKey !== previousFocusNode.getKey() || currentFocusNode !== previousFocusNode && (!(previousFocusNode instanceof lexical.TextNode) || currentFocusNode.updateDOM(previousFocusNode, currentFocusNodeDOM, editor._config));
+      if (differentAnchorDOM || differentFocusDOM) {
+        const anchorHTMLElement = editor.getElementByKey(anchor.getNode().getKey());
+        const focusHTMLElement = editor.getElementByKey(focus.getNode().getKey());
+        // TODO handle selection beyond the common TextNode
+        if (anchorHTMLElement !== null && focusHTMLElement !== null && anchorHTMLElement.tagName === 'SPAN' && focusHTMLElement.tagName === 'SPAN') {
+          const range = document.createRange();
+          let firstHTMLElement;
+          let firstOffset;
+          let lastHTMLElement;
+          let lastOffset;
+          if (focus.isBefore(anchor)) {
+            firstHTMLElement = focusHTMLElement;
+            firstOffset = focus.offset;
+            lastHTMLElement = anchorHTMLElement;
+            lastOffset = anchor.offset;
+          } else {
+            firstHTMLElement = anchorHTMLElement;
+            firstOffset = anchor.offset;
+            lastHTMLElement = focusHTMLElement;
+            lastOffset = focus.offset;
+          }
+          const firstTextNode = firstHTMLElement.firstChild;
+          if (!(firstTextNode !== null)) {
+            throw Error(`Expected text node to be first child of span`);
+          }
+          const lastTextNode = lastHTMLElement.firstChild;
+          if (!(lastTextNode !== null)) {
+            throw Error(`Expected text node to be first child of span`);
+          }
+          range.setStart(firstTextNode, firstOffset);
+          range.setEnd(lastTextNode, lastOffset);
+          removeRangeListener();
+          removeRangeListener = positionNodeOnRange(editor, range, domNodes => {
+            for (const domNode of domNodes) {
+              const domNodeStyle = domNode.style;
+              if (domNodeStyle.background !== 'Highlight') {
+                domNodeStyle.background = 'Highlight';
+              }
+              if (domNodeStyle.color !== 'HighlightText') {
+                domNodeStyle.color = 'HighlightText';
+              }
+              if (domNodeStyle.zIndex !== '-1') {
+                domNodeStyle.zIndex = '-1';
+              }
+              if (domNodeStyle.pointerEvents !== 'none') {
+                domNodeStyle.pointerEvents = 'none';
+              }
+              if (domNodeStyle.marginTop !== px(-1.5)) {
+                domNodeStyle.marginTop = px(-1.5);
+              }
+              if (domNodeStyle.paddingTop !== px(4)) {
+                domNodeStyle.paddingTop = px(4);
+              }
+              if (domNodeStyle.paddingBottom !== px(0)) {
+                domNodeStyle.paddingBottom = px(0);
+              }
+            }
+            if (onReposition !== undefined) {
+              onReposition(domNodes);
+            }
+          });
+        }
+      }
+      previousAnchorNode = currentAnchorNode;
+      previousAnchorOffset = currentAnchorOffset;
+      previousFocusNode = currentFocusNode;
+      previousFocusOffset = currentFocusOffset;
+    });
+  }
+  compute(editor.getEditorState());
+  return mergeRegister(editor.registerUpdateListener(({
+    editorState
+  }) => compute(editorState)), removeRangeListener, () => {
+    removeRangeListener();
+  });
+}
+
+/** @module @lexical/utils */
 /**
  * Takes an HTML element and adds the classNames passed within an array,
  * ignoring any non-string types. A space can be used to add multiple classes
@@ -27,6 +318,7 @@ function addClassNamesToElement(element, ...classNames) {
     }
   });
 }
+
 /**
  * Takes an HTML element and removes the classNames passed within an array,
  * ignoring any non-string types. A space can be used to remove multiple classes
@@ -35,7 +327,6 @@ function addClassNamesToElement(element, ...classNames) {
  * @param element - The element in which the classes are removed
  * @param classNames - An array defining the class names to remove from the element
  */
-
 function removeClassNamesFromElement(element, ...classNames) {
   classNames.forEach(className => {
     if (typeof className === 'string') {
@@ -43,6 +334,7 @@ function removeClassNamesFromElement(element, ...classNames) {
     }
   });
 }
+
 /**
  * Returns true if the file type matches the types passed within the acceptableMimeTypes array, false otherwise.
  * The types passed must be strings and are CASE-SENSITIVE.
@@ -51,16 +343,15 @@ function removeClassNamesFromElement(element, ...classNames) {
  * @param acceptableMimeTypes - An array of strings of types which the file is checked against.
  * @returns true if the file is an acceptable mime type, false otherwise.
  */
-
 function isMimeType(file, acceptableMimeTypes) {
   for (const acceptableType of acceptableMimeTypes) {
     if (file.type.startsWith(acceptableType)) {
       return true;
     }
   }
-
   return false;
 }
+
 /**
  * Lexical File Reader with:
  *  1. MIME type support
@@ -72,47 +363,40 @@ function isMimeType(file, acceptableMimeTypes) {
  *   src: file.result,
  * }));
  */
-
 function mediaFileReader(files, acceptableMimeTypes) {
   const filesIterator = files[Symbol.iterator]();
   return new Promise((resolve, reject) => {
     const processed = [];
-
     const handleNextFile = () => {
       const {
         done,
         value: file
       } = filesIterator.next();
-
       if (done) {
         return resolve(processed);
       }
-
       const fileReader = new FileReader();
       fileReader.addEventListener('error', reject);
       fileReader.addEventListener('load', () => {
         const result = fileReader.result;
-
         if (typeof result === 'string') {
           processed.push({
             file,
             result
           });
         }
-
         handleNextFile();
       });
-
       if (isMimeType(file, acceptableMimeTypes)) {
         fileReader.readAsDataURL(file);
       } else {
         handleNextFile();
       }
     };
-
     handleNextFile();
   });
 }
+
 /**
  * "Depth-First Search" starts at the root/top node of a tree and goes as far as it can down a branch end
  * before backtracking and finding a new path. Consider solving a maze by hugging either wall, moving down a
@@ -123,30 +407,25 @@ function mediaFileReader(files, acceptableMimeTypes) {
  * @returns An array of objects of all the nodes found by the search, including their depth into the tree.
  * {depth: number, node: LexicalNode} It will always return at least 1 node (the ending node) so long as it exists
  */
-
 function $dfs(startingNode, endingNode) {
   const nodes = [];
   const start = (startingNode || lexical.$getRoot()).getLatest();
   const end = endingNode || (lexical.$isElementNode(start) ? start.getLastDescendant() : start);
   let node = start;
   let depth = $getDepth(node);
-
   while (node !== null && !node.is(end)) {
     nodes.push({
       depth,
       node
     });
-
     if (lexical.$isElementNode(node) && node.getChildrenSize() > 0) {
       node = node.getFirstChild();
       depth++;
     } else {
       // Find immediate sibling or nearest parent sibling
       let sibling = null;
-
       while (sibling === null && node !== null) {
         sibling = node.getNextSibling();
-
         if (sibling === null) {
           node = node.getParent();
           depth--;
@@ -156,27 +435,23 @@ function $dfs(startingNode, endingNode) {
       }
     }
   }
-
   if (node !== null && node.is(end)) {
     nodes.push({
       depth,
       node
     });
   }
-
   return nodes;
 }
-
 function $getDepth(node) {
   let innerNode = node;
   let depth = 0;
-
   while ((innerNode = innerNode.getParent()) !== null) {
     depth++;
   }
-
   return depth;
 }
+
 /**
  * Takes a node and traverses up its ancestors (toward the root node)
  * in order to find a specific type of node.
@@ -184,39 +459,31 @@ function $getDepth(node) {
  * @param klass - an instance of the type of node to look for.
  * @returns the node of type klass that was passed, or null if none exist.
  */
-
-
 function $getNearestNodeOfType(node, klass) {
   let parent = node;
-
   while (parent != null) {
     if (parent instanceof klass) {
       return parent;
     }
-
     parent = parent.getParent();
   }
-
   return null;
 }
+
 /**
  * Returns the element node of the nearest ancestor, otherwise throws an error.
  * @param startNode - The starting node of the search
  * @returns The ancestor node found
  */
-
 function $getNearestBlockElementAncestorOrThrow(startNode) {
   const blockNode = $findMatchingParent(startNode, node => lexical.$isElementNode(node) && !node.isInline());
-
   if (!lexical.$isElementNode(blockNode)) {
     {
       throw Error(`Expected node ${startNode.__key} to have closest block element node.`);
     }
   }
-
   return blockNode;
 }
-
 /**
  * Starts with a node and moves up the tree (toward the root node) to find a matching node based on
  * the search parameters of the findFn. (Consider JavaScripts' .find() function where a testing function must be
@@ -227,45 +494,15 @@ function $getNearestBlockElementAncestorOrThrow(startNode) {
  */
 function $findMatchingParent(startingNode, findFn) {
   let curr = startingNode;
-
   while (curr !== lexical.$getRoot() && curr != null) {
     if (findFn(curr)) {
       return curr;
     }
-
     curr = curr.getParent();
   }
-
   return null;
 }
 
-/**
- * Returns a function that will execute all functions passed when called. It is generally used
- * to register multiple lexical listeners and then tear them down with a single function call, such
- * as React's useEffect hook.
- * @example
- * ```ts
- * useEffect(() => {
- *   return mergeRegister(
- *     editor.registerCommand(...registerCommand1 logic),
- *     editor.registerCommand(...registerCommand2 logic),
- *     editor.registerCommand(...registerCommand3 logic)
- *   )
- * }, [editor])
- * ```
- * In this case, useEffect is returning the function returned by mergeRegister as a cleanup
- * function to be executed after either the useEffect runs again (due to one of its dependencies
- * updating) or the compenent it resides in unmounts.
- * Note the functions don't neccesarily need to be in an array as all arguements
- * are considered to be the func argument and spread from there.
- * @param func - An array of functions meant to be executed by the returned function.
- * @returns the function which executes all the passed register command functions.
- */
-function mergeRegister(...func) {
-  return () => {
-    func.forEach(f => f());
-  };
-}
 /**
  * Attempts to resolve nested element nodes of the same type into a single node of that type.
  * It is generally used for marks/commenting
@@ -275,32 +512,25 @@ function mergeRegister(...func) {
  * @param handleOverlap - Handles any overlap between the node to extract and the targetNode
  * @returns The lexical editor
  */
-
 function registerNestedElementResolver(editor, targetNode, cloneNode, handleOverlap) {
   const $isTargetNode = node => {
     return node instanceof targetNode;
   };
-
   const $findMatch = node => {
     // First validate we don't have any children that are of the target,
     // as we need to handle them first.
     const children = node.getChildren();
-
     for (let i = 0; i < children.length; i++) {
       const child = children[i];
-
       if ($isTargetNode(child)) {
         return null;
       }
     }
-
     let parentNode = node;
     let childNode = node;
-
     while (parentNode !== null) {
       childNode = parentNode;
       parentNode = parentNode.getParent();
-
       if ($isTargetNode(parentNode)) {
         return {
           child: childNode,
@@ -308,73 +538,64 @@ function registerNestedElementResolver(editor, targetNode, cloneNode, handleOver
         };
       }
     }
-
     return null;
   };
-
   const elementNodeTransform = node => {
     const match = $findMatch(node);
-
     if (match !== null) {
       const {
         child,
         parent
-      } = match; // Simple path, we can move child out and siblings into a new parent.
+      } = match;
+
+      // Simple path, we can move child out and siblings into a new parent.
 
       if (child.is(node)) {
         handleOverlap(parent, node);
         const nextSiblings = child.getNextSiblings();
         const nextSiblingsLength = nextSiblings.length;
         parent.insertAfter(child);
-
         if (nextSiblingsLength !== 0) {
           const newParent = cloneNode(parent);
           child.insertAfter(newParent);
-
           for (let i = 0; i < nextSiblingsLength; i++) {
             newParent.append(nextSiblings[i]);
           }
         }
-
         if (!parent.canBeEmpty() && parent.getChildrenSize() === 0) {
           parent.remove();
         }
       }
     }
   };
-
   return editor.registerNodeTransform(targetNode, elementNodeTransform);
 }
+
 /**
  * Clones the editor and marks it as dirty to be reconciled. If there was a selection,
  * it would be set back to its previous state, or null otherwise.
  * @param editor - The lexical editor
  * @param editorState - The editor's state
  */
-
 function $restoreEditorState(editor, editorState) {
   const FULL_RECONCILE = 2;
   const nodeMap = new Map();
   const activeEditorState = editor._pendingEditorState;
-
   for (const [key, node] of editorState._nodeMap) {
     const clone = selection.$cloneWithProperties(node);
-
     if (lexical.$isTextNode(clone)) {
       clone.__text = node.__text;
     }
-
     nodeMap.set(key, clone);
   }
-
   if (activeEditorState) {
     activeEditorState._nodeMap = nodeMap;
   }
-
   editor._dirtyType = FULL_RECONCILE;
   const selection$1 = editorState._selection;
   lexical.$setSelection(selection$1 === null ? null : selection$1.clone());
 }
+
 /**
  * If the selected insertion area is the root/shadow root node (see {@link lexical!$isRootOrShadowRoot}),
  * the node will be appended there, otherwise, it will be inserted before the insertion area.
@@ -383,35 +604,28 @@ function $restoreEditorState(editor, editorState) {
  * @param node - The node to be inserted
  * @returns The node after its insertion
  */
-
 function $insertNodeToNearestRoot(node) {
   const selection = lexical.$getSelection() || lexical.$getPreviousSelection();
-
   if (lexical.$isRangeSelection(selection)) {
     const {
       focus
     } = selection;
     const focusNode = focus.getNode();
     const focusOffset = focus.offset;
-
     if (lexical.$isRootOrShadowRoot(focusNode)) {
       const focusChild = focusNode.getChildAtIndex(focusOffset);
-
       if (focusChild == null) {
         focusNode.append(node);
       } else {
         focusChild.insertBefore(node);
       }
-
       node.selectNext();
     } else {
       let splitNode;
       let splitOffset;
-
       if (lexical.$isTextNode(focusNode)) {
         splitNode = focusNode.getParentOrThrow();
         splitOffset = focusNode.getIndexWithinParent();
-
         if (focusOffset > 0) {
           splitOffset += 1;
           focusNode.splitText(focusOffset);
@@ -420,7 +634,6 @@ function $insertNodeToNearestRoot(node) {
         splitNode = focusNode;
         splitOffset = focusOffset;
       }
-
       const [, rightTree] = lexical.$splitNode(splitNode, splitOffset);
       rightTree.insertBefore(node);
       rightTree.selectStart();
@@ -433,44 +646,27 @@ function $insertNodeToNearestRoot(node) {
       const root = lexical.$getRoot();
       root.append(node);
     }
-
     const paragraphNode = lexical.$createParagraphNode();
     node.insertAfter(paragraphNode);
     paragraphNode.select();
   }
-
   return node.getLatest();
 }
+
 /**
  * Wraps the node into another node created from a createElementNode function, eg. $createParagraphNode
  * @param node - Node to be wrapped.
- * @param createElementNode - Creates a new lexcial element to wrap the to-be-wrapped node and returns it.
- * @returns A new lexcial element with the previous node appended within (as a child, including its children).
+ * @param createElementNode - Creates a new lexical element to wrap the to-be-wrapped node and returns it.
+ * @returns A new lexical element with the previous node appended within (as a child, including its children).
  */
-
 function $wrapNodeInElement(node, createElementNode) {
   const elementNode = createElementNode();
   node.replace(elementNode);
   elementNode.append(node);
   return elementNode;
 }
-/**
- * @param x - The element being tested
- * @returns Returns true if x is an HTML anchor tag, false otherwise
- */
-
-function isHTMLAnchorElement(x) {
-  return isHTMLElement(x) && x.tagName === 'A';
-}
-/**
- * @param x - The element being testing
- * @returns Returns true if x is an HTML element, false otherwise.
- */
 
-function isHTMLElement(x) {
-  // @ts-ignore-next-line - strict check on nodeType here should filter out non-Element EventTarget implementors
-  return x.nodeType === 1;
-} // eslint-disable-next-line @typescript-eslint/no-explicit-any
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 
 /**
  * @param object = The instance of the type
@@ -480,6 +676,7 @@ function isHTMLElement(x) {
 function objectKlassEquals(object, objectClass) {
   return object !== null ? Object.getPrototypeOf(object).constructor.name === objectClass.name : false;
 }
+
 /**
  * Filter the nodes
  * @param nodes Array of nodes that needs to be filtered
@@ -489,15 +686,12 @@ function objectKlassEquals(object, objectClass) {
 
 function $filter(nodes, filterFn) {
   const result = [];
-
   for (let i = 0; i < nodes.length; i++) {
     const node = filterFn(nodes[i]);
-
     if (node !== null) {
       result.push(node);
     }
   }
-
   return result;
 }
 /**
@@ -505,10 +699,8 @@ function $filter(nodes, filterFn) {
  * @param parent A parent node
  * @param node Node that needs to be appended
  */
-
 function $insertFirst(parent, node) {
   const firstChild = parent.getFirstChild();
-
   if (firstChild !== null) {
     firstChild.insertBefore(node);
   } else {
@@ -516,22 +708,49 @@ function $insertFirst(parent, node) {
   }
 }
 
+/**
+ * This function is for internal use of the library.
+ * Please do not use it as it may change in the future.
+ */
+function INTERNAL_$isBlock(node) {
+  if (lexical.$isDecoratorNode(node) && !node.isInline()) {
+    return true;
+  }
+  if (!lexical.$isElementNode(node) || lexical.$isRootOrShadowRoot(node)) {
+    return false;
+  }
+  const firstChild = node.getFirstChild();
+  const isLeafElement = firstChild === null || lexical.$isLineBreakNode(firstChild) || lexical.$isTextNode(firstChild) || firstChild.isInline();
+  return !node.isInline() && node.canBeEmpty() !== false && isLeafElement;
+}
+function $getAncestor(node, predicate) {
+  let parent = node;
+  while (parent !== null && parent.getParent() !== null && !predicate(parent)) {
+    parent = parent.getParentOrThrow();
+  }
+  return predicate(parent) ? parent : null;
+}
+
 exports.$splitNode = lexical.$splitNode;
+exports.isHTMLAnchorElement = lexical.isHTMLAnchorElement;
+exports.isHTMLElement = lexical.isHTMLElement;
 exports.$dfs = $dfs;
 exports.$filter = $filter;
 exports.$findMatchingParent = $findMatchingParent;
+exports.$getAncestor = $getAncestor;
 exports.$getNearestBlockElementAncestorOrThrow = $getNearestBlockElementAncestorOrThrow;
 exports.$getNearestNodeOfType = $getNearestNodeOfType;
 exports.$insertFirst = $insertFirst;
 exports.$insertNodeToNearestRoot = $insertNodeToNearestRoot;
 exports.$restoreEditorState = $restoreEditorState;
 exports.$wrapNodeInElement = $wrapNodeInElement;
+exports.INTERNAL_$isBlock = INTERNAL_$isBlock;
 exports.addClassNamesToElement = addClassNamesToElement;
-exports.isHTMLAnchorElement = isHTMLAnchorElement;
-exports.isHTMLElement = isHTMLElement;
 exports.isMimeType = isMimeType;
+exports.markSelection = markSelection;
 exports.mediaFileReader = mediaFileReader;
 exports.mergeRegister = mergeRegister;
 exports.objectKlassEquals = objectKlassEquals;
+exports.positionNodeOnRange = positionNodeOnRange;
 exports.registerNestedElementResolver = registerNestedElementResolver;
 exports.removeClassNamesFromElement = removeClassNamesFromElement;

package/LexicalUtils.prod.js

@@ -4,14 +4,21 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-'use strict';var g=require("@lexical/selection"),n=require("lexical");function p(a){let b=new URLSearchParams;b.append("code",a);for(let c=1;c<arguments.length;c++)b.append("v",arguments[c]);throw Error(`Minified Lexical error #${a}; visit https://lexical.dev/docs/error?${b} for the full message or `+"use the non-minified dev environment for full errors and additional helpful warnings.");}function q(a,b){for(let c of b)if(a.type.startsWith(c))return!0;return!1}
-function t(a,b){for(;a!==n.$getRoot()&&null!=a;){if(b(a))return a;a=a.getParent()}return null}function u(a){return 1===a.nodeType}exports.$splitNode=n.$splitNode;
-exports.$dfs=function(a,b){let c=[];a=(a||n.$getRoot()).getLatest();b=b||(n.$isElementNode(a)?a.getLastDescendant():a);for(var e=a,d=0;null!==(e=e.getParent());)d++;for(e=d;null!==a&&!a.is(b);)if(c.push({depth:e,node:a}),n.$isElementNode(a)&&0<a.getChildrenSize())a=a.getFirstChild(),e++;else for(d=null;null===d&&null!==a;)d=a.getNextSibling(),null===d?(a=a.getParent(),e--):a=d;null!==a&&a.is(b)&&c.push({depth:e,node:a});return c};
-exports.$filter=function(a,b){let c=[];for(let e=0;e<a.length;e++){let d=b(a[e]);null!==d&&c.push(d)}return c};exports.$findMatchingParent=t;exports.$getNearestBlockElementAncestorOrThrow=function(a){let b=t(a,c=>n.$isElementNode(c)&&!c.isInline());n.$isElementNode(b)||p(4,a.__key);return b};exports.$getNearestNodeOfType=function(a,b){for(;null!=a;){if(a instanceof b)return a;a=a.getParent()}return null};exports.$insertFirst=function(a,b){let c=a.getFirstChild();null!==c?c.insertBefore(b):a.append(b)};
-exports.$insertNodeToNearestRoot=function(a){var b=n.$getSelection()||n.$getPreviousSelection();if(n.$isRangeSelection(b)){var {focus:c}=b;b=c.getNode();c=c.offset;if(n.$isRootOrShadowRoot(b))c=b.getChildAtIndex(c),null==c?b.append(a):c.insertBefore(a),a.selectNext();else{let e,d;n.$isTextNode(b)?(e=b.getParentOrThrow(),d=b.getIndexWithinParent(),0<c&&(d+=1,b.splitText(c))):(e=b,d=c);[,b]=n.$splitNode(e,d);b.insertBefore(a);b.selectStart()}}else n.$isNodeSelection(b)||n.DEPRECATED_$isGridSelection(b)?
-(b=b.getNodes(),b[b.length-1].getTopLevelElementOrThrow().insertAfter(a)):n.$getRoot().append(a),b=n.$createParagraphNode(),a.insertAfter(b),b.select();return a.getLatest()};exports.$restoreEditorState=function(a,b){let c=new Map,e=a._pendingEditorState;for(let [d,f]of b._nodeMap){let h=g.$cloneWithProperties(f);n.$isTextNode(h)&&(h.__text=f.__text);c.set(d,h)}e&&(e._nodeMap=c);a._dirtyType=2;a=b._selection;n.$setSelection(null===a?null:a.clone())};
-exports.$wrapNodeInElement=function(a,b){b=b();a.replace(b);b.append(a);return b};exports.addClassNamesToElement=function(a,...b){b.forEach(c=>{"string"===typeof c&&(c=c.split(" ").filter(e=>""!==e),a.classList.add(...c))})};exports.isHTMLAnchorElement=function(a){return u(a)&&"A"===a.tagName};exports.isHTMLElement=u;exports.isMimeType=q;
-exports.mediaFileReader=function(a,b){let c=a[Symbol.iterator]();return new Promise((e,d)=>{let f=[],h=()=>{const {done:m,value:k}=c.next();if(m)return e(f);const l=new FileReader;l.addEventListener("error",d);l.addEventListener("load",()=>{const r=l.result;"string"===typeof r&&f.push({file:k,result:r});h()});q(k,b)?l.readAsDataURL(k):h()};h()})};exports.mergeRegister=function(...a){return()=>{a.forEach(b=>b())}};
-exports.objectKlassEquals=function(a,b){return null!==a?Object.getPrototypeOf(a).constructor.name===b.name:!1};
-exports.registerNestedElementResolver=function(a,b,c,e){return a.registerNodeTransform(b,d=>{a:{var f=d.getChildren();for(var h=0;h<f.length;h++)if(f[h]instanceof b){f=null;break a}for(f=d;null!==f;)if(h=f,f=f.getParent(),f instanceof b){f={child:h,parent:f};break a}f=null}if(null!==f){const {child:m,parent:k}=f;if(m.is(d)){e(k,d);d=m.getNextSiblings();f=d.length;k.insertAfter(m);if(0!==f){h=c(k);m.insertAfter(h);for(let l=0;l<f;l++)h.append(d[l])}k.canBeEmpty()||0!==k.getChildrenSize()||k.remove()}}})};
+'use strict';var g=require("@lexical/selection"),B=require("lexical");function C(a){let b=new URLSearchParams;b.append("code",a);for(let c=1;c<arguments.length;c++)b.append("v",arguments[c]);throw Error(`Minified Lexical error #${a}; visit https://lexical.dev/docs/error?${b} for the full message or `+"use the non-minified dev environment for full errors and additional helpful warnings.");}function D(...a){return()=>{a.forEach(b=>b())}}let E={attributes:!0,characterData:!0,childList:!0,subtree:!0};
+function F(a,b,c){function e(){if(null===h)throw Error("Unexpected null rootDOMNode");if(null===n)throw Error("Unexpected null parentDOMNode");let {left:p,top:z}=h.getBoundingClientRect();var q=n;let r=g.createRectsFromDOMRange(a,b);t.isConnected||q.append(t);q=!1;for(let x=0;x<r.length;x++){var w=r[x];let u=k[x]||document.createElement("div"),y=u.style;"absolute"!==y.position&&(y.position="absolute",q=!0);var l=`${w.left-p}px`;y.left!==l&&(y.left=l,q=!0);l=`${w.top-z}px`;y.top!==l&&(u.style.top=
+l,q=!0);l=`${w.width}px`;y.width!==l&&(u.style.width=l,q=!0);w=`${w.height}px`;y.height!==w&&(u.style.height=w,q=!0);u.parentNode!==t&&(t.append(u),q=!0);k[x]=u}for(;k.length>r.length;)k.pop();q&&c(k)}function d(){h=n=null;null!==m&&m.disconnect();m=null;t.remove();for(let p of k)p.remove();k=[]}function f(){let p=a.getRootElement();if(null===p)return d();let z=p.parentElement;if(!(z instanceof HTMLElement))return d();d();h=p;n=z;m=new MutationObserver(q=>{let r=a.getRootElement(),w=r&&r.parentElement;
+if(r!==h||w!==n)return f();for(let l of q)if(!t.contains(l.target))return e()});m.observe(z,E);e()}let h=null,n=null,m=null,k=[],t=document.createElement("div"),A=a.registerRootListener(f);return()=>{A();d()}}function G(a,b){for(let c of b)if(a.type.startsWith(c))return!0;return!1}function H(a,b){for(;a!==B.$getRoot()&&null!=a;){if(b(a))return a;a=a.getParent()}return null}exports.$splitNode=B.$splitNode;exports.isHTMLAnchorElement=B.isHTMLAnchorElement;exports.isHTMLElement=B.isHTMLElement;
+exports.$dfs=function(a,b){let c=[];a=(a||B.$getRoot()).getLatest();b=b||(B.$isElementNode(a)?a.getLastDescendant():a);for(var e=a,d=0;null!==(e=e.getParent());)d++;for(e=d;null!==a&&!a.is(b);)if(c.push({depth:e,node:a}),B.$isElementNode(a)&&0<a.getChildrenSize())a=a.getFirstChild(),e++;else for(d=null;null===d&&null!==a;)d=a.getNextSibling(),null===d?(a=a.getParent(),e--):a=d;null!==a&&a.is(b)&&c.push({depth:e,node:a});return c};
+exports.$filter=function(a,b){let c=[];for(let e=0;e<a.length;e++){let d=b(a[e]);null!==d&&c.push(d)}return c};exports.$findMatchingParent=H;exports.$getAncestor=function(a,b){for(;null!==a&&null!==a.getParent()&&!b(a);)a=a.getParentOrThrow();return b(a)?a:null};exports.$getNearestBlockElementAncestorOrThrow=function(a){let b=H(a,c=>B.$isElementNode(c)&&!c.isInline());B.$isElementNode(b)||C(4,a.__key);return b};
+exports.$getNearestNodeOfType=function(a,b){for(;null!=a;){if(a instanceof b)return a;a=a.getParent()}return null};exports.$insertFirst=function(a,b){let c=a.getFirstChild();null!==c?c.insertBefore(b):a.append(b)};
+exports.$insertNodeToNearestRoot=function(a){var b=B.$getSelection()||B.$getPreviousSelection();if(B.$isRangeSelection(b)){var {focus:c}=b;b=c.getNode();c=c.offset;if(B.$isRootOrShadowRoot(b))c=b.getChildAtIndex(c),null==c?b.append(a):c.insertBefore(a),a.selectNext();else{let e,d;B.$isTextNode(b)?(e=b.getParentOrThrow(),d=b.getIndexWithinParent(),0<c&&(d+=1,b.splitText(c))):(e=b,d=c);[,b]=B.$splitNode(e,d);b.insertBefore(a);b.selectStart()}}else B.$isNodeSelection(b)||B.DEPRECATED_$isGridSelection(b)?
+(b=b.getNodes(),b[b.length-1].getTopLevelElementOrThrow().insertAfter(a)):B.$getRoot().append(a),b=B.$createParagraphNode(),a.insertAfter(b),b.select();return a.getLatest()};exports.$restoreEditorState=function(a,b){let c=new Map,e=a._pendingEditorState;for(let [d,f]of b._nodeMap){let h=g.$cloneWithProperties(f);B.$isTextNode(h)&&(h.__text=f.__text);c.set(d,h)}e&&(e._nodeMap=c);a._dirtyType=2;a=b._selection;B.$setSelection(null===a?null:a.clone())};
+exports.$wrapNodeInElement=function(a,b){b=b();a.replace(b);b.append(a);return b};exports.INTERNAL_$isBlock=function(a){if(B.$isDecoratorNode(a)&&!a.isInline())return!0;if(!B.$isElementNode(a)||B.$isRootOrShadowRoot(a))return!1;var b=a.getFirstChild();b=null===b||B.$isLineBreakNode(b)||B.$isTextNode(b)||b.isInline();return!a.isInline()&&!1!==a.canBeEmpty()&&b};exports.addClassNamesToElement=function(a,...b){b.forEach(c=>{"string"===typeof c&&(c=c.split(" ").filter(e=>""!==e),a.classList.add(...c))})};
+exports.isMimeType=G;
+exports.markSelection=function(a,b){function c(m){m.read(()=>{var k=B.$getSelection();if(B.$isRangeSelection(k)){var {anchor:t,focus:A}=k;k=t.getNode();var p=k.getKey(),z=t.offset,q=A.getNode(),r=q.getKey(),w=A.offset,l=a.getElementByKey(p),x=a.getElementByKey(r);p=null===e||null===l||z!==d||p!==e.getKey()||k!==e&&(!(e instanceof B.TextNode)||k.updateDOM(e,l,a._config));r=null===f||null===x||w!==h||r!==f.getKey()||q!==f&&(!(f instanceof B.TextNode)||q.updateDOM(f,x,a._config));if(p||r){l=a.getElementByKey(t.getNode().getKey());
+var u=a.getElementByKey(A.getNode().getKey());if(null!==l&&null!==u&&"SPAN"===l.tagName&&"SPAN"===u.tagName){r=document.createRange();A.isBefore(t)?(p=u,x=A.offset,u=l,l=t.offset):(p=l,x=t.offset,l=A.offset);p=p.firstChild;if(null===p)throw Error("Expected text node to be first child of span");u=u.firstChild;if(null===u)throw Error("Expected text node to be first child of span");r.setStart(p,x);r.setEnd(u,l);n();n=F(a,r,y=>{for(let I of y){let v=I.style;"Highlight"!==v.background&&(v.background="Highlight");
+"HighlightText"!==v.color&&(v.color="HighlightText");"-1"!==v.zIndex&&(v.zIndex="-1");"none"!==v.pointerEvents&&(v.pointerEvents="none");"-1.5px"!==v.marginTop&&(v.marginTop="-1.5px");"4px"!==v.paddingTop&&(v.paddingTop="4px");"0px"!==v.paddingBottom&&(v.paddingBottom="0px")}void 0!==b&&b(y)})}}e=k;d=z;f=q;h=w}else h=f=d=e=null,n(),n=()=>{}})}let e=null,d=null,f=null,h=null,n=()=>{};c(a.getEditorState());return D(a.registerUpdateListener(({editorState:m})=>c(m)),n,()=>{n()})};
+exports.mediaFileReader=function(a,b){let c=a[Symbol.iterator]();return new Promise((e,d)=>{let f=[],h=()=>{const {done:n,value:m}=c.next();if(n)return e(f);const k=new FileReader;k.addEventListener("error",d);k.addEventListener("load",()=>{const t=k.result;"string"===typeof t&&f.push({file:m,result:t});h()});G(m,b)?k.readAsDataURL(m):h()};h()})};exports.mergeRegister=D;exports.objectKlassEquals=function(a,b){return null!==a?Object.getPrototypeOf(a).constructor.name===b.name:!1};
+exports.positionNodeOnRange=F;
+exports.registerNestedElementResolver=function(a,b,c,e){return a.registerNodeTransform(b,d=>{a:{var f=d.getChildren();for(var h=0;h<f.length;h++)if(f[h]instanceof b){f=null;break a}for(f=d;null!==f;)if(h=f,f=f.getParent(),f instanceof b){f={child:h,parent:f};break a}f=null}if(null!==f){const {child:n,parent:m}=f;if(n.is(d)){e(m,d);d=n.getNextSiblings();f=d.length;m.insertAfter(n);if(0!==f){h=c(m);n.insertAfter(h);for(let k=0;k<f;k++)h.append(d[k])}m.canBeEmpty()||0!==m.getChildrenSize()||m.remove()}}})};
 exports.removeClassNamesFromElement=function(a,...b){b.forEach(c=>{"string"===typeof c&&a.classList.remove(...c.split(" "))})}

package/index.d.ts

@@ -6,8 +6,11 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-import { $splitNode, EditorState, ElementNode, Klass, LexicalEditor, LexicalNode } from 'lexical';
-export { $splitNode };
+import { DecoratorNode, EditorState, ElementNode, Klass, LexicalEditor, LexicalNode } from 'lexical';
+export { default as markSelection } from './markSelection';
+export { default as mergeRegister } from './mergeRegister';
+export { default as positionNodeOnRange } from './positionNodeOnRange';
+export { $splitNode, isHTMLAnchorElement, isHTMLElement } from 'lexical';
 export type DFSNode = Readonly<{
     depth: number;
     node: LexicalNode;
@@ -90,30 +93,6 @@ export type DOMNodeToLexicalConversionMap = Record<string, DOMNodeToLexicalConve
  * @returns A parent node that matches the findFn parameters, or null if one wasn't found.
  */
 export declare function $findMatchingParent(startingNode: LexicalNode, findFn: (node: LexicalNode) => boolean): LexicalNode | null;
-type Func = () => void;
-/**
- * Returns a function that will execute all functions passed when called. It is generally used
- * to register multiple lexical listeners and then tear them down with a single function call, such
- * as React's useEffect hook.
- * @example
- * ```ts
- * useEffect(() => {
- *   return mergeRegister(
- *     editor.registerCommand(...registerCommand1 logic),
- *     editor.registerCommand(...registerCommand2 logic),
- *     editor.registerCommand(...registerCommand3 logic)
- *   )
- * }, [editor])
- * ```
- * In this case, useEffect is returning the function returned by mergeRegister as a cleanup
- * function to be executed after either the useEffect runs again (due to one of its dependencies
- * updating) or the compenent it resides in unmounts.
- * Note the functions don't neccesarily need to be in an array as all arguements
- * are considered to be the func argument and spread from there.
- * @param func - An array of functions meant to be executed by the returned function.
- * @returns the function which executes all the passed register command functions.
- */
-export declare function mergeRegister(...func: Array<Func>): () => void;
 /**
  * Attempts to resolve nested element nodes of the same type into a single node of that type.
  * It is generally used for marks/commenting
@@ -143,20 +122,10 @@ export declare function $insertNodeToNearestRoot<T extends LexicalNode>(node: T)
 /**
  * Wraps the node into another node created from a createElementNode function, eg. $createParagraphNode
  * @param node - Node to be wrapped.
- * @param createElementNode - Creates a new lexcial element to wrap the to-be-wrapped node and returns it.
- * @returns A new lexcial element with the previous node appended within (as a child, including its children).
+ * @param createElementNode - Creates a new lexical element to wrap the to-be-wrapped node and returns it.
+ * @returns A new lexical element with the previous node appended within (as a child, including its children).
  */
 export declare function $wrapNodeInElement(node: LexicalNode, createElementNode: () => ElementNode): ElementNode;
-/**
- * @param x - The element being tested
- * @returns Returns true if x is an HTML anchor tag, false otherwise
- */
-export declare function isHTMLAnchorElement(x: Node): x is HTMLAnchorElement;
-/**
- * @param x - The element being testing
- * @returns Returns true if x is an HTML element, false otherwise.
- */
-export declare function isHTMLElement(x: Node | EventTarget): x is HTMLElement;
 type ObjectKlass<T> = new (...args: any[]) => T;
 /**
  * @param object = The instance of the type
@@ -177,3 +146,9 @@ export declare function $filter<T>(nodes: Array<LexicalNode>, filterFn: (node: L
  * @param node Node that needs to be appended
  */
 export declare function $insertFirst(parent: ElementNode, node: LexicalNode): void;
+/**
+ * This function is for internal use of the library.
+ * Please do not use it as it may change in the future.
+ */
+export declare function INTERNAL_$isBlock(node: LexicalNode): node is ElementNode | DecoratorNode<unknown>;
+export declare function $getAncestor<NodeType extends LexicalNode = LexicalNode>(node: LexicalNode, predicate: (ancestor: LexicalNode) => ancestor is NodeType): NodeType | null;

package/markSelection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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';
+export default function markSelection(editor: LexicalEditor, onReposition?: (node: Array<HTMLElement>) => void): () => void;

package/mergeRegister.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ *
+ */
+type Func = () => void;
+/**
+ * Returns a function that will execute all functions passed when called. It is generally used
+ * to register multiple lexical listeners and then tear them down with a single function call, such
+ * as React's useEffect hook.
+ * @example
+ * ```ts
+ * useEffect(() => {
+ *   return mergeRegister(
+ *     editor.registerCommand(...registerCommand1 logic),
+ *     editor.registerCommand(...registerCommand2 logic),
+ *     editor.registerCommand(...registerCommand3 logic)
+ *   )
+ * }, [editor])
+ * ```
+ * In this case, useEffect is returning the function returned by mergeRegister as a cleanup
+ * function to be executed after either the useEffect runs again (due to one of its dependencies
+ * updating) or the component it resides in unmounts.
+ * Note the functions don't neccesarily need to be in an array as all arguements
+ * are considered to be the func argument and spread from there.
+ * @param func - An array of functions meant to be executed by the returned function.
+ * @returns the function which executes all the passed register command functions.
+ */
+export default function mergeRegister(...func: Array<Func>): () => void;
+export {};

package/package.json

@@ -8,15 +8,15 @@
     "utils"
   ],
   "license": "MIT",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "main": "LexicalUtils.js",
   "peerDependencies": {
-    "lexical": "0.12.1"
+    "lexical": "0.12.3"
   },
   "dependencies": {
-    "@lexical/list": "0.12.1",
-    "@lexical/table": "0.12.1",
-    "@lexical/selection": "0.12.1"
+    "@lexical/list": "0.12.3",
+    "@lexical/table": "0.12.3",
+    "@lexical/selection": "0.12.3"
   },
   "repository": {
     "type": "git",

package/positionNodeOnRange.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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';
+export default function positionNodeOnRange(editor: LexicalEditor, range: Range, onReposition: (node: Array<HTMLElement>) => void): () => void;

package/px.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 default function px(value: number): string;