components

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package components provides reusable bubbletea TUI components for the Nexus CLI's interactive wizards.

This file implements a Yes/No confirmation prompt built on bubbletea. It presents a binary choice with a highlighted default, left/right arrow key toggling, and enter to confirm. The prompt renders in the familiar "Y/n" or "y/N" style, with the current selection highlighted using the theme's primary color.

Usage: 

model := components.NewConfirm("Enable authentication?", true)
// Use as a bubbletea model inside a parent model or program.

Package components provides reusable bubbletea TUI components for the Nexus CLI's interactive wizards.

This file implements a multi-select list component built on top of bubbletea. It presents a vertical list of items, each with a name and description, that the user can toggle on or off with the space bar. The component renders checkbox indicators ([x] / [ ]) with colored names and muted descriptions.

Usage: 

items := []components.MultiSelectItem{
    {Name: "REST", Description: "HTTP/JSON API via Fiber"},
    {Name: "gRPC", Description: "Protocol Buffers over HTTP/2"},
}
model := components.NewMultiSelect("Select protocols:", items)
// Use as a bubbletea model inside a parent model or program.

Package components provides reusable bubbletea TUI components for the Nexus CLI's interactive wizards.

This file implements a single-select list component built on top of bubbletea. It presents a vertical list of items, each with a name and description, where the user can choose exactly one option. The component renders a radio-button style indicator (● / ○) with colored names and muted descriptions.

This is distinct from the MultiSelect component — only one item can be selected at a time, and pressing space or enter on an item selects it and optionally confirms the selection.

Usage: 

items := []components.SingleSelectItem{
    {Name: "SQLite", Description: "Zero-config, pure Go, file-based"},
    {Name: "PostgreSQL", Description: "Production-grade relational database"},
    {Name: "None", Description: "In-memory only (for prototyping)"},
}
model := components.NewSingleSelect("Select database:", items)
// Use as a bubbletea model inside a parent model or program.

Package components provides reusable bubbletea TUI components for the Nexus CLI's interactive wizards.

This file implements a styled spinner component built on top of the bubbles/spinner model. It displays an animated spinner icon alongside a message string, styled with the theme's primary color. The spinner is used for any operation that takes longer than ~200ms to provide visual feedback that work is in progress.

The component wraps the bubbles spinner and adds:

  • A configurable message displayed to the right of the spinner icon
  • Automatic styling with the theme's primary color
  • A "done" state that replaces the spinner with a success checkmark
  • Focus control so the spinner can be embedded in multi-step wizards

Usage: 

model := components.NewSpinner("Generating project...")
// Use as a bubbletea model inside a parent model or program.

Package components provides reusable bubbletea TUI components for the Nexus CLI's interactive wizards.

This file implements a summary/review panel component that displays key-value pairs inside a bordered box styled with the theme colors. It is used on the review screen before code generation to give the user a clear overview of all their selections.

Features:

  • Left column: keys rendered with KeyStyle (bold, primary, right-aligned)
  • Right column: values rendered with ValueStyle (light text)
  • List values rendered as comma-separated colored tags
  • Wrapped in a rounded border box with the theme's primary color
  • Optional title displayed above the key-value pairs

Usage: 

s := components.NewSummary("Review Your Selections")
s.AddRow("Project", "my-backend")
s.AddRow("Module", "github.com/user/my-backend")
s.AddListRow("Protocols", []string{"REST", "gRPC", "WebSocket"})
// Render with s.View() inside a parent model or standalone.

Package components provides reusable bubbletea TUI components for the Nexus CLI's interactive wizards.

This file implements a styled text input component built on top of the bubbles/textinput model. It adds a label displayed above the input field, placeholder text, and inline validation that renders a red border and error message when the current value is invalid.

The component delegates all cursor movement, character insertion, and deletion to the underlying bubbles textinput — we only add visual chrome and validation on top.

Usage: 

validate := func(s string) error {
    if s == "" { return fmt.Errorf("project name is required") }
    return nil
}
model := components.NewTextInput("Project name:", "my-backend", validate)
// Use as a bubbletea model inside a parent model or program.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Confirm 

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

