devtui

README

DevTUI

Reusable terminal user interface abstraction for Go development tools. Built on top of bubbletea, DevTUI provides a pre-configured, minimalist interface where you can inject different handlers to display organized messages and interactions.

→ Why DevTUI? - Complete purpose and functionality description

Quick Start

DevTUI uses specialized handler interfaces that require minimal implementation. Here's a complete example with message tracking:

// HandlerExecution with MessageTracker - Action buttons with progress tracking
type BackupHandler struct {
    lastOpID string
}

func (h *BackupHandler) Name() string  { return "SystemBackup" }
func (h *BackupHandler) Label() string { return "Create System Backup" }
func (h *BackupHandler) Execute(progress ...func(string)) error {
    if len(progress) > 0 {
        progress[0]("Preparing backup...")
        time.Sleep(200 * time.Millisecond)
        progress[0]("Backing up database...")
        time.Sleep(500 * time.Millisecond)
        progress[0]("Backup completed successfully")
    }
    return nil
}

// MessageTracker implementation for operation tracking
func (h *BackupHandler) GetLastOperationID() string   { return h.lastOpID }
func (h *BackupHandler) SetLastOperationID(id string) { h.lastOpID = id }

func main() {
    tui := devtui.NewTUI(&devtui.TuiConfig{
        AppName:  "Demo",
        ExitChan: make(chan bool),
        Color: &devtui.ColorStyle{
            Foreground: "#F4F4F4",
            Background: "#000000",
            Highlight:  "#FF6600",
            Lowlight:   "#666666",
        },
        LogToFile: func(messages ...any) {
            // Replace with actual logging implementation
        },
    })

    // Operations tab with ExecutionHandlers (action buttons)
    ops := tui.NewTabSection("Operations", "System Operations")
    ops.NewExecutionHandlerTracking(&BackupHandler{}).WithTimeout(5 * time.Second)

    var wg sync.WaitGroup
    wg.Add(1)
    go tui.Start(&wg)
    wg.Wait()
}

👉 See complete example with all handler types

Handler Interfaces

DevTUI provides 5 specialized handler types, each requiring minimal implementation:

1. HandlerDisplay - Read-only Information (2 methods)

type HandlerDisplay interface {
    Name() string    // Full text to display in footer
    Content() string // Content shown immediately
}

2. HandlerEdit - Interactive Input Fields (4 methods)

type HandlerEdit interface {
    Name() string    // Unique identifier for logging
    Label() string   // Field label
    Value() string   // Current/initial value
    Change(newValue any, progress ...func(string)) error
}

3. HandlerExecution - Action Buttons (3 methods)

type HandlerExecution interface {
    Name() string  // Unique identifier for logging
    Label() string // Button label
    Execute(progress ...func(string)) error
}

4. HandlerWriter - Simple Logging (1 method)

type HandlerWriter interface {
    Name() string // Writer identifier
}

5. HandlerWriterTracker - Advanced Logging (3 methods)

type HandlerWriterTracker interface {
    Name() string
    MessageTracker
}

type MessageTracker interface {
    GetLastOperationID() string
    SetLastOperationID(id string)
}

Registration Methods

// Basic handlers
tab.NewDisplayHandler(handler).Register()
tab.NewEditHandler(handler).WithTimeout(5*time.Second)
tab.NewExecutionHandler(handler).WithTimeout(10*time.Second)

// Handlers with tracking (can update existing messages)
tab.NewEditHandlerTracking(handlerWithTracker).WithTimeout(5*time.Second)
tab.NewExecutionHandlerTracking(handlerWithTracker).WithTimeout(10*time.Second)

// Writers
tab.NewWriterHandler(handler).Register()
tab.NewWriterHandlerTracking(handlerWithTracker).Register()

// Direct writer registration (auto-detects tracking)
writer := tab.RegisterHandlerWriter(basicWriter)
writer := tab.RegisterHandlerWriterTracker(trackerWriter)

Key Features

• Minimal Implementation: 1-4 methods per handler
• Specialized Interfaces: Clear separation by purpose (Display, Edit, Execution, Writing)
• Progress Callbacks: Real-time feedback for long-running operations
• Message Tracking: Update existing messages instead of creating new ones
• Method Chaining: Clean timeout configuration with .WithTimeout(duration)
• Thread-Safe: Concurrent handler registration and execution

Navigation

