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
- Variables
- func CIIconFor(status string) string
- func ConfirmPreset(preset PresetOption) (bool, error)
- func ContentWidth(total int) int
- func HintStrip(styles Styles, pairs ...HintPair) string
- func Indent(n int) string
- func IsInteractive() bool
- func PrintError(message string)
- func PrintSuccess(message string)
- func PrintTitle(title string)
- func PriorityIconFor(priority string) string
- func PromptAddAnotherGate() (bool, error)
- func PromptConfirm(title string) (bool, error)
- func PromptExpression() (string, string, error)
- func PromptGateType() (string, error)
- func PromptMultiSelectStages(stages []string, title, description string) ([]string, error)
- func PromptSectionSlug() (string, error)
- func PromptSelectStage(stages []string, title, description string) (string, error)
- func PromptStageIcon() (string, error)
- func PromptStageName(existing []string) (string, error)
- func PromptStageOwner(defaultOwner string) (string, error)
- func PromptStagePosition(stages []string) (afterStage string, err error)
- func RuleLine(width int) string
- func SelectPreset(presets []PresetOption) (string, error)
- func StageIconAt(pos int) string
- func StepIconFor(status string) string
- func ThemeNames() []string
- type App
- type GateType
- type GlamourRenderer
- type HintPair
- type KeyMap
- func (k KeyMap) ActionBindings() []key.Binding
- func (k KeyMap) AllBindings() []key.Binding
- func (k KeyMap) CreationBindings() []key.Binding
- func (k KeyMap) GlobalBindings() []key.Binding
- func (k KeyMap) NavigationBindings() []key.Binding
- func (k KeyMap) SettingsBindings() []key.Binding
- func (k KeyMap) ViewBindings() []key.Binding
- type PlainRenderer
- type PresetOption
- type Renderer
- type StageInput
- type Styles
- type Theme
- type View
Constants ¶
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.
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 )
const ViewCount = 6
ViewCount is the total number of top-level views.
Variables ¶
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.
var CommonRoles = []string{"anyone", "author", "pm", "tl", "designer", "engineer", "qa", "security"}
Common roles
var StageIcons = []string{ IconIncoming, IconPending, IconReview, IconChanges, IconActive, IconFilled, IconReview, IconDone, IconActive, IconBullet, IconDone, IconFilled, IconBlocked, IconBullet, IconReview, IconOpen, }
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 ConfirmPreset ¶
func ConfirmPreset(preset PresetOption) (bool, error)
ConfirmPreset shows a preset preview and asks for confirmation.
func ContentWidth ¶ added in v0.8.3
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
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 PriorityIconFor ¶ added in v0.8.3
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 ¶
PromptAddAnotherGate asks if the user wants to add another gate.
func PromptConfirm ¶
PromptConfirm asks for yes/no confirmation.
func PromptExpression ¶
PromptExpression prompts for a custom expression.
func PromptGateType ¶
PromptGateType prompts the user to select a gate type.
func PromptMultiSelectStages ¶
PromptMultiSelectStages prompts to select multiple stages.
func PromptSectionSlug ¶
PromptSectionSlug prompts for a section slug.
func PromptSelectStage ¶
PromptSelectStage prompts to select a stage from a list.
func PromptStageIcon ¶
PromptStageIcon prompts for a stage icon.
func PromptStageName ¶
PromptStageName prompts for a stage name.
func PromptStageOwner ¶
PromptStageOwner prompts for a stage owner role.
func PromptStagePosition ¶
PromptStagePosition prompts for where to insert a new stage.
func RuleLine ¶ added in v0.8.3
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
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
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
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
Close releases resources held by the App, notably the local store. It is safe to call when the store failed to open.
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.
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
ActionBindings returns the spec action bindings for help display.
func (KeyMap) AllBindings ¶ added in v0.8.3
AllBindings returns every binding for the full help view.
func (KeyMap) CreationBindings ¶ added in v0.8.3
CreationBindings returns the creation/tool bindings for help display.
func (KeyMap) GlobalBindings ¶ added in v0.6.0
GlobalBindings returns bindings shown in every context.
func (KeyMap) NavigationBindings ¶ added in v0.6.0
NavigationBindings returns the nav-related bindings for help display.
func (KeyMap) SettingsBindings ¶ added in v0.8.0
SettingsBindings returns keybindings for the Settings tab edit flow.
func (KeyMap) ViewBindings ¶ added in v0.6.0
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.
type PresetOption ¶
PresetOption represents a pipeline preset for selection.
type Renderer ¶ added in v0.6.0
Renderer renders markdown content into ANSI-styled terminal text.
func NewGlamourRenderer ¶ added in v0.6.0
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.
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
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.
Source Files
¶
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. |