layout

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 at a given (width, height). 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(w, h int) string { ... })),
    layout.Flex(1, body),
    layout.Fixed(1, layout.RenderFunc(func(w, h int) string { ... })),
)
return root.Render(termW, termH)

Index

• type Item
  • func Fixed(size int, node Node) Item
  • func Flex(weight int, node Node) Item
• type Node
  • func Bar(w Widther) Node
  • func Center(naturalW, naturalH int, child Node) Node
  • func HStack(items ...Item) Node
  • func Sized(s Sizer) Node
  • func VStack(items ...Item) Node
  • func ZStack(base, overlay Node) Node
• type RenderFunc
  • func (f RenderFunc) Render(w, h int) string
• type Sizer
• type Widther

Types

type Item

type Item struct {
	// contains filtered or unexported fields
}

Item is a child of VStack or HStack. Construct with Fixed or Flex.

func Fixed

func Fixed(size int, node Node) Item

Fixed reserves an exact number of cells (rows in VStack, columns in HStack) for node.

func Flex

func Flex(weight int, node Node) Item

Flex asks for a proportional share of the space remaining after all Fixed items are accounted for. Weight picks the share ratio: Flex(2, ...) + Flex(1, ...) gives the first twice as much as the second. A non-positive weight is clamped to 1.

type Node

type Node interface {
	Render(w, h int) string
}

Node is the unit of layout — something that can render itself at a given outer size. Components participate by being wrapped in RenderFunc (or any adapter that yields a Node).

func Bar

func Bar(w Widther) Node

Bar wraps a single-row component (breadcrumb.Model, statusbar.Model, …) as a Node. The height argument to Render is ignored — these components always render one row. Pass a pointer: &m.bc, &m.sb.

func Center

func Center(naturalW, naturalH int, child Node) Node

Center renders child at its natural size (given by naturalW/naturalH) padded to the parent's (w, h) with surrounding whitespace. Useful as the overlay layer inside a ZStack.

func HStack

func HStack(items ...Item) Node

HStack stacks items left to right within its allotted width.

func Sized

func Sized(s Sizer) Node

Sized wraps a two-dimensional component (pane.Pane, list.Model, …) as a Node. Pass a pointer: &m.list, &m.body.

func VStack

func VStack(items ...Item) Node

VStack stacks items top to bottom within its allotted height.

func ZStack

func ZStack(base, overlay Node) Node

ZStack layers overlay on top of base. Both are rendered at the full (w, h). 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.

type RenderFunc

type RenderFunc func(w, h int) string

RenderFunc adapts a render-at-size function into a Node. It is the primary bridge from existing components: close over the component, set its dimensions inside the func, and return its View().

func (RenderFunc) Render

func (f RenderFunc) Render(w, h int) string

Render satisfies Node.

type Sizer

type Sizer interface {
	SetDimensions(w, h int)
	View() string
}

Sizer is satisfied by components sized by both width and height. Sized wraps one into a Node.

type Widther

type Widther interface {
	SetWidth(int)
	View() string
}

Widther is satisfied by components sized by width alone (single-row bars like breadcrumb and statusbar). Bar wraps one into a Node.