fromFlat

Build the recursive node table Z.tree expects from a flat array of items where each item carries a parent link. Useful for ECS entity snapshots (each entity has parentId) and any other parent-pointer dataset.

Exports

• fromFlat(items, opts?) -> (roots, nodeById) — returns the array of root nodes and a stringified-id → node map. Module returns the builder function directly.

Types:

• FromFlatOpts = { idKey?, parentKey?, labelFn?, iconFn?, actionsFn?, expanded?, defaultExpanded? }
• TreeNode = { key, label, children?, payload, icon?, actions?, expanded? }

Usage

local fromFlat = require("@builtin::modules.zui.widget.tree.fromFlat")

local roots, byId = fromFlat(entities, {
    idKey           = "id",
    parentKey       = "parentId",
    labelFn         = function(e) return e.name or "#" .. e.id end,
    iconFn          = function(e) return e.children and "▣" or "·" end,
    expanded        = state.expanded,
    defaultExpanded = false,
})

Notes

• Items missing the id field are silently skipped — we cannot place them in the tree without a key, and crashing on bad data would kill the inspector.
• Items whose parentKey value isn't found in the input array are treated as roots, matching typical ECS behaviour where a filtered list may contain children whose parents were filtered out.
• The expanded map is consulted by stringified key first, then by the raw id; absent keys fall back to defaultExpanded.