state

Reactive state container for Z.app. Backs the Layer 3 example in docs/specs/ui-v3-architecture.md — state:default(...), state.nodes, state:set("size", n), etc. Writes via the data-store path (state.foo = bar) or the method path (state:set("foo", bar)) both auto-mark the owning App dirty.

Exports

• State.create(initial: { [string]: any }?, app: App?) -> StateInstance — make a new container.
• Instance methods (also reachable via reactive state.foo = bar writes):
  • state:default(initial) — write only keys not already present; idempotent. Does NOT mark dirty.
  • state:get(key) — typed read of a data-store key.
  • state:set(key, value) — write one key; marks dirty on change.
  • state:update(updates) — bulk write; single dirty-mark per call.
  • state:all() — return the raw data-store table.

Types:

• App = { markDirty: ((App) -> ())? } — minimum owning-App contract.
• StateInstance — the metatable-bound container; supports state.foo field access in addition to the methods.

Usage

local State = require("@builtin::modules.zui.state")
local s = State.create({ count = 0 }, app)
s:default({ size = 10 })   -- idempotent, no dirty mark
s.nodes = { ... }          -- reactive __newindex, marks dirty
s:set("count", 5)          -- method path, marks dirty

Notes

• The methods table is consulted by __index BEFORE the data store, so state:default resolves to the method even if a default data key exists.
• :default is a setup-time merge and intentionally does NOT mark the App dirty — it's safe to call inside an App.create builder.
• :update collapses multiple key writes into a single dirty-mark; use it in hot loops where the per-key __newindex path would mark dirty on every assignment.