smelt.ui.layout¶
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.
Composable layout-tree primitives for the retained main TUI layout. smelt.ui.layout.set(fn) registers a composer; call invalidate() when closed-over state changes the resulting tree.
smelt.ui.layout.hbox¶
Horizontal container. items is an array of { child_layout, width = <constraint>, collapse_when_empty = bool? }. opts accepts border, title, gap, justify = "space-between", padding (uniform inner inset on all sides, inside any border).
smelt.ui.layout.invalidate¶
Invalidate the retained main layout so its composer runs during the next frame. Use this after changing closed-over state that affects layout structure or constraints.
smelt.ui.layout.leaf¶
Wrap a Win handle or paint id into a leaf node. opts accepts border, title, collapse_when_empty (force the slot to zero size when the wrapped window's buffer is empty), measure (a {w, h} table for a static natural size or a smelt.ui.layout.measure(...) handle for one the plugin can live-update).
smelt.ui.layout.measure¶
Types: smelt.ui.layout.Measure
Construct a shareable natural-size handle for use with smelt.ui.layout.leaf(opts.measure = ...). Initial size is (w, h) (default (0, 0)); update at any time via handle:set(w, h) to drive a live resize on the next frame. Read current size via handle:get().
smelt.ui.layout.set¶
Register the retained main layout composer. The callback receives a state table (term_w, term_h, prompt_input_rows, plus dialog while a root dialog is active) and returns a layout userdata built via smelt.ui.layout.{vbox,hbox,leaf}. state.dialog is an opaque transcript-dialog stage with host-owned sizing and expansion behavior. While a root dialog is active, the returned tree must include the current stage exactly once and no retained dialog stages from earlier calls; otherwise the host uses the safe transcript-dialog-statusline fallback. Passing nil clears the composer and reverts to the engine's hardcoded layout. The tree is retained until dimensions change or smelt.ui.layout.invalidate() is called.
smelt.ui.layout.vbox¶
Vertical container. items is an array of { child_layout, height = <constraint>, collapse_when_empty = bool? }. opts accepts border, title, gap (minimum cells between children), justify = "space-between" (put surplus cells into gaps), padding (uniform inner inset on all sides, inside any border).