Help us shape the future of Go! Take the 2026 Go Developer Survey

phoenix

module
v0.1.0-beta.1 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2025 License: MIT

README

Phoenix TUI Framework

Next-generation Terminal User Interface framework for Go

Status: ✅ v0.1.0-beta.1 READY - First Public Beta Progress: 80% complete (16/20 weeks) 🎉 Organization: github.com/phoenix-tui Go Version: 1.25+ Test Coverage: 93.5-96.4% (Excellent across all modules) Performance: 29,000 FPS (489x faster than 60 FPS target) Latest: Ready for first public beta release 🚀

Why Phoenix?

Phoenix rises from the ashes of legacy TUI frameworks, solving critical problems:

  • ✅ Perfect Unicode/Emoji support - No more layout bugs
  • ✅ 10x Performance - Differential rendering, caching, zero allocations
  • ✅ DDD Architecture - Clean, testable, extendable
  • ✅ Rich Component Library - Everything you need out of the box
  • ✅ Public Cursor API - Full control for shell applications

Libraries

Phoenix is a modular framework with 8 independent libraries:

  • phoenix/core ✅ - Terminal primitives, Unicode/Emoji support (CORRECT width calculation!)
  • phoenix/style ✅ - CSS-like styling (bold, colors, borders, padding)
  • phoenix/layout ✅ - Flexbox & grid layout (Box model, responsive sizing)
  • phoenix/tea ✅ - Elm Architecture (Model-View-Update, type-safe)
  • phoenix/render ✅ - High-performance differential renderer (29,000 FPS!)
  • phoenix/components ✅ - Universal UI components (94.5% avg coverage):
    • TextArea (multiline editing, 96.4%) | TextInput (single-line, 90%)
    • List (94.7%) | Viewport (94.5%) | Table (92%) | Menu | Tabs
    • Modal (96.5%) | Progress (98.5%)
  • phoenix/mouse ✅ - Mouse events (click, scroll, drag-drop, right-click support)
  • phoenix/clipboard ✅ - Cross-platform clipboard (OSC 52 for SSH)

Quick Start

go get github.com/phoenix-tui/phoenix/tea

package main

import (
    "fmt"
    "os"
    "github.com/phoenix-tui/phoenix/tea/api"
)

type Model struct {
    count int
}

func (m Model) Init() api.Cmd { return nil }

func (m Model) Update(msg api.Msg) (Model, api.Cmd) {
    switch msg := msg.(type) {
    case api.KeyMsg:
        if msg.String() == "q" {
            return m, api.Quit()
        }
        m.count++
    }
    return m, nil
}

func (m Model) View() string {
    return fmt.Sprintf("Count: %d\nPress any key to increment, 'q' to quit\n", m.count)
}

func main() {
    p := api.New(Model{}, api.WithAltScreen[Model]())
    if err := p.Run(); err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        os.Exit(1)
    }
}

Documentation

Public Documents
Strategic
Quality & Readiness
Research

Development Status

Library Status Coverage Week Notes
core ✅ Complete 98.4% 3-4 Unicode/Emoji CORRECT!
style ✅ Complete 90%+ 5-6 CSS-like styling
tea ✅ Complete 95.7% 7-8 Elm Architecture
layout ✅ Complete 97.9% 9-10 Flexbox + Box model
components ✅ Complete 94.5% 11-12 6 universal components
render ✅ Complete 91.7% 13-14 29,000 FPS (489x faster!)
mouse ✅ Complete 99.7% 16 3 critical bugs fixed!
clipboard ✅ Complete 82.0% 16 Cross-platform + SSH
Overall Progress
Phase 1: Foundation     ████░░░░░░░░░░░░░░░░  (10%)  ✅ Weeks 1-2
Phase 2: Core Libs      ░░░░████████░░░░░░░░  (30%)  ✅ Weeks 3-8
Phase 3: Components     ░░░░░░░░░░░░████░░░░  (20%)  ✅ Weeks 9-12
Phase 4: Advanced       ░░░░░░░░░░░░░░░░████  (15%)  ✅ Weeks 13-16
Phase 5: Launch         ░░░░░░░░░░░░░░░░░░█░  (5%)   ✅ Coverage Sprint
                        ══════════════════════
                        Progress: 80% (Ready for v0.1.0!)

Test Coverage Sprint Complete: 36,000 lines of test code, 4,340+ test cases, 3 critical bugs fixed

Completed Features

Week 3-4: phoenix/core

  • Terminal primitives (ANSI, raw mode, capabilities)
  • Unicode/Emoji width calculation (CORRECT - fixes Charm bug!)
  • Grapheme cluster support (👋🏽 = 1 cluster, 2 cells)
  • 98.4% test coverage

Week 5-6: phoenix/style

  • CSS-like styling (bold, italic, colors)
  • Border/padding/margin support
  • 8-stage rendering pipeline
  • Fluent builder API
  • 90%+ test coverage

Week 7-8: phoenix/tea

  • Elm Architecture (Model-Update-View)
  • Type-safe event loop
  • Command system (Quit, Batch, Sequence, Tick)
  • Generic constraints (no interface{} casts!)
  • 95.7% test coverage

Week 9-10: phoenix/layout

  • Box model (padding, margin, border, sizing)
  • Flexbox layout (row/column, gap, flex grow/shrink)
  • Responsive sizing
  • 97.9% test coverage (highest!)

