tui

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: May 29, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package tui provides interactive terminal UI components for spec.

Package tui provides interactive terminal UI components for spec.

The theme sub-system resolves a colour palette from user preferences or terminal capabilities and exposes semantic style constructors that all views and components reference. No hardcoded colour values outside this file.

Index

Constants

View Source
const (
	IconFocus    = glyph.Focus
	IconActive   = glyph.Active
	IconStale    = glyph.Stale
	IconBlocked  = glyph.Blocked
	IconReview   = glyph.Review
	IconIncoming = glyph.Incoming
	IconDone     = glyph.Done
	IconRejected = glyph.Rejected
	IconChanges  = glyph.Changes
	IconPending  = glyph.Pending
	IconFilled   = glyph.Filled
	IconOpen     = glyph.Open

	IconBullet = glyph.Bullet
	IconCursor = glyph.Cursor
	IconCaret  = glyph.Caret
	IconClock  = glyph.Clock

	IconToastOK   = glyph.ToastOK
	IconToastErr  = glyph.ToastErr
	IconToastInfo = glyph.ToastInfo

	GlyphVSep    = glyph.VSep
	GlyphHRule   = glyph.HRule
	GlyphSection = glyph.Section
)

Icon and glyph names for the tui package. The glyph literals themselves live in the dependency-free internal/tui/glyph package (the single source of truth), so the tui package and its components subpackage share one icon vocabulary without an import cycle. No glyph literals appear outside internal/tui/glyph.

View Source
const (
	// Gutter is the left/right content padding in cells. The prevailing
	// convention was width-4 (two cells each side), which this formalises.
	Gutter = 2

	// IndentUnit is one indentation step in cells. Nesting is Indent(1),
	// Indent(2), etc.
	IndentUnit = 2

	// MinContent is the floor for derived content width, uniform across all
	// views (some previously floored at 30, others at 40).
	MinContent = 40
)
View Source
const ViewCount = 6

ViewCount is the total number of top-level views.

Variables

View Source
var CommonGateTypes = []GateType{
	{Name: "Section has content", Description: "Require a section to be non-empty", Value: "section_not_empty"},
	{Name: "PR stack exists", Description: "Require PR stack plan in §7.3", Value: "pr_stack_exists"},
	{Name: "PRs approved", Description: "All PRs must be approved", Value: "prs_approved"},
	{Name: "Decisions resolved", Description: "All decisions must be resolved", Value: "decisions_resolved"},
	{Name: "Custom expression", Description: "Write a custom expression", Value: "expr"},
	{Name: "No gate", Description: "Skip adding a gate", Value: "none"},
}

CommonGateTypes are the built-in gate types.

View Source
var CommonRoles = []string{"anyone", "author", "pm", "tl", "designer", "engineer", "qa", "security"}

Common roles

StageIcons is the ordered set of mono-width glyphs used to mark pipeline stages by position. It replaces the previous emoji array; the pipeline view and stage-selection prompts both index into it. Colour distinguishes stage state at the call site. Indices beyond the slice fall back via StageIconAt.

Functions

func CIIconFor added in v0.8.3

func CIIconFor(status string) string

CIIconFor returns the glyph for a CI status.

func ConfirmPreset

func ConfirmPreset(preset PresetOption) (bool, error)

ConfirmPreset shows a preset preview and asks for confirmation.

func ContentWidth added in v0.8.3

func ContentWidth(total int) int

ContentWidth derives the usable content width from the total terminal width: total minus the gutter on both sides, clamped to MinContent.

func HintStrip added in v0.8.3

func HintStrip(styles Styles, pairs ...HintPair) string

HintStrip formats footer key hints uniformly. The key is rendered in the accent style and the label in the muted style, with pairs joined by " · ". The result is prefixed by one indent unit so every footer aligns with the standard content gutter.

func Indent added in v0.8.3

func Indent(n int) string

Indent returns n indentation units as spaces. Indent(0) is empty.

func IsInteractive

func IsInteractive() bool

IsInteractive returns true if stdin is a terminal.

func PrintError

func PrintError(message string)

PrintError prints an error message.

func PrintSuccess

func PrintSuccess(message string)

PrintSuccess prints a success message.

func PrintTitle

func PrintTitle(title string)

PrintTitle prints a title.

func PriorityIconFor added in v0.8.3

func PriorityIconFor(priority string) string

PriorityIconFor returns the mono-width glyph for a triage priority. Meaning is carried by shape (filled dot vs hollow) plus the caller-applied colour.

func PromptAddAnotherGate

func PromptAddAnotherGate() (bool, error)

PromptAddAnotherGate asks if the user wants to add another gate.

func PromptConfirm

func PromptConfirm(title string) (bool, error)

PromptConfirm asks for yes/no confirmation.

func PromptExpression

func PromptExpression() (string, string, error)

PromptExpression prompts for a custom expression.

func PromptGateType

func PromptGateType() (string, error)

PromptGateType prompts the user to select a gate type.

func PromptMultiSelectStages

func PromptMultiSelectStages(stages []string, title, description string) ([]string, error)

PromptMultiSelectStages prompts to select multiple stages.

func PromptSectionSlug

func PromptSectionSlug() (string, error)

PromptSectionSlug prompts for a section slug.

func PromptSelectStage

func PromptSelectStage(stages []string, title, description string) (string, error)

PromptSelectStage prompts to select a stage from a list.

func PromptStageIcon

func PromptStageIcon() (string, error)

PromptStageIcon prompts for a stage icon.

func PromptStageName

func PromptStageName(existing []string) (string, error)

PromptStageName prompts for a stage name.

func PromptStageOwner

func PromptStageOwner(defaultOwner string) (string, error)

PromptStageOwner prompts for a stage owner role.

func PromptStagePosition

func PromptStagePosition(stages []string) (afterStage string, err error)

PromptStagePosition prompts for where to insert a new stage.

func RuleLine added in v0.8.3

func RuleLine(width int) string

RuleLine returns a horizontal rule of the given width using the standard rule glyph. A non-positive width yields an empty string.

func SelectPreset

func SelectPreset(presets []PresetOption) (string, error)

SelectPreset prompts the user to select a pipeline preset.

func StageIconAt added in v0.8.3

func StageIconAt(pos int) string

StageIconAt returns the stage glyph for the given zero-based stage position, falling back to IconOpen when the position is out of range.

func StepIconFor added in v0.8.3

func StepIconFor(status string) string

StepIconFor returns the glyph for a build-step status.

func ThemeNames added in v0.6.0

func ThemeNames() []string

ThemeNames returns the ordered list of available named themes.

Types

type App added in v0.6.0

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

App is the top-level Bubble Tea model. It owns the tab strip, header, status bar, and delegates to the active view.

func New added in v0.6.0

func New(rc *config.ResolvedConfig, reg *adapter.Registry, role string) App

New creates a new App ready to run as a tea.Program. The caller is responsible for invoking Close once the program exits.

func (App) Close added in v0.8.2

func (a App) Close() error

Close releases resources held by the App, notably the local store. It is safe to call when the store failed to open.

func (App) Init added in v0.6.0

func (a App) Init() tea.Cmd

Init runs the initial commands — fetch data + start tick.

func (App) Update added in v0.6.0

func (a App) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update handles all messages.

func (App) View added in v0.6.0

func (a App) View() string

View renders the full application.

type GateType

type GateType struct {
	Name        string
	Description string
	Value       string
}

GateType represents a type of gate.

type GlamourRenderer added in v0.6.0

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

GlamourRenderer renders markdown using Glamour with a pre-resolved style. The TermRenderer is constructed once per (style, width) pair and cached, so termenv.HasDarkBackground is never called on the hot render path.

func (*GlamourRenderer) Render added in v0.6.0

func (g *GlamourRenderer) Render(ctx context.Context, md string, width int) (string, error)

Render implements Renderer.

type HintPair added in v0.8.3

type HintPair struct {
	Key   string
	Label string
}

HintPair is a single footer hint: a key and its label.

func Hint added in v0.8.3

func Hint(key, label string) HintPair

Hint constructs a HintPair.

type KeyMap added in v0.6.0

type KeyMap struct {
	// Navigation
	Up       key.Binding
	Down     key.Binding
	Enter    key.Binding
	Back     key.Binding
	PageUp   key.Binding
	PageDown key.Binding
	Home     key.Binding
	End      key.Binding

	// Scroll (contextual, e.g. settings theme list)
	ScrollUp   key.Binding
	ScrollDown key.Binding

	// View switching
	Tab1 key.Binding
	Tab2 key.Binding
	Tab3 key.Binding
	Tab4 key.Binding
	Tab5 key.Binding
	Tab6 key.Binding

	NextTab key.Binding
	PrevTab key.Binding

	// Global actions
	Help    key.Binding
	Search  key.Binding
	Refresh key.Binding
	Quit    key.Binding

	// Spec actions
	Advance       key.Binding
	Edit          key.Binding
	Build         key.Binding
	Block         key.Binding // x — toggle block (confirm modal)
	Unblock       key.Binding // u — explicit unblock (kept for dispatch)
	ToggleArchive key.Binding // ` — toggle archive list in spec tab
	Revert        key.Binding
	Focus         key.Binding // f — toggle focus
	Open          key.Binding
	Yank          key.Binding
	Decide        key.Binding
	Push          key.Binding
	Sync          key.Binding
	Archive       key.Binding // g a — archive (confirm modal)
	Restore       key.Binding // g r — restore (confirm modal)

	// Creation
	NewSpec   key.Binding
	NewIntake key.Binding
	Standup   key.Binding // g s — standup

	// Prefix keys
	GPrefix key.Binding // g — arms prefix for g a / g r / g s
}

KeyMap defines all keybindings for the TUI.

func DefaultKeyMap added in v0.6.0

func DefaultKeyMap() KeyMap

DefaultKeyMap returns the default keybindings.