Confirm is a bubbletea model that renders an interactive Yes/No prompt with keyboard navigation and styled output.

func NewConfirm 

func NewConfirm(label string, defaultYes bool) Confirm

NewConfirm creates a new Confirm model with the given label and default value. If defaultYes is true, the prompt defaults to "Yes" and renders as "Y/n". If false, it defaults to "No" and renders as "y/N". The component starts focused by default.

func (Confirm) Confirmed 

func (m Confirm) Confirmed() bool

Confirmed returns whether the user has pressed enter to finalize the choice.

func (Confirm) Init 

func (m Confirm) Init() tea.Cmd

Init returns nil — this component has no initial command.

func (*Confirm) Reset 

func (m *Confirm) Reset()

Reset clears the confirmed state and restores the default value, returning the component to its initial interactive state.

func (*Confirm) SetFocused 

func (m *Confirm) SetFocused(focused bool)

SetFocused sets whether the component accepts keyboard input.

func (*Confirm) SetValue 

func (m *Confirm) SetValue(v bool)

SetValue programmatically sets the current selection.

func (Confirm) Update 

func (m Confirm) Update(msg tea.Msg) (Confirm, tea.Cmd)

Update handles keyboard input for toggling and confirming the selection.

Key bindings:

  • ← / h / y — select Yes
  • → / l / n — select No
  • tab — toggle between Yes and No
  • enter — confirm the current selection and emit ConfirmMsg

func (Confirm) Value 

func (m Confirm) Value() bool

Value returns the current selection: true for Yes, false for No.

func (Confirm) View 

func (m Confirm) View() string

View renders the confirmation prompt with the current selection state.

When not yet confirmed, it shows the label followed by styled Yes/No options with the active choice highlighted. When confirmed, it shows a checkmark with the final answer.

type ConfirmMsg 

type ConfirmMsg struct {
	// Value is true if the user selected "Yes", false for "No".
	Value bool
}

ConfirmMsg is sent when the user confirms their choice by pressing enter. Parent models should handle this message to receive the boolean result.

type MultiSelect 

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

MultiSelect is a bubbletea model that renders an interactive multi-select list with keyboard navigation, space-to-toggle, and enter-to-confirm.

func NewMultiSelect 

func NewMultiSelect(title string, items []MultiSelectItem) MultiSelect

NewMultiSelect creates a new MultiSelect model with the given title and items. All items start unselected unless their Selected field is pre-set. The component starts focused by default.

func (MultiSelect) Confirmed 

func (m MultiSelect) Confirmed() bool

Confirmed returns whether the user has pressed enter to finalize selection.

func (MultiSelect) Init 

func (m MultiSelect) Init() tea.Cmd

Init returns nil — this component has no initial command.

func (MultiSelect) Items 

func (m MultiSelect) Items() []MultiSelectItem

Items returns the current list of items (including their selected state).

func (*MultiSelect) Reset 

func (m *MultiSelect) Reset()

Reset clears the confirmed state and deselects all items, returning the component to its initial interactive state.

func (MultiSelect) SelectedItems 

func (m MultiSelect) SelectedItems() []MultiSelectItem

SelectedItems returns a slice of items that are currently toggled on.

func (MultiSelect) SelectedNames 

func (m MultiSelect) SelectedNames() []string

SelectedNames returns just the names of the selected items, which is convenient for passing to downstream configuration structs.

func (*MultiSelect) SetFocused 

func (m *MultiSelect) SetFocused(focused bool)

SetFocused sets whether the component accepts keyboard input.

func (*MultiSelect) SetItems 

func (m *MultiSelect) SetItems(items []MultiSelectItem)

SetItems replaces the current item list. The cursor is reset to zero.

func (MultiSelect) Update 

func (m MultiSelect) Update(msg tea.Msg) (MultiSelect, tea.Cmd)

Update handles keyboard input for navigation, toggling, and confirmation.

Key bindings:

  • ↑ / k — move cursor up
  • ↓ / j — move cursor down
  • space — toggle the item under the cursor
  • a — select all items
  • n — deselect all items
  • enter — confirm selection and emit MultiSelectMsg

func (MultiSelect) View 

func (m MultiSelect) View() string

View renders the multi-select list with checkbox indicators, a cursor, and a footer help line.

type MultiSelectItem 

type MultiSelectItem struct {
	// Name is the primary label displayed next to the checkbox.
	Name string

	// Description is a short explanation shown to the right of the name
	// in muted text. Can be empty.
	Description string

	// Selected indicates whether this item is currently toggled on.
	Selected bool
}

MultiSelectItem represents a single option in the multi-select list. Each item has a display name, an optional description, and a selected state.

type MultiSelectMsg 

type MultiSelectMsg struct {
	// Selected contains the items that were toggled on at the time of
	// confirmation.
	Selected []MultiSelectItem
}

MultiSelectMsg is sent when the user confirms their selection by pressing enter. Parent models should handle this message to receive the results.

type SingleSelect 

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

SingleSelect is a bubbletea model that renders an interactive single-select list with keyboard navigation, space/enter to select and confirm.

func NewSingleSelect 

func NewSingleSelect(title string, items []SingleSelectItem) SingleSelect

NewSingleSelect creates a new SingleSelect model with the given title and items. The first item is selected by default. The component starts focused by default.

func (SingleSelect) Confirmed 

func (m SingleSelect) Confirmed() bool

Confirmed returns whether the user has pressed enter to finalize selection.

func (SingleSelect) Init 

func (m SingleSelect) Init() tea.Cmd

Init returns nil — this component has no initial command.

func (SingleSelect) Items 

func (m SingleSelect) Items() []SingleSelectItem

Items returns the current list of items.

func (*SingleSelect) Reset 

func (m *SingleSelect) Reset()

Reset clears the confirmed state and resets the selection to the first item, returning the component to its initial interactive state.

func (SingleSelect) SelectedItem 

func (m SingleSelect) SelectedItem() SingleSelectItem

SelectedItem returns the currently selected item.

func (SingleSelect) SelectedName 

func (m SingleSelect) SelectedName() string

SelectedName returns the name of the currently selected item.

func (SingleSelect) SelectedValue 

func (m SingleSelect) SelectedValue() string

SelectedValue returns the effective value of the currently selected item. This is the Value field if set, otherwise the Name.

func (*SingleSelect) SetFocused 

func (m *SingleSelect) SetFocused(focused bool)

SetFocused sets whether the component accepts keyboard input.

func (*SingleSelect) SetItems 

func (m *SingleSelect) SetItems(items []SingleSelectItem)

SetItems replaces the current item list. The cursor and selection are reset to zero.

func (*SingleSelect) SetSelected 

func (m *SingleSelect) SetSelected(index int)

SetSelected sets the selected item by index. If the index is out of range, it is clamped to the valid range.

func (*SingleSelect) SetSelectedByValue 

func (m *SingleSelect) SetSelectedByValue(value string)

SetSelectedByValue sets the selected item by matching the Value (or Name fallback) field. If no match is found, the selection is unchanged.

func (SingleSelect) Update 

func (m SingleSelect) Update(msg tea.Msg) (SingleSelect, tea.Cmd)

Update handles keyboard input for navigation, selection, and confirmation.

Key bindings:

  • ↑ / k — move cursor up
  • ↓ / j — move cursor down
  • space — select the item under the cursor
  • enter — select the item under the cursor and confirm

func (SingleSelect) View 

func (m SingleSelect) View() string

View renders the single-select list with radio indicators, a cursor, and a footer help line.

type SingleSelectItem 

type SingleSelectItem struct {
	// Name is the primary label displayed next to the radio indicator.
	Name string

	// Description is a short explanation shown to the right of the name
	// in muted text. Can be empty.
	Description string

	// Value is the internal value associated with this item. If empty,
	// the Name is used as the value. This allows display names to differ
	// from the values passed to downstream logic.
	Value string
}

