Tree API Reference

API reference › The tree module

All 29 pages Everything on one page → Developer guide →

The tree module

modules/tree is an opt-in, standalone tree - expand, select, tri-state checkboxes and drag to reparent - built on the grid's own tree mode (see Tree data) rather than a hierarchy of its own: createTree configures one generated column, no header, no grid lines, its single visible column drawing the expander, an optional per-node icon, an optional checkbox and the label. Expansion, selection and drag-to-reparent are the grid's; this module's own surface is the data shape (flat parentKey rows or nested items), the tri-state checkbox rollup, and the thin tree.on event vocabulary a standalone tree is expected to speak.

import { createTree } from '@toclocoinc/lattice-grid/modules/tree';

const tree = createTree(document.querySelector('#tree'), {
  data: [
    { id: 1, label: 'Documents' },
    { id: 2, parentKey: 1, label: 'Report.docx' },
  ],
  checkboxes: true,
  selection: 'single',
  dragMode: 'both',
  open: [1],
});

Two data shapes, the grid's own. data is flat rows each naming its parent by parentKey (default field name 'parentKey', default id field 'id'); items is the same tree nested under a childrenField array (default 'children') and is flattened once, on construction. A node's label comes from labelField (default 'label') or a template(node) function, which wins when given.

Checkboxes are tri-state and roll up. With checkboxes: true, checking or unchecking a node checks or unchecks every node under it - the usual tree-checkbox convention - and every ancestor's own box repaints to 'checked' when every descendant leaf is, 'unchecked' when none are, and 'mixed' (drawn indeterminate) otherwise. getChecked() lists the ids whose rolled-up state is fully checked; a mixed branch is never among them.

Drag to reparent is two already-shipped grid primitives, not a third drag implementation. dragMode ('source', 'target' or 'both'; false, the default, leaves the handle undrawn) turns on the grid's own rowReorder over a field-form tree.parentKey, which drops on the upper or lower quarter of a node as a new sibling before or after it, and on the middle half as that node's new last child - see Drag to reparent for the mechanism itself, shared with a plain grid's tree. A node cannot be dropped into one of its own descendants; the drop is refused outright, before any data changes.

Lazy children. hasChildren(node) draws an expander for a branch not yet in the data, and loadChildren(node, signal) fetches it the first time it is opened - fetched once, aborted through signal if closed before it resolves, the same contract as the grid's own tree.loadChildren.

The data API, selection and the checkbox rollup, executed

A four-node tree, a collapse/re-expand, a selection, a checkbox rollup through a mixed state to fully checked, an added node read back through every data method, and a removal that leaves the hierarchy consistent - run headless on every build with the suite's own DOM test double, since this module always needs a real element and createGrid behind it.

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { createTree } = await import('../packages/modules/tree/index.js');

const seen = [];
const host = createTestDom().root;
const tree = createTree(host, {
  data: [
    { id: '1', label: 'Documents' },
    { id: '2', parentKey: '1', label: 'Report.docx' },
    { id: '3', parentKey: '1', label: 'Budget.xlsx' },
    { id: '4', label: 'Photos' },
  ],
  checkboxes: true,
  selection: 'single',
  open: ['1'],
});
tree.on('expand', (e) => seen.push(`expand:${e.id}`));
tree.on('collapse', (e) => seen.push(`collapse:${e.id}`));
tree.on('selectionChange', (e) => seen.push(`sel:${e.ids.join(',')}`));
tree.on('check', (e) => seen.push(`check:${e.id}:${e.checked}`));

tree.collapse('1');
tree.expand('1');
tree.select('2');
const selected = tree.getSelected().join(',');

tree.check('2');
const mixedCheck = tree.getChecked().join(',');            // '2' -- '1' is mixed, '3' unchecked
tree.check('3');
const rolledUp = tree.getChecked().join(',');             // '1,2,3' -- both children checked rolls '1' up

tree.data.add({ id: '5', label: 'Appendix.docx' }, '2');
const childrenOf2 = tree.data.getChildren('2').join(',');
tree.data.update('5', { label: 'Appendix (final).docx' });
const updatedLabel = tree.data.getItem('5').label;
const parentOf5 = tree.data.getParentId('5');

tree.data.remove('3');
const rootsNow = tree.data.getChildren().join(',');
const nested = tree.data.serialize('1').map((n) => n.id).join(',');

tree.destroy();
return [selected, mixedCheck, rolledUp, childrenOf2, updatedLabel, parentOf5, rootsNow, nested, seen.join('|')].join(' || ');

Nested items, a label template, a per-node icon and initial checks, executed

The other data shape: items nested under childrenField, flattened once on construction. template wins over labelField when both are given; icon and dragMode are per-node and drag config a headless run cannot show on screen, so this only proves they are accepted and read.

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { createTree } = await import('../packages/modules/tree/index.js');

const host = createTestDom().root;
const tree = createTree(host, {
  items: [
    { id: 'a', name: 'Root', children: [{ id: 'b', name: 'Child' }] },
  ],
  childrenField: 'children',
  labelField: 'name',           // loses to template, below, when both are given
  template: (node) => `#${node.id}`,
  icon: (node) => (node.id === 'a' ? 'folder' : 'file'),
  checked: ['b'],                // rolls 'a' up to fully checked too
  dragMode: 'source',
});

const nestedBack = tree.data.serialize().map((n) => n.name).join(',');   // Root
const childChecked = tree.getChecked().join(',');                        // a,b
tree.destroy();
return `${nestedBack} | ${childChecked}`;

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The tree module

TreeModuleConfig

The configuration for {@link createTree}. Built on the grid's own tree mode (one generated column, no header, no grid lines) rather than a hierarchy of its own - `data`/`items`, `key`, `parentKey` and `childrenField` describe the same two row shapes `GridConfig.tree` reads from a plain grid.

TreeDataApi

`tree.data`: add, remove, change and read nodes, and read the hierarchy back out.

TreeItemEvent

The payload `itemClick`, `itemDoubleClick`, `expand` and `collapse` all carry.

TreeCheckEvent

The `check` payload: a node's own checkbox was explicitly set, independently of what its rolled-up state then reads as.

TreeSelectionChangeEvent

The `selectionChange` payload.

TreeBeforeDropEvent

The cancellable `beforeDrop` payload: a node is about to be dropped before, after or inside another. Call `preventDefault(reason?)` (or return `false`) to veto, leaving the node exactly where it was.

TreeAfterDropEvent

The `afterDrop` payload: a drop that was not vetoed has committed.

TreeItemContextMenuEvent

The `itemContextMenu` payload: a right-click on a node (and the context-menu key on a focused one).

TreeEventPayloads

The payload each tree event name carries.

Tree

The tree instance {@link createTree} returns.

Properties

Methods

Events

This surface raises events, but the names are not declared: on() accepts any string. They cannot be listed here until the declaration names them.