tui

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package tui provides terminal user interface components.

Package tui provides terminal user interface components.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Confirm 

func Confirm(message string, defaultValue bool) (bool, error)

Confirm shows a yes/no confirmation prompt.

func ConfirmDangerous 

func ConfirmDangerous(message string) (bool, error)

ConfirmDangerous shows a confirmation prompt for dangerous actions.

func ConfirmSetDefault 

func ConfirmSetDefault(valueName string) (bool, error)

ConfirmSetDefault asks the user if they want to save a value as the default.

func Form 

func Form(title string, fields []FormField) (map[string]string, error)

Form shows a multi-field form and returns a map of key -> value.

func Input 

func Input(title, placeholder string) (string, error)

Input shows a text input prompt.

func InputRequired 

func InputRequired(title, placeholder string) (string, error)

InputRequired shows a required text input prompt.

func MultiSelect 

func MultiSelect(title string, options []SelectOption) ([]string, error)

MultiSelect shows a multi-select prompt.

func Note 

func Note(title, body string) error

Note shows an informational note (non-interactive).

func Select 

func Select(title string, options []SelectOption) (string, error)

Select shows a single-select prompt.

func SelectScope 

func SelectScope() (string, error)

SelectScope shows a prompt for selecting the config scope (global or local).

func SelectWithDescription 

func SelectWithDescription(title, description string, options []SelectOption) (string, error)

SelectWithDescription shows a select prompt with descriptions.

func TextArea 

func TextArea(title, placeholder string) (string, error)

TextArea shows a multiline text input prompt.

func ThemeFilePath added in v0.2.0 

func ThemeFilePath() string

ThemeFilePath returns the resolved path to the active theme file, or "" if using defaults or NO_COLOR is set.

Types

type FormField 

type FormField struct {
	Key         string
	Title       string
	Placeholder string
	Required    bool
	Default     string
}

FormField represents a field in a form.

type ItemLoader 

type ItemLoader func() ([]PickerItem, error)

ItemLoader is a function that loads items asynchronously.

type PageFetcher 

type PageFetcher func(ctx context.Context, cursor string) (*PageResult, error)

PageFetcher fetches a page of items. It receives the cursor from the previous page (empty string for the first page) and returns the items and pagination info.

type PageResult 

type PageResult struct {
	Items   []PickerItem
	HasMore bool
	// NextCursor can be used by the PageFetcher to track pagination state.
	// The paginated picker doesn't interpret this value; it just passes it back.
	NextCursor string
}

PageResult represents a page of items from a paginated API.

type PaginatedPicker 

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

PaginatedPicker shows a fuzzy-search picker with progressive pagination.

func NewPaginatedPicker 

func NewPaginatedPicker(ctx context.Context, fetcher PageFetcher, opts ...PaginatedPickerOption) *PaginatedPicker

NewPaginatedPicker creates a new paginated picker.

func (*PaginatedPicker) Run 

func (p *PaginatedPicker) Run() (*PickerItem, error)

Run shows the picker and returns the selected item. Returns nil if the user canceled.

type PaginatedPickerOption 

type PaginatedPickerOption func(*paginatedPickerModel)

PaginatedPickerOption configures a paginated picker.

func WithFetchThreshold 

func WithFetchThreshold(n int) PaginatedPickerOption

WithFetchThreshold sets how many items from the bottom triggers a fetch.

func WithLoadingMessage 

func WithLoadingMessage(msg string) PaginatedPickerOption

WithLoadingMessage sets the loading message.

func WithPaginatedMaxVisible 

func WithPaginatedMaxVisible(n int) PaginatedPickerOption

WithPaginatedMaxVisible sets the maximum number of visible items.

func WithPaginatedPickerTitle 

func WithPaginatedPickerTitle(title string) PaginatedPickerOption

WithPaginatedPickerTitle sets the picker title.

type Picker 

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

Picker shows a fuzzy-search picker and returns the selected item.

func NewPicker 

func NewPicker(items []PickerItem, opts ...PickerOption) *Picker

NewPicker creates a new picker.

func NewPickerWithLoader 

func NewPickerWithLoader(loader ItemLoader, opts ...PickerOption) *Picker

NewPickerWithLoader creates a picker that loads items asynchronously.

func (*Picker) Run 

func (p *Picker) Run() (*PickerItem, error)

