tui

package
v0.0.0-...-a4aab55 Latest Latest
Warning

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

 Go to latest Published: Jan 11, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package tui implements the terminal user interface for graph visualization. It uses the Bubbletea framework to create an interactive TUI with support for pan, zoom, search, and theme switching. The implementation follows The Elm Architecture pattern with a Model-Update-View cycle.

Package tui implements cosmo-style rendering for graph visualization. Based on original TypeScript implementation from: https://github.com/turutupa/cosmo

COSMO RENDERING CONVENTIONS: ============================

Node Position:

  • position.Y refers to the TOP of the VALUE frame (not the ID frame!)
  • ID frame is rendered IDOffset (2) rows ABOVE the value frame
  • Total node rendering spans from (position.Y - IDOffset) to (position.Y + FrameHeight)

Node Structure (5 lines total at position): 

Y-2: ┌──────────────┐  (ID frame top)
Y-1: │   node-id    │  (ID frame middle)
Y+0: ┌──────────────┐  (Value frame top - overwrites ID frame bottom)
Y+1: │  node-value  │  (Value frame middle - EDGE CONNECTION POINT)
Y+2: └──────────────┘  (Value frame bottom)

Edge Connections:

  • Edges connect at position.Y + 1 (center line of value frame)
  • Use orthogonal routing with box-drawing characters (─│┌┐└┘)

Rendering Order:

  1. Edges first (background layer)
  2. Nodes second (foreground layer)

