ui

package
v1.205.0 Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Badge added in v1.205.0 

func Badge(text, background, foreground string) string

Badge returns a styled badge with the given text, background color, and foreground color. Badges are compact labels with background styling, typically used for status indicators. The background and foreground should be hex colors (e.g., "#FF9800", "#000000"). Use this when you need the formatted string without writing (e.g., in help text).

func ClearLine added in v1.200.0 

func ClearLine()

ClearLine clears the current line in the terminal and returns cursor to the beginning. Respects NO_COLOR and terminal capabilities - uses ANSI escape sequences only when supported. When colors are disabled, only writes carriage return to move cursor to start of line. This is useful for replacing spinner messages or other dynamic output with final status messages. Flow: ui.ClearLine() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

Example usage: 

ui.ClearLine()
ui.Success("Operation completed successfully")

func Error 

func Error(text string)

Error writes an error message with red X to stderr (UI channel). Flow: ui.Error() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Errorf 

func Errorf(format string, a ...interface{})

Errorf writes a formatted error message with red X to stderr (UI channel). Flow: ui.Errorf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Experimental added in v1.205.0 

func Experimental(feature string)

Experimental writes an experimental feature notification with test tube icon to stderr (UI channel). This is used to notify users when they're using an experimental feature that may change. The notification behavior is controlled by settings.experimental in atmos.yaml (silence, disable, warn, error). The caller (root.go PersistentPreRun) handles the config check - this function just outputs. Flow: ui.Experimental() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Experimentalf added in v1.205.0 

func Experimentalf(format string, a ...interface{})

Experimentalf writes a formatted experimental feature notification with test tube icon to stderr (UI channel). Flow: ui.Experimentalf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func FormatError added in v1.203.0 

func FormatError(text string) string

FormatError returns an error message with red X as a formatted string. Use this when you need the formatted string without writing (e.g., in bubbletea views).

func FormatExperimentalBadge added in v1.205.0 

func FormatExperimentalBadge() string

FormatExperimentalBadge returns an "EXPERIMENTAL" badge using theme colors. Use this to indicate experimental features in help text or command descriptions.

func FormatInline added in v1.205.0 

func FormatInline(text string) string

FormatInline renders inline markdown (backticks, bold, etc.) without icons or newlines. Use this for spinner progress messages or other single-line styled text.

func FormatSuccess added in v1.203.0 

func FormatSuccess(text string) string

FormatSuccess returns a success message with green checkmark as a formatted string. Use this when you need the formatted string without writing (e.g., in bubbletea views).

func GetColorProfile added in v1.205.0 

func GetColorProfile() termenv.Profile

GetColorProfile returns the configured termenv color profile. Use this instead of termenv.ColorProfile() to respect atmos's terminal detection. This ensures colors degrade gracefully in terminals that don't support TrueColor (like macOS Terminal.app which only supports 256 colors until macOS Tahoe).

The returned profile respects:

  • --force-color flag (returns TrueColor for screenshot generation).
  • --no-color / NO_COLOR env var (returns Ascii).
  • Terminal capabilities detected via COLORTERM env var.

Example usage. 

profile := ui.GetColorProfile()
glamour.WithColorProfile(profile)

func Hint added in v1.203.0 

func Hint(text string)

Hint writes a hint/tip message with lightbulb icon to stderr (UI channel). This is a convenience wrapper with themed hint icon and muted color. Flow: ui.Hint() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Hintf added in v1.203.0 

func Hintf(format string, a ...interface{})

Hintf writes a formatted hint/tip message with lightbulb icon to stderr (UI channel). This is a convenience wrapper with themed hint icon and muted color. Flow: ui.Hintf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Info 

func Info(text string)

Info writes an info message with cyan info icon to stderr (UI channel). Flow: ui.Info() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Infof 

func Infof(format string, a ...interface{})

Infof writes a formatted info message with cyan info icon to stderr (UI channel). Flow: ui.Infof() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func InitFormatter 

func InitFormatter(ioCtx io.Context)

InitFormatter initializes the global formatter with an I/O context. This should be called once at application startup (in root.go).

func Markdown 

func Markdown(content string)

Markdown writes rendered markdown to stdout (data channel). Use this for help text, documentation, and other pipeable formatted content. Note: Delegates to globalFormatter.Markdown() for rendering, then writes to data channel. Write errors are logged but not returned since callers cannot meaningfully handle them.

func MarkdownMessage 

func MarkdownMessage(content string)

MarkdownMessage writes rendered markdown to stderr (UI channel). Use this for formatted UI messages and errors. Write errors are logged but not returned since callers cannot meaningfully handle them.

func MarkdownMessagef 

func MarkdownMessagef(format string, a ...interface{})

MarkdownMessagef writes formatted markdown to stderr (UI channel).

func Markdownf 

func Markdownf(format string, a ...interface{})

Markdownf writes formatted markdown to stdout (data channel).

func Reset added in v1.203.0 

func Reset()

Reset clears all UI globals (formatter, I/O, terminal). This is primarily used in tests to ensure clean state between test executions.

func SetColorProfile added in v1.200.0 

func SetColorProfile(profile termenv.Profile)

