ux

package
v1.23.13 Latest Latest
Warning

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

Go to latest
Published: Mar 26, 2026 License: MIT Imports: 27 Imported by: 1

Documentation

Index

Constants

View Source
const SIGWINCH = syscall.Signal(0x1c)

Variables

View Source
var BoldString = color.New(color.Bold).SprintfFunc()
View Source
var ErrCancelled = internal.ErrCancelled

Functions

func ConsoleWidth

func ConsoleWidth() int

ConsoleWidth returns the width of the console in characters. It uses the consolesize package to get the size and falls back to check the COLUMNS environment variable Defaults to 120 if the console size cannot be determined.

func CountLineBreaks

func CountLineBreaks(content string, width int) int

countLineBreaks calculates the number of lines that will be displayed on the screen, considering both explicit line breaks (`\n`) and automatic wrapping based on console width.

func Hyperlink(url string, text ...string) string

Hyperlink returns a hyperlink formatted string. When stdout is not a terminal (e.g., in CI/CD pipelines like GitHub Actions), it returns the plain URL without escape codes to avoid displaying raw ANSI sequences.

func NewVisualElement

func NewVisualElement(renderFn RenderFn) *visualElement

func Ptr

func Ptr[T any](value T) *T

func VisibleLength

func VisibleLength(s string) int

visibleLength calculates the number of visible characters in a string by removing ANSI codes and counting the actual characters. Cannot use len() as it counts bytes not runes

Types

type Canvas

type Canvas interface {
	Run() error
	Update() error
	Clear() error
	Close()
	WithWriter(writer io.Writer) Canvas
}

func NewCanvas

func NewCanvas(visuals ...Visual) Canvas

NewCanvas creates a new Canvas instance.

type CanvasSize

type CanvasSize struct {
	Rows int
	Cols int
}

CanvasSize represents the size of the canvas.

type Confirm

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

Confirm is a component for prompting the user to confirm a message.

func NewConfirm

func NewConfirm(options *ConfirmOptions) *Confirm

NewConfirm creates a new Confirm instance.

func (*Confirm) Ask

func (p *Confirm) Ask(ctx context.Context) (*bool, error)

Ask prompts the user to confirm a message.

func (*Confirm) Render

func (p *Confirm) Render(printer Printer) error

Render renders the Confirm component.

func (*Confirm) WithCanvas

func (p *Confirm) WithCanvas(canvas Canvas) Visual

WithCanvas sets the canvas for the Confirm component.

type ConfirmOptions

type ConfirmOptions struct {
	// The writer to use for output (default: os.Stdout)
	Writer io.Writer
	// The reader to use for input (default: os.Stdin)
	Reader io.Reader
	// The default value to use for the prompt (default: nil)
	DefaultValue *bool
	// The message to display before the prompt
	Message string
	// The optional message to display when the user types ? (default: "")
	HelpMessage string
	// The optional hint text that display after the message (default: "[Type ? for hint]")
	Hint string
	// The optional placeholder text to display when the value is empty (default: "")
	PlaceHolder string
}

ConfirmOptions represents the options for the Confirm component.

var DefaultConfirmOptions ConfirmOptions = ConfirmOptions{
	Writer: os.Stdout,
	Reader: os.Stdin,
}

type CursorPosition

type CursorPosition struct {
	Row int
	Col int
}

CursorPosition represents the position of the cursor on the canvas.

type MultiSelect

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

Select is a component for prompting the user to select an option from a list.

func NewMultiSelect

func NewMultiSelect(options *MultiSelectOptions) *MultiSelect

NewSelect creates a new Select instance.

func (*MultiSelect) Ask

Ask prompts the user to select an option from a list.

func (*MultiSelect) Render

func (p *MultiSelect) Render(printer Printer) error

Render renders the Select component.

func (*MultiSelect) WithCanvas

func (p *MultiSelect) WithCanvas(canvas Canvas) Visual

WithCanvas sets the canvas for the select component.

type MultiSelectChoice

type MultiSelectChoice struct {
	Value    string
	Label    string
	Selected bool
}

type MultiSelectOptions

type MultiSelectOptions struct {
	// The writer to use for output (default: os.Stdout)
	Writer io.Writer
	// The reader to use for input (default: os.Stdin)
	Reader io.Reader
	// The message to display before the prompt
	Message string
	// The available options to display
	Choices []*MultiSelectChoice
	// The optional message to display when the user types ? (default: "")
	HelpMessage string
	// The maximum number of options to display at one time (default: 6)
	DisplayCount int
	// Whether or not to display the number prefix before each option (default: false)
	DisplayNumbers *bool
	// Whether or not to disable filtering (default: true)
	EnableFiltering *bool
}