Run shows the picker and returns the selected item. Returns nil if the user canceled.

type PickerItem 

type PickerItem struct {
	ID          string
	Title       string
	Description string
}

PickerItem represents an item in a picker.

func Pick 

func Pick(title string, items []PickerItem) (*PickerItem, error)

Pick is a convenience function for simple picking.

func PickAccount 

func PickAccount(accounts []PickerItem) (*PickerItem, error)

PickAccount shows a picker for accounts.

func PickHost 

func PickHost(hosts []PickerItem) (*PickerItem, error)

PickHost shows a picker for hosts/environments.

func PickPaginated 

func PickPaginated(ctx context.Context, title string, fetcher PageFetcher) (*PickerItem, error)

PickPaginated is a convenience function for paginated picking.

func PickPerson 

func PickPerson(people []PickerItem) (*PickerItem, error)

PickPerson shows a picker for people.

func PickProject 

func PickProject(projects []PickerItem) (*PickerItem, error)

PickProject shows a picker for projects.

func PickTodolist 

func PickTodolist(todolists []PickerItem) (*PickerItem, error)

PickTodolist shows a picker for todolists.

func (PickerItem) FilterValue 

func (i PickerItem) FilterValue() string

FilterValue returns the string to filter on.

func (PickerItem) String 

func (i PickerItem) String() string

type PickerItemsLoadedMsg 

type PickerItemsLoadedMsg struct {
	Items []PickerItem
	Err   error
}

PickerItemsLoadedMsg is sent when items are loaded asynchronously.

type PickerOption 

type PickerOption func(*pickerModel)

PickerOption configures a picker.

func WithAutoSelectSingle 

func WithAutoSelectSingle() PickerOption

WithAutoSelectSingle automatically selects and returns if only one item exists.

func WithEmptyMessage 

func WithEmptyMessage(msg string) PickerOption

WithEmptyMessage sets a custom message shown when no items are available.

func WithHelp 

func WithHelp(show bool) PickerOption

WithHelp shows keyboard shortcuts in the picker.

func WithLoading 

func WithLoading(msg string) PickerOption

WithLoading sets the picker to start in loading state.

func WithMaxVisible 

func WithMaxVisible(n int) PickerOption

WithMaxVisible sets the maximum number of visible items.

func WithPickerTitle 

func WithPickerTitle(title string) PickerOption

WithPickerTitle sets the picker title.

func WithRecentItems 

func WithRecentItems(items []PickerItem) PickerOption

WithRecentItems prepends recently used items to the list, marked with a prefix.

type SelectOption 

type SelectOption struct {
	Value string
	Label string
}

SelectOption represents an option in a select prompt.

type Spinner 

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

Spinner runs a spinner while a function executes.

func NewSpinner 

func NewSpinner(message string, opts ...SpinnerOption) *Spinner

NewSpinner creates a new spinner with a message.

func (*Spinner) Run 

func (s *Spinner) Run(fn func() (string, error)) (string, error)

Run executes the given function while displaying a spinner. Returns the result and any error from the function.

func (*Spinner) RunSimple 

func (s *Spinner) RunSimple(fn func() error) error

RunSimple executes a function while displaying a spinner. Use this for functions that don't return a result message.

type SpinnerOption 

type SpinnerOption func(*spinnerModel)

SpinnerOption configures a spinner.

func WithSpinnerColor 

func WithSpinnerColor(color lipgloss.TerminalColor) SpinnerOption

WithSpinnerColor sets the spinner color.

func WithSpinnerStyle 

func WithSpinnerStyle(style SpinnerStyle) SpinnerOption

WithSpinnerStyle sets the spinner animation style.

type SpinnerStyle 

type SpinnerStyle int

SpinnerStyle defines the visual style of a spinner. 

const (
	SpinnerDots SpinnerStyle = iota
	SpinnerLine
	SpinnerPulse
	SpinnerPoints
	SpinnerGlobe
	SpinnerMoon
	SpinnerMonkey
	SpinnerMeter
	SpinnerHamburger
)

type Styles 

type Styles struct {

	// Text styles
	Title    lipgloss.Style
	Subtitle lipgloss.Style
	Heading  lipgloss.Style
	Body     lipgloss.Style
	Muted    lipgloss.Style
	Bold     lipgloss.Style
	Success  lipgloss.Style
	Warning  lipgloss.Style
	Error    lipgloss.Style

	// Container styles
	Box   lipgloss.Style
	Card  lipgloss.Style
	Panel lipgloss.Style

	// Interactive styles
	Focused  lipgloss.Style
	Selected lipgloss.Style
	Cursor   lipgloss.Style

	// Status styles
	StatusOK    lipgloss.Style
	StatusError lipgloss.Style
	StatusInfo  lipgloss.Style
	// contains filtered or unexported fields
}

Styles holds the styled components for the TUI.

func NewStyles 

func NewStyles() *Styles

NewStyles creates a new Styles with the default theme.

func NewStylesWithTheme 

func NewStylesWithTheme(theme Theme) *Styles

NewStylesWithTheme creates a new Styles with a custom theme.

func (*Styles) RenderCheckbox 

func (s *Styles) RenderCheckbox(checked bool, label string) string

RenderCheckbox renders a checkbox item.

func (*Styles) RenderKeyValue 

func (s *Styles) RenderKeyValue(key, value string) string

RenderKeyValue renders a key-value pair.

func (*Styles) RenderStatus 

func (s *Styles) RenderStatus(ok bool, message string) string

RenderStatus renders a status message with appropriate styling.

func (*Styles) RenderTitle 

func (s *Styles) RenderTitle(title string, subtitle ...string) string

RenderTitle renders a title with optional subtitle.

func (*Styles) Theme 

func (s *Styles) Theme() Theme

Theme returns the current theme.

func (*Styles) UpdateTheme added in v0.2.0 

func (s *Styles) UpdateTheme(theme Theme)

UpdateTheme re-applies a theme to the existing Styles in place. Because all components hold a *Styles pointer, the next View() call picks up the new colors with zero propagation.

type Theme 

type Theme struct {
	Primary    lipgloss.AdaptiveColor
	Secondary  lipgloss.AdaptiveColor
	Success    lipgloss.AdaptiveColor
	Warning    lipgloss.AdaptiveColor
	Error      lipgloss.AdaptiveColor
	Muted      lipgloss.AdaptiveColor
	Background lipgloss.AdaptiveColor
	Foreground lipgloss.AdaptiveColor
	Border     lipgloss.AdaptiveColor
}

Theme defines the color palette for the TUI.

func DefaultTheme 

func DefaultTheme() Theme

DefaultTheme returns the default basecamp theme.

func LoadThemeFromFile 

func LoadThemeFromFile(path string) (Theme, error)

LoadThemeFromFile parses a colors.toml file and returns a Theme.

func LoadUserTheme 

func LoadUserTheme() (Theme, error)

LoadUserTheme attempts to load a theme from the user's basecamp config. The theme directory can be a symlink to another theme system.

func NoColorTheme 

func NoColorTheme() Theme

NoColorTheme returns a theme with empty colors (honors NO_COLOR standard). Lipgloss treats empty strings as "no color", resulting in plain text output.

func ResolveTheme 

func ResolveTheme() Theme

ResolveTheme loads a theme with the following precedence:

  1. NO_COLOR env var set → returns NoColorTheme (industry standard)
  2. BASECAMP_THEME env var → parse custom colors.toml file
  3. User theme from ~/.config/basecamp/theme/colors.toml
  4. Default basecamp theme

On systems like Omarchy, users can symlink to their system theme: 

ln -s ~/.config/omarchy/current/theme ~/.config/basecamp/theme

Source Files

View all Source files

Directories

Path Synopsis
Package empty provides empty state messages for TUI components.
 Package empty provides empty state messages for TUI components.
Package format provides formatting helpers for TUI components.
 Package format provides formatting helpers for TUI components.
Package recents provides a store for tracking recently used items.
 Package recents provides a store for tracking recently used items.
Package resolve provides interactive prompts for resolving missing CLI options.
 Package resolve provides interactive prompts for resolving missing CLI options.
Package workspace provides the persistent TUI application.
 Package workspace provides the persistent TUI application.
chrome
Package chrome provides always-visible shell components for the workspace.
 Package chrome provides always-visible shell components for the workspace.
data
views
Package views provides the individual screens for the workspace TUI.
 Package views provides the individual screens for the workspace TUI.
widget
Package widget provides reusable TUI components.
 Package widget provides reusable TUI components.

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.