tuiweave

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: MIT Imports: 2 Imported by: 0

README

tuiweave

tuiweave is a composable Go component library for custom terminal interfaces built on Bubble Tea v2 and Lip Gloss v2. It provides themed primitives for layout, navigation, scrolling, text editing, overlays, testing, and optional agentic interfaces while leaving application state and orchestration to you.

This is an independent community project and is not affiliated with Charmbracelet.

Pre-v1: APIs may change in minor releases. Breaking changes are documented in the changelog and release notes.

Why tuiweave?

tuiweave is for Bubble Tea applications that want reusable components without giving up application-owned state and routing.

  • Uniform composition: components share explicit sizing, focus, theme, and state-ownership contracts.
  • Deterministic verification: snaptest checks layout, Unicode, style roles, and named interaction scenarios without requiring a live terminal session.
  • Human- and agent-operable surfaces: inspect and semantic actions expose discoverable UI state without making tuiweave own an event loop or transport.

Compared with using individual Bubbles, tuiweave provides a consistent cross-component contract and an application-oriented verification layer. It is still a component library, not an application framework: your app owns layout decisions, visibility, routing, persistence, and side effects.

Install

tuiweave requires Go 1.25.8 or newer and is coupled to Bubble Tea v2.

go get github.com/ishan5ain/tuiweave@v0.1.0

package main

import (
	"fmt"

	"github.com/ishan5ain/tuiweave"
	"github.com/ishan5ain/tuiweave/statusbar"
)

func main() {
	bar := statusbar.New(tuiweave.Dark())
	bar.SetSize(40, 1)
	bar.SetLeft(statusbar.Segment{Text: "ready", Kind: statusbar.KindSuccess})
	fmt.Println(bar.View())
}

Explore

The root package supplies semantic theme roles. Domain-neutral components live in top-level packages such as layout, frame, tabs, menu, viewport, textinput, and textarea; optional domain packages live under agentic/. The agent catalog maps common tasks to packages and examples.

Canonical non-agentic reference app

examples/ops is the complete non-agentic reference app. It composes tabs, menus, tables, status controls, nested overlays, semantic inspection, mouse routing, and deterministic interaction tests into a small operations console:

go run ./examples/ops

Use tab and shift+tab to move focus, arrow keys to navigate the focused component, ctrl+p to open the command palette, and q to quit. Mouse clicks focus controls and select tabs, menu rows, or table rows; clicking the toggle or button also emits its normal typed result command. While a palette or confirmation is open, the application keeps background controls inert.

The example keeps ownership boundaries explicit:

Concern Owner in examples/ops
Layout and sizing The app splits every window size into rectangles and calls each component's SetSize.
Focus The app retains a focus.Stack, reapplies fresh component addresses, and restores the parent index after an overlay closes.
Mouse input The app hit-tests its retained rectangles, then translates global clicks into local focus, selection, or activation.
Modal routing The app owns visibility and sends input only to the top visible layer; overlay only composites rendered strings.
Commands and side effects Components emit typed messages; the app handles delivered results and owns the resulting notice/state change.
Semantic actions The app assembles absolute inspection bounds, validates visible enabled actions, and forwards only the local action suffix.

The layout intentionally has a narrow-terminal fallback, and its important focus, modal, mouse, command-delivery, semantic-routing, and narrow states are captured as readable and role-aware goldens:

go test ./examples/ops

Read examples/ops/main.go for the application wiring and examples/ops/main_test.go for the snapshot and scenario workflow. examples/consumer remains the smaller public-API smoke example, while the other runnable examples continue to teach individual packages.

Start with five packages

For a small interactive application, start with layout, focus, frame, one interaction component such as list or textarea, and snaptest. Add inspect when the application needs machine-readable state or semantic actions.

Package guides

Foundations and composition: action, focus, frame, inspect, layout, line, mouse, overlay, scrollbar, snaptest, splitpane, and stack.

General-purpose components: autocomplete, button, dialog, help, list, menu, palette, progress, spinner, statusbar, table, tabs, textarea, textinput, toggle, toolbar, and viewport.

Agentic domain components: chat, diffview, markdown, permission, toolcall, and usagebar.

Eight built-in theme presets are available through tuiweave.Presets() and tuiweave.ThemeForPreset(id). Named constructors such as Dark(), Nord(), and CatppuccinLatte() are convenient when an app does not need discovery. Components derive styles when constructed, so an app that changes themes reconstructs its components from the newly selected Theme while preserving application-owned state. See examples/statusbar.