SelectOptions represents the options for the Select component.

var DefaultMultiSelectOptions MultiSelectOptions = MultiSelectOptions{
	Writer:          os.Stdout,
	Reader:          os.Stdin,
	DisplayCount:    6,
	EnableFiltering: new(true),
	DisplayNumbers:  new(false),
}

type Printer

type Printer interface {
	internal.Cursor

	Fprintf(format string, a ...any)
	Fprintln(a ...any)

	ClearCanvas()

	CursorPosition() CursorPosition
	SetCursorPosition(position CursorPosition)
	Size() CanvasSize
}

Printer is a base component for UX components that require a printer for rendering.

func NewPrinter

func NewPrinter(writer io.Writer) Printer

NewPrinter creates a new Printer instance.

type Prompt

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

Prompt is a component for prompting the user for input.

func NewPrompt

func NewPrompt(options *PromptOptions) *Prompt

NewPrompt creates a new Prompt instance.

func (*Prompt) Ask

func (p *Prompt) Ask(ctx context.Context) (string, error)

Ask prompts the user for input.

func (*Prompt) Render

func (p *Prompt) Render(printer Printer) error

Render renders the prompt.

func (*Prompt) WithCanvas

func (p *Prompt) WithCanvas(canvas Canvas) Visual

WithCanvas sets the canvas for the prompt.

type PromptOptions

type PromptOptions struct {
	// The writer to use for output (default: os.Stdout)
	Writer io.Writer
	// The reader to use for input (default: os.Stdin)
	Reader io.Reader
	// The default value to use for the prompt (default: "")
	DefaultValue string
	// The message to display before the prompt
	Message string
	// The optional message to display when the user types ? (default: "")
	HelpMessage string
	// The optional hint text displayed after the message.
	// When empty (default), auto-generated as "[Type ? for hint]" only if HelpMessage is set.
	Hint string
	// The optional placeholder text to display when the value is empty (default: "")
	PlaceHolder string
	// The optional validation function to use
	ValidationFn func(string) (bool, string)
	// The optional validation message to display when validation fails (default: "Invalid input")
	ValidationMessage string
	// The optional validation message to display when the value is empty and required (default: "This field is required")
	RequiredMessage string
	// Whether or not the prompt is required (default: false)
	Required bool
	// Whether or not to clear the prompt after completion (default: false)
	ClearOnCompletion bool
	// Whether or not to capture hint keys (default: true)
	IgnoreHintKeys bool
	// The optional help message that displays on the next line (default: "")
	HelpMessageOnNextLine string
}

PromptOptions represents the options for the Prompt component.

var DefaultPromptOptions PromptOptions = PromptOptions{
	Writer:            os.Stdout,
	Reader:            os.Stdin,
	Required:          false,
	ValidationMessage: "Invalid input",
	RequiredMessage:   "This field is required",
	Hint:              "",
	ClearOnCompletion: false,
	IgnoreHintKeys:    false,
	ValidationFn: func(input string) (bool, string) {
		return true, ""
	},
}

type RenderFn

type RenderFn func(printer Printer) error

type Select

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

Select is a component for prompting the user to select an option from a list.

func NewSelect

func NewSelect(options *SelectOptions) *Select

NewSelect creates a new Select instance.

func (*Select) Ask

func (p *Select) Ask(ctx context.Context) (*int, error)

Ask prompts the user to select an option from a list.

func (*Select) Render

func (p *Select) Render(printer Printer) error

Render renders the Select component.

func (*Select) WithCanvas

func (p *Select) WithCanvas(canvas Canvas) Visual

WithCanvas sets the canvas for the select component.

type SelectChoice

type SelectChoice struct {
	Value string
	Label string
}

type SelectOptions

type SelectOptions struct {
	// The writer to use for output (default: os.Stdout)
	Writer io.Writer
	// The reader to use for input (default: os.Stdin)
	Reader io.Reader
	// The default value to use for the prompt (default: nil)
	SelectedIndex *int
	// The message to display before the prompt
	Message string
	// The available options to display
	Choices []*SelectChoice
	// The optional message to display when the user types ? (default: "")
	HelpMessage string
	// The optional hint text that display after the message (default: "[Type ? for hint]")
	Hint string
	// The maximum number of options to display at one time (default: 6)
	DisplayCount int
	// Whether or not to display the number prefix before each option (default: false)
	DisplayNumbers *bool
	// Whether or not to disable filtering (default: true)
	EnableFiltering *bool
}