• Tab/Shift+Tab: Switch between tabs
• Left/Right: Navigate fields within tab
• Up/Down: Scroll viewport line by line
• Page Up/Page Down: Scroll viewport page by page
• Mouse Wheel: Scroll viewport (when available)
• Enter: Edit/Execute
• Esc: Cancel edit
• Ctrl+C: Exit

Note: DevTUI automatically loads a built-in ShortcutsHandler at position 0 in the first tab, which displays detailed keyboard navigation commands. This handler demonstrates the HandlerDisplay interface and provides interactive help within the application.

Text Selection: Terminal text selection is enabled for copying error messages and logs. Mouse scroll functionality may vary depending on bubbletea version and terminal capabilities.

Documentation

• Complete API Specification - Final API design and interfaces

Acknowledgments

DevTUI is built on top of the excellent libraries from github.com/charmbracelet: bubbletea, bubbles and lipgloss, which provide the solid foundation for creating terminal interfaces in Go.

Contributing

Documentation

Index

• type ColorStyle
• type DevTUI
  • func NewTUI(c *TuiConfig) *DevTUI
  • func (t *DevTUI) AddTabSections(sections ...*tabSection) *DevTUI
  • func (h *DevTUI) ContentView() string
  • func (t *DevTUI) GetTotalTabSections() int
  • func (h *DevTUI) HandleKeyboard(msg tea.KeyMsg) (bool, tea.Cmd)
  • func (h *DevTUI) Init() tea.Cmd
  • func (t *DevTUI) NewTabSection(title, footer string) *tabSection
  • func (h *DevTUI) Print(messages ...any)
  • func (t *DevTUI) ReturnFocus() error
  • func (h *DevTUI) SetTestMode(enabled bool)
  • func (h *DevTUI) Start(args ...any)
  • func (h *DevTUI) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (h *DevTUI) View() string
• type HandlerDisplay
• type HandlerEdit
• type HandlerEditTracker
• type HandlerExecution
• type HandlerExecutionTracker
• type HandlerWriter
• type HandlerWriterTracker
• type MessageTracker
• type ShortcutsHandler
  • func NewShortcutsHandler() *ShortcutsHandler
  • func (h *ShortcutsHandler) Content() string
  • func (h *ShortcutsHandler) Name() string
• type TuiConfig

Types

type ColorStyle

type ColorStyle struct {
	Foreground string // eg: #F4F4F4
	Background string // eg: #000000
	Highlight  string // eg: #FF6600
	Lowlight   string // eg: #666666
}

type DevTUI

type DevTUI struct {
	*TuiConfig
	// contains filtered or unexported fields
}

DevTUI mantiene el estado de la aplicación

func NewTUI

func NewTUI(c *TuiConfig) *DevTUI

NewTUI creates a new DevTUI instance and initializes it.

Usage Example:

config := &TuiConfig{
    AppName: "MyApp",
    ExitChan: make(chan bool),
    Color: nil, // or your *ColorStyle
    LogToFile: func(err any) { fmt.Println(err) },
}
tui := NewTUI(config)

// Configure your sections and fields:
tui.NewTabSection("My Section", "Description").
	NewField("Field1", "value", true, nil)

// Start the TUI:
var wg sync.WaitGroup
wg.Add(1)
go tui.Start(&wg)
wg.Wait()

func (*DevTUI) AddTabSections

func (t *DevTUI) AddTabSections(sections ...*tabSection) *DevTUI

AddTabSections adds one or more tabSections to the DevTUI If a tab with title "DEFAULT" exists, it will be replaced by the first tab section Deprecated: Use NewTabSection and append to tabSections directly

func (*DevTUI) ContentView

func (h *DevTUI) ContentView() string

ContentView renderiza los mensajes para una sección de contenido

func (*DevTUI) GetTotalTabSections

func (t *DevTUI) GetTotalTabSections() int

GetTotalTabSections returns the total number of tab sections

func (*DevTUI) HandleKeyboard

func (h *DevTUI) HandleKeyboard(msg tea.KeyMsg) (bool, tea.Cmd)

HandleKeyboard processes keyboard input and updates the model state returns whether the update function should continue processing or return early

func (*DevTUI) Init

func (h *DevTUI) Init() tea.Cmd

Init initializes the terminal UI application.

func (*DevTUI) NewTabSection

func (t *DevTUI) NewTabSection(title, footer string) *tabSection

NewTabSection creates and initializes a new tabSection with the given title and footer NewTabSection creates a new tab section and automatically adds it to the TUI

Example:

