components

package
v0.12.1 Latest Latest
Warning

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

 Go to latest Published: Jun 1, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package components provides reusable TUI building blocks.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types 

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

Header renders the top bar: greeting, role, cycle, breadcrumb.

func NewHeader 

func NewHeader(userName, role, cycle string, styles HeaderStyles) Header

NewHeader creates a new header component.

func (Header) Height 

func (h Header) Height() int

Height returns how many lines the header occupies at the current width. It must stay in lockstep with View(): the app reserves exactly this many rows for the header, so any divergence overflows the terminal and corrupts the layout.

func (*Header) SetWidth 

func (h *Header) SetWidth(w int)

SetWidth updates the header width.

func (Header) View 

func (h Header) View() string

View renders the header.

type HeaderStyles 

type HeaderStyles struct {
	Bar        lipgloss.Style
	Greeting   lipgloss.Style
	Meta       lipgloss.Style
	Breadcrumb lipgloss.Style
}

HeaderStyles holds the styles for the header component. 

type Modal struct {
	Title   string
	Message string
	Kind    ModalKind
	Input   string
	Visible bool
	// contains filtered or unexported fields
}

Modal renders a centered overlay dialog for confirmations or short text input.

func NewModal 

func NewModal(styles ModalStyles) Modal

NewModal creates a new modal.

func (*Modal) AppendInput 

func (m *Modal) AppendInput(s string)

AppendInput adds a character to the input.

func (*Modal) BackspaceInput 

func (m *Modal) BackspaceInput()

BackspaceInput removes the last rune from the input. It deletes a whole UTF-8 rune (not a single byte) so backspacing over a multi-byte character never leaves invalid UTF-8 in the captured value.

func (*Modal) Hide 

func (m *Modal) Hide()

Hide closes the modal.

func (*Modal) SetSize 

func (m *Modal) SetSize(w, h int)

SetSize updates modal dimensions.

func (*Modal) ShowConfirm 

func (m *Modal) ShowConfirm(title, message string)

ShowConfirm opens a confirmation modal.

func (*Modal) ShowInfo added in v0.12.0 

func (m *Modal) ShowInfo(title, message string)

ShowInfo opens a read-only message modal (full-text display, esc to close).

func (*Modal) ShowInput 

func (m *Modal) ShowInput(title, message string)

ShowInput opens a text input modal.

func (Modal) View 

func (m Modal) View() string

View renders the modal overlay.

type ModalKind 

type ModalKind int

ModalKind distinguishes between confirmation and text input modals. 

const (
	ModalConfirm ModalKind = iota
	ModalInput
	// ModalInfo is a read-only message dialog (e.g. a full error detail). It
	// takes no input and is dismissed with esc.
	ModalInfo
)

type ModalStyles 

type ModalStyles struct {
	Border  lipgloss.Style
	Title   lipgloss.Style
	Message lipgloss.Style
	Input   lipgloss.Style
	Hint    lipgloss.Style
}

ModalStyles holds the styles for the modal component.

type Status added in v0.12.0 

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

Status is the single status component. It owns the status-bar slot formerly held by the "pending" notification and is the sole producer of status visuals. It maps the current StatusKind to an icon (animated for StatusPending) and a label, redrawn in place into a fixed footprint.

Transient kinds (success, error) carry an expiry; once elapsed the component decays back to idle on the next View(). Expiry is evaluated lazily against the wall clock — like the retired Toast — so no extra timer is introduced and the pending animation reuses the existing refresh cadence (§7.2).

func NewStatus added in v0.12.0 

func NewStatus(styles StatusStyles) Status

NewStatus creates a status component in the idle state.

func (Status) Animating added in v0.12.0 

func (s Status) Animating() bool

Animating reports whether the element currently needs animation ticks, so the app can render frames only while a task is pending.

func (Status) Detail added in v0.12.0 

func (s Status) Detail() string

Detail returns the full, untruncated text for the current state (the error message). Empty when there is nothing to expand.

func (Status) HasError added in v0.12.0 

func (s Status) HasError() bool

HasError reports whether a sticky error is currently shown, so the app can gate the "expand error" affordance.

func (Status) Kind added in v0.12.0 

func (s Status) Kind() StatusKind

Kind returns the current (decay-resolved) status kind.

func (Status) Label added in v0.12.0 

func (s Status) Label() string

Label returns the current effective label.

func (*Status) NextFrame added in v0.12.0 

