tui

package
v0.24.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package tui holds the look that every command shares: the styles, the help page, the error block, the masked field of a key, and the confirmation. A spinner or a progress bar joins it with the first command that needs one.

Build every interactive screen from this package, so every command looks the same. A component joins it after Pascal picks its look from a published mockup, as dev-preferences.md asks, and the spec of each command holds the look that Pascal picked in M07. A command whose spec gives no look reuses the help and error styles of M00 and prints the rest as plain text, so it waits on no mockup.

Index

Constants

This section is empty.

Variables

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

ErrInterrupted is the error of a form or a prompt that the human ended with Ctrl-C.

Functions

func AskChoice added in v0.18.0

func AskChoice(ctx context.Context, in *os.File, out io.Writer, noColor bool, c Choice) (string, error)

AskChoice asks the human to pick one option of a choice, as AskMasked asks for a key, and returns its value. On a terminal whose TERM is dumb, it lists the options by number, and an answer that names none of them, the end of input included, returns an empty value.

func AskMasked added in v0.18.0

func AskMasked(ctx context.Context, in *os.File, out io.Writer, noColor bool, m Masked) (string, error)

AskMasked asks for a key in the masked field, a password field of the form's look, which shows one * per typed character. It reads the terminal in, draws on out, and returns the typed text. Ctrl-C returns ErrInterrupted, and the end of ctx returns its error, after the field has left the terminal as it found it.

func AskText added in v0.18.0

func AskText(ctx context.Context, in *os.File, out io.Writer, noColor bool, t Text) (string, error)

AskText asks for a value in a text field, as AskMasked asks for a key, and returns the typed text.

func Bold added in v0.18.0

func Bold(s string) string

Bold, ErrorLabel, HintLabel, and Muted style a word of a report as the help and the error block do: a name in bold, a problem's label in bold red, hint: in bold cyan, and a label of lesser weight in bright black.

func Checks added in v0.18.0

func Checks(checks []Check, hint string) string

Checks renders a report in three aligned columns: each check's status, in bold and in its color, its id, and its message. A check with a problem adds a line under it, with its code, in the color of its status, in the column of the id, then the hint label, such as hint:, and its hint in the column of the message.

func Confirm added in v0.18.0

func Confirm(ctx context.Context, in io.Reader, out io.Writer, noColor bool, c Confirmation) (bool, error)

Confirm asks c on out, then reads the answer from in, a terminal whose echo leaves the question and the answer on screen. It reports whether the answer is one of the words of c.Yes. Any other answer, an empty one, and the end of input mean no. The end of ctx, such as by Ctrl-C, returns its error.

func ErrorLabel added in v0.18.0

func ErrorLabel(s string) string

func Help

func Help(p HelpPage) string

Help renders a help page, which ends with its examples. Columns take the width of the translated text.

func HintLabel added in v0.18.0

func HintLabel(s string) string

func Markdown added in v0.18.0

func Markdown(markdown string, width int, noColor bool) (string, error)

Markdown renders a skill's Markdown in the look of ncly skill view: the style of the help, with headings in bold uppercase, inline code in cyan, and dashes for bullets, wrapped at width. Without color, inline code keeps its backticks, so it stays apart from the prose. A link or an image shows its destination as the skill writes it, so a relative path still resolves against the skill's folder. Glamour writes the styles, and Output turns them into plain text when color is off.

func Muted added in v0.18.0

func Muted(s string) string

func Names added in v0.18.0

func Names(entries []Entry) string

Names renders entries as the help renders its commands: each name and a colon, in bold, then its summary, aligned after the widest name, so the terminal wraps a long summary.

func Output

func Output(w io.Writer, noColor bool) io.Writer

Output wraps a stream so that styles become plain text when color is off. noColor turns color off even with CLICOLOR_FORCE. Otherwise a stream that is not a terminal gets plain text unless CLICOLOR_FORCE asks for color. The decision reads only the environment and the stream, and never queries the terminal.

func Problems

func Problems(errs, warnings []contract.Problem, label func(code contract.Code, warning bool) string, hint string) string

Problems renders errors, then warnings. Each one leads with a label that carries its code, such as error[USAGE_INVALID]:, then shows its hint after the hint label. label returns the translated label of a code.

func Profile added in v0.18.0

func Profile(w io.Writer, noColor bool) colorprofile.Profile

Profile returns the color profile of styles written to w, by the rule of Output: the 16 ANSI colors, or plain text when color is off. A form takes this profile, so Bubble Tea never detects one, which queries tmux.

Types

type Check added in v0.18.0

type Check struct {
	// Status is pass, warn, or fail, and Label its word in the active
	// language.
	Status, Label string
	ID, Message   string
	// Code and Hint stay empty for a check that passes.
	Code, Hint string
}

Check is one finding of a report, such as a check of ncly doctor, with its text in the active language.

type Choice added in v0.18.0

type Choice struct {
	Title       string
	Description string
	Options     []Option
	Keys        Keys
	// Number asks for the number of an option, on a terminal whose TERM is
	// dumb, which lists the options by number.
	Number string
}

Choice is a choice among options, with its text in the active language.

type Confirmation added in v0.18.0

type Confirmation struct {
	Question string
	// Facts are what the answer rests on, each on a labeled line under the
	// question, such as the path of an extension that a grant names.
	Facts []Fact
	// Choices shows the answers and the default, such as [y/N].
	Choices string
	// Yes holds the answers that confirm, separated by commas, such as
	// "y, yes".
	Yes string
}

Confirmation is a question that a human answers by typing a line, never by picking a button, with its text in the active language.

type Entry

type Entry struct {
	Name    string
	Summary string
}

Entry is one line of a list: a command or a flag, then its summary.

type Fact added in v0.18.0

type Fact struct {
	Label, Value string
}

Fact is one fact of a confirmation: a label, such as Path, and its value.

type HelpPage

type HelpPage struct {
	Summary string
	// Note is one plain line under the summary, such as the effects of a
	// command, or empty.
	Note          string
	UsageTitle    string
	Usage         string
	Sections      []Section
	ExamplesTitle string
	Examples      []string
}

HelpPage is a help page, already in the active language.

type Keys added in v0.18.0

type Keys struct {
	Enter, Esc, Submit string
	// Up, Down, and Filter are what ↑, ↓, and / do in a choice, and
	// SetFilter and ClearFilter what Escape does while the human filters
	// it and once a filter is set.
	Up, Down, Filter, SetFilter, ClearFilter string
	// Complete is what ctrl+e does in a text field that suggests values.
	Complete string
}

Keys is the help of a form's keys, in the active language: the names of Enter and Escape, then what each key does.

type Masked added in v0.18.0

type Masked struct {
	Title       string
	Description string
	Keys        Keys
}

Masked is the masked field of a key, with its text in the active language.

type Option added in v0.18.0

type Option struct {
	Label, Value string
}

Option is one option of a choice: what it shows, and the value that it stands for.

type Section

type Section struct {
	Title   string
	Entries []Entry
	// Colon follows each name with a colon, as for commands.
	Colon bool
}

Section is a titled list of entries.

type Text added in v0.18.0

type Text struct {
	Title       string
	Description string
	Suggestions []string
	Keys        Keys
}

Text is a text field, with its text in the active language. It shows the first suggestion that starts with what the human typed, and accepts any other value.

Jump to

Keyboard shortcuts

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