popup

Anchored floating popup. Wraps egui::Popup (added 0.32). Pins itself to a referenced widget's rect — useful for button-anchored dropdowns, autocompletes, callouts. The anchor MUST render before the popup in the tree, otherwise the rect lookup misses and the popup silently does not paint.

Exports

• popup(opts: Opts?) -> any — build the popup widget node. Returned directly by the module.

Types:

• Opts = { id?, anchor: string, pivot?, open?, onDismiss?, focusable?, children?, props?, style? }

Usage

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

Z.btn("Save", "saveBtn"),
popup({
    anchor   = "saveBtn",
    open     = state.popupOpen,
    onDismiss = "save:popup-dismiss",
    children = {
        Z.btn("PNG", "save:png"),
        Z.btn("JPG", "save:jpg"),
    },
})

Notes

• The anchor is required — the wrapper asserts and errors loudly on nil rather than silently failing.
• Pivot maps to egui's RectAlign: "belowLeft" → BOTTOM_START (default), "belowRight" → BOTTOM_END, "aboveLeft" → TOP_START, "aboveRight" → TOP_END.
• Auto-dismiss fires onDismiss on click-outside / Escape so the caller can mirror the new state. Falls back to <id>-dismiss if onDismiss is omitted.
• The Lua-facing key is anchor; the underlying Rust prop is anchorTo (egui already claims anchor for an enum). The wrapper bridges the two names automatically.