tuiweave

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 11, 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.

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.

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 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 Dark 

func Dark() Theme

Dark is the default dark theme.

func Light 

func Light() Theme

Light is the default light theme.

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 bounded suggestion window for an application-owned text input.
 Package autocomplete provides a 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.
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.