Tree

Module Extensions

ColumnRegular (Extended from @revolist/revogrid)

interface ColumnRegular {
  /**
       * Enables tree template on cells
       */
      tree?: boolean
}

---

HTMLRevoGridElement (Extended from global)

interface HTMLRevoGridElement {
  tree?: TreeConfig
}

---

AdditionalData (Extended from @revolist/revogrid)

interface AdditionalData {
  /**
       * Additional data property tree
       * @deprecated Use `grid.tree` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.additionalData = {
       *   tree: {
       *     idField: 'id',
       *     parentIdField: 'parentId',
       *     rootParentId: null,
       *     expandAll: true,
       *     expandedRowIds: new Set(),
       *   },
       * };
       * ```
       */
      tree?: TreeConfig
}

---

HTMLRevoGridElementEventMap (Extended from global)

interface HTMLRevoGridElementEventMap {
  [TREE_ROW_SELECT_EVENT]: TreeRowSelectEvent;
  [TREE_TOGGLE_EVENT]: { rowId: any };
  [TREE_EXPAND_ALL_EVENT]: undefined;
  [TREE_COLLAPSE_ALL_EVENT]: undefined;
  [TREE_STATE_CHANGED_EVENT]: { expandedRowIds: Set<any> }
}

Plugin API

TreeDataPlugin

The TreeDataPlugin now uses Revogrid’s row trimming mechanism without modifying the original data.

All tree metadata (level, expanded, hasChildren, visible) is computed separately and stored in a Map. The plugin builds a parent→children mapping from the original flat data and then recursively computes, for each row, its tree level and whether it should be visible based on the expanded/collapsed state of its ancestors.

The cell template uses a supplied “getMeta” function to look up computed tree metadata for rendering (indentation and expand/collapse icons) without changing the underlying row.

Usage Example:

import { TreeDataPlugin } from './tree/index';

const grid = document.createElement('revo-grid');
grid.plugins = [TreeDataPlugin];

grid.columns = [
  {
    prop: 'treeColumn',
    name: 'Hierarchy',
    tree: true,
    cellTemplate: TreeCellTemplate, // or you can let the plugin override it
  },
];

Dependencies

• Event integration row-order: Integrates with RowOrderPlugin row order events to reparent tree rows after drag and drop.
• Event integration row-select: Integrates with RowSelectPlugin row selection events for parent and descendant selection.
• Event integration DimensionAnimationPlugin: Auto-installs DimensionAnimationPlugin when tree.animation is enabled to animate tree collapse and expand trim changes.

class TreeDataPlugin {
  /**
     * Recomputes the tree metadata for every row in the original data and builds a trimmed map.
     * Call this method after the original data/order/visibility/set changes
     *
     * This method builds a parent→children mapping (without modifying the original data) and then
     * recursively computes for each row:
     *  - its level (indentation),
     *  - whether it is expanded (based on the expandedRowIds set),
     *  - whether it has children,
     *  - and whether it should be visible (i.e. none of its ancestors are collapsed).
     *
     * The trimmed map is then applied via providers.data.setTrimmed().
     */
  async updateTree(type?: DimensionRows);

  /**
     * Toggle the expanded state for a row and then re-calculate tree metadata.
     */
  toggleRowExpanded(row: DataType);

  getExpandedRowIds();

  toggleRowExpandedById(rowId: any);

  expandAll();

  collapseAll();

  /**
     * Gets all descendant row IDs (children, grandchildren, etc.) for a given row
     * @param rowId - The ID of the row to get descendants for
     * @returns Array of physical indices of all descendant rows
     */
  public getAllDescendantPhysicalIndices(rowId: any, type: DimensionRows = 'rgRow'): number[];
}

---

TreeMeta

This is the shape of computed tree metadata. Notice that nothing is stored on the row itself.

interface TreeMeta {
  level: number;
  expanded: boolean;
  hasChildren: boolean;
  visible: boolean;
  parentId: any
}

---

TreeConfig

interface TreeConfig {
  idField?: string;
  parentIdField?: string;
  rootParentId?: any;
  expandAll?: boolean;
  expandedRowIds?: Set<any>;
  /**
     * Mark tree parent rows as sticky through StickyCellsPlugin.
     *
     * Parent detection uses the row model fields configured by `idField` and
     * `parentIdField`, plus tree metadata computed by TreeDataPlugin. It does not
     * depend on virtual row indexes.
     *
     * This option only adds sticky behavior to tree-enabled columns. Register
     * StickyCellsPlugin separately to render those parent rows in pinned top rows.
     *
     * @default false
     */
    stickyParents?: boolean;
  /**
     * Animate tree collapse and expand through DimensionAnimationPlugin.
     *
     * TreeDataPlugin auto-registers DimensionAnimationPlugin when this option is
     * enabled and the dimension animation plugin is not already registered.
     *
     * @default false
     */
    animation?: boolean
}

---

TreeRowSelectEvent

Event emitted when a tree row with children is selected. This event allows for custom handling of parent-child selection relationships.