SetColorProfile sets the color profile for all UI systems (lipgloss, theme, logger). This is primarily intended for testing when environment variables are set after package initialization. For normal operation, color profiles are automatically configured during InitFormatter() based on terminal capabilities.

Example usage in tests: 

t.Setenv("NO_COLOR", "1")
ui.SetColorProfile(termenv.Ascii)

func Success 

func Success(text string)

Success writes a success message with green checkmark to stderr (UI channel). Flow: ui.Success() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Successf 

func Successf(format string, a ...interface{})

Successf writes a formatted success message with green checkmark to stderr (UI channel). Flow: ui.Successf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Toast added in v1.199.0 

func Toast(icon, message string)

Toast writes a toast message with custom icon to stderr (UI channel). Flow: ui.Toast() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Toastf added in v1.199.0 

func Toastf(icon, format string, a ...interface{})

Toastf writes a formatted toast message with custom icon to stderr (UI channel). Flow: ui.Toastf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Warning 

func Warning(text string)

Warning writes a warning message with yellow warning sign to stderr (UI channel). Flow: ui.Warning() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Warningf 

func Warningf(format string, a ...interface{})

Warningf writes a formatted warning message with yellow warning sign to stderr (UI channel). Flow: ui.Warningf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Write 

func Write(text string)

Write writes plain text to stderr (UI channel) without icons or automatic styling. Flow: ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Writef 

func Writef(format string, a ...interface{})

Writef writes formatted text to stderr (UI channel) without icons or automatic styling. Flow: ui.Writef() → terminal.Write() → io.Write(UIStream) → masking → stderr.

func Writeln 

func Writeln(text string)

Writeln writes text followed by a newline to stderr (UI channel) without icons or automatic styling. Flow: ui.Writeln() → terminal.Write() → io.Write(UIStream) → masking → stderr.

Types

type Formatter 

type Formatter interface {
	// Toast formatting - flexible toast notifications with custom icons and multiline support
	// Automatically handles newlines with proper indentation
	Toast(icon, message string) string                   // Returns "{icon} {message}" with multiline support
	Toastf(icon, format string, a ...interface{}) string // Returns formatted toast

	// Status message formatting - standardized output with icons
	// This is the foundational method used by Success/Error/Warning/Info
	StatusMessage(icon string, style *lipgloss.Style, text string) string

	// Semantic formatting - returns styled strings with automatic icons (uses theme.StyleSet)
	// These methods use Toast internally with predefined icons and colors
	Success(text string) string                      // Returns "✓ {text}" in green
	Successf(format string, a ...interface{}) string // Returns "✓ {formatted}" in green
	Warning(text string) string                      // Returns "⚠ {text}" in yellow
	Warningf(format string, a ...interface{}) string // Returns "⚠ {formatted}" in yellow
	Error(text string) string                        // Returns "✗ {text}" in red
	Errorf(format string, a ...interface{}) string   // Returns "✗ {formatted}" in red
	Info(text string) string                         // Returns "ℹ {text}" in cyan
	Infof(format string, a ...interface{}) string    // Returns "ℹ {formatted}" in cyan
	Hint(text string) string                         // Returns "💡 {text}" in muted color
	Hintf(format string, a ...interface{}) string    // Returns "💡 {formatted}" in muted color
	Muted(text string) string                        // Returns muted text (gray, no icon)

	// Text formatting - returns styled strings
	Bold(text string) string    // Returns bold text
	Heading(text string) string // Returns heading-styled text
	Label(text string) string   // Returns label-styled text

	// Theme access
	Styles() *theme.StyleSet // Access to full theme-aware StyleSet

	// Capability queries (delegates to terminal.Terminal)
	ColorProfile() terminal.ColorProfile
	SupportsColor() bool

	// Markdown rendering - returns rendered markdown string (pure function, no I/O)
	// For writing markdown to channels, use package-level ui.Markdown() or ui.MarkdownMessage()
	Markdown(content string) (string, error)
}

Formatter provides text formatting with automatic degradation. Key Principle: Formatter RETURNS FORMATTED STRINGS - it never writes to streams.

Usage Pattern: 

io := cmd.Context().Value(ioContextKey).(io.Context)
ui := cmd.Context().Value(uiFormatterKey).(ui.Formatter)

// Format text with automatic icons
msg := ui.Success("Deployment complete!")  // Returns "✓ Deployment complete!" in green

// Developer chooses channel
fmt.Fprintf(io.UI(), "%s\n", msg)  // UI message → stderr

Uses io.Terminal for capability detection and theme.StyleSet for styling. 

var Format Formatter

Format exposes the global formatter for advanced use cases. Most code should use the package-level functions (ui.Success, ui.Error, etc.). Use this when you need the formatted string without writing it.

func NewFormatter 

func NewFormatter(ioCtx io.Context, term terminal.Terminal) Formatter

NewFormatter creates a new Formatter with I/O context and terminal. Most code should use the package-level functions instead (ui.Markdown, ui.Success, etc.).

Source Files

View all Source files

Directories

Path Synopsis
Package markdown provides custom markdown rendering with extended syntax support.
 Package markdown provides custom markdown rendering with extended syntax support.
extensions
Package extensions provides custom goldmark extensions for enhanced markdown syntax.
 Package extensions provides custom goldmark extensions for enhanced markdown syntax.

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.