fileList

Flat row list of files in a directory. Folders first (orange), then files (selected file highlighted). Stateless — caller passes the entries array [{name, isDirectory}] and a callback prefix; receives a scrollable vbox of clickable rows. Each click emits <onSelect>-<index> where index is 1-based into the original entries array, so the caller doesn't need a sorted-vs-original map.

Exports

• fileList(entries: { FileEntry }?, opts: FileListOpts?) -> WidgetNode — build a scrollable vbox of rows. Folders style differently from files; the selected file row is highlighted.

Types:

• FileEntry = { name: string, isDirectory: boolean? }
• FileListOpts = { id: string?, onSelect: string?, selectedKey: string?, sort: string?, maxHeight: number? }
• WidgetNode = { [string]: any }

Usage

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

return Z.fs.fileList(state.entries, {
    onSelect    = "files-row",
    selectedKey = state.selectedName,
    sort        = "dirs_first",   -- or "alpha"
})

app:on("^files%-row%-(%d+)$", function(_v, _id, idx)
    state.selectedName = state.entries[tonumber(idx)].name
end)

Notes

• Stateless. The caller owns the entries array and the selection key.
• The callback id carries an index (1-based) rather than the file name, so unusual characters in paths can't break the router.
• sort defaults to "dirs_first" (folders alphabetically, then files alphabetically). "alpha" ignores type. Any other value preserves the caller's order.
• An empty entries array produces a single (empty directory) label.