router

Layer 4 callback router for Z.app. Pattern-matched dispatch with auto-data.value extraction and a one-shot warning on unhandled ids so authors find stale callbacks during iteration. Each router instance owns its own handler map, pattern list, and warning gate.

Exports

• Router.create() -> RouterInstance — make a fresh router.
• Router:on(idOrPattern: string, handler: Handler) -> RouterInstance — register a handler; patterns are auto-detected.
• Router:cb(id: string, handler: Handler) -> string — inline-register shorthand; returns the id so it can be bound to a widget in one expression.
• Router:dispatch(callbackId: string, data: any?) -> boolean — look up and invoke a handler; logs a one-shot warning on unhandled ids.
• Router:_resetWarnings() — test-only: clear the unhandled-id warning gate.
• Router:_wasWarned(id: string) -> boolean — test-only: query whether an id has been warned.

Types:

• Handler = (value: any, callbackId: string, ...any) -> ()
• RouterInstance — the metatable-bound router object.

Usage

local Router = require("@builtin::modules.zui.router")
local router = Router.create()

router:on("save:click", function(value, id) end)
router:on("cell:%d+:%d+", function(value, id, row, col) end)
router:dispatch("save:click", data)

Notes

• Pattern detection is heuristic: strings containing any of % ( ) [ ] + * ? ^ $ . are treated as Lua patterns. - is excluded because it is common in literal ids ("system-tools-tab-entities").
• Handlers receive (value, callbackId, ...captures). value is pre-extracted via Utils.eventValue(data) so handlers don't unwrap data manually.
• Unhandled ids log Warn exactly once per id; subsequent dispatches of the same id are silent so a per-frame fired callback doesn't drown the log.