ui

package
v0.2.3 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2025 License: GPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package ui provides terminal user interface components and utilities.

This package contains all terminal-facing UI elements used by nssh CLI commands, including styled output, prompts, tables, and fuzzy selection.

Output Functions

Styled output functions for consistent CLI appearance: 

ui.Info("Processing %d hosts", count)     // Blue info message
ui.Success("Connection established")       // Green success message
ui.Warning("Certificate expires soon")     // Yellow warning
ui.Error("Connection failed: %v", err)     // Red error message

Prompts

Interactive prompts for user input: 

name, err := ui.Prompt("Hostname", "default-value")
password, err := ui.PasswordSecure("Password")  // Returns *memguard.LockedBuffer
confirmed, err := ui.Confirm("Delete host?", false)

Fuzzy Selection

Integration with fzf for fuzzy selection: 

selected, err := ui.FuzzySelectString("Select host", hosts, "")

Tables

Formatted table output: 

t := ui.NewTable("Name", "Host", "Port")
t.AddRow("server1", "10.0.0.1", "22")
t.Print()

Styled Help

Custom help formatting for Cobra commands: 

ui.ApplyStyledHelp(cmd)           // Single command
ui.ApplyStyledHelpRecursive(cmd)  // Command and all subcommands

Components

Visual components for command output: 

ui.Ruler("SECTION TITLE")   // Horizontal rule with title
ui.CommandStart("CONNECT")  // Command header
ui.CommandEnd(ui.StatusSuccess)  // Command footer with status

Package ui provides terminal user interface components including styled text, panels, tables, prompts, and progress bars using lipgloss and huh.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ColorCyan    = lipgloss.Color("6")   // ANSI cyan
	ColorGreen   = lipgloss.Color("78")  // Soft green
	ColorYellow  = lipgloss.Color("220") // Warning yellow
	ColorRed     = lipgloss.Color("196") // Error red
	ColorGray    = lipgloss.Color("245") // Muted gray
	ColorDim     = lipgloss.Color("240") // Dimmer gray for borders
	ColorWhite   = lipgloss.Color("255") // Bright white
	ColorMagenta = lipgloss.Color("213") // Soft magenta
)

Color palette - muted, professional tones

View Source 
var (
	StyleBold      = lipgloss.NewStyle().Bold(true)
	StyleDim       = lipgloss.NewStyle().Foreground(ColorGray)
	StyleCyan      = lipgloss.NewStyle().Foreground(ColorCyan)
	StyleGreen     = lipgloss.NewStyle().Foreground(ColorGreen)
	StyleYellow    = lipgloss.NewStyle().Foreground(ColorYellow)
	StyleRed       = lipgloss.NewStyle().Foreground(ColorRed)
	StyleMagenta   = lipgloss.NewStyle().Foreground(ColorMagenta)
	StyleWhite     = lipgloss.NewStyle().Foreground(ColorWhite)
	StyleLabel     = lipgloss.NewStyle().Foreground(ColorGray).Bold(true)
	StyleValue     = lipgloss.NewStyle().Foreground(ColorCyan)
	StyleValueDim  = lipgloss.NewStyle().Foreground(ColorGray)
	StyleHighlight = lipgloss.NewStyle().Foreground(ColorGreen).Bold(true)
)

Text styles

View Source 
var ErrInterrupted = errors.New("input interrupted")

ErrInterrupted is returned when the user cancels input with Ctrl+C or SIGTERM. Callers should check for this error and exit gracefully without printing an error message.

Functions

func Abort 

func Abort(format string, args ...any)

Abort prints an abort message (user canceled).

func ApplyStyledHelp 

func ApplyStyledHelp(cmd *cobra.Command)

ApplyStyledHelp sets a command to use styled help rendering. It also adds an --explain flag for extended help if the command has a Long description.

func ApplyStyledHelpRecursive 

func ApplyStyledHelpRecursive(cmd *cobra.Command)

ApplyStyledHelpRecursive applies styled help to a command and all subcommands.

func BatchPreview 

func BatchPreview(groups []BatchGroup, action string)

BatchPreview displays a pretty preview of batch operations grouped by context. action is "+" for add, "-" for remove

func BatchSummaryLine 

func BatchSummaryLine(totalItems, groupCount int, itemNoun string)

BatchSummaryLine prints a summary line for batch operations. Example: " 6 hosts across 2 contexts"

func Bold 

func Bold(s string) string

Bold renders text in bold.

func BorderedPanel 

func BorderedPanel(title, content string, titleAlign string, width int, padY ...bool) string

BorderedPanel renders content in a bordered panel with title on the border. titleAlign: "left" (default) or "center" width: 0 = auto-fit to content padY: add empty lines inside top/bottom of box

func Box 

func Box(title, content string)

Box prints content in a styled box with optional title.

func CommandEnd 

func CommandEnd(status StatusType)

CommandEnd prints a status-colored footer banner.

func CommandStart 

func CommandStart(title string)

CommandStart prints the header banner for a command (cyan-colored).

func CompatFixPreview 

func CompatFixPreview(hostname string, fixes []string)

CompatFixPreview displays what compatibility fixes will be applied.

func Confirm 

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

Confirm shows a yes/no confirmation prompt. Returns the user's choice.

func Creation 

func Creation(format string, args ...any)

Creation prints a creation message (item being added).

func Cyan 

func Cyan(s string) string

Cyan renders text in cyan color.

func Deletion 

func Deletion(format string, args ...any)

Deletion prints a deletion message (item being removed).

func DimCyan 

func DimCyan(s string) string

DimCyan renders text in dimmed cyan color.

func DimGreen 

func DimGreen(s string) string

DimGreen renders text in dimmed green color.

func DimRed 

func DimRed(s string) string

DimRed renders text in dimmed red color.

func Error 

func Error(format string, args ...any)

Error prints an error message.

func FuzzySelect 

func FuzzySelect(prompt string, options []FuzzySelectOption, initialQuery ...string) (int, error)

FuzzySelect presents a fuzzy finder interface and returns the selected option. Returns the index of the selected option, or -1 if canceled. Optional initialQuery pre-fills the search input. Falls back to huh's filtered select if fzf is unavailable.

func FuzzySelectMulti 

func FuzzySelectMulti(prompt string, options []FuzzySelectOption) ([]int, error)

FuzzySelectMulti presents a fuzzy finder for multi-selection. Returns indices of selected options, or empty slice if canceled. Falls back to huh's multi-select if fzf is unavailable.

func FuzzySelectString 

func FuzzySelectString(prompt string, options []string, initialQuery ...string) (string, error)

FuzzySelectString presents a fuzzy finder for a simple string list. Returns the selected string, or empty string if canceled. Optional initialQuery pre-fills the search input. Falls back to huh's filtered select if fzf is unavailable.

func FzfAvailable 

func FzfAvailable() bool

FzfAvailable checks if fzf is installed.

func Gray 

func Gray(s string) string

Gray renders text in gray color.

func Green 

func Green(s string) string

Green renders text in green color. 

func Header(title string)

Header prints a prominent header (cyan-colored, for top-level commands).

func Indent 

func Indent(s string, level int) string

Indent returns a string with consistent indentation.

func Info 

func Info(format string, args ...any)

Info prints an info message.

func InfoBox 

func InfoBox(title, content string)

InfoBox prints content in a cyan info box.

func InfoCentered 

func InfoCentered(format string, args ...any)

InfoCentered prints a centered info message.

func InfoWithMargin 

func InfoWithMargin(margin int, format string, args ...any)

InfoWithMargin prints an info message with a left margin.

func Input 

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

Input shows a text input prompt. After completion, prints the result so it persists on screen.

func InputHostname 

func InputHostname(title, defaultValue string) (string, error)

InputHostname shows a text input prompt for a hostname (FQDN, short name, or IP). After completion, prints the result so it persists on screen.

func InputWithDefault 

func InputWithDefault(title, defaultValue string) (string, error)

InputWithDefault shows a text input prompt with a pre-filled default value. After completion, prints the result so it persists on screen.

func InputWithFzf 

func InputWithFzf(title, defaultValue string, fzfChoices []string, fzfPrompt string) (string, error)

InputWithFzf shows a text input prompt with optional Tab-triggered fzf selection. User can:

  • Press Enter to accept default
  • Type a value and press Enter
  • Press Tab to launch fzf browser (if choices provided and fzf is available)

After completion, prints the result so it persists on screen.

func InsertionPreview 

func InsertionPreview(newLines, beforeHost, afterHost []string, targetFile string, maxContextLines int)

InsertionPreview displays a diff-style preview of where a new host will be inserted in the SSH config file.

Parameters:

  • newLines: The new host config lines to be inserted
  • beforeHost: Lines of the host that will appear before (nil if inserting at start)
  • afterHost: Lines of the host that will appear after (nil if inserting at end)
  • targetFile: Path to the target file (for display)
  • maxContextLines: Maximum lines to show per context block (0 = show all)

func IsExplainShown 

func IsExplainShown(err error) bool

IsExplainShown checks if the error is from --explain being handled.

func KeyValue 

func KeyValue(key, value string) string

KeyValue returns a formatted key-value pair.

func KeyValueBlock 

func KeyValueBlock(pairs map[string]string, order []string)

KeyValueBlock prints multiple key-value pairs aligned.

func List 

func List(items []string)

List prints a bulleted list.

func Magenta 

func Magenta(s string) string

Magenta renders text in magenta color.

func Noop 

func Noop(format string, args ...any)

Noop prints a no-op message (nothing changed).

func NumberedList 

func NumberedList(items []string)

NumberedList prints a numbered list.

func Password 

func Password(title string) (string, error)

Password shows a password input prompt (masked). After completion, prints a masked indicator so it persists on screen.

func PasswordSecure 

func PasswordSecure(title string) (*memguard.LockedBuffer, error)

PasswordSecure prompts for password input and returns a secure buffer. The returned buffer must be destroyed by the caller after use. Returns ErrInterrupted if the user cancels with Ctrl+C or SIGTERM.

func PasswordSecureWithConfirm 

func PasswordSecureWithConfirm(title string) (*memguard.LockedBuffer, error)

PasswordSecureWithConfirm prompts for password input twice and verifies they match. Returns a secure buffer containing the confirmed password. The returned buffer must be destroyed by the caller after use. Returns ErrInterrupted if the user cancels with Ctrl+C or SIGTERM.

NOTE: This function does NOT validate passphrase requirements (length, etc.). For passphrase initialization, use PassphraseStore.Initialize() which validates BEFORE confirmation to provide better UX (fail fast on invalid input). This function is for general-purpose confirmed input where validation is handled by the caller or not required.

func PasswordWithConfirm 

func PasswordWithConfirm(title string) (string, error)

PasswordWithConfirm shows two password prompts and validates they match. Returns an error if passwords don't match or are empty.

func PrintKeyValue 

func PrintKeyValue(key, value string)

PrintKeyValue prints a formatted key-value pair with info status prefix.

func PrintRuler 

func PrintRuler(title string)

PrintRuler prints a ruler to stdout.

func PrintTable 

func PrintTable(headers []TableHeader, rows [][]string) int

PrintTable prints a table with styled headers and returns the left margin.

func Red 

func Red(s string) string

Red renders text in red color.

func RemovalPreview 

func RemovalPreview(hostLines []string, targetFile string)

RemovalPreview displays a diff-style preview of a host being removed.

func RenderProgress 

func RenderProgress(label string, current, total int) string

RenderProgress is a helper to render a simple one-line progress bar. Returns the rendered string without printing.

func RenderStyledHelp 

func RenderStyledHelp(cmd *cobra.Command, cfg StyledHelpConfig) string

RenderStyledHelp renders a command's help in styled panel format.

func Ruler 

func Ruler(title string) string

Ruler prints a horizontal line with optional centered title. Example: ──────────── HOST DETAILS ────────────

func Section 

func Section(title string)

Section prints a section header (ruler with title).

func Select 

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

Select shows a select prompt and returns the selected value. Returns empty string if canceled.

func SelectIndex 

func SelectIndex(title string, options []string, input io.Reader) (int, error)

SelectIndex shows a select prompt and returns the selected index. Returns -1 if canceled.

func SimpleTable 

func SimpleTable(headers []string, rows [][]string)

SimpleTable prints a quick table from headers and rows.

func StatusLine 

func StatusLine(ok bool, label, value string)

StatusLine prints an inline status with icon. ok=true shows green [✓], ok=false shows red [✗]

func StatusLineNeutral 

func StatusLineNeutral(label, value string)

StatusLineNeutral prints an inline status with neutral [-] icon (dimmed).

func StatusLineNeutralText 

func StatusLineNeutralText(text string)

StatusLineNeutralText prints text with neutral [-] icon (dimmed), no label.

func StripANSI 

func StripANSI(s string) string

StripANSI removes ANSI escape codes from a string.

func SubSection 

func SubSection(title string, skipNewline ...bool)

SubSection prints a lightweight sub-section header with a mini ruler. Example: ── Preview Pass skipNewline=true to omit the leading blank line.

func Success 

func Success(format string, args ...any)

Success prints a success message.

func SuccessBox 

func SuccessBox(title, content string)

SuccessBox prints content in a green success box.

func Truncate 

func Truncate(s string, maxWidth int) string

Truncate shortens a string to maxWidth display width, adding ellipsis if needed. Handles multi-byte characters correctly using runewidth.

func VisualWidth 

func VisualWidth(s string) int

VisualWidth returns the visual width of a string, ignoring ANSI escape codes.

func Warning 

func Warning(format string, args ...any)

Warning prints a warning message.

func WarningBox 

func WarningBox(title, content string)

WarningBox prints content in a red warning box.

func WarningCentered 

func WarningCentered(format string, args ...any)

WarningCentered prints a centered warning message.

func Yellow 

func Yellow(s string) string

Yellow renders text in yellow color.

Types

type BatchGroup 

type BatchGroup struct {
	Name  string
	Items []BatchItem
}

BatchGroup represents a group of items for batch display.

type BatchItem 

type BatchItem struct {
	Name   string
	Detail string // optional additional info (e.g., hostname when different from alias)
}

BatchItem represents an item in a batch operation.

type BatchProgress 

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

BatchProgress tracks and displays progress of batch operations.

func NewBatchProgress 

func NewBatchProgress(items []string) *BatchProgress

NewBatchProgress creates a new batch progress tracker.

func (*BatchProgress) MarkError 

func (bp *BatchProgress) MarkError(name, message string)

MarkError marks an item as failed.

func (*BatchProgress) MarkSuccess 

func (bp *BatchProgress) MarkSuccess(name string)

MarkSuccess marks an item as successful.

type FuzzySelectOption 

type FuzzySelectOption struct {
	// Label is the main display text
	Label string

	// Description is the secondary text (shown on the right)
	Description string

	// Value is the underlying value to return when selected
	Value any
}

FuzzySelectOption represents an option in fuzzy selection.

func HostSelectOption 

func HostSelectOption(alias, hostname, user, configFile string) FuzzySelectOption

HostSelectOption creates a FuzzySelectOption for a host entry.

type Panel 

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

Panel displays key-value content within rulers. Top ruler has title, bottom ruler has optional footer (like "OK").

func NewPanel 

func NewPanel(title string) *Panel

NewPanel creates a new panel with title.

func (*Panel) Print 

func (p *Panel) Print()

Print renders the panel to stdout.

func (*Panel) Render 

func (p *Panel) Render() string

Render returns the panel as a string.

func (*Panel) Row 

func (p *Panel) Row(label, value string) *Panel

Row adds a key-value row.

func (*Panel) WithFooter 

func (p *Panel) WithFooter(footer string) *Panel

WithFooter sets the footer text.

func (*Panel) WithWarning 

func (p *Panel) WithWarning() *Panel

WithWarning makes the panel use warning colors.

type ProgressBar 

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

ProgressBar renders a styled progress bar that matches the UI theme. Example output: 

[-] Exporting [████████████░░░░░░░░░░░░] 60/100 60%

func NewProgressBar 

func NewProgressBar(label string, total int) *ProgressBar

NewProgressBar creates a new progress bar with the given label.

func (*ProgressBar) Clear 

func (p *ProgressBar) Clear()

Clear clears the progress bar line.

func (*ProgressBar) Print 

func (p *ProgressBar) Print()

Print renders the progress bar to stdout with carriage return (for updates).

func (*ProgressBar) PrintLn 

func (p *ProgressBar) PrintLn()

PrintLn renders the progress bar to stdout with newline (final state).

func (*ProgressBar) Render 

func (p *ProgressBar) Render() string

Render returns the progress bar as a styled string.

func (*ProgressBar) Update 

func (p *ProgressBar) Update(current int)

Update sets the current progress value.

func (*ProgressBar) WithWidth 

func (p *ProgressBar) WithWidth(width int) *ProgressBar

WithWidth sets the bar width (default 30).

func (*ProgressBar) WithoutCount 

func (p *ProgressBar) WithoutCount() *ProgressBar

WithoutCount hides the count display.

func (*ProgressBar) WithoutPercent 

func (p *ProgressBar) WithoutPercent() *ProgressBar

WithoutPercent hides the percentage display.

type SelectOption 

type SelectOption struct {
	Label string
	Value string
}

SelectOption represents a choice in a select prompt.

type StatusType 

type StatusType int

StatusType represents the type of status message for output formatting. 

const (
	StatusSuccess  StatusType = iota // Success status with checkmark
	StatusNoop                       // No operation performed
	StatusAbort                      // Operation aborted
	StatusInfo                       // Informational message
	StatusWarning                    // Warning message
	StatusError                      // Error message
	StatusDeletion                   // Item being deleted
	StatusCreation                   // Item being created
)

Status message types for formatted output.

type StyledHelpConfig 

type StyledHelpConfig struct {
	// ShowGlobalFlags includes global flags in output
	ShowGlobalFlags bool
	// Width is the panel width (0 = auto-detect terminal width)
	Width int
}

StyledHelpConfig holds configuration for styled help rendering.

func DefaultHelpConfig 

func DefaultHelpConfig() StyledHelpConfig

DefaultHelpConfig returns the default styled help configuration.

type Table 

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

Table wraps table data for consistent styling.

func BuildTable 

func BuildTable(headers []TableHeader, rows [][]string) *Table

BuildTable creates a table without printing it.

func NewTable 

func NewTable(headers ...string) *Table

NewTable creates a new table with the given headers.

func (*Table) AddFooterRow 

func (t *Table) AddFooterRow(cells ...string)

AddFooterRow adds a row that will be styled as a footer with a separator border.

func (*Table) AddRow 

func (t *Table) AddRow(cells ...string)

AddRow adds a row to the table.

func (*Table) IsEmpty 

func (t *Table) IsEmpty() bool

IsEmpty returns true if the table has no data rows.

func (*Table) LeftMargin 

func (t *Table) LeftMargin() int

LeftMargin returns the left margin that would be used for centering without printing.

func (*Table) Render 

func (t *Table) Render() int

Render prints the table to stdout (centered) and returns the left margin used for centering.

func (*Table) RenderLeft 

func (t *Table) RenderLeft()

RenderLeft prints the table to stdout with left alignment (no centering).

func (*Table) RowCount 

func (t *Table) RowCount() int

RowCount returns the number of data rows (excluding header).

type TableHeader 

type TableHeader struct {
	Title string
	Color string // not used currently, kept for API compatibility
}

TableHeader represents a column header with optional styling.

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.