SingleSelectItem represents a single option in the single-select list. Each item has a display name and an optional description.

type SingleSelectMsg 

type SingleSelectMsg struct {
	// Selected is the item that was chosen at the time of confirmation.
	Selected SingleSelectItem
}

SingleSelectMsg is sent when the user confirms their selection by pressing enter. Parent models should handle this message to receive the result.

type Spinner 

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

Spinner is a bubbletea model that renders an animated spinner icon with a message string. It wraps the bubbles/spinner model and adds theme styling, a configurable message, and a done state.

func NewSpinner 

func NewSpinner(message string) Spinner

NewSpinner creates a new Spinner model with the given message. The spinner uses the "Dot" style by default and is colored with the theme's primary color. The component starts focused by default so it begins animating immediately.

func (Spinner) Done 

func (m Spinner) Done() bool

Done returns whether the spinner has completed.

func (Spinner) Init 

func (m Spinner) Init() tea.Cmd

Init returns the initial tick command from the underlying spinner so the animation begins immediately.

func (Spinner) Message 

func (m Spinner) Message() string

Message returns the current spinner message text.

func (*Spinner) Reset 

func (m *Spinner) Reset()

Reset restores the spinner to its initial state: not done, original message, and ready to animate.

func (*Spinner) SetDone 

func (m *Spinner) SetDone(done bool)

SetDone manually sets the done state. Prefer sending a SpinnerDoneMsg through the bubbletea update loop when possible.

func (*Spinner) SetDoneMessage 

func (m *Spinner) SetDoneMessage(msg string)

SetDoneMessage sets the message displayed when the spinner transitions to the done state. If not set, the original message is used.

func (*Spinner) SetFocused 

func (m *Spinner) SetFocused(focused bool)

SetFocused sets whether the component processes tick messages to animate the spinner. When unfocused, the spinner freezes at its current frame.

func (*Spinner) SetMessage 

func (m *Spinner) SetMessage(msg string)

SetMessage updates the message displayed next to the spinner. This is useful for multi-step operations where the status text changes over time.

func (*Spinner) SetSpinnerStyle 

func (m *Spinner) SetSpinnerStyle(style spinner.Spinner)

SetSpinnerStyle sets the spinner animation style. Available styles from the bubbles/spinner package include Dot, Line, MiniDot, Jump, Pulse, Points, Globe, Moon, Monkey, Meter, and Hamburger.

func (Spinner) Tick 

func (m Spinner) Tick() tea.Cmd

Tick returns the tick command needed to keep the spinner animation running. Parent models should call this in their Init() or when embedding the spinner in a larger model to ensure the animation starts.

func (Spinner) Update 

func (m Spinner) Update(msg tea.Msg) (Spinner, tea.Cmd)

Update handles tick messages to advance the spinner animation and SpinnerDoneMsg to transition into the done state.

When not focused or already done, tick messages are ignored.

func (Spinner) View 

func (m Spinner) View() string

View renders the spinner icon and message. When done, the spinner icon is replaced with a success checkmark and the message changes to the done message (or the original message if no done message was set).

type SpinnerDoneMsg 

type SpinnerDoneMsg struct{}

SpinnerDoneMsg is sent when the spinner's work is complete. Parent models can send this message to transition the spinner into its "done" state, which replaces the animated icon with a success checkmark.

type Summary 

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

Summary is a display-only component (not interactive) that renders a bordered box containing key-value pairs. It implements a View() method compatible with bubbletea's rendering pattern, but does not process any messages — it is purely visual.

func NewSummary 

func NewSummary(title string) Summary

NewSummary creates a new Summary panel with the given title. The title is displayed at the top of the bordered box. Pass an empty string to omit it.

func (*Summary) AddListRow 

func (m *Summary) AddListRow(key string, values []string)

AddListRow appends a key with multiple values to the summary. The values are rendered as comma-separated colored tags in the right column.

func (*Summary) AddRow 

func (m *Summary) AddRow(key, value string)