Layout Algorithm:

  • Uses tree-based BFS layout (similar to ELK's mrtree)
  • Nodes arranged in levels based on graph depth
  • Horizontal spacing: 18 units, Vertical spacing: 8 units

Index

Constants

View Source 
const (
	DefaultNodeWidth = 16 // Width of node frames (inner content width)
	TotalNodeWidth   = 18 // Total width including borders (DefaultNodeWidth + 2)
	FrameHeight      = 5  // Height of complete node rendering (cosmo uses 5, not 3!)
	IDOffset         = 2  // Vertical offset of ID frame above value frame
	TotalNodeHeight  = 5  // Total rendering height
	MaxTextLength    = 14 // Maximum length before text is truncated
	SliceLength      = 12 // Length to slice text to when truncating
)

Constants from cosmo implementation (cosmo/src/components/node.tsx)

Variables

This section is empty.

Functions

func Run 

func Run(g *graph.Graph, options ...ModelOption) error

Run is a convenience function that creates a new Model and runs the bubbletea program. It returns any error encountered during model creation or program execution.

Types

type Cell 

type Cell struct {
	Char  rune
	Style CellStyle
}

Cell represents a character with its style

type CellStyle 

type CellStyle int

CellStyle represents the styling for a cell 

const (
	StyleNormal CellStyle = iota
	StyleHighlight
	StyleFocused
)

type FitViewMsg 

type FitViewMsg struct{}

FitViewMsg centers and fits the graph in view

type HideMenuMsg 

type HideMenuMsg struct{}

HideMenuMsg hides the current overlay

type KeyMap 

type KeyMap struct {
	// Navigation
	Up    key.Binding
	Down  key.Binding
	Left  key.Binding
	Right key.Binding

	// Fast navigation (with Shift modifier)
	FastUp    key.Binding
	FastDown  key.Binding
	FastLeft  key.Binding
	FastRight key.Binding

	// View controls
	Center key.Binding

	// Node selection
	NextNode key.Binding
	PrevNode key.Binding

	// Actions
	Search key.Binding
	Menu   key.Binding
	Help   key.Binding
	Quit   key.Binding

	// Internal keys (for menus, search, etc.)
	Enter  key.Binding
	Escape key.Binding
}

KeyMap defines the keybindings for the graph visualizer. All bindings are configurable to allow users to customize navigation and actions.

func DefaultKeyMap 

func DefaultKeyMap() KeyMap

DefaultKeyMap returns the default keybindings. These match the original vim-style navigation.

func (KeyMap) FullHelp 

func (k KeyMap) FullHelp() [][]key.Binding

FullHelp returns an extended group of help key bindings to be displayed in the full help view.

func (KeyMap) ShortHelp 

func (k KeyMap) ShortHelp() []key.Binding

ShortHelp returns a slice of key bindings to be displayed in the short help view.

type Model 

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

Model represents the main bubbletea model

func NewModel 

func NewModel(options ...ModelOption) (Model, error)

func NewModelSimple 

func NewModelSimple(g *graph.Graph, themeName string) Model

NewModel creates a new TUI model with graph and theme. Deprecated: Use NewModel with ModelOption for better configurability.

func (Model) Init 

func (m Model) Init() tea.Cmd

Init initializes the model

func (Model) Update 

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

Update handles messages and updates model state

func (Model) View 

func (m Model) View() string

View renders the UI

type ModelOption 

type ModelOption func(*Model) error

ModelOption sets an option on the TUI Model. This follows the functional options pattern used in glamour and other Bubbletea components.

func WithAutoSelectFirst 

func WithAutoSelectFirst() ModelOption

WithAutoSelectFirst automatically selects the first node when a graph is loaded.

func WithAutoTheme 

func WithAutoTheme() ModelOption

WithAutoTheme automatically selects light or dark theme based on terminal settings.

func WithGraph 

func WithGraph(g *graph.Graph) ModelOption

WithGraph sets the graph to visualize.

func WithInitialPan 

func WithInitialPan(x, y int) ModelOption

WithInitialPan sets the initial viewport offset.

func WithInitialZoom 

func WithInitialZoom(zoom float64) ModelOption

WithInitialZoom sets the initial zoom level. Valid range: 0.5 (50%) to 2.0 (200%)

func WithKeyMap 

func WithKeyMap(keyMap KeyMap) ModelOption

WithKeyMap sets custom keybindings for navigation and actions.

func WithLayoutDirection 

func WithLayoutDirection(direction layout.Direction) ModelOption

WithLayoutDirection sets the graph layout direction. Valid directions: layout.DirectionDown, layout.DirectionUp, layout.DirectionRight, layout.DirectionLeft

func WithLayoutOptions 

func WithLayoutOptions(opts layout.LayoutOptions) ModelOption

WithLayoutOptions sets custom layout options for the graph.

func WithOptions 

func WithOptions(options ...ModelOption) ModelOption

WithOptions sets multiple Model options within a single ModelOption.

func WithSelectedNode 

func WithSelectedNode(nodeID string) ModelOption

WithSelectedNode sets the initially selected node.

func WithStyles 

func WithStyles(styles *theme.Styles) ModelOption

WithStyles sets custom lipgloss styles for rendering. This allows complete control over the visual appearance.

func WithTheme 

func WithTheme(themeName string) ModelOption

WithTheme sets the visual theme for the TUI. Theme names include: "aura", "dracula", "monokai", etc.

type NodePositions 

type NodePositions map[string]Position

NodePositions stores calculated positions for each node

type PanMsg 

type PanMsg struct {
	DX int
	DY int
}

PanMsg represents a pan operation

type PathPoint 

type PathPoint struct {
	Position Position
	Char     rune
}

PathPoint represents a point on an edge path with its character

type Position 

type Position struct {
	X int
	Y int
}

Position represents a 2D coordinate

type QuitMsg 

type QuitMsg struct{}

QuitMsg quits the application

type Screen 

type Screen int

Screen represents different UI screens/overlays 

const (
	ScreenMain Screen = iota
	ScreenMenu
	ScreenSearch
	ScreenKeybindings
	ScreenThemeSelector
)

type SearchMsg 

type SearchMsg struct {
	Query string
}

SearchMsg represents a search operation

type SelectNodeMsg 

type SelectNodeMsg struct {
	NodeID string
}

SelectNodeMsg represents node selection

type ShowKeybindingsMsg 

type ShowKeybindingsMsg struct{}

ShowKeybindingsMsg shows the keybindings help

type ShowMenuMsg 

type ShowMenuMsg struct{}

ShowMenuMsg toggles the main menu

type ShowSearchMsg 

type ShowSearchMsg struct{}

ShowSearchMsg shows the search input

type ThemeChangeMsg 

type ThemeChangeMsg struct {
	ThemeName string
}

ThemeChangeMsg changes the theme

type WindowSizeMsg 

type WindowSizeMsg tea.WindowSizeMsg

WindowSizeMsg handles terminal resize

type ZoomMsg 

type ZoomMsg struct {
	Delta float64
}

ZoomMsg represents a zoom operation

Source Files

View all Source files

Directories

Path Synopsis
Package theme provides color schemes and styling for the TUI.
 Package theme provides color schemes and styling for the TUI.

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.