API highlights

  • Theme defines the semantic roles consumed by every themed component.
  • Dark, Light, Nord, and other named constructors provide fixed themes.
  • Presets and ThemeForPreset support application-owned theme selection.

Development

gofmt -w .
go mod tidy -diff
go mod verify
go build ./...
go vet ./...
go test ./...
go test -race ./...
govulncheck ./...

Rendering changes require intentional snapshot review; see AGENTS.md.

Known limitations

  • The API is pre-v1 and may evolve between minor versions.
  • Input-method editor behavior is incomplete.
  • Components currently target Bubble Tea v2.
  • Layout and rendering internals rely on a pre-v1 Ultraviolet dependency.

Licensed under the MIT License.

Documentation

Overview

Package tuiweave is a composable component library for building custom terminal UIs on bubbletea v2 and lipgloss v2, designed so that humans and coding agents can reliably compose and evolve complete frontends with it.

The root package defines the semantic theme roles every component consumes. Layout lives in tuiweave/layout, the snapshot test harness in tuiweave/snaptest, and domain-neutral components live in one package each (e.g. tuiweave/statusbar). Agentic and other domain components live in subpackages such as tuiweave/agentic and are built on the same primitives.

See DESIGN.md for architecture and AGENTS.md for authoring conventions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Preset added in v0.2.0 

type Preset struct {
	ID   string
	Name string
	Dark bool
}

Preset describes one built-in theme. IDs are stable and suitable for application configuration and persistence.

func Presets added in v0.2.0 

func Presets() []Preset

Presets returns the built-in themes in their stable display order. The returned slice is a copy and may be modified by the caller.

type Theme 

type Theme struct {
	// Surfaces.
	Surface       color.Color // app background
	SurfaceRaised color.Color // panels, dialogs, popovers
	SurfaceSunken color.Color // input wells, code blocks

	// Text.
	Text         color.Color // primary text
	TextMuted    color.Color // secondary text, placeholders, help
	TextFaint    color.Color // tertiary text, timestamps, subtle separators
	TextInverted color.Color // text rendered on accent/intent fills

	// Intent.
	Accent      color.Color // interactive/brand emphasis
	AccentMuted color.Color // subdued accent fills and highlights
	Success     color.Color
	Warning     color.Color
	Danger      color.Color
	Info        color.Color

	// Chrome.
	Border        color.Color // default borders
	BorderFocused color.Color // border of the focused element
	BorderMuted   color.Color // subtle dividers

	// Selection.
	SelectionBg color.Color // background of selected rows/items
	SelectionFg color.Color // foreground of selected rows/items
}

Theme is the set of semantic color roles that every tuiweave component consumes. Components derive their styles exclusively from these roles and never use color literals, so swapping the Theme restyles an entire app consistently.

Adding a role is an API event: it requires justification that no existing role covers the semantics. This is what keeps the theme surface from growing with every new component.

func CatppuccinLatte added in v0.2.0 

func CatppuccinLatte() Theme

CatppuccinLatte returns the official light Catppuccin flavor. Palette source: https://catppuccin.com/palette/

func CatppuccinMocha added in v0.2.0 

func CatppuccinMocha() Theme

CatppuccinMocha returns the darkest official Catppuccin flavor. Palette source: https://catppuccin.com/palette/

func Dark 

func Dark() Theme

Dark is the default dark theme.

func Dracula added in v0.2.0 

func Dracula() Theme

Dracula returns a theme based on the official Dracula color palette. Palette source: https://spec.draculatheme.com/

func GruvboxDark added in v0.2.0 

func GruvboxDark() Theme

GruvboxDark returns the dark variant of the original Gruvbox palette. Palette source: https://github.com/morhetz/gruvbox

func GruvboxLight added in v0.2.0 

func GruvboxLight() Theme

GruvboxLight returns the light variant of the original Gruvbox palette. Palette source: https://github.com/morhetz/gruvbox

func Light 

func Light() Theme

Light is the default light theme.

func Nord added in v0.2.0 

func Nord() Theme

Nord returns a theme based on the official Nord color palette. Palette source: https://www.nordtheme.com/docs/colors-and-palettes

func ThemeForPreset added in v0.2.0 

func ThemeForPreset(id string) (Theme, bool)

ThemeForPreset resolves a built-in theme by stable preset ID.

Source Files

View all Source files

Directories

Path Synopsis
Package action defines stable, application-owned actions shared by selectable components such as menu, toolbar, and palette.
 Package action defines stable, application-owned actions shared by selectable components such as menu, toolbar, and palette.
