@lexical/utils 0.8.1 → 0.9.1

package/LexicalUtils.dev.js

@@ -10,6 +10,15 @@ var selection = require('@lexical/selection');
 var lexical = require('lexical');
 
 /** @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
+ * eg. addClassNamesToElement(element, ['element-inner active', true, null])
+ * will add both 'element-inner' and 'active' as classes to that element.
+ * @param element - The element in which the classes are added
+ * @param classNames - An array defining the class names to add to the element
+ */
 function addClassNamesToElement(element, ...classNames) {
   classNames.forEach(className => {
     if (typeof className === 'string') {
@@ -18,6 +27,15 @@ 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
+ * eg. removeClassNamesFromElement(element, ['active small', true, null])
+ * will remove both the 'active' and 'small' classes from that element.
+ * @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') {
@@ -25,15 +43,24 @@ 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.
+ * eg. if file is of type 'text' and acceptableMimeTypes = ['TEXT', 'IMAGE'] the function will return false.
+ * @param file - The file you want to type check.
+ * @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
@@ -45,58 +72,81 @@ 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
+ * branch until you hit a dead-end (leaf) and backtracking to find the nearest branching path and repeat.
+ * It will then return all the nodes found in the search in an array of objects.
+ * @param startingNode - The node to start the search, if ommitted, it will start at the root node.
+ * @param endingNode - The node to end the search, if ommitted, it will find all descendants of the startingNode.
+ * @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--;
@@ -106,75 +156,151 @@ 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.
+ * @param node - the node to begin searching.
+ * @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
+ * passed as an argument. eg. if( (node) => node.__type === 'div') ) return true; otherwise return false
+ * @param startingNode - The node where the search starts.
+ * @param findFn - A testing function that returns true if the current node satisfies the testing parameters.
+ * @returns A parent node that matches the findFn parameters, or null if one wasn't found.
+ */
 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
+ * @param editor - The lexical editor
+ * @param targetNode - The target for the nested element to be extracted from.
+ * @param cloneNode - See {@link $createMarkNode}
+ * @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,
@@ -182,78 +308,110 @@ 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.
+ * If there is no selection where the node is to be inserted, it will be appended after any current nodes
+ * within the tree, as a child of the root node. A paragraph node will then be added after the inserted node and selected.
+ * @param node - The node to be inserted
+ * @returns The node after its insertion
+ */
+
 function $insertNodeToNearestRoot(node) {
   const selection = lexical.$getSelection();
+
   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);
@@ -262,6 +420,7 @@ function $insertNodeToNearestRoot(node) {
         splitNode = focusNode;
         splitOffset = focusOffset;
       }
+
       const [, rightTree] = lexical.$splitNode(splitNode, splitOffset);
       rightTree.insertBefore(node);
       rightTree.selectStart();
@@ -274,21 +433,40 @@ 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).
+ */
+
 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;

package/index.d.ts

@@ -12,8 +12,32 @@ export declare type DFSNode = Readonly<{
     depth: number;
     node: LexicalNode;
 }>;
+/**
+ * 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
+ * eg. addClassNamesToElement(element, ['element-inner active', true, null])
+ * will add both 'element-inner' and 'active' as classes to that element.
+ * @param element - The element in which the classes are added
+ * @param classNames - An array defining the class names to add to the element
+ */
 export declare function addClassNamesToElement(element: HTMLElement, ...classNames: Array<typeof undefined | boolean | null | string>): void;
+/**
+ * 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
+ * eg. removeClassNamesFromElement(element, ['active small', true, null])
+ * will remove both the 'active' and 'small' classes from that element.
+ * @param element - The element in which the classes are removed
+ * @param classNames - An array defining the class names to remove from the element
+ */
 export declare function removeClassNamesFromElement(element: HTMLElement, ...classNames: Array<typeof undefined | boolean | null | string>): void;
+/**
+ * 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.
+ * eg. if file is of type 'text' and acceptableMimeTypes = ['TEXT', 'IMAGE'] the function will return false.
+ * @param file - The file you want to type check.
+ * @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.
+ */
 export declare function isMimeType(file: File, acceptableMimeTypes: Array<string>): boolean;
 /**
  * Lexical File Reader with:
@@ -30,17 +54,106 @@ export declare function mediaFileReader(files: Array<File>, acceptableMimeTypes:
     file: File;
     result: string;
 }>>;
+/**
+ * "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
+ * branch until you hit a dead-end (leaf) and backtracking to find the nearest branching path and repeat.
+ * It will then return all the nodes found in the search in an array of objects.
+ * @param startingNode - The node to start the search, if ommitted, it will start at the root node.
+ * @param endingNode - The node to end the search, if ommitted, it will find all descendants of the startingNode.
+ * @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
+ */
 export declare function $dfs(startingNode?: LexicalNode, endingNode?: LexicalNode): Array<DFSNode>;
+/**
+ * Takes a node and traverses up its ancestors (toward the root node)
+ * in order to find a specific type of node.
+ * @param node - the node to begin searching.
+ * @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.
+ */
 export declare function $getNearestNodeOfType<T extends ElementNode>(node: LexicalNode, klass: Klass<T>): T | 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
+ */
 export declare function $getNearestBlockElementAncestorOrThrow(startNode: LexicalNode): ElementNode;
 export declare type DOMNodeToLexicalConversion = (element: Node) => LexicalNode;
 export declare type DOMNodeToLexicalConversionMap = Record<string, DOMNodeToLexicalConversion>;
+/**
+ * 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
+ * passed as an argument. eg. if( (node) => node.__type === 'div') ) return true; otherwise return false
+ * @param startingNode - The node where the search starts.
+ * @param findFn - A testing function that returns true if the current node satisfies the testing parameters.
+ * @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;
 declare 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
+ * @param editor - The lexical editor
+ * @param targetNode - The target for the nested element to be extracted from.
+ * @param cloneNode - See {@link $createMarkNode}
+ * @param handleOverlap - Handles any overlap between the node to extract and the targetNode
+ * @returns The lexical editor
+ */
 export declare function registerNestedElementResolver<N extends ElementNode>(editor: LexicalEditor, targetNode: Klass<N>, cloneNode: (from: N) => N, handleOverlap: (from: N, to: N) => void): () => void;
+/**
+ * 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
+ */
 export declare function $restoreEditorState(editor: LexicalEditor, editorState: EditorState): void;
+/**
+ * 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.
+ * If there is no selection where the node is to be inserted, it will be appended after any current nodes
+ * within the tree, as a child of the root node. A paragraph node will then be added after the inserted node and selected.
+ * @param node - The node to be inserted
+ * @returns The node after its insertion
+ */
 export declare function $insertNodeToNearestRoot<T extends LexicalNode>(node: T): 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).
+ */
 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;

package/package.json

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