func (s *Status) NextFrame()

NextFrame advances the pending-spinner animation. It is a no-op unless the element is pending, so non-pending states consume no animation frames (§7.1). Driven by the existing TUI spinner tick.

func (*Status) SetError added in v0.12.0 

func (s *Status) SetError(summary, detail string)

SetError shows a failure as a sticky state: it does NOT auto-decay, so a failed advance/push/sync stays legible until the user starts the next operation or dismisses it (§7.2 — errors must remain as legible as the old banner). summary is the short, slot-sized headline that is rendered inline; detail is the full, untruncated message reachable via Detail() (shown in a modal on demand) so truncation never hides the actionable part.

func (*Status) SetIdle added in v0.12.0 

func (s *Status) SetIdle()

SetIdle returns the element to its resting state immediately. The resting label is derived from the pending-spec count, not stored, so the slot always reflects the latest count.

func (*Status) SetPending added in v0.12.0 

func (s *Status) SetPending(label string)

SetPending puts the element into the animated pending state with a present-tense label (e.g. "Syncing…"). Pending does not expire; it is cleared by a later SetSuccess/SetError or Idle. Starting new work also supersedes any sticky error, since the user has clearly moved on.

func (*Status) SetRestingCount added in v0.12.0 

func (s *Status) SetRestingCount(n int)

SetRestingCount records how many specs are pending. It updates the standing idle signal only; it never disturbs a live pending/success/error state, which will reveal the new count when it decays back to idle.

func (*Status) SetSuccess added in v0.12.0 

func (s *Status) SetSuccess(label string, duration time.Duration)

SetSuccess shows a positive outcome that decays back to idle after duration. A success supersedes any sticky error (the later operation succeeded).

func (Status) ShowingOutcome added in v0.12.0 

func (s Status) ShowingOutcome() bool

ShowingOutcome reports whether a live success or error outcome is currently displayed (i.e. set and not yet decayed to idle).

func (Status) View added in v0.12.0 

func (s Status) View() string

View renders the status element as "<icon> <label>" through the kind's style. The element is always non-empty (idle reports pending work or "No pending work"), so the slot never collapses and surrounding panes never reflow (AC-3, AC-4). The caller owns the surrounding fixed-width slot; this returns the styled inner content.

type StatusBar 

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

StatusBar renders the bottom bar: view name, the canonical status element, help hint, and time. The status element is the single authoritative place to learn "what's going on right now" (SPEC-016); it occupies the fixed slot formerly held by the scattered pending/spinner/banner/toast surfaces.

func NewStatusBar 

func NewStatusBar(styles StatusBarStyles) StatusBar

NewStatusBar creates a new status bar with the canonical status element in its idle state.

func (StatusBar) Animating added in v0.12.0 

func (s StatusBar) Animating() bool

Animating reports whether the status element needs animation ticks.

func (StatusBar) ErrorDetail added in v0.12.0 

func (s StatusBar) ErrorDetail() string

ErrorDetail returns the full untruncated text of the current error, or empty.

func (StatusBar) HasError added in v0.12.0 

func (s StatusBar) HasError() bool

HasError reports whether a sticky error is currently shown.

func (*StatusBar) NextSpinner 

func (s *StatusBar) NextSpinner()

NextSpinner advances the pending-status animation frame. It is a no-op unless the status element is pending, so idle/success/error consume no animation frames.

func (*StatusBar) SetExitArmed added in v0.8.3 

func (s *StatusBar) SetExitArmed(armed bool)

SetExitArmed sets whether the status bar should show the double-esc-to-quit hint.

func (*StatusBar) SetPending 

func (s *StatusBar) SetPending(count int)

SetPending records the number of pending specs. This is the standing work signal shown by the canonical status element in its resting (idle) state — the former "N pending" badge, now folded into the single status element so the bar carries one status surface instead of two.

func (*StatusBar) SetRefresh 

func (s *StatusBar) SetRefresh(t time.Time)

SetRefresh updates the last refresh time.

func (*StatusBar) SetScroll 

func (s *StatusBar) SetScroll(pos string)

SetScroll updates the scroll position indicator (e.g. "3/12").

func (*StatusBar) SetStatusError added in v0.12.0 

func (s *StatusBar) SetStatusError(summary, detail string)

SetStatusError shows a sticky error in the status element. It stays until the next operation supersedes it or the user dismisses it; the full message is reachable via ErrorDetail (shown in a modal on demand). Replaces the error toast/banner path. summary is the short slot-sized headline; detail is the full untruncated message.

