Tree query & update functions

comins-table@0.2.2React

comins-table root imports.

CominsTreeNode

export type CominsTreeNode<TItem> = {
    children?: readonly CominsTreeNode<TItem>[];
    expand?: boolean;
    item: TItem;
};

item holds business data, children holds child nodes and expand overrides expansion per node. A node without children is a leaf. Objects and arrays are application-owned.

CominsTreeExpansionOptions

export type CominsTreeExpansionOptions = {
    defaultExpandAll?: boolean;
};

Core defaults to false. node.expand takes precedence. This differs from the React CominsTable defaultExpandAll default (true); pass the option explicitly for matching projections.

CominsVisibleTreeRow

export type CominsVisibleTreeRow<TItem> = {
    depth: number;
    expanded: boolean;
    hasChildren: boolean;
    item: TItem;
    path: readonly number[];
    rowId: CominsRowId;
};

depth starts at zero for roots; path is the child-index path in the original tree. rowId comes from getRowId and item references the original business object. expanded and hasChildren support expansion controls.

flattenCominsTree

export declare function flattenCominsTree<TItem>(nodes: readonly CominsTreeNode<TItem>[], getRowId: (item: TItem, index: number) => CominsRowId, options?: CominsTreeExpansionOptions): CominsVisibleTreeRow<TItem>[];

Returns nodes on expanded paths in depth-first order. getRowId receives a depth-first index over the complete tree, including collapsed descendants. IDs are checked even in hidden descendants; duplicates throw. Returned items are not cloned.

getCominsTreeLeafItems

export declare function getCominsTreeLeafItems<TItem>(nodes: readonly CominsTreeNode<TItem>[]): TItem[];

Returns all leaf items regardless of expansion. Useful for Tree aggregation without double-counting parent values. Preserves original item references.

toggleCominsTreeNode

export declare function toggleCominsTreeNode<TItem>(nodes: readonly CominsTreeNode<TItem>[], rowId: CominsRowId, getRowId: (item: TItem, index: number) => CominsRowId, options?: CominsTreeExpansionOptions): CominsTreeNode<TItem>[];

Toggles the target expand flag from its effective value. Copies the affected path and preserves other references. A missing ID returns a shallow copy of the root array; duplicate IDs throw.

updateCominsTreeItem

export declare function updateCominsTreeItem<TItem>(nodes: readonly CominsTreeNode<TItem>[], rowId: CominsRowId, getRowId: (item: TItem, index: number) => CominsRowId, update: (item: TItem) => TItem): CominsTreeNode<TItem>[];

Applies update to the target item while preserving children and expand. Return a new item rather than mutating it. A missing ID returns a shallow root-array copy; duplicate IDs throw.

sortCominsTreeSiblings

export declare function sortCominsTreeSiblings<TItem>(nodes: readonly CominsTreeNode<TItem>[], compare: (left: TItem, right: TItem) => number): CominsTreeNode<TItem>[];

Recursively sorts each sibling array without changing parent-child relationships. Returns new nodes and arrays while preserving item references and expand flags. compare receives two items.

moveCominsTreeNode

export declare function moveCominsTreeNode<TItem>(nodes: readonly CominsTreeNode<TItem>[], rowId: CominsRowId, destination: CominsTreeMoveDestination, getRowId: (item: TItem, index: number) => CominsRowId, options?: {
    allowReparent?: boolean;
}): readonly CominsTreeNode<TItem>[];

Moves the complete subtree before beforeRowId under the destination parent, or appends when null. Reparenting requires allowReparent: true; defaults to sibling moves only. Invalid, cyclic and unchanged moves return the original array. Duplicate IDs throw. See drag constraints and destinations.