router

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jun 30, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const ColorProfileEnvVar = "TUI_BASE_COLOR_PROFILE"

ColorProfileEnvVar is the environment variable consumers can set to override the auto-detected terminal color profile.

This is the primary remedy for washed-out or mis-quantized colors over SSH. SSH does not forward COLORTERM unless the client's SendEnv and the server's AcceptEnv are both configured, so a remote process running in a TrueColor terminal usually falls back to ANSI256 and downsamples 24-bit theme colors to the nearest 256-color palette entry (e.g. a dark slate background becomes a brighter, saturated blue).

Accepted values (case-insensitive): truecolor, 24bit, ansi256, 256, ansi, 16, ascii, none, notty. Any other value is ignored (auto-detect is used).

View Source 
const DefaultAppName = "TUI Base"

DefaultAppName is the fallback application name used when Options.AppName is empty.

Variables

This section is empty.

Functions

func ClearRegisteredPages added in v0.1.11 

func ClearRegisteredPages()

ClearRegisteredPages clears the global page registry (primarily useful for tests).

func EffectiveColorProfile 

func EffectiveColorProfile() colorprofile.Profile

EffectiveColorProfile returns the color profile the program actually renders with: the forced profile from TUI_BASE_COLOR_PROFILE if set, otherwise the auto-detected profile for stdout.

This mirrors exactly what Bubble Tea's renderer uses to downsample SGR color sequences. Callers MUST convert any color they emit OUTSIDE of SGR — most importantly tea.View.BackgroundColor / ForegroundColor, which Bubble Tea sends as an OSC sequence that the color-profile writer passes through unchanged.

Without this conversion, over a downsampling profile (e.g. ANSI256 on SSH) the OSC-set terminal background stays exact 24-bit while every lipgloss Background() cell is quantized to the nearest palette entry — producing two visibly different shades of the "same" color on screen.

func ForcedColorProfile 

func ForcedColorProfile() (colorprofile.Profile, bool)

ForcedColorProfile returns the color profile requested via the TUI_BASE_COLOR_PROFILE environment variable and whether one was set.

It is exported so pages (e.g. the inspector) can surface whether an override is active, and so consumers can apply the same logic to their own programs.

func FormOverlayWidth added in v0.1.2 

func FormOverlayWidth(termW int) int

FormOverlayWidth re-exports [overlay.FormWidth].

func NewProgram 

func NewProgram(m tea.Model, opts ...tea.ProgramOption) *tea.Program

NewProgram constructs a tea.Program for a tui-base model with the framework's standard options applied. Today that means honoring TUI_BASE_COLOR_PROFILE so users can force a specific color profile (most commonly TrueColor over SSH, where COLORTERM is typically stripped and 24-bit theme colors get quantized to a washed-out ANSI256 approximation).

Additional tea.ProgramOption values are appended after the defaults, so callers can still customize or override behavior. Every app built on tui-base should construct its program through this helper for consistent color handling across local, WSL, and SSH sessions.

The first element of opts may be a string — if it is, it is treated as the app-specific color-profile env-var name (e.g. m.ColorProfileEnvVar()) and is consumed before the remaining options are forwarded to tea.NewProgram. This allows consumer apps to pass their branded env var without needing a separate function: 

p := router.NewProgram(m, m.ColorProfileEnvVar(), tea.WithAltScreen())

func NewProgramWithEnvVar added in v0.1.1 

func NewProgramWithEnvVar(m tea.Model, colorProfileEnvVar string, opts ...tea.ProgramOption) *tea.Program

NewProgramWithEnvVar constructs a tea.Program that honors the given colorProfileEnvVar for color-profile overrides. Call this instead of NewProgram when using a RouterModel so the program and router agree on which environment variable controls the color profile: 

m := router.NewWithOptions(router.Options{AppName: "My App"})
p := router.NewProgramWithEnvVar(m, m.ColorProfileEnvVar())

func RegisterPage added in v0.1.11 

func RegisterPage(title string, model tea.Model)

RegisterPage adds a page to the global registry. This is typically called from a page package's init() function so pages can self-register.

Types

type CenteredBase added in v0.1.2 

type CenteredBase = ov.CenteredBase

CenteredBase re-exports [overlay.CenteredBase].

type Context added in v0.1.2 

type Context = ov.Context

Context re-exports [overlay.Context].

type FormOverlayHost added in v0.1.2 

type FormOverlayHost = ov.FormOverlayHost

FormOverlayHost re-exports [overlay.FormOverlayHost].

type KeyConsumer added in v0.1.2 

type KeyConsumer = ov.KeyConsumer

KeyConsumer re-exports [overlay.KeyConsumer].

type MouseConsumer added in v0.1.2 

type MouseConsumer = ov.MouseConsumer