SelectOptions represents the options for the Select component.

var DefaultSelectOptions SelectOptions = SelectOptions{
	Writer:          os.Stdout,
	Reader:          os.Stdin,
	SelectedIndex:   new(0),
	DisplayCount:    6,
	EnableFiltering: new(true),
	DisplayNumbers:  new(false),
}

type SetProgressFunc

type SetProgressFunc func(string)

SetProgressFunc is a function that sets the progress of a task.

type Spinner

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

Spinner is a component for displaying a spinner.

func NewSpinner

func NewSpinner(options *SpinnerOptions) *Spinner

NewSpinner creates a new Spinner instance.

func (*Spinner) Render

func (s *Spinner) Render(printer Printer) error

Render renders the spinner.

func (*Spinner) Run

func (s *Spinner) Run(ctx context.Context, task func(context.Context) error) error

Run runs a task with the spinner.

func (*Spinner) Start

func (s *Spinner) Start(ctx context.Context) error

Start starts the spinner.

func (*Spinner) Stop

func (s *Spinner) Stop(ctx context.Context) error

Stop stops the spinner.

func (*Spinner) UpdateText

func (s *Spinner) UpdateText(text string)

UpdateText updates the text of the spinner.

func (*Spinner) WithCanvas

func (s *Spinner) WithCanvas(canvas Canvas) Visual

WithCanvas sets the canvas for the spinner.

type SpinnerOptions

type SpinnerOptions struct {
	Animation   []string
	Text        string
	Interval    time.Duration
	ClearOnStop bool
	Writer      io.Writer
}

SpinnerOptions represents the options for the Spinner component.

var DefaultSpinnerOptions SpinnerOptions = SpinnerOptions{
	Animation: []string{"|", "/", "-", "\\"},
	Text:      "Loading...",
	Interval:  250 * time.Millisecond,
	Writer:    os.Stdout,
}

type Task

type Task struct {
	Title  string
	Action func(SetProgressFunc) (TaskState, error)
	State  TaskState
	Error  error
	// contains filtered or unexported fields
}

Task represents a task in the task list.

type TaskList

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

TaskList is a component for managing a list of tasks.

func NewTaskList

func NewTaskList(options *TaskListOptions) *TaskList

NewTaskList creates a new TaskList instance.

func (*TaskList) AddTask

func (t *TaskList) AddTask(options TaskOptions) *TaskList

AddTask adds a task to the task list and manages async/sync execution.

func (*TaskList) Render

func (t *TaskList) Render(printer Printer) error

Render renders the task list.

func (*TaskList) Run

func (t *TaskList) Run() error

Run executes all async tasks first and then runs queued sync tasks sequentially.

func (*TaskList) WithCanvas

func (t *TaskList) WithCanvas(canvas Canvas) Visual

WithCanvas sets the canvas for the TaskList component.

type TaskListOptions

type TaskListOptions struct {
	ContinueOnError bool
	// The writer to use for output (default: os.Stdout)
	Writer             io.Writer
	MaxConcurrentAsync int
	SuccessStyle       string
	ErrorStyle         string
	WarningStyle       string
	RunningStyle       string
	SkippedStyle       string
	PendingStyle       string
}

TaskListOptions represents the options for the TaskList component.

var DefaultTaskListOptions TaskListOptions = TaskListOptions{
	ContinueOnError:    false,
	Writer:             os.Stdout,
	MaxConcurrentAsync: 5,

	SuccessStyle: output.WithSuccessFormat("(✔) Done "),
	ErrorStyle:   output.WithErrorFormat("(x) Error "),
	WarningStyle: output.WithWarningFormat("(!) Warning "),
	RunningStyle: output.WithHighLightFormat("(-) Running "),
	SkippedStyle: output.WithGrayFormat("(-) Skipped "),
	PendingStyle: output.WithGrayFormat("(o) Pending "),
}

type TaskOptions

type TaskOptions struct {
	Title  string
	Action func(SetProgressFunc) (TaskState, error)
	Async  bool
}

TaskOptions represents the options for the Task component.

type TaskState

type TaskState int

TaskState represents the state of a task.

const (
	Pending TaskState = iota
	Running
	Skipped
	Warning
	Error
	Success
)

type Visual

type Visual interface {
	Render(printer Printer) error
	WithCanvas(canvas Canvas) Visual
}

func Render

func Render(renderFn RenderFn) Visual

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL