app

Documentation

Overview

Package app is the standard TUI shell: a breadcrumb header, a flex body that renders the active screen's layout, and a statusbar footer. It owns the nav stack, cycles themes, and routes global keys (quit, theme swap) around any screen-owned input focus.

Callers provide a root screen and a theme list; the app handles the rest. Screens implement pkg/screen.Screen and return their own layout trees, so each screen can have a different body composition without any shell changes.

Index

• func ClearStatus() tea.Cmd
• func Error(s string) tea.Cmd
• func Info(s string) tea.Cmd
• func SetTheme(name string) tea.Cmd
• type Model
  • func New(opts Options) Model
  • func (m Model) Init() tea.Cmd
  • func (m Model) Theme() theme.Theme
  • func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (m Model) View() string
• type Options
• type SetThemeMsg
• type StatusClearMsg
• type StatusErrorMsg
• type StatusInfoMsg

Functions

func ClearStatus

func ClearStatus() tea.Cmd

ClearStatus returns a command that clears any active statusbar message.

func Error

func Error(s string) tea.Cmd

Error returns a command that posts an error message to the statusbar.

func Info

func Info(s string) tea.Cmd

Info returns a command that posts an info message to the statusbar.

func SetTheme

func SetTheme(name string) tea.Cmd

SetTheme returns a command that tells the app shell to switch to the theme whose Name matches. Useful for a theme-picker screen that wants to preview palettes live as the cursor moves. No-op if no theme with that name is in the app's Themes list.

Types

type Model

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

Model is the app shell. Instantiate with New and pass to tea.NewProgram.

func New

func New(opts Options) Model

New constructs an app shell. By default it reorders Themes via theme.Resolve so Themes[0] reflects the user's config file (and ThemeEnvVar, when set) — pass SkipConfig=true to opt out. The root screen's SetTheme is then called with the resulting Themes[0] so the root renders in the initial palette immediately.

func (Model) Init

func (m Model) Init() tea.Cmd

Init runs the root screen's Init + OnEnter(nil).

func (Model) Theme

func (m Model) Theme() theme.Theme

Theme exposes the app's current palette for screens that need it outside of SetTheme (rare — most screens just cache the theme they were last told about).

func (Model) Update

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

Update handles resize, global keys, and forwards everything else to the stack. Global keys are suppressed when the active screen reports IsCapturingKeys so text input isn't hijacked.

func (Model) View

func (m Model) View() string

View composes the standard shell as a vertical stack: breadcrumb (1 row), active screen's body layout (flex), statusbar (1 row). The screen never knows its own terminal dimensions — the layout engine hands it a body rect to fill.

type Options

type Options struct {
	// Root is the root screen — the bottom of the nav stack. Required.
	Root screen.Screen

	// Themes is the list the user cycles through. At least one entry is
	// required; Themes[0] is the initial theme.
	Themes []theme.Theme

	// Version is rendered on the right side of the statusbar.
	Version string

	// QuitKey quits the program when the stack depth is 1 and no screen
	// is capturing keys. Defaults to "q" (and "ctrl+c").
	QuitKey key.Binding

	// ThemeKey cycles themes. Leave zero to disable cycling (useful when
	// the app is pinned to a single theme).
	ThemeKey key.Binding

	// ThemeEnvVar names an environment variable consulted for the initial
	// theme during app.New (e.g. "MYAPP_THEME"). When the var is set to a
	// theme's Name, that theme becomes Themes[0]. Empty string disables
	// env-var lookup but the user config file is still consulted; see
	// SkipConfig to disable both.
	ThemeEnvVar string

	// SkipConfig disables the automatic theme.Resolve call inside app.New.
	// By default app.New reorders Themes so Themes[0] reflects the user's
	// $XDG_CONFIG_HOME/tuilib/config.yaml `theme:` field (and ThemeEnvVar,
	// when set) — set this to true if you've already called theme.Resolve
	// yourself, or if you want to pin the app to Themes[0] regardless.
	SkipConfig bool

	// DisableAutoEscPop turns off automatic esc→pop handling. When false
	// (the default) esc pops the stack whenever depth > 1 and the active
	// screen is not capturing keys.
	DisableAutoEscPop bool
}

Options configures the app shell.

type SetThemeMsg

type SetThemeMsg struct{ Name string }

SetThemeMsg asks the app to switch to the named theme and rebroadcast it across the stack. Emit via SetTheme(name) from any screen.

type StatusClearMsg

type StatusClearMsg struct{}

StatusClearMsg asks the app to clear any active statusbar message immediately. Useful for screens that want to wipe a stale message on a non-key event (e.g. a fetch result that resolves cleanly).

type StatusErrorMsg

type StatusErrorMsg struct{ Text string }

StatusErrorMsg asks the app to show s as an error message in the statusbar's center slot. Same auto-clear semantics as StatusInfoMsg. Emit via Error(s) from any screen.

type StatusInfoMsg

type StatusInfoMsg struct{ Text string }

StatusInfoMsg asks the app to show s as an info message in the statusbar's center slot. The message auto-clears on the next KeyMsg (matching the statusbar's own Update behavior). Emit via Info(s) from any screen.