func (KeyMap) ActionBindings added in v0.6.0

func (k KeyMap) ActionBindings() []key.Binding

ActionBindings returns the spec action bindings for help display.

func (KeyMap) AllBindings added in v0.8.3

func (k KeyMap) AllBindings() []key.Binding

AllBindings returns every binding for the full help view.

func (KeyMap) CreationBindings added in v0.8.3

func (k KeyMap) CreationBindings() []key.Binding

CreationBindings returns the creation/tool bindings for help display.

func (KeyMap) GlobalBindings added in v0.6.0

func (k KeyMap) GlobalBindings() []key.Binding

GlobalBindings returns bindings shown in every context.

func (KeyMap) NavigationBindings added in v0.6.0

func (k KeyMap) NavigationBindings() []key.Binding

NavigationBindings returns the nav-related bindings for help display.

func (KeyMap) SettingsBindings added in v0.8.0

func (k KeyMap) SettingsBindings() []key.Binding

SettingsBindings returns keybindings for the Settings tab edit flow.

func (KeyMap) ViewBindings added in v0.6.0

func (k KeyMap) ViewBindings() []key.Binding

ViewBindings returns the view-switching bindings for help display.

type PlainRenderer added in v0.6.0

type PlainRenderer struct{}

PlainRenderer is a plain-text fallback with no ANSI styling.

func (PlainRenderer) Render added in v0.6.0

func (PlainRenderer) Render(ctx context.Context, md string, _ int) (string, error)

type PresetOption

type PresetOption struct {
	Name        string
	Description string
	Stages      []string
	Features    []string
}

PresetOption represents a pipeline preset for selection.

type Renderer added in v0.6.0

type Renderer interface {
	Render(ctx context.Context, md string, width int) (string, error)
}

Renderer renders markdown content into ANSI-styled terminal text.

func NewGlamourRenderer added in v0.6.0

func NewGlamourRenderer(theme Theme) Renderer

NewGlamourRenderer creates a renderer whose style is derived from the already-resolved Theme. No terminal I/O is performed at construction time.

func NewPlainRenderer added in v0.6.0

func NewPlainRenderer() Renderer

NewPlainRenderer creates a plain-text renderer.

type StageInput

type StageInput struct {
	Name     string
	Owner    string
	Icon     string
	Position string // "after:<stage>" or "before:<stage>"
}

StageInput holds input for creating a new stage.

type Styles added in v0.6.0

type Styles struct {
	// Layout
	Header    lipgloss.Style
	StatusBar lipgloss.Style
	TabActive lipgloss.Style
	TabNormal lipgloss.Style
	Content   lipgloss.Style

	// Text
	Title    lipgloss.Style
	Subtitle lipgloss.Style
	Muted    lipgloss.Style
	Bold     lipgloss.Style

	// Semantic
	Success lipgloss.Style
	Warning lipgloss.Style
	Error   lipgloss.Style
	Accent  lipgloss.Style

	// Table
	RowSelected lipgloss.Style
	RowNormal   lipgloss.Style

	// Section headers within views
	SectionTitle lipgloss.Style
	Separator    lipgloss.Style
}

Styles holds pre-built lipgloss styles derived from the active theme.

func NewStyles added in v0.6.0

func NewStyles(t Theme) Styles

NewStyles constructs all styles from a theme.

type Theme added in v0.6.0

type Theme struct {
	Base    lipgloss.Color // background / deepest layer
	Surface lipgloss.Color // panels, selected rows
	Overlay lipgloss.Color // borders, separators
	Text    lipgloss.Color // primary text
	SubText lipgloss.Color // secondary, dimmed
	Accent  lipgloss.Color // highlights, active tab
	Success lipgloss.Color // done, approved
	Warning lipgloss.Color // stale, blocked
	Error   lipgloss.Color // critical, failed
	Muted   lipgloss.Color // disabled, inactive
}

Theme holds the semantic colour palette for the entire TUI.

func ResolveTheme added in v0.6.0

func ResolveTheme(pref string) Theme

ResolveTheme returns a Theme for the given preference string. An empty string or "auto" detects from the terminal.

type View added in v0.6.0

type View int

View identifies each top-level view in the TUI.

const (
	ViewDashboard View = iota
	ViewPipeline
	ViewSpecs
	ViewTriage
	ViewReviews
	ViewSettings
)

func (View) Label added in v0.6.0

func (v View) Label() string

Label returns the display name for a view.

func (View) Next added in v0.6.0

func (v View) Next() View

Next returns the next view, wrapping around.

func (View) Prev added in v0.6.0

func (v View) Prev() View

Prev returns the previous view, wrapping around.

func (View) Shortcut added in v0.6.0

func (v View) Shortcut() string

Shortcut returns the keyboard shortcut for a view.

Directories

Path Synopsis
Package components provides reusable TUI building blocks.
Package components provides reusable TUI building blocks.
Package glyph is the single source of truth for every glyph the TUI renders.
Package glyph is the single source of truth for every glyph the TUI renders.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL