ui

Documentation

Overview

Package ui hosts terminal output helpers — tables, spinners, colors, and formatted error rendering for API responses.

Package ui — named lipgloss styles for the finna CLI.

Index

• Variables
• func BarChart(labels []string, values []float64, opts BarChartOpts) string
• func CSVOutput(headers []string, rows [][]string, w io.Writer) error
• func ColorEnabled(noColor bool) bool
• func FormatAPIError(w io.Writer, err error)
• func FormatCurrency(f float64, currency string) string
• func FormatTime(t time.Time) string
• func LogLevelColor(level string, noColor bool) lipgloss.Style
• func OutputJSON(w io.Writer, v any) error
• func OutputYAML(w io.Writer, v any) error
• func Sparkline(values []float64, width int) string
• func StatusBadge(status string, noColor bool) string
• func StatusColor(status string, noColor bool) lipgloss.Style
• type BarChartOpts
• type OutputFormat
  • func ParseOutputFormat(s string) (OutputFormat, error)
• type Spinner
  • func Start(label string) *Spinner
  • func (s *Spinner) Stop()
  • func (s *Spinner) StopWithError(msg string)
  • func (s *Spinner) StopWithSuccess(msg string)
• type Table
  • func NewTable(headers []string, noColor bool) *Table
  • func (tb *Table) AddRow(cells ...string)
  • func (tb *Table) Render(w io.Writer)
  • func (tb *Table) RenderString() string

Variables

var (
	// Header is used for section titles and table headers.
	Header = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("12"))

	// Muted is used for secondary / de-emphasised text.
	Muted = lipgloss.NewStyle().Foreground(lipgloss.Color("240"))

	// Success is used for ok / healthy / pass messages.
	Success = lipgloss.NewStyle().Foreground(lipgloss.Color("10"))

	// Warning is used for degraded / near-threshold messages.
	Warning = lipgloss.NewStyle().Foreground(lipgloss.Color("11"))

	// Danger is used for error / critical / failed messages.
	Danger = lipgloss.NewStyle().Foreground(lipgloss.Color("9"))

	// Accent is used for highlights and call-to-action text.
	Accent = lipgloss.NewStyle().Foreground(lipgloss.Color("14"))
)

Shared styles. All callers should reference these rather than creating one-off styles so the colour palette stays consistent.

Functions

func BarChart

func BarChart(labels []string, values []float64, opts BarChartOpts) string

BarChart renders a horizontal ASCII bar chart. Each line: "label │████░░░ $value" Values are normalised to the maximum. Zero-value bars show a thin line.

func CSVOutput

func CSVOutput(headers []string, rows [][]string, w io.Writer) error

CSVOutput writes headers and rows as RFC 4180 CSV to w.

func ColorEnabled

func ColorEnabled(noColor bool) bool

ColorEnabled returns true when ANSI color output is appropriate. Resolution order: NO_COLOR env (RFC) > explicit disable flag > config "never". The noColor parameter comes from the --no-color global flag (via AppState).

func FormatAPIError

func FormatAPIError(w io.Writer, err error)

FormatAPIError pretty-prints a backend error to w. For 422 validation errors, each field violation is printed on its own line. For ordinary errors a single "HTTP <code>: <message>" line is produced.

Any non-APIError is rendered with err.Error().

func FormatCurrency

func FormatCurrency(f float64, currency string) string

FormatCurrency formats a float as a currency string. currency is an ISO code like "USD" or "EUR"; defaults to USD if empty.

func FormatTime

func FormatTime(t time.Time) string

FormatTime returns a human-readable relative time string ("2h ago", "just now", "3d ago"). Falls back to RFC3339 for very old times (>30d).

func LogLevelColor

func LogLevelColor(level string, noColor bool) lipgloss.Style

LogLevelColor returns the lipgloss style for a log level string.

func OutputJSON

func OutputJSON(w io.Writer, v any) error

OutputJSON writes v as indented JSON to w.

func OutputYAML

func OutputYAML(w io.Writer, v any) error

OutputYAML writes v as YAML to w.

func Sparkline

func Sparkline(values []float64, width int) string

Sparkline renders values as a single-line inline sparkline using block chars. width is the maximum character width; if 0 it defaults to len(values). Returns an empty string when values is nil or empty.

func StatusBadge

func StatusBadge(status string, noColor bool) string

StatusBadge returns a colored "● <status>" string for use in tables. When noColor is true the plain status string is returned unchanged.

func StatusColor

func StatusColor(status string, noColor bool) lipgloss.Style

StatusColor returns a lipgloss style for the given run/extractor status. Colors are suppressed when NO_COLOR is set or the noColor flag is active.

Types

type BarChartOpts

type BarChartOpts struct {
	// Width is the total bar width in characters (default 40).
	Width int
	// MaxLabel is the maximum label length before truncation (default 20).
	MaxLabel int
	// ColorEnabled enables ANSI colour for bars (respects NO_COLOR).
	ColorEnabled bool
	// Currency is appended to value labels (default "").
	Currency string
}

BarChartOpts configures BarChart rendering.

type OutputFormat

type OutputFormat string

OutputFormat is the user-visible output format selector.

const (
	FormatTable OutputFormat = "table"
	FormatJSON  OutputFormat = "json"
	FormatYAML  OutputFormat = "yaml"
	FormatCSV   OutputFormat = "csv"
	FormatWide  OutputFormat = "wide"
)

Output format constants used by --output / -o.

func ParseOutputFormat

func ParseOutputFormat(s string) (OutputFormat, error)

ParseOutputFormat validates and normalises the string from --output / -o.

type Spinner

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

Spinner provides a minimal progress indicator. When stdout is not a TTY (e.g. CI, pipe) it writes a plain "label... " line and nothing more.

func Start

func Start(label string) *Spinner

Start creates and starts a Spinner. Call Stop/StopWithSuccess/StopWithError when the operation completes.

func (*Spinner) Stop

func (s *Spinner) Stop()

Stop halts the spinner without printing a result message.

func (*Spinner) StopWithError

func (s *Spinner) StopWithError(msg string)

StopWithError halts and prints an error message.

func (*Spinner) StopWithSuccess

func (s *Spinner) StopWithSuccess(msg string)

StopWithSuccess halts and prints a success message.

type Table

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

Table is a consistent table renderer built on go-pretty.

func NewTable

func NewTable(headers []string, noColor bool) *Table

NewTable creates a Table with bold header row and alternating row shading. noColor disables ANSI styling; pass State().Flags.NoColor.

func (*Table) AddRow

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

AddRow appends a data row. All values are converted to strings.

func (*Table) Render

func (tb *Table) Render(w io.Writer)

Render writes the table to w.

func (*Table) RenderString

func (tb *Table) RenderString() string

RenderString returns the rendered table as a string (useful in tests).