tree

Folder tree composite. Wraps Z.tree with folder-friendly defaults: folder icon for directories, file icon for leaves, callback ids that carry the absolute path. Stateless — caller owns the recursive node table. Use this when you want a single deep tree of folders + files; for the classic two-pane ("folder tree | file list") layout, use this for the left pane and Z.fs.fileList for the right.

Exports

• tree(roots: { FsNode }?, opts: FsTreeOpts?) -> WidgetNode — build a recursive folder tree. Callback ids: <onSelect>-<path> (label click), <onToggle>-<path> (chevron click).

Types:

• FsNode = { name: string, path: string?, isDirectory: boolean?, children: { FsNode }?, expanded: boolean? }
• FsTreeOpts = { id: string?, onSelect: string?, onToggle: string?, selectedKey: string?, expanded: { [string]: boolean }?, basePath: string?, indentPx: number?, gap: number? }
• WidgetNode = { [string]: any }

Usage

local Z = require("@builtin::modules.zui")

return Z.fs.tree(state.roots, {
    onSelect    = "files-tree-select",
    onToggle    = "files-tree-toggle",
    selectedKey = state.selectedPath,
    expanded    = state.expandedSet,
})

app:on("^files%-tree%-select%-(.+)$", function(_v, _id, path)
    state.selectedPath = path
end)
app:on("^files%-tree%-toggle%-(.+)$", function(_v, _id, path)
    state.expandedSet[path] = not state.expandedSet[path]
end)

Notes

• Stateless. Caller owns selection, expansion, and on-demand listing (the onToggle handler is where you'd vfs.list and refill children for the next render).
• Folders without listed children (children == nil) still get a chevron via expandable = true. This is the lazy-load shape.
• basePath defaults to /. Used when an FsNode has no path — the recursive walk builds the absolute path on the fly.