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.frame¶
Wrap a subtree in optional border, title and padding. Natural size is the child's demand plus chrome; the child fills the inset area when the parent grows. Unlike a box slot, no fit/fill constraint is needed. Child chrome and shared split positions remain intact.
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.hsplit¶
fun(first: smelt.ui.layout, second: smelt.ui.layout, opts: smelt.ui.layout.SplitOpts?): smelt.ui.layout
Types: smelt.ui.layout.SplitOpts
Place two subtrees side by side with a draggable divider. Retain this node across composer calls to preserve sizing. For independently rebuilt children or direct size control, use layout.split("horizontal", opts) and handle:layout(first, second). win:resize("width", delta) targets the nearest enclosing horizontal split.
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.split¶
Types: smelt.ui.layout.SplitOpts, smelt.ui.layout.Split
Create a retained split handle independent of its children. axis is horizontal (side by side) or vertical (stacked). Use handle:layout(first, second, chrome_opts) in composers; rebuilding children preserves sizing. Handle methods inspect, restore, reset, resize, or equalize this exact split.
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).
smelt.ui.layout.vsplit¶
fun(first: smelt.ui.layout, second: smelt.ui.layout, opts: smelt.ui.layout.SplitOpts?): smelt.ui.layout
Types: smelt.ui.layout.SplitOpts
Stack two subtrees with a draggable divider. Retain this node across composer calls to preserve sizing. For independently rebuilt children or direct size control, use layout.split("vertical", opts) and handle:layout(first, second). win:resize("height", delta) targets the nearest enclosing vertical split.
smelt.ui.layout.windows¶
Types: smelt.win.Win
Return a layout's live window leaves in declaration order, excluding paints and repeated windows. Useful for installing shared callbacks and composing dialog bodies from arbitrary layouts.