utils

Formatting and dispatch helpers shared across zui layers. Anything domain-agnostic and useful both inside zui and to library consumers goes here — numeric formatting (WASM-safe, no string.format dependency), stable hierarchical widget id construction, callback payload unwrap, and small list comprehensions.

Exports

• M.round(v: number?, decimals: number?) -> number — round to decimals places (default 2). nil → 0.
• M.fmt(v: number?, decimals: number?) -> string — tostring(round(v, decimals)).
• M.fmtVec3(vec: Vec3Array?, decimals: number?) -> string — format {x, y, z} as "(x, y, z)".
• M.id(parent: any, child: any) -> string — stable widget id ("parent/child"); empty parent drops the prefix.
• M.eventValue(data: EventEnvelope?) -> any — unwrap data.value from v2 event envelopes; pass through raw payloads (nil returns nil).
• M.map(items: { any }?, fn: (any, number) -> any?) -> { any } — map and drop nils.
• M.when(cond: any, widget: any) -> any — widget if cond, else nil. Pairs with compact.
• M.compact(widgets: { any }?) -> { any } — drop nil entries.

Types:

• Vec3Array = { number } — array form, { x, y, z }.
• EventEnvelope = { value: any? } | any

Usage

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

Utils.round(1.2345)         -- 1.23
Utils.fmt(1.2345, 1)        -- "1.2"
Utils.fmtVec3({1, 2, 3})    -- "(1.00, 2.00, 3.00)"
Utils.id("toolbar", "save") -- "toolbar/save"

local rows = Utils.map(items, function(r) return Z.lbl(r.name) end)
local kids = Utils.compact{ Z.lbl("a"), Utils.when(showFoo, Z.lbl("foo")) }

Notes

• Pure module — no engine calls, no module state. Safe to call from any context.
• round / fmt / fmtVec3 are WASM-safe; they avoid string.format for the rounding step and use repeated multiplication for 10^n.
• eventValue is the canonical onCallback unwrap — preferred over manual data.value access because it transparently handles the older raw-payload flow too.
• map / compact / when are the canonical list comprehensions; demos rely on the nil filtering for conditional widgets.