AddRow appends a plain key-value pair to the summary. The value is rendered as a single string in the right column.

func (*Summary) ClearRows 

func (m *Summary) ClearRows()

ClearRows removes all rows from the summary.

func (Summary) Rows 

func (m Summary) Rows() []SummaryRow

Rows returns a copy of the current rows for inspection.

func (*Summary) SetKeyWidth 

func (m *Summary) SetKeyWidth(w int)

SetKeyWidth manually overrides the key column width. By default it is automatically calculated from the longest key name.

func (*Summary) SetRows 

func (m *Summary) SetRows(rows []SummaryRow)

SetRows replaces all rows in the summary with the provided slice. This is useful when rebuilding the summary from scratch (e.g., after navigating back through the wizard).

func (*Summary) SetTitle 

func (m *Summary) SetTitle(title string)

SetTitle updates the title displayed at the top of the summary box.

func (Summary) View 

func (m Summary) View() string

View renders the summary panel as a bordered box containing the title (if set) and all key-value rows with consistent column alignment.

type SummaryRow 

type SummaryRow struct {
	// Key is the label displayed in the left column.
	Key string

	// Value is the plain string value displayed in the right column.
	// Ignored if ListValue is non-empty.
	Value string

	// ListValue holds multiple values that are rendered as comma-separated
	// colored tags. When non-empty, this takes precedence over Value.
	ListValue []string
}

SummaryRow represents a single key-value pair in the summary panel. The value can be either a plain string or a list of strings rendered as tags.

type TextInput 

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

TextInput is a bubbletea model that renders a labeled text input field with optional placeholder text and inline validation feedback.

func NewTextInput 

func NewTextInput(label, placeholder string, validate ValidateFunc) TextInput

NewTextInput creates a new TextInput model with the given label, placeholder text, and optional validation function. Pass nil for validate to accept any input. The component starts focused by default.

func (TextInput) Confirmed 

func (m TextInput) Confirmed() bool

Confirmed returns whether the user has pressed enter with a valid value.

func (TextInput) Err 

func (m TextInput) Err() error

Err returns the current validation error, or nil if valid.

func (TextInput) Init 

func (m TextInput) Init() tea.Cmd

Init returns the blink command from the underlying textinput so the cursor animates immediately.

func (*TextInput) Reset 

func (m *TextInput) Reset()

Reset clears the input value, validation state, and confirmed flag, returning the component to its initial interactive state.

func (*TextInput) SetCharLimit 

func (m *TextInput) SetCharLimit(n int)

SetCharLimit sets the maximum number of characters the input field accepts.

func (*TextInput) SetFocused 

func (m *TextInput) SetFocused(focused bool)

SetFocused sets whether the component accepts keyboard input and shows the blinking cursor.

func (*TextInput) SetValue 

func (m *TextInput) SetValue(v string)

SetValue programmatically sets the input field text. This is useful for pre-filling a value (e.g., when a project name is passed via CLI args).

func (*TextInput) SetWidth 

func (m *TextInput) SetWidth(w int)

SetWidth sets the width of the underlying text input field.

func (TextInput) Update 

func (m TextInput) Update(msg tea.Msg) (TextInput, tea.Cmd)

Update handles keyboard input by delegating to the inner textinput and running validation on every change. Enter confirms the value if valid.

Key bindings:

  • enter — attempt to confirm the current value
  • all others — delegated to the bubbles textinput

func (TextInput) Value 

func (m TextInput) Value() string

Value returns the current text in the input field.

func (TextInput) View 

func (m TextInput) View() string

View renders the label, input field, and any validation error message.

type TextInputMsg 

type TextInputMsg struct {
	// Value is the confirmed, validated text.
	Value string
}

TextInputMsg is sent when the user confirms the input by pressing enter and the value passes validation. Parent models should handle this message to receive the final value.

type ValidateFunc 

type ValidateFunc func(string) error

ValidateFunc is a function that validates a text input value. It returns nil if the value is valid, or an error describing what is wrong. The error message is displayed inline beneath the input field.

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.