agentic
chat
Package chat provides a scrolling transcript for agentic sessions: a stack of cells (user/assistant messages, tool calls, diffs, notes) inside a viewport that auto-follows new content.
 Package chat provides a scrolling transcript for agentic sessions: a stack of cells (user/assistant messages, tool calls, diffs, notes) inside a viewport that auto-follows new content.
diffview
Package diffview renders unified diffs with theme-role line coloring — additions Success, deletions Danger, hunk headers Info.
 Package diffview renders unified diffs with theme-role line coloring — additions Success, deletions Danger, hunk headers Info.
markdown
Package markdown renders markdown to styled terminal text using the theme's roles.
 Package markdown renders markdown to styled terminal text using the theme's roles.
permission
Package permission provides the modal prompt agentic tools show before a sensitive action: a question with vertically stacked options and optional structured provenance for the operation being approved.
 Package permission provides the modal prompt agentic tools show before a sensitive action: a question with vertically stacked options and optional structured provenance for the operation being approved.
toolcall
Package toolcall renders a tool invocation as a transcript block: status icon, tool name, argument summary, and collapsible output.
 Package toolcall renders a tool invocation as a transcript block: status icon, tool name, argument summary, and collapsible output.
usagebar
Package usagebar renders the session status line of an agentic tool: model name, token counts, cost, and context usage, formatted onto a tuiweave statusbar.
 Package usagebar renders the session status line of an agentic tool: model name, token counts, cost, and context usage, formatted onto a tuiweave statusbar.
Package autocomplete provides a conditional, width-bounded suggestion window for an application-owned text input.
 Package autocomplete provides a conditional, width-bounded suggestion window for an application-owned text input.
Package button provides a compact, focusable action button.
 Package button provides a compact, focusable action button.
Package dialog provides a modal confirmation box with OK/Cancel buttons.
 Package dialog provides a modal confirmation box with OK/Cancel buttons.
examples
autocomplete command
Autocomplete demonstrates an app-owned textinput paired with the reusable suggestion window.
 Autocomplete demonstrates an app-owned textinput paired with the reusable suggestion window.
browser command
Command browser is a mock file-browser reference app.
 Command browser is a mock file-browser reference app.
chat command
Command chat is the Phase 3 exit-criterion app: a mock-backed agentic chat session exercising every tuiweave/agentic component — streaming markdown, a tool call gated by a permission prompt, an inline diff, and a live usage bar.
 Command chat is the Phase 3 exit-criterion app: a mock-backed agentic chat session exercising every tuiweave/agentic component — streaming markdown, a tool call gated by a permission prompt, an inline diff, and a live usage bar.
consumer command
Command consumer is a small public-API consumer smoke app.
 Command consumer is a small public-API consumer smoke app.
demo command
Command demo is the Phase 2 exit-criterion app: a multi-pane TUI composed purely from tuiweave components, laid out with tuiweave/layout, with focus cycling and a modal dialog composited by tuiweave/overlay.
 Command demo is the Phase 2 exit-criterion app: a multi-pane TUI composed purely from tuiweave components, laid out with tuiweave/layout, with focus cycling and a modal dialog composited by tuiweave/overlay.
frame command
Command frame demonstrates tuiweave's domain-neutral framing helpers in a small dashboard-like composition.
 Command frame demonstrates tuiweave's domain-neutral framing helpers in a small dashboard-like composition.
ops command
Command ops is a non-agentic operations-console reference app.
 Command ops is a non-agentic operations-console reference app.
palette command
Command palette demonstrates the reusable command-palette foundation with stable action IDs, filtering, semantic activation, and a framed app shell.
 Command palette demonstrates the reusable command-palette foundation with stable action IDs, filtering, semantic activation, and a framed app shell.
statusbar command
Command statusbar demonstrates the tuiweave statusbar component and the canonical app wiring pattern: window size → layout split → SetSize → composed string view.
 Command statusbar demonstrates the tuiweave statusbar component and the canonical app wiring pattern: window size → layout split → SetSize → composed string view.
table command
Command table is a mock git-status app: a table of changed files beside a scrollable diff of the selected row, with scrollbars on both panes.
 Command table is a mock git-status app: a table of changed files beside a scrollable diff of the selected row, with scrollbars on both panes.
textarea-autocomplete command
Textarea autocomplete demonstrates an app-owned completion engine paired with textarea.ReplaceRange.
 Textarea autocomplete demonstrates an app-owned completion engine paired with textarea.ReplaceRange.
