Documentation
¶
Overview ¶
Package layout is a tiny declarative engine for composing Bubble Tea view strings. Every layout is a tree of Node; each Node knows how to render itself into a given geom.Rect. VStack and HStack split their allotment among Fixed- and Flex-sized children; ZStack overlays children.
The point is to remove hand-written "m.h-2" math from callers. You describe what goes where and let the stack engine divide the pixels.
Typical use:
root := layout.VStack(
layout.Fixed(1, layout.RenderFunc(func(r geom.Rect) string { ... })),
layout.Flex(1, body),
layout.Fixed(1, layout.RenderFunc(func(r geom.Rect) string { ... })),
)
return root.Render(geom.New(0, 0, termW, termH))
Rects, not sizes ¶
A Node receives a geom.Rect rather than a bare (width, height): it learns where it sits in absolute terminal coordinates, not merely how big it is. Components store the rect they were handed and use it to answer mouse events without any marker injection into the rendered string — see pkg/geom.
The root of a render calls geom.NextGen once per frame and seeds its rect with geom.New; every child inherits that generation as the rect propagates down. A nested root (pkg/tab rendering its active body's layout) must not call NextGen — it renders inside an existing frame and passes the generation from the rect it was given.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Item ¶
type Item struct {
// contains filtered or unexported fields
}
Item is a child of VStack or HStack. Construct with Fixed or Flex.
type Node ¶
Node is the unit of layout — something that can render itself into a given rect. Components participate by being wrapped in Sized (or any adapter that yields a Node).
func Bar ¶
Bar wraps a single-row component (breadcrumb.Model, statusbar.Model, …) as a Node. It behaves exactly as Sized — the name documents intent, since a bar is expected to sit in a Fixed(1, …) slot and render one row.
func Center ¶
Center renders child at its natural size (given by naturalW/naturalH) padded to the parent's rect with surrounding whitespace. Useful as the overlay layer inside a ZStack.
The child's rect is offset to where lipgloss.Place will actually draw it, so a centered modal hit-tests against its visible position rather than the parent's origin.
func Sized ¶
Sized wraps a component as a Node, handing it its rect at render time. Pass a pointer: &m.list, &m.body.
func ZStack ¶
ZStack layers overlay on top of base. Both are rendered into the full rect. Compositing happens cell-by-cell: cells that are spaces in the overlay pass the base through; non-space cells replace base at that column. Empty overlay rows pass through entirely.
In practice this means a centered modal drawn with Center(...) only blots out the modal's bounding box; pane borders and content to the left and right of the modal stay visible. Wide characters and ANSI styles are handled via x/ansi cell-aware cutting.
Both layers receive the same rect, so a component in the base still believes it owns cells the overlay covers. Occlusion is the host screen's job: while a modal is up, forward messages to the modal alone (see the confirm and alert examples) so the covered components never see the click.
type RenderFunc ¶
RenderFunc adapts a render-into-rect function into a Node. It is the escape hatch for content the component adapters don't cover: close over whatever you need, render at r.W by r.H, and return the string.
Source Files