Week 11-12: phoenix/components

  • TextInput (90.0%) - Public cursor API, grapheme-aware, selection, validation
  • List (94.7%) - Single/multi selection, filtering, custom rendering
  • Viewport (94.5%) - Scrolling, follow mode, large content (10K+ lines)
  • Table (92.0%) - Sortable columns, custom cell renderers, navigation
  • Modal (96.5%) - Focus trap, buttons, dimming, keyboard shortcuts
  • Progress (98.5%) - Bar + 15 spinner styles
  • Average coverage: 94.5% (exceeds 90% target!)

Week 13-14: phoenix/render

  • Differential rendering (virtual buffer)
  • 29,000 FPS achieved (489x faster than 60 FPS target!)
  • Zero allocations in hot paths
  • 91.7% test coverage (improved from 87.1%)

Week 16: phoenix/mouse 🔥

  • All buttons (Left, Right, Middle, WheelUp, WheelDown)
  • Click detection (single/double/triple - automatic!)
  • Drag & drop state tracking
  • Multi-protocol (SGR, X10, URxvt)
  • Comprehensive README (588 lines)
  • 99.7% test coverage - 6,000+ lines test code
  • 3 critical bugs found and fixed during coverage sprint!

Week 16: phoenix/clipboard

  • Cross-platform (Windows/macOS/Linux)
  • OSC 52 for SSH sessions (auto-detect)
  • Native APIs (user32.dll, pbcopy/pbpaste, xclip/xsel)
  • DDD architecture
  • 82% average test coverage (domain 100%)

Key Features

1. Perfect Unicode/Emoji Support ✅

Problem: Charm's Lipgloss has broken emoji width calculation (issue #562) Solution: Phoenix uses grapheme cluster detection with correct East Asian Width (UAX #11)

// Phoenix: CORRECT
text := "Hello 👋 World 🌍"
width := style.Width(text)  // Returns 17 (correct!)

// Charm Lipgloss: BROKEN
width := lipgloss.Width(text)  // Returns 19 (wrong!)
2. 10x Performance ✅

Benchmark: 29,000 FPS (489x faster than 60 FPS target) Techniques: Differential rendering, caching, zero allocations

3. DDD Architecture ✅
library/
├── domain/        # Business logic (95%+ coverage)
├── application/   # Use cases
├── infrastructure/ # Technical details
└── api/           # Public interface
4. Public Cursor API ✅

Problem: Bubbles TextArea has private cursor - syntax highlighting impossible Solution: Phoenix TextInput exposes CursorPosition() and ContentParts()

// Phoenix: PUBLIC API (syntax highlighting works!)
before, at, after := input.ContentParts()
highlighted := syntax.Highlight(before) +
               cursor.Render(at) +
               syntax.Highlight(after)

// Bubbles: PRIVATE (syntax highlighting impossible!)
// cursor is internal field - no access
5. Mouse & Clipboard Support ✅

Mouse: All buttons (Left, Right, Middle, Wheel), drag-drop, click detection Clipboard: Cross-platform (Windows/macOS/Linux), SSH support (OSC 52)

6. Progress Component ✅

Available: Progress Bar + 15 Spinner Styles (Week 11-12, 98.5% coverage) Location: github.com/phoenix-tui/phoenix/components/progress/api

Phoenix includes a comprehensive Progress component with both bars and animated spinners:

import progress "github.com/phoenix-tui/phoenix/components/progress/api"

// Progress Bar
bar := progress.NewBar(100).  // Max value 100
    SetWidth(40).
    SetLabel("Downloading").
    SetValue(65)  // Current progress 65%

// Animated Spinner (15 styles available!)
spinner := progress.NewSpinner(progress.SpinnerDots).
    SetLabel("Loading").
    SetFPS(10)

// Example styles: SpinnerDots, SpinnerLine, SpinnerArrow, SpinnerCircle,
// SpinnerBounce, SpinnerPulse, SpinnerGrowHorizontal, SpinnerGrowVertical, etc.

Features:

  • Progress bars with customizable width and characters
  • 15 pre-built spinner styles (dots, lines, arrows, circles, bouncing, etc.)
  • Label support for both bars and spinners
  • Configurable FPS for smooth animations
  • 98.5% test coverage

Examples: See examples/progress/ for working demonstrations:

  • bar_simple.go - Basic progress bar
  • bar_styled.go - Styled progress bar with colors
  • spinner_simple.go - Animated spinner
  • multi_progress.go - Multiple progress indicators

Documentation: See components/progress/README.md for full API reference

Next Steps

Week 17-18: GoSh Migration (Real-World Validation)
  • Migrate GoSh shell to Phoenix components
  • Validate all libraries in production application
  • Performance benchmarks vs Charm-based GoSh
  • Expected: 90x faster rendering + new features!
Week 19-20: Polish & v0.1.0 Launch
  • Final performance optimizations
  • Documentation polish
  • Public release preparation
  • Community engagement

Contributing

Phoenix is part of an active development effort. See docs/dev/ for:

  • Architecture documentation
  • Development roadmap
  • Contribution guidelines

License

MIT License - see LICENSE file for details

Special Thanks

Professor Ancha Baranova - This project would not have been possible without her invaluable help and support. Her assistance was crucial in bringing Phoenix to life.

Rising from the ashes of legacy TUI frameworks 🔥 PRODUCTION READY - Test Coverage Sprint Complete! ⭐ 93.5% average coverage | 36,000 lines test code | 3 critical bugs fixed

Directories

Path Synopsis
clipboard module
components module
list module
core module
examples
progress command
wheel-scroll module
layout module
mouse module
render module
style module
tea module
terminal module
testing module

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.