interface TreeRowSelectEvent {
  /** The row type (e.g., 'rgRow') */
    type: DimensionRows;
  /** The physical index of the parent row in the source data */
    parentIndex: number;
  /** Array of physical indices of all descendant rows */
    childrenIndices: number[];
  /** The original row selection event that triggered this tree selection */
    originalEvent?: any
}

---

TreeSelectionProvider

Runtime contract exposed by TreeDataPlugin for plugins that need tree descendant lookup without depending on the TreeDataPlugin class.

interface TreeSelectionProvider {
  getAllDescendantPhysicalIndices(rowId: unknown, type: DimensionRows): number[]
}

---

TreeAnimationCoordinator

class TreeAnimationCoordinator {
  beginUpdate(type: DimensionRows): number;

  isCurrent(type: DimensionRows, version: number): boolean;

  canAnimate(type: DimensionRows, dimensionAnimation?: DimensionAnimationPlugin): dimensionAnimation is DimensionAnimationPlugin;

  markInitialized(type: DimensionRows, sourceLength: number);

  hasTrimChanges(
    currentTrimmed: Record<number, boolean>,
    nextTrimmed: Record<number, boolean>,
  ): boolean;

  async applyAnimatedTrim(;
}

---

TreeRowOrderController

class TreeRowOrderController {
  isParentUpdatePending(type: DimensionRows): boolean;

  handleDragEnd();

  handleDropValidation(context: RowOrderDropValidationContext): TreeDropValidation;

  handleRowDrop(e: CustomEvent<RowOrderChange>);

  highlightDropTarget(context: RowOrderDropStateChange);

  clearDropTarget();
}

---

isTreeRowType

export function isTreeRowType(type: unknown): type is DimensionRows;

---

resolveTreeTrimState

export function resolveTreeTrimState(
  allTrimmed: Record<string, Record<number, boolean>> =;

---

computeTreeState

export function computeTreeState(;

---

collectExpandableRowIds

export function collectExpandableRowIds(;

---

TRIMMED_COLLAPSED

TRIMMED_COLLAPSED: string;

---

TREE_ROW_TYPES

TREE_ROW_TYPES: DimensionRows[];

---

TreeState

export type TreeState = {
  itemParentOrder: number[];
  metaData: Map<any, TreeMeta>;
  rowMetaEntries: Array<[DataType, TreeMeta]>;
  trimmed: Record<number, boolean>;
};

---

TreeTrimState

export type TreeTrimState = {
  currentTreeTrimmed: Record<number, boolean>;
  outsideTrimmed: TrimmedEntity;
};

---

TreeRuntimeState

class TreeRuntimeState {
  setConfig(options: TreeConfig =;

  snapshotExpandedRowIds(): Set<any>;

  toggleExpanded(rowId: any);

  setExpandedRowIds(expandedRowIds: Set<any>);

  clearExpandedRowIds();

  setExpandAllPending(pending: boolean);
}

---

isNoopTreeDrop

export function isNoopTreeDrop(;

---

resolveTreeDropParentId

export function resolveTreeDropParentId(;

---

validateTreeRowDrop

export function validateTreeRowDrop(;

---

resolveTreeDropValidation

export function resolveTreeDropValidation(;

---

moveProxySubtreesAfterTarget

export function moveProxySubtreesAfterTarget(;

---

moveProxySubtreesToTarget

export function moveProxySubtreesToTarget(;

---

TreeCellTemplate

The TreeCellTemplate now receives an extra “getMeta” callback that provides the computed tree metadata for the given row. It does not assume that any tree information has been stored on the row itself.

TreeCellTemplate: (toggleRowExpanded: (data: DataType) => void, getMeta: (row: DataType) => TreeMeta) => CellTemplate<DataType<any, ColumnProp>>;

---

applyTreeStickyParentColumns

export function applyTreeStickyParentColumns(
  columnsByType: ColumnCollection['columns'],
  resolveStickyCell: (model: CellTemplateProp, stickyCell: StickyCellPredicate | undefined) => boolean,
);

---

resolveTreeStickyCell

export function resolveTreeStickyCell(
  model: CellTemplateProp,
  stickyCell: StickyCellPredicate | undefined,
  context: TreeStickyCellContext,
): boolean;

---

getStickyTreeConfig

export function getStickyTreeConfig(revogrid: HTMLRevoGridElement): TreeConfig | undefined;

---

resolveActiveTreeStickyRows

export function resolveActiveTreeStickyRows(;

---

TreeStickyCellContext

interface TreeStickyCellContext {
  config: TreeConfig | undefined;
  getMeta(row: DataType): TreeMeta
}

---

ActiveTreeStickyRowsContext

interface ActiveTreeStickyRowsContext {
  rowIndex: number;
  maxRows: number;
  config: TreeConfig;
  includeRow?: boolean;
  rowStore: {
      get(key: 'source'): DataType[];
      get(key: 'items'): number[];
    };
  resolveStickyColumns(rowIndex: number): boolean
}