tui

README

go-widgets/tui

Terminal I/O layer around go-widgets/painter's CellPainter. Renders a widget tree as a self-contained ANSI stream sized to the current terminal, so the same widget code that produces pixels for a WUI or GUI back-end also produces text for a terminal.

What it is (and what it isn't)

The package is deliberately minimal — no raw mode, no keyboard event loop, no alt-screen management. It ships a snapshot model: render one frame to a writer and return. Compose it with a caller-managed event loop or a CLI that prints once and exits.

import (
    "os"

    "github.com/go-widgets/painter"
    "github.com/go-widgets/tui"
)

widgets := []painter.Widget{
    &painter.Label{Bounds: painter.Rect{X: 2, Y: 1, W: 30, H: 1}, Text: "GO WIDGETS TUI"},
    &painter.Button{Bounds: painter.Rect{X: 2, Y: 3, W: 12, H: 3}, Label: "OK"},
    &painter.ProgressBar{Bounds: painter.Rect{X: 2, Y: 8, W: 30, H: 3}, Value: 0.72},
}
_ = tui.RenderOnce(os.Stdout, widgets, nil) // nil theme = LightTheme

An App runner with input, resize, and cleanup handling is future work — this repo intentionally leaves that surface for a follow-up cycle rather than shipping a half-baked event loop.

Sizing

Two variants, take your pick:

• RenderOnceSized(w, cols, rows, widgets, theme) — explicit dimensions. The reliable form for tests, size-aware callers, and headless renderers.
• RenderOnce(w, widgets, theme) — queries EnvSize() (COLUMNS / LINES environment variables) and falls back to DefaultCols x DefaultRows (80 x 24) when the environment does not report a size.

The env-vars-only strategy is a deliberate trade-off: it keeps the package stdlib-only — no TIOCGWINSZ ioctl per platform, no cgo, no dependency on golang.org/x/term. Interactive shells that need dynamic sizes should export COLUMNS / LINES from their prompt hook, or pass an explicit size to RenderOnceSized.

Try it

# Default terminal size (or COLUMNS / LINES if set)
go run ./cmd/tui-snapshot

# Force a specific size + dark theme
go run ./cmd/tui-snapshot --cols=100 --rows=25 --theme=dark

The tui-snapshot demo mirrors painter/cmd/tui-demo: same three-widget layout (label, two buttons, progress bar), same theme selection.

For a broader showcase using the real go-widgets/toolkit widgets (Button, ToggleButton, Switch, Entry, ProgressBar, Alert, Stat, Timeline …) rendered through the same cell backend:

# Toolkit widget catalogue in two columns
go run ./cmd/tui-catalogue

# Force size + dark theme
go run ./cmd/tui-catalogue --cols=100 --rows=25 --theme=dark

Internally uses tui.RenderToolkit (the bridge that accepts toolkit.Widget and translates toolkit.Theme to what painter.CellPainter expects) so the on-screen widgets are the same objects a wasm gallery or a native window would compose.

Design axiom

Same as the rest of go-widgets: dependency-free, stdlib-only, 100% coverage (library packages and cmd/). CI enforces the coverage gate on every push.

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package tui is the terminal-I/O layer around github.com/go-widgets/painter's CellPainter. It renders a widget tree into an ANSI cell stream sized to the current terminal, so the same widget code that produces pixels for a WUI or GUI back-end also produces text for a terminal — no widget changes required.

The package is deliberately minimal: no raw mode, no keyboard event loop, no alt-screen management. It ships a "snapshot" model — render one frame to a writer and return — that composes cleanly with either a caller-managed event loop or a CLI that prints once and exits. Higher-level facilities (an [App] runner with input, resize, and cleanup handling) live in a follow-up cycle.

Sizing follows the caller's preference:

• RenderOnceSized takes explicit (cols, rows) — the reliable form used by tests, size-aware callers, and headless renderers.
• RenderOnce queries the size from environment variables (EnvSize) and falls back to [DefaultCols]x[DefaultRows] when the environment does not report a size. This keeps the package stdlib-only — no ioctl, no cgo, no dependency on golang.org/x/term.

Both variants write a self-contained ANSI stream to the caller's writer via painter.CellPainter.WriteANSI; the caller is responsible for the surrounding terminal state (raw mode, alt screen, cursor visibility) if any.

Index

• Constants
• Variables
• func EnvSize() (cols, rows int, ok bool)
• func RenderOnce(w io.Writer, widgets []painter.Widget, theme *painter.Theme) error
• func RenderOnceSized(w io.Writer, cols, rows int, widgets []painter.Widget, theme *painter.Theme) error
• func RenderToolkit(w io.Writer, widgets []toolkit.Widget, theme *toolkit.Theme) error
• func RenderToolkitSized(w io.Writer, cols, rows int, widgets []toolkit.Widget, theme *toolkit.Theme) error
• func SizeOrDefault() (cols, rows int)
• type InputParser
  • func NewInputParser() *InputParser
  • func (p *InputParser) Feed(b []byte) []toolkit.Event
  • func (p *InputParser) Flush() []toolkit.Event
• type TTY
  • func OpenTTY(f *os.File) (TTY, error)

Constants

const (
	DefaultCols = 80
	DefaultRows = 24
)

DefaultCols and DefaultRows are the terminal dimensions used when neither the environment nor the caller supplies a size — the classic VT100 defaults every terminal emulator honours as a floor.

Variables

var ErrNotSupported = errors.New("tui: interactive TTY setup is Unix-only in v0.3.0")

ErrNotSupported is returned by OpenTTY on platforms where the interactive TTY setup path is not implemented (Windows, Plan 9, WebAssembly). It is a package-level sentinel so callers can errors.Is against it to fall back to a non-interactive rendering path.

Functions

func EnvSize

func EnvSize() (cols, rows int, ok bool)

EnvSize reads the terminal size from the COLUMNS and LINES environment variables. It returns (cols, rows, true) when both parse cleanly and hold positive integers; otherwise it returns (0, 0, false) and the caller should substitute defaults.

The env-vars-only strategy is a deliberate trade-off: it keeps the package stdlib-only (no TIOCGWINSZ ioctl per platform, no cgo, no golang.org/x/term dependency). Interactive shells that need dynamic sizes should export COLUMNS / LINES from their prompt hook, or pass an explicit size to RenderOnceSized.

func RenderOnce

func RenderOnce(w io.Writer, widgets []painter.Widget, theme *painter.Theme) error

RenderOnce paints the widget tree into a fresh CellPainter sized to SizeOrDefault, fills the background with theme.Background, calls each widget's Draw, and writes the resulting ANSI stream to w. It is the snapshot form: no raw mode, no event loop; one frame then return.

The theme argument may be nil, in which case painter.LightTheme is used. This keeps CLI callers ergonomic (`tui.RenderOnce(os.Stdout, widgets, nil)`) without forcing them to import painter just to name the default theme.

func RenderOnceSized

func RenderOnceSized(w io.Writer, cols, rows int, widgets []painter.Widget, theme *painter.Theme) error

RenderOnceSized is like RenderOnce but uses the explicit (cols, rows) dimensions instead of querying the environment. Cols and rows must both be positive; a non-positive value falls back to the corresponding default so callers cannot accidentally produce an empty render.

func RenderToolkit

func RenderToolkit(w io.Writer, widgets []toolkit.Widget, theme *toolkit.Theme) error

RenderToolkit paints a toolkit.Widget tree into a fresh CellPainter sized to SizeOrDefault, fills the background with theme.Background, calls each widget's Draw, and writes the resulting ANSI stream to w.

It is the toolkit-widget counterpart of RenderOnce (which renders painter.Widget). The two exist side-by-side because toolkit.Theme carries fields (SurfaceAlt, OnBackground, Extra) that painter.Theme does not, so a toolkit widget cannot be rendered through RenderOnce without losing theme surface.

The theme argument may be nil, in which case toolkit.DefaultLight is used.

func RenderToolkitSized

func RenderToolkitSized(w io.Writer, cols, rows int, widgets []toolkit.Widget, theme *toolkit.Theme) error

RenderToolkitSized is like RenderToolkit but uses the explicit (cols, rows) dimensions instead of querying the environment. Cols and rows must both be positive; a non-positive value falls back to the corresponding default so callers cannot accidentally produce an empty render.

func SizeOrDefault

func SizeOrDefault() (cols, rows int)

SizeOrDefault returns EnvSize when the environment reports a size, otherwise [DefaultCols]x[DefaultRows]. This is what RenderOnce consumes.

Types

type InputParser

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

InputParser reads bytes from a terminal stdin stream and emits toolkit.Event values. A single call to InputParser.Feed may produce zero, one, or many events: typing "abc" yields three toolkit.EventChar events, pasting a control sequence like "\x1b[A" yields one arrow-up event but consumes three bytes.

The toolkit exposes toolkit.EventKeyDown for named-key presses (Enter, Tab, arrows, Escape, …) and toolkit.EventChar for printable characters — the parser routes accordingly.

The pending buffer holds the incomplete tail of the last Feed call: a lone ESC (0x1B) whose next byte has not arrived, an ESC [ … partial CSI sequence still waiting for its final byte (0x40..0x7E), or a partial UTF-8 rune (1–3 bytes of a multi-byte codepoint split across two Reads). It is consumed automatically on the next Feed call, or drained by InputParser.Flush on an input-idle deadline.

func NewInputParser

func NewInputParser() *InputParser

NewInputParser returns a fresh parser with an empty buffer.

func (*InputParser) Feed

func (p *InputParser) Feed(b []byte) []toolkit.Event

Feed hands b bytes to the parser and returns any events that completed as a result. Bytes belonging to an incomplete sequence (a lone ESC, a partial CSI, a partial UTF-8 rune) are buffered internally and consumed on the next Feed call.

The classic Escape-vs-CSI ambiguity is resolved as follows: a lone ESC at the end of the buffer is held pending; on the next Feed a leading '[' starts a CSI sequence, any other byte causes the held ESC to be emitted as "Escape" and the following byte is then processed as a fresh input. Callers waiting on an idle deadline flush the held ESC via InputParser.Flush.

func (*InputParser) Flush

func (p *InputParser) Flush() []toolkit.Event

Flush emits any pending ESC (or partial CSI) as an "Escape" event and clears the buffer. Callers invoke it on an input-idle deadline to resolve the Escape-vs-CSI ambiguity in favour of a plain Escape. A partial UTF-8 rune is discarded silently — its tail bytes would be indistinguishable from an unrelated new keystroke by the time an idle timeout fires.

type TTY

type TTY interface {
	Enter() error
	Leave() error
	Size() (cols, rows int, err error)
}

TTY is the abstraction the App runner uses to talk to a real terminal. On non-Unix platforms the concrete TTY implementation is not available and OpenTTY returns ErrNotSupported; the interface is exported so callers can still write portable code that consumes a TTY handed to them from a Unix host.

func OpenTTY

func OpenTTY(f *os.File) (TTY, error)

OpenTTY on non-Unix platforms always returns ErrNotSupported. The Unix implementation lives in termios_unix.go.