lexical - npm Package Compare versions

Comparing version 0.25.1-nightly.20250221.0 to 0.25.1-nightly.20250224.0

caret/LexicalCaret.d.ts

@@ -9,3 +9,3 @@ /**
 import type { LexicalNode } from '../LexicalNode';
-import { type ElementNode } from '../nodes/LexicalElementNode';
+import { ElementNode } from '../nodes/LexicalElementNode';
 import { TextNode } from '../nodes/LexicalTextNode';
@@ -464,2 +464,79 @@ /**
 export declare function makeStepwiseIterator<State, Stop, Value>(config: StepwiseIteratorConfig<State, Stop, Value>): IterableIterator<Value>;
+/**
+ * A total ordering for `PointCaret<'next'>`, based on
+ * the same order that a {@link CaretRange} would iterate
+ * them.
+ *
+ * For a given origin node:
+ * - ChildCaret comes before SiblingCaret
+ * - TextPointCaret comes before SiblingCaret
+ *
+ * An exception is thrown when a and b do not have any
+ * common ancestor.
+ *
+ * This ordering is a sort of mix of pre-order and post-order
+ * because each ElementNode will show up as a ChildCaret
+ * on 'enter' (pre-order) and a SiblingCaret on 'leave' (post-order).
+ *
+ * @param a
+ * @param b
+ * @returns -1 if a comes before b, 0 if a and b are the same, or 1 if a comes after b
+ */
+export declare function $comparePointCaretNext(a: PointCaret<'next'>, b: PointCaret<'next'>): -1 | 0 | 1;
+/**
+ * Return the ordering of siblings in a CommonAncestorResultBranch
+ * @param branch Returns -1 if a precedes b, 1 otherwise
+ */
+export declare function $getCommonAncestorResultBranchOrder<A extends LexicalNode, B extends LexicalNode>(compare: CommonAncestorResultBranch<A, B>): -1 | 1;
+/**
+ * The two compared nodes are the same
+ */
+export interface CommonAncestorResultSame<A extends LexicalNode> {
+    readonly type: 'same';
+    readonly commonAncestor: A;
+}
+/**
+ * Node a was a descendant of node b, and not the same node
+ */
+export interface CommonAncestorResultDescendant<B extends ElementNode> {
+    readonly type: 'descendant';
+    readonly commonAncestor: B;
+}
+/**
+ * Node a is an ancestor of node b, and not the same node
+ */
+export interface CommonAncestorResultAncestor<A extends ElementNode> {
+    readonly type: 'ancestor';
+    readonly commonAncestor: A;
+}
+/**
+ * Node a and node b have a common ancestor but are on different branches,
+ * the `a` and `b` properties of this result are the ancestors of a and b
+ * that are children of the commonAncestor. Since they are siblings, their
+ * positions are comparable to determine order in the document.
+ */
+export interface CommonAncestorResultBranch<A extends LexicalNode, B extends LexicalNode> {
+    readonly type: 'branch';
+    readonly commonAncestor: ElementNode;
+    /** The ancestor of `a` that is a child of `commonAncestor`  */
+    readonly a: A | ElementNode;
+    /** The ancestor of `b` that is a child of `commonAncestor`  */
+    readonly b: B | ElementNode;
+}
+/**
+ * The result of comparing two nodes that share some common ancestor
+ */
+export type CommonAncestorResult<A extends LexicalNode, B extends LexicalNode> = CommonAncestorResultSame<A> | CommonAncestorResultAncestor<A & ElementNode> | CommonAncestorResultDescendant<B & ElementNode> | CommonAncestorResultBranch<A, B>;
+/**
+ * Find a common ancestor of a and b and return a detailed result object,
+ * or null if there is no common ancestor between the two nodes.
+ *
+ * The result object will have a commonAncestor property, and the other
+ * properties can be used to quickly compare these positions in the tree.
+ *
+ * @param a A LexicalNode
+ * @param b A LexicalNode
+ * @returns A comparison result between the two nodes or null if they have no common ancestor
+ */
+export declare function $getCommonAncestor<A extends LexicalNode, B extends LexicalNode>(a: A, b: B): null | CommonAncestorResult<A, B>;
 export {};

index.d.ts

@@ -8,4 +8,4 @@ /**
  */
