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 and any active file watcher. 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. |
|
Package watch observes a fixed set of files for changes and emits debounced, coalesced notifications.
|
Package watch observes a fixed set of files for changes and emits debounced, coalesced notifications. |