tab := tui.NewTabSection("BUILD", "Press enter to compile")

func (*DevTUI) Print

func (h *DevTUI) Print(messages ...any)

Print sends a normal Label or error to the tui in current tab

func (*DevTUI) ReturnFocus

func (t *DevTUI) ReturnFocus() error

func (*DevTUI) SetTestMode

func (h *DevTUI) SetTestMode(enabled bool)

SetTestMode enables or disables test mode for synchronous behavior in tests. This should only be used in test files to make tests deterministic.

func (*DevTUI) Start

func (h *DevTUI) Start(args ...any)

Start initializes and runs the terminal UI application.

It accepts optional variadic arguments of any type. If a *sync.WaitGroup is provided among these arguments, Start will call its Done() method before returning.

The method runs the UI using the internal tea engine, and handles any errors that may occur during execution. If an error occurs, it will be displayed on the console and the application will wait for user input before exiting.

Parameters:

• args ...any: Optional arguments. Can include a *sync.WaitGroup for synchronization.

func (*DevTUI) Update

func (h *DevTUI) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update maneja las actualizaciones del estado

func (*DevTUI) View

func (h *DevTUI) View() string

type HandlerDisplay

type HandlerDisplay interface {
	Name() string    // Full text to display in footer (handler responsible for content) eg. "System Status Information Display"
	Content() string // Display content (e.g., "help\n1-..\n2-...", "executing deploy wait...")
}

HandlerDisplay defines the interface for read-only information display handlers. These handlers show static or dynamic content without user interaction.

type HandlerEdit

type HandlerEdit interface {
	Name() string                                        // Identificador para logging: "ServerPort", "DatabaseURL"
	Label() string                                       // Field label (e.g., "Server Port", "Host Configuration")
	Value() string                                       // Current/initial value (e.g., "8080", "localhost")
	Change(newValue any, progress ...func(string)) error // Sin return string - usar Value() si no hay error
}

HandlerEdit defines the interface for interactive fields that accept user input. These handlers allow users to modify values through text input.

type HandlerEditTracker

type HandlerEditTracker interface {
	HandlerEdit
	MessageTracker
}

HandlerEditTracker combines HandlerEdit with MessageTracker for advanced edit handlers that need message tracking capabilities.

type HandlerExecution

type HandlerExecution interface {
	Name() string  // Identificador para logging: "DeployProd", "BuildProject"
	Label() string // Button label (e.g., "Deploy to Production", "Build Project")
	Execute(progress ...func(string)) error
}

HandlerExecution defines the interface for action buttons that execute operations. These handlers trigger business logic when activated by the user.

type HandlerExecutionTracker

type HandlerExecutionTracker interface {
	HandlerExecution
	MessageTracker
}

HandlerExecutionTracker combines HandlerExecution with MessageTracker for advanced execution handlers that need message tracking capabilities.

type HandlerWriter

type HandlerWriter interface {
	Name() string // Writer identifier (e.g., "webBuilder", "ApplicationLog")
}

HandlerWriter defines the interface for basic writers that create new lines for each write. These writers are suitable for simple logging or output display.

type HandlerWriterTracker

type HandlerWriterTracker interface {
	Name() string
	MessageTracker
}

HandlerWriterTracker defines the interface for advanced writers that can update existing lines. These writers support message tracking and can modify previously written content.

type MessageTracker

type MessageTracker interface {
	GetLastOperationID() string
	SetLastOperationID(id string)
}

MessageTracker provides optional interface for message tracking control. Handlers can implement this to control message updates and operation tracking.

type ShortcutsHandler

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

ShortcutsHandler - Shows keyboard navigation instructions

func NewShortcutsHandler

func NewShortcutsHandler() *ShortcutsHandler

func (*ShortcutsHandler) Content

func (h *ShortcutsHandler) Content() string

func (*ShortcutsHandler) Name

func (h *ShortcutsHandler) Name() string

type TuiConfig

type TuiConfig struct {
	AppName  string    // app name eg: "MyApp"
	ExitChan chan bool //  global chan to close app eg: make(chan bool)
	/*// *ColorStyle style for the TUI
	  // if nil it will use default style:
	type ColorStyle struct {
	 Foreground string // eg: #F4F4F4
	 Background string // eg: #000000
	 Highlight  string // eg: #FF6600
	 Lowlight   string // eg: #666666
	}*/
	Color *ColorStyle

	LogToFile func(messages ...any) // function to write log error
}