Package focus provides tab-order managers and copy-safe focus scopes for interactive components.
 Package focus provides tab-order managers and copy-safe focus scopes for interactive components.
Package frame provides small, domain-neutral decoration helpers for composing tuiweave views.
 Package frame provides small, domain-neutral decoration helpers for composing tuiweave views.
Package help provides a one-line key-hint bar, e.g.:
 Package help provides a one-line key-hint bar, e.g.:
Package inspect defines an optional, data-only semantic representation of a tuiweave interface.
 Package inspect defines an optional, data-only semantic representation of a tuiweave interface.
internal
grapheme
Package grapheme contains small internal helpers for preserving Unicode graphemes while ANSI strings are decomposed into terminal cells.
 Package grapheme contains small internal helpers for preserving Unicode graphemes while ANSI strings are decomposed into terminal cells.
Package layout partitions terminal space into rectangles using flexbox-like constraints, and sizes tuiweave components from the result.
 Package layout partitions terminal space into rectangles using flexbox-like constraints, and sizes tuiweave components from the result.
Package line provides small, style-preserving helpers for composing one terminal row.
 Package line provides small, style-preserving helpers for composing one terminal row.
Package list provides a scrolling list of single-line items with a selection cursor and optional filtering.
 Package list provides a scrolling list of single-line items with a selection cursor and optional filtering.
Package menu provides a focusable vertical menu of application-owned actions.
 Package menu provides a focusable vertical menu of application-owned actions.
Package mouse contains small, application-owned helpers for Bubble Tea mouse messages.
 Package mouse contains small, application-owned helpers for Bubble Tea mouse messages.
Package overlay composites one rendered view on top of another — the mechanism behind modals, popovers, and toasts.
 Package overlay composites one rendered view on top of another — the mechanism behind modals, popovers, and toasts.
Package palette provides a bounded command-palette foundation: a query input, filtered action window, stable IDs, and semantic activation.
 Package palette provides a bounded command-palette foundation: a query input, filtered action window, stable IDs, and semantic activation.
Package progress renders a compact, themed progress indicator for a task or operation.
 Package progress renders a compact, themed progress indicator for a task or operation.
Package scrollbar renders a vertical scroll indicator for any scrolling component.
 Package scrollbar renders a vertical scroll indicator for any scrolling component.
Package snaptest is tuiweave's snapshot test harness: it renders component views to golden files and compares them on subsequent runs, giving agents (and humans) a deterministic, readable way to verify what a TUI renders without a terminal.
 Package snaptest is tuiweave's snapshot test harness: it renders component views to golden files and compares them on subsequent runs, giving agents (and humans) a deterministic, readable way to verify what a TUI renders without a terminal.
Package spinner provides an animated activity indicator.
 Package spinner provides an animated activity indicator.
Package splitpane provides small helpers for composing sibling views into a horizontal split.
 Package splitpane provides small helpers for composing sibling views into a horizontal split.
Package stack provides small helpers for composing width-aware vertical sections such as headers, body regions, and footers.
 Package stack provides small helpers for composing width-aware vertical sections such as headers, body regions, and footers.
Package statusbar provides a one-line status bar with themed segments aligned left and right, in the style of editor status lines.
 Package statusbar provides a one-line status bar with themed segments aligned left and right, in the style of editor status lines.
Package table provides a scrolling table with fixed and flexible columns, a styled header, and row selection.
 Package table provides a scrolling table with fixed and flexible columns, a styled header, and row selection.
Package tabs provides a one-line, focusable tab strip for navigating sibling views.
 Package tabs provides a one-line, focusable tab strip for navigating sibling views.
Package textarea provides a multi-line text input for chat-style prompts: soft-wrapped display, a prompt gutter, and content-driven height.
 Package textarea provides a multi-line text input for chat-style prompts: soft-wrapped display, a prompt gutter, and content-driven height.
Package textinput provides a single-line text input with a prompt, placeholder, cursor, and grapheme-aware horizontal scrolling.
 Package textinput provides a single-line text input with a prompt, placeholder, cursor, and grapheme-aware horizontal scrolling.
Package toggle provides a compact, focusable on/off control.
 Package toggle provides a compact, focusable on/off control.
Package toolbar provides a one-line, focusable strip of application-owned actions.
 Package toolbar provides a one-line, focusable strip of application-owned actions.
Package viewport provides a scrollable window over pre-rendered content.
 Package viewport provides a scrollable window over pre-rendered content.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.