@lexical/selection 0.9.0 → 0.9.2

package/LexicalSelection.dev.js

@@ -48,6 +48,16 @@ function getDOMIndexWithinParent(node) {
 
   return [parent, Array.from(parent.childNodes).indexOf(node)];
 }
+/**
+ * Creates a selection range for the DOM.
+ * @param editor - The lexical editor.
+ * @param anchorNode - The anchor node of a selection.
+ * @param _anchorOffset - The amount of space offset from the anchor to the focus.
+ * @param focusNode - The current focus.
+ * @param _focusOffset - The amount of space offset from the focus to the anchor.
+ * @returns The range of selection for the DOM that was created.
+ */
+
 
 function createDOMRange(editor, anchorNode, _anchorOffset, focusNode, _focusOffset) {
   const anchorKey = anchorNode.getKey();
@@ -99,6 +109,13 @@ function createDOMRange(editor, anchorNode, _anchorOffset, focusNode, _focusOffs
 
   return range;
 }
+/**
+ * Creates DOMRects, generally used to help the editor find a specific location on the screen.
+ * @param editor - The lexical editor
+ * @param range - A fragment of a document that can contain nodes and parts of text nodes.
+ * @returns The selectionRects as an array.
+ */
+
 function createRectsFromDOMRange(editor, range) {
   const rootElement = editor.getRootElement();
 
@@ -134,6 +151,12 @@ function createRectsFromDOMRange(editor, range) {
 
   return selectionRects;
 }
+/**
+ * Creates an object containing all the styles and their values provided in the CSS string.
+ * @param css - The CSS string of styles and their values.
+ * @returns The styleObject containing all the styles and their values.
+ */
+
 function getStyleObjectFromRawCSS(css) {
   const styleObject = {};
   const styles = css.split(';');
@@ -148,6 +171,12 @@ function getStyleObjectFromRawCSS(css) {
 
   return styleObject;
 }
+/**
+ * Given a CSS string, returns an object from the style cache.
+ * @param css - The CSS property as a string.
+ * @returns The value of the given CSS property.
+ */
+
 function getStyleObjectFromCSS(css) {
   let value = CSS_TO_STYLES.get(css);
 
@@ -158,6 +187,12 @@ function getStyleObjectFromCSS(css) {
 
   return value;
 }
+/**
+ * Gets the CSS styles from the style object.
+ * @param styles - The style object containing the styles to get.
+ * @returns A string containing the CSS styles and their values.
+ */
+
 function getCSSFromStyleObject(styles) {
   let css = '';
 
@@ -195,6 +230,12 @@ function $updateTextNodeProperties(target, source) {
   target.__detail = source.__detail;
   return target;
 }
+/**
+ * Returns a copy of a node, but generates a new key for the copy.
+ * @param node - The node to be cloned.
+ * @returns The clone of the node.
+ */
+
 
 function $cloneWithProperties(node) {
   const latest = node.getLatest();
@@ -215,6 +256,14 @@ function $cloneWithProperties(node) {
 
   return clone;
 }
+/**
+ * Generally used to append text content to HTML and JSON. Grabs the text content and "slices"
+ * it to be generated into the new TextNode.
+ * @param selection - The selection containing the node whose TextNode is to be edited.
+ * @param textNode - The TextNode to be edited.
+ * @returns The updated TextNode.
+ */
+
 function $sliceSelectedTextNodeContent(selection, textNode) {
   if (textNode.isSelected() && !textNode.isSegmented() && !textNode.isToken() && (lexical.$isRangeSelection(selection) || lexical.DEPRECATED_$isGridSelection(selection))) {
     const anchorNode = selection.anchor.getNode();
@@ -251,6 +300,12 @@ function $sliceSelectedTextNodeContent(selection, textNode) {
 
   return textNode;
 }
+/**
+ * Determines if the current selection is at the end of the node.
+ * @param point - The point of the selection to test.
+ * @returns true if the provided point offset is in the last possible position, false otherwise.
+ */
+
 function $isAtNodeEnd(point) {
   if (point.type === 'text') {
     return point.offset === point.getNode().getTextContentSize();
@@ -258,6 +313,15 @@ function $isAtNodeEnd(point) {
 
   return point.offset === point.getNode().getChildrenSize();
 }
+/**
+ * Trims text from a node in order to shorten it, eg. to enforce a text's max length. If it deletes text
+ * that is an ancestor of the anchor then it will leave 2 indents, otherwise, if no text content exists, it deletes
+ * the TextNode. It will move the focus to either the end of any left over text or beginning of a new TextNode.
+ * @param editor - The lexical editor.
+ * @param anchor - The anchor of the current selection, where the selection should be pointing.
+ * @param delCount - The amount of characters to delete. Useful as a dynamic variable eg. textContentSize - maxLength;
+ */
+
 function trimTextContentFromAnchor(editor, anchor, delCount) {
   // Work from the current selection anchor point
   let currentNode = anchor.getNode();
@@ -381,6 +445,11 @@ function trimTextContentFromAnchor(editor, anchor, delCount) {
     }
   }
 }
+/**
+ * Gets the TextNode's style object and adds the styles to the CSS.
+ * @param node - The TextNode to add styles to.
+ */
+
 function $addNodeStyle(node) {
   const CSSText = node.getStyle();
   const styles = getStyleObjectFromRawCSS(CSSText);
@@ -403,6 +472,14 @@ function $patchStyle(target, patch) {
   target.setStyle(newCSSText);
   CSS_TO_STYLES.set(newCSSText, newStyles);
 }
+/**
+ * Applies the provided styles to the TextNodes in the provided Selection.
+ * Will update partially selected TextNodes by splitting the TextNode and applying
+ * the styles to the appropriate one.
+ * @param selection - The selected node(s) to update.
+ * @param patch - The patch to apply, which can include multiple styles. { CSSProperty: value }
+ */
+
 
 function $patchStyleText(selection, patch) {
   const selectedNodes = selection.getNodes();
@@ -517,11 +594,9 @@ function $patchStyleText(selection, patch) {
  *
  */
 /**
- * Converts all nodes in the selection that are of one block type to another specified by parameter
- *
- * @param selection
- * @param createElement
- * @returns
+ * Converts all nodes in the selection that are of one block type to another.
+ * @param selection - The selected blocks to be converted.
+ * @param createElement - The function that creates the node. eg. $createParagraphNode.
  */
 
 function $setBlocksType(selection, createElement) {
@@ -596,7 +671,13 @@ function $removeParentEmptyElements(startingNode) {
     node = parentNode;
   }
 }
-/** @deprecated */
+/**
+ * @deprecated
+ * Wraps all nodes in the selection into another node of the type returned by createElement.
+ * @param selection - The selection of nodes to be wrapped.
+ * @param createElement - A function that creates the wrapping ElementNode. eg. $createParagraphNode.
+ * @param wrappingElement - An element to append the wrapped selection and its children to.
+ */
 
 
 function $wrapNodes(selection, createElement, wrappingElement = null) {
@@ -643,6 +724,16 @@ function $wrapNodes(selection, createElement, wrappingElement = null) {
 
   $wrapNodesImpl(selection, descendants, descendants.length, createElement, wrappingElement);
 }
+/**
+ * Wraps each node into a new ElementNode.
+ * @param selection - The selection of nodes to wrap.
+ * @param nodes - An array of nodes, generally the descendants of the selection.
+ * @param nodesLength - The length of nodes.
+ * @param createElement - A function that creates the wrapping ElementNode. eg. $createParagraphNode.
+ * @param wrappingElement - An element to wrap all the nodes into.
+ * @returns
+ */
+
 function $wrapNodesImpl(selection, nodes, nodesLength, createElement, wrappingElement = null) {
   if (nodes.length === 0) {
     return;
@@ -803,22 +894,55 @@ function $wrapNodesImpl(selection, nodes, nodesLength, createElement, wrappingEl
     selection.dirty = true;
   }
 }
+/**
+ * Determines if the default character selection should be overridden. Used with DecoratorNodes
+ * @param selection - The selection whose default character selection may need to be overridden.
+ * @param isBackward - Is the selection backwards (the focus comes before the anchor)?
+ * @returns true if it should be overridden, false if not.
+ */
+
 function $shouldOverrideDefaultCharacterSelection(selection, isBackward) {
   const possibleNode = lexical.$getAdjacentNode(selection.focus, isBackward);
   return lexical.$isDecoratorNode(possibleNode) && !possibleNode.isIsolated() || lexical.$isElementNode(possibleNode) && !possibleNode.isInline() && !possibleNode.canBeEmpty();
 }
+/**
+ * Moves the selection according to the arguments.
+ * @param selection - The selected text or nodes.
+ * @param isHoldingShift - Is the shift key being held down during the operation.
+ * @param isBackward - Is the selection selected backwards (the focus comes before the anchor)?
+ * @param granularity - The distance to adjust the current selection.
+ */
+
 function $moveCaretSelection(selection, isHoldingShift, isBackward, granularity) {
   selection.modify(isHoldingShift ? 'extend' : 'move', isBackward, granularity);
 }
+/**
+ * Tests a parent element for right to left direction.
+ * @param selection - The selection whose parent is to be tested.
+ * @returns true if the selections' parent element has a direction of 'rtl' (right to left), false otherwise.
+ */
+
 function $isParentElementRTL(selection) {
   const anchorNode = selection.anchor.getNode();
   const parent = lexical.$isRootNode(anchorNode) ? anchorNode : anchorNode.getParentOrThrow();
   return parent.getDirection() === 'rtl';
 }
+/**
+ * Moves selection by character according to arguments.
+ * @param selection - The selection of the characters to move.
+ * @param isHoldingShift - Is the shift key being held down during the operation.
+ * @param isBackward - Is the selection backward (the focus comes before the anchor)?
+ */
+
 function $moveCharacter(selection, isHoldingShift, isBackward) {
   const isRTL = $isParentElementRTL(selection);
   $moveCaretSelection(selection, isHoldingShift, isBackward ? !isRTL : isRTL, 'character');
 }
+/**
+ * Expands the current Selection to cover all of the content in the editor.
+ * @param selection - The current selection.
+ */
+
 function $selectAll(selection) {
   const anchor = selection.anchor;
   const focus = selection.focus;
@@ -849,6 +973,13 @@ function $selectAll(selection) {
     focus.set(lastNode.getKey(), lastOffset, lastType);
   }
 }
+/**
+ * Returns the current value of a CSS property for Nodes, if set. If not set, it returns the defaultValue.
+ * @param node - The node whose style value to get.
+ * @param styleProperty - The CSS style property.
+ * @param defaultValue - The default value for the property.
+ * @returns The value of the property for node.
+ */
 
 function $getNodeStyleValueForProperty(node, styleProperty, defaultValue) {
   const css = node.getStyle();
@@ -860,6 +991,15 @@ function $getNodeStyleValueForProperty(node, styleProperty, defaultValue) {
 
   return defaultValue;
 }
+/**
+ * Returns the current value of a CSS property for TextNodes in the Selection, if set. If not set, it returns the defaultValue.
+ * If all TextNodes do not have the same value, it returns an empty string.
+ * @param selection - The selection of TextNodes whose value to find.
+ * @param styleProperty - The CSS style property.
+ * @param defaultValue - The default value for the property, defaults to an empty string.
+ * @returns The value of the property for the selected TextNodes.
+ */
+
 
 function $getSelectionStyleValueForProperty(selection, styleProperty, defaultValue = '') {
   let styleValue = null;

package/lexical-node.d.ts

@@ -6,9 +6,45 @@
  *
  */
 import type { GridSelection, LexicalEditor, LexicalNode, NodeSelection, Point, RangeSelection, TextNode } from 'lexical';
+/**
+ * Returns a copy of a node, but generates a new key for the copy.
+ * @param node - The node to be cloned.
+ * @returns The clone of the node.
+ */
 export declare function $cloneWithProperties<T extends LexicalNode>(node: T): T;
+/**
+ * Generally used to append text content to HTML and JSON. Grabs the text content and "slices"
+ * it to be generated into the new TextNode.
+ * @param selection - The selection containing the node whose TextNode is to be edited.
+ * @param textNode - The TextNode to be edited.
+ * @returns The updated TextNode.
+ */
 export declare function $sliceSelectedTextNodeContent(selection: RangeSelection | GridSelection | NodeSelection, textNode: TextNode): LexicalNode;
+/**
+ * Determines if the current selection is at the end of the node.
+ * @param point - The point of the selection to test.
+ * @returns true if the provided point offset is in the last possible position, false otherwise.
+ */
 export declare function $isAtNodeEnd(point: Point): boolean;
+/**
+ * Trims text from a node in order to shorten it, eg. to enforce a text's max length. If it deletes text
+ * that is an ancestor of the anchor then it will leave 2 indents, otherwise, if no text content exists, it deletes
+ * the TextNode. It will move the focus to either the end of any left over text or beginning of a new TextNode.
+ * @param editor - The lexical editor.
+ * @param anchor - The anchor of the current selection, where the selection should be pointing.
+ * @param delCount - The amount of characters to delete. Useful as a dynamic variable eg. textContentSize - maxLength;
+ */
 export declare function trimTextContentFromAnchor(editor: LexicalEditor, anchor: Point, delCount: number): void;
+/**
+ * Gets the TextNode's style object and adds the styles to the CSS.
+ * @param node - The TextNode to add styles to.
+ */
 export declare function $addNodeStyle(node: TextNode): void;
+/**
+ * Applies the provided styles to the TextNodes in the provided Selection.
+ * Will update partially selected TextNodes by splitting the TextNode and applying
+ * the styles to the appropriate one.
+ * @param selection - The selected node(s) to update.
+ * @param patch - The patch to apply, which can include multiple styles. { CSSProperty: value }
+ */
 export declare function $patchStyleText(selection: RangeSelection, patch: Record<string, string | null>): void;

package/package.json

@@ -9,10 +9,10 @@
     "selection"
   ],
   "license": "MIT",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "main": "LexicalSelection.js",
   "peerDependencies": {
-    "lexical": "0.9.0"
+    "lexical": "0.9.2"
   },
   "repository": {
     "type": "git",

package/range-selection.d.ts

@@ -7,19 +7,68 @@
  */
 import type { ElementNode, GridSelection, LexicalNode, RangeSelection } from 'lexical';
 /**
- * Converts all nodes in the selection that are of one block type to another specified by parameter
- *
- * @param selection
- * @param createElement
- * @returns
+ * Converts all nodes in the selection that are of one block type to another.
+ * @param selection - The selected blocks to be converted.
+ * @param createElement - The function that creates the node. eg. $createParagraphNode.
  */
 export declare function $setBlocksType(selection: RangeSelection | GridSelection, createElement: () => ElementNode): void;
-/** @deprecated */
+/**
+ * @deprecated
+ * Wraps all nodes in the selection into another node of the type returned by createElement.
+ * @param selection - The selection of nodes to be wrapped.
+ * @param createElement - A function that creates the wrapping ElementNode. eg. $createParagraphNode.
+ * @param wrappingElement - An element to append the wrapped selection and its children to.
+ */
 export declare function $wrapNodes(selection: RangeSelection | GridSelection, createElement: () => ElementNode, wrappingElement?: null | ElementNode): void;
+/**
+ * Wraps each node into a new ElementNode.
+ * @param selection - The selection of nodes to wrap.
+ * @param nodes - An array of nodes, generally the descendants of the selection.
+ * @param nodesLength - The length of nodes.
+ * @param createElement - A function that creates the wrapping ElementNode. eg. $createParagraphNode.
+ * @param wrappingElement - An element to wrap all the nodes into.
+ * @returns
+ */
 export declare function $wrapNodesImpl(selection: RangeSelection | GridSelection, nodes: LexicalNode[], nodesLength: number, createElement: () => ElementNode, wrappingElement?: null | ElementNode): void;
+/**
+ * Determines if the default character selection should be overridden. Used with DecoratorNodes
+ * @param selection - The selection whose default character selection may need to be overridden.
+ * @param isBackward - Is the selection backwards (the focus comes before the anchor)?
+ * @returns true if it should be overridden, false if not.
+ */
 export declare function $shouldOverrideDefaultCharacterSelection(selection: RangeSelection, isBackward: boolean): boolean;
+/**
+ * Moves the selection according to the arguments.
+ * @param selection - The selected text or nodes.
+ * @param isHoldingShift - Is the shift key being held down during the operation.
+ * @param isBackward - Is the selection selected backwards (the focus comes before the anchor)?
+ * @param granularity - The distance to adjust the current selection.
+ */
 export declare function $moveCaretSelection(selection: RangeSelection, isHoldingShift: boolean, isBackward: boolean, granularity: 'character' | 'word' | 'lineboundary'): void;
+/**
+ * Tests a parent element for right to left direction.
+ * @param selection - The selection whose parent is to be tested.
+ * @returns true if the selections' parent element has a direction of 'rtl' (right to left), false otherwise.
+ */
 export declare function $isParentElementRTL(selection: RangeSelection): boolean;
+/**
+ * Moves selection by character according to arguments.
+ * @param selection - The selection of the characters to move.
+ * @param isHoldingShift - Is the shift key being held down during the operation.
+ * @param isBackward - Is the selection backward (the focus comes before the anchor)?
+ */
 export declare function $moveCharacter(selection: RangeSelection, isHoldingShift: boolean, isBackward: boolean): void;
+/**
+ * Expands the current Selection to cover all of the content in the editor.
+ * @param selection - The current selection.
+ */
 export declare function $selectAll(selection: RangeSelection): void;
+/**
+ * Returns the current value of a CSS property for TextNodes in the Selection, if set. If not set, it returns the defaultValue.
+ * If all TextNodes do not have the same value, it returns an empty string.
+ * @param selection - The selection of TextNodes whose value to find.
+ * @param styleProperty - The CSS style property.
+ * @param defaultValue - The default value for the property, defaults to an empty string.
+ * @returns The value of the property for the selected TextNodes.
+ */
 export declare function $getSelectionStyleValueForProperty(selection: RangeSelection, styleProperty: string, defaultValue?: string): string;

package/utils.d.ts

@@ -6,8 +6,38 @@
  *
  */
 import type { LexicalEditor, LexicalNode } from 'lexical';
+/**
+ * Creates a selection range for the DOM.
+ * @param editor - The lexical editor.
+ * @param anchorNode - The anchor node of a selection.
+ * @param _anchorOffset - The amount of space offset from the anchor to the focus.
+ * @param focusNode - The current focus.
+ * @param _focusOffset - The amount of space offset from the focus to the anchor.
+ * @returns The range of selection for the DOM that was created.
+ */
 export declare function createDOMRange(editor: LexicalEditor, anchorNode: LexicalNode, _anchorOffset: number, focusNode: LexicalNode, _focusOffset: number): Range | null;
+/**
+ * Creates DOMRects, generally used to help the editor find a specific location on the screen.
+ * @param editor - The lexical editor
+ * @param range - A fragment of a document that can contain nodes and parts of text nodes.
+ * @returns The selectionRects as an array.
+ */
 export declare function createRectsFromDOMRange(editor: LexicalEditor, range: Range): Array<ClientRect>;
+/**
+ * Creates an object containing all the styles and their values provided in the CSS string.
+ * @param css - The CSS string of styles and their values.
+ * @returns The styleObject containing all the styles and their values.
+ */
 export declare function getStyleObjectFromRawCSS(css: string): Record<string, string>;
+/**
+ * Given a CSS string, returns an object from the style cache.
+ * @param css - The CSS property as a string.
+ * @returns The value of the given CSS property.
+ */
 export declare function getStyleObjectFromCSS(css: string): Record<string, string>;
+/**
+ * Gets the CSS styles from the style object.
+ * @param styles - The style object containing the styles to get.
+ * @returns A string containing the CSS styles and their values.
+ */
 export declare function getCSSFromStyleObject(styles: Record<string, string>): string;