utils/node_operations
library
Functions
-
appendChild(FNode parent, FNode newNode)
→ bool
-
Appends
newNode as the last child of parent.
-
childrenOf(FNode node)
→ List<FNode>
-
Returns the direct children of
node for any type, including
Root, FluentList, FluentTable/FluentRow.
It's the base function to use everywhere instead of direct getChildren().
-
cleanupEmptyInlineParents(Root root, FNode? node, {FluentDocument? document})
→ void
-
Removes empty Links and other inline wrappers that no longer contain
any text fragments after a deletion.
-
clearCellKeepingEmptyFragment(FluentCell cell, Root root)
→ void
-
Empties a cell by removing all children except an empty Paragraph.
Maintains the table structure preserving at least one empty paragraph
to allow the cursor to be positioned in the cell.
-
findAncestorCached<T extends FNode>(FluentDocument document, FNode node)
→ T?
-
O(depth) ancestor lookup using cached parent chain. Each step is O(1).
-
findById(FNode root, String id, {Map<String, FNode>? nodeIndex})
→ FNode?
-
Finds a node by ID in the entire tree.
If
nodeIndex is provided (e.g. document.nodeIndex), it is used
directly for an O(1) lookup instead of a full DFS traversal.
-
findFirstParagraph(FNode node)
→ Paragraph?
-
Returns the first Paragraph child of
node, or null if none.
-
findLastParagraph(FNode node)
→ Paragraph?
-
Returns the last Paragraph child of
node, or null if none.
-
findLogicalContainer(FNode root, String fragmentId, {Map<String, InlineContainerNode?>? logicalContainerCache})
→ InlineContainerNode?
-
Finds the first InlineContainerNode (Paragraph/ListItem/FluentCell)
that contains
fragmentId as a direct text descendant.
Link is transparent: its fragments belong to the parent container.
-
findNode(FNode root, bool test(FNode))
→ FNode?
-
Traverses ALL node types, including Root, FluentList, FluentTable
and ListItem with sublists.
-
findParent(FNode root, FNode target)
→ FNode?
-
Finds the direct parent of
target in the tree with root root.
Returns null if target is the root or not found.
-
findParentCached(FluentDocument document, FNode node)
→ FNode?
-
O(1) per step parent lookup using the document's cached parent map.
Returns the direct parent FNode of
node, or null if node is the root.
-
findPredecessorFragment(List<FNode> flat, int index)
→ Fragment?
-
Finds the nearest non-empty plain Fragment predecessor of the element at
index in flat. Returns null if none exists.
A "plain" Fragment is one that is not an InlineContainerNode.
-
flattenInlineChildren(InlineContainerNode container)
→ List<FNode>
-
Returns the "flat" list of children of
container in reading order,
expanding Links (transparent) into their fragments.
-
insertAfter(FNode parent, FNode sibling, FNode newNode)
→ bool
-
Inserts
newNode as a child of parent after sibling.
Returns false if sibling is not a direct child of parent.
-
insertBefore(FNode parent, FNode sibling, FNode newNode)
→ bool
-
Inserts
newNode as a child of parent before sibling.
-
insertFragmentAt(InlineContainerNode container, Fragment fragment, int index)
→ bool
-
Inserts
fragment in container at position index.
-
isContainerEmpty(InlineContainerNode container)
→ bool
-
Returns true if
container has no children or a single empty Fragment.
-
mergeConsecutiveLists(Root root)
→ void
-
Merges consecutive lists with the same listType in the document.
This ensures that if two bullet lists are adjacent, they become one list.
This should be called after operations that create or modify lists.
-
mergeConsecutiveListsInContainer(FNode container, Root root)
→ void
-
Merges consecutive lists with the same listType inside a specific container.
-
mergeWithNext(InlineContainerNode container, Fragment fragment)
→ bool
-
Merges
fragment with the Fragment immediately following in the container,
if it exists and if both have the same style.
Returns true if the merge occurred.
-
moveAfter(FNode root, FNode target, FNode sibling)
→ bool
-
Moves
target after sibling in the tree.
Equivalent to removeNode + insertAfter on the parent of sibling.
-
moveInlineChildren(Root root, InlineContainerNode source, InlineContainerNode target)
→ void
-
Moves all Fragment and Link children from
source to target.
-
outdentListItemToParagraph(Root root, FluentList listParent, ListItem currentItem, {FluentDocument? document})
→ Paragraph?
-
Outdent of a ListItem at the first level: transforms into paragraph.
Removes the item from the list, takes the first Paragraph as content,
and promotes the other children (images, tables, sublists) to the parent level.
Returns the created Paragraph or null if the operation fails.
-
pathTo(FNode root, FNode target)
→ List<FNode>?
-
Returns the path from the tree
root to target
as a list of nodes (including root and target).
Returns null if not found.
-
prependChild(FNode parent, FNode newNode)
→ bool
-
Prepends
newNode as the first child of parent.
-
pruneEmptyContainers(FNode node, Root root)
→ void
-
Cleans
node from the document if it's an empty InlineContainerNode.
Climbs the tree and repeats if necessary (ex pruneEmpty).
-
pruneEmptyFragments(InlineContainerNode container)
→ void
-
Removes empty Fragments from
container (text == '').
Always leaves at least one Fragment to keep the container valid.
-
recalculateListIndices(Root root)
→ void
-
Recalculates the indices of all lists in the document.
Updates indexList for each ListItem based on hierarchical position.
-
recalculateListIndicesFor(Root root, Set<FNode> affectedNodes, {FluentDocument? document})
→ void
-
Recalculates list indices only for lists that contain any of the
given
affectedNodes (or their ancestors). This avoids walking the
entire document tree when only a subset of lists changed.
-
removeFragment(InlineContainerNode container, Fragment fragment)
→ bool
-
Removes
fragment from container. Returns false if not present.
-
removeNode(FNode root, FNode target)
→ bool
-
Removes
target from the tree with root root.
Returns false if not found or if it's the root itself.
-
replaceNode(FNode root, FNode old, FNode replacement)
→ bool
-
Replaces
old with replacement in the tree with root root.
Returns false if old is not found.
-
resolveFragmentFromCursor(FNode? currentNode, int offset)
→ Fragment?
-
Resolves the actual Fragment from the cursor anchor node.
The anchor may be a Fragment directly, or an InlineContainerNode
whose child at
offset (or first Fragment child) is the target.
-
splitFragmentInContainer(InlineContainerNode container, Fragment fragment, int offset)
→ Fragment
-
Splits
fragment at offset and inserts the right part in the container
immediately after fragment. Returns the right Fragment.
-
walkTree(FNode root, bool visitor(FNode node, FNode? parent), {FNode? parent})
→ bool
-
Visits all nodes in DFS pre-order, calling
visitor on each.
If visitor returns false, stops the visit.