func (*StatusBar) SetStatusIdle added in v0.12.0 

func (s *StatusBar) SetStatusIdle()

SetStatusIdle returns the canonical status element to its resting state.

func (*StatusBar) SetStatusPending added in v0.12.0 

func (s *StatusBar) SetStatusPending(label string)

SetStatusPending puts the canonical status element into the animated pending state with a present-tense label. This replaces the retired spinner + pending notice; callers set the status model rather than toggling widgets.

func (*StatusBar) SetStatusSuccess added in v0.12.0 

func (s *StatusBar) SetStatusSuccess(label string, duration time.Duration)

SetStatusSuccess shows a success outcome in the status element; it decays back to idle after duration. Replaces the success toast path.

func (*StatusBar) SetView 

func (s *StatusBar) SetView(label string)

SetView updates the displayed view label.

func (*StatusBar) SetWidth 

func (s *StatusBar) SetWidth(w int)

SetWidth updates the status bar width.

func (StatusBar) ShowingOutcome added in v0.12.0 

func (s StatusBar) ShowingOutcome() bool

ShowingOutcome reports whether a live (non-decayed) success or error outcome is currently displayed, so callers can avoid stomping it with lower-salience pending cues such as a background refresh.

func (StatusBar) StatusKind added in v0.12.0 

func (s StatusBar) StatusKind() StatusKind

StatusKind returns the canonical status element's current (decay-resolved) kind. Intended for assertions about which status is showing.

func (StatusBar) StatusLabel added in v0.12.0 

func (s StatusBar) StatusLabel() string

StatusLabel returns the canonical status element's current label.

func (StatusBar) View 

func (s StatusBar) View() string

View renders the status bar. The canonical status element sits immediately after the view label and sizes to its content; the freshness ("Ns ago") indicator lives in the right-hand cluster, only appearing once data is stale.

type StatusBarStyles 

type StatusBarStyles struct {
	Bar     lipgloss.Style
	Label   lipgloss.Style
	Pending lipgloss.Style
	Hint    lipgloss.Style
	Clock   lipgloss.Style
	Stale   lipgloss.Style
	Status  StatusStyles
}

StatusBarStyles holds the styles for the status bar.

type StatusKind added in v0.12.0 

type StatusKind int

StatusKind is the canonical set of status signals surfaced by the TUI. It formalises the previously scattered surfaces (spinner, pending notice, banner, toasts) into one taxonomy — no new application states are added (SPEC-016 §7.1). Ordering is significant for muscle-memory: idle is the resting state and every transient outcome decays back to it. 

const (
	// StatusIdle is the resting state. The slot stays present (never collapses)
	// showing a dim glyph and a muted label so the layout never reflows.
	StatusIdle StatusKind = iota
	// StatusPending marks in-progress work. Its glyph is the only animated one.
	StatusPending
	// StatusSuccess marks a completed outcome. Decays back to idle.
	StatusSuccess
	// StatusError marks a failed outcome. Decays back to idle.
	StatusError
)

type StatusStyles added in v0.12.0 

type StatusStyles struct {
	Idle    lipgloss.Style
	Pending lipgloss.Style
	Success lipgloss.Style
	Error   lipgloss.Style
}

StatusStyles holds the styles for each status kind. All are derived from the existing "pending" element palette tokens by the caller for visual continuity (SPEC-016 §5.4 / AC-6); this component never defines colours.

type Tab 

type Tab struct {
	Label    string
	Shortcut string
}

Tab represents a single tab in the tab strip.

type TabStrip 

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

TabStrip renders a horizontal tab bar.

func NewTabStrip 

func NewTabStrip(tabs []Tab, styles TabStripStyles) TabStrip

NewTabStrip creates a new tab strip.

func (*TabStrip) SetActive 

func (t *TabStrip) SetActive(idx int)

SetActive updates the active tab index.

func (*TabStrip) SetWidth 

func (t *TabStrip) SetWidth(w int)

SetWidth updates the tab strip width.

func (TabStrip) View 

func (t TabStrip) View() string

View renders the tab strip.

type TabStripStyles 

type TabStripStyles struct {
	Active    lipgloss.Style
	Inactive  lipgloss.Style
	Bar       lipgloss.Style
	Separator lipgloss.Style
}

TabStripStyles holds the styles for the tab strip.

Source Files

View all Source files

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.