MouseConsumer re-exports [overlay.MouseConsumer].

type Options 

type Options struct {
	// AppName is the display name shown in the terminal window title and the
	// info modal (ℹ overlay). Defaults to "TUI Base" when empty.
	AppName string
	// AppVersion overrides the version string shown in the info modal.
	// When empty, common.AppVersion() (set via -ldflags at build time) is used.
	AppVersion string
	// ConfigDirName is the subdirectory name used under os.UserConfigDir() for
	// storing notifications and other persistent state. Defaults to AppName
	// (lowercased) when empty, and further falls back to "tui-base".
	ConfigDirName string
	// ConfigDir directly overrides the settings configuration directory.
	// If set, this path is used directly.
	ConfigDir  string
	ExtraPages []RegisteredPage
	// DefaultPage is the Title of the page to activate on startup.
	// When empty the first page in the list is shown.
	DefaultPage      string
	InitialLogLevel  string
	SettingsSections []cfg.Section[string]
	KeyMap           *keys.AppKeyMap
	Gates            *gate.GateRegistry
}

Options controls router startup behavior for embedding applications.

type OutsideCloser added in v0.1.2 

type OutsideCloser = ov.OutsideCloser

OutsideCloser re-exports [overlay.OutsideCloser].

type Overlay added in v0.1.2 

type Overlay = ov.Overlay

Overlay re-exports [overlay.Overlay].

type Rect added in v0.1.2 

type Rect = geom.Rect

Rect aliases geom.Rect for backward-compat use in this file.

type RegisteredPage 

type RegisteredPage struct {
	Title string
	Model tea.Model
}

RegisteredPage describes one application page to be added to the router. Only Title and Model are required; the navigation ID is derived automatically from the Title so callers never need to manage IDs separately.

func RegisteredPages added in v0.1.11 

func RegisteredPages() []RegisteredPage

RegisteredPages returns a copy of all dynamically registered pages.

type ReplaceAppPagesMsg 

type ReplaceAppPagesMsg struct {
	Pages       []RegisteredPage
	ActiveTitle string
	ActiveIndex int
}

ReplaceAppPagesMsg replaces the app-provided pages at runtime. Router-managed pages (Inspector and Settings) are preserved automatically.

ActiveIndex is preferred when it is in range; otherwise ActiveTitle is used. If neither matches, the first app page becomes active.

type RouterModel 

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

func New 

func New() *RouterModel

func NewWithOptions 

func NewWithOptions(opts Options) *RouterModel

NewWithOptions creates a router with built-in pages and optional app pages. When DefaultPageID is set and found, that page is selected on startup.

func NewWithRegisteredPages 

func NewWithRegisteredPages(extraPages []RegisteredPage) *RouterModel

NewWithRegisteredPages creates a router with the built-in pages and app provided pages appended after them.

func (*RouterModel) ColorProfileEnvVar added in v0.1.1 

func (m *RouterModel) ColorProfileEnvVar() string

ColorProfileEnvVar returns the env-var name the router uses to honor a forced color profile override. For an app named "My App" this will be "MY_APP_COLOR_PROFILE". Pass this name to NewProgram so the program and the router agree on which variable to read: 

m := router.NewWithOptions(router.Options{AppName: "My App"})
p := router.NewProgram(m, m.ColorProfileEnvVar())

func (*RouterModel) DebugEnvVar added in v0.1.1 

func (m *RouterModel) DebugEnvVar() string

DebugEnvVar returns the env-var name the router uses to enable verbose debug logging (e.g. "MY_APP_DEBUG"). Set it to "1" at runtime to activate.

func (*RouterModel) GetActivePage 

func (m *RouterModel) GetActivePage() tea.Model

func (*RouterModel) Init 

func (m *RouterModel) Init() tea.Cmd

func (*RouterModel) RegisterOverlay added in v0.1.2 

func (m *RouterModel) RegisterOverlay(o Overlay)

RegisterOverlay inserts an external overlay into the router's Z-ordered stack.

func (*RouterModel) RegisterPage added in v0.1.11 

func (m *RouterModel) RegisterPage(title string, model tea.Model) tea.Cmd

RegisterPage adds a page to the router at runtime. It initializes the new page's model, updates the navigation layout, and returns the model's Init command.

func (*RouterModel) StatusBarContent added in v0.1.9 

func (m *RouterModel) StatusBarContent() (string, bool)

StatusBarContent reports the status bar's currently rendered text and whether it is visible. Exposed as an introspection seam so conformance tests (testutil.CheckStatusBarVisible) can assert the status bar is present in every rendered frame — on every page and with overlays open. Satisfies testutil.StatusProvider structurally.

func (*RouterModel) Update 

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

func (*RouterModel) View 

func (m *RouterModel) View() tea.View

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.