-export type { BaseCaret, CaretDirection, CaretRange, CaretType, ChildCaret, FlipDirection, NodeCaret, PointCaret, RootMode, SiblingCaret, StepwiseIteratorConfig, TextPointCaret, TextPointCaretSlice, TextPointCaretSliceTuple, } from './caret/LexicalCaret';
-export { $extendCaretToRange, $getAdjacentChildCaret, $getCaretRange, $getChildCaret, $getChildCaretOrSelf, $getSiblingCaret, $getTextNodeOffset, $getTextPointCaret, $getTextPointCaretSlice, $isChildCaret, $isNodeCaret, $isSiblingCaret, $isTextPointCaret, $isTextPointCaretSlice, flipDirection, makeStepwiseIterator, } from './caret/LexicalCaret';
+export type { BaseCaret, CaretDirection, CaretRange, CaretType, ChildCaret, CommonAncestorResult, CommonAncestorResultAncestor, CommonAncestorResultBranch, CommonAncestorResultDescendant, CommonAncestorResultSame, FlipDirection, NodeCaret, PointCaret, RootMode, SiblingCaret, StepwiseIteratorConfig, TextPointCaret, TextPointCaretSlice, TextPointCaretSliceTuple, } from './caret/LexicalCaret';
+export { $comparePointCaretNext, $extendCaretToRange, $getAdjacentChildCaret, $getCaretRange, $getChildCaret, $getChildCaretOrSelf, $getCommonAncestor, $getCommonAncestorResultBranchOrder, $getSiblingCaret, $getTextNodeOffset, $getTextPointCaret, $getTextPointCaretSlice, $isChildCaret, $isNodeCaret, $isSiblingCaret, $isTextPointCaret, $isTextPointCaretSlice, flipDirection, makeStepwiseIterator, } from './caret/LexicalCaret';
 export { $caretFromPoint, $caretRangeFromSelection, $getAdjacentSiblingOrParentSiblingCaret, $getCaretInDirection, $getCaretRangeInDirection, $getChildCaretAtIndex, $normalizeCaret, $removeTextFromCaretRange, $rewindSiblingCaret, $setPointFromCaret, $setSelectionFromCaretRange, $updateRangeSelectionFromCaretRange, } from './caret/LexicalCaretUtils';
@@ -12,0 +12,0 @@ export type { PasteCommandType } from './LexicalCommands';

LexicalNode.d.ts

@@ -217,2 +217,4 @@ /**
     /**
+     * @deprecated use {@link $getCommonAncestor}
+     *
      * Returns the closest common ancestor of this node and the provided one or null
@@ -232,4 +234,10 @@ * if one cannot be found.
     /**
-     * Returns true if this node logical precedes the target node in the editor state.
+     * Returns true if this node logically precedes the target node in the
+     * editor state, false otherwise (including if there is no common ancestor).
      *
+     * Note that this notion of isBefore is based on post-order; a descendant
+     * node is always before its ancestors. See also
+     * {@link $getCommonAncestor} and {@link $comparePointCaretNext} for
+     * more flexible ways to determine the relative positions of nodes.
+     *
      * @param targetNode - the node we're testing to see if it's after this one.
@@ -239,3 +247,3 @@ */
     /**
-     * Returns true if this node is the parent of the target node, false otherwise.
+     * Returns true if this node is an ancestor of and distinct from the target node, false otherwise.
      *
@@ -242,0 +250,0 @@ * @param targetNode - the would-be child node.

LexicalSelection.d.ts

@@ -118,2 +118,7 @@ /**
      *
+     * See also the {@link CaretRange} APIs (starting with
+     * {@link $caretRangeFromSelection}), which are likely to provide a better
+     * foundation for any operation where partial selection is relevant
+     * (e.g. the anchor or focus are inside an ElementNode and TextNode)
+     *
      * @returns an Array containing all the nodes in the Selection
@@ -120,0 +125,0 @@ */

package.json

@@ -12,3 +12,3 @@ {
   "license": "MIT",
-  "version": "0.25.1-nightly.20250221.0",
+  "version": "0.25.1-nightly.20250224.0",
   "main": "Lexical.js",
@@ -15,0 +15,0 @@ "types": "index.d.ts",

No alert changes

Improved metrics

Total package byte prevSize

1340914

increased by1.23%

Lines of code

28212

increased by1.27%

No dependency changes