{"id":32745982,"url":"https://github.com/phoenix-tui/phoenix","last_synced_at":"2026-01-14T11:38:21.860Z","repository":{"id":319702635,"uuid":"1076419320","full_name":"phoenix-tui/phoenix","owner":"phoenix-tui","description":" High-performance TUI framework for Go with DDD + Rich model inspired architecture, perfect Unicode, and Elm-inspired design. Modern alternative to Bubbletea/Lipgloss.","archived":false,"fork":false,"pushed_at":"2025-12-03T21:42:40.000Z","size":3136,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-06T10:52:44.654Z","etag":null,"topics":["bubbles","bubbletea","cli","command-line","component-library","cross-platform","ddd","elm-architecture","framework","go","golang","lipgloss","performance","terminal","terminal-app","terminal-ui","testing","tui","ui-framework","unicode"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phoenix-tui.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":null},"created_at":"2025-10-14T20:43:51.000Z","updated_at":"2025-12-03T21:15:51.000Z","dependencies_parsed_at":"2025-10-20T01:00:44.888Z","dependency_job_id":"e8dc63ae-e6d4-4e8e-985a-ed1aae17c645","html_url":"https://github.com/phoenix-tui/phoenix","commit_stats":null,"previous_names":["phoenix-tui/phoenix"],"tags_count":102,"template":false,"template_full_name":null,"purl":"pkg:github/phoenix-tui/phoenix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoenix-tui%2Fphoenix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoenix-tui%2Fphoenix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoenix-tui%2Fphoenix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoenix-tui%2Fphoenix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phoenix-tui","download_url":"https://codeload.github.com/phoenix-tui/phoenix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoenix-tui%2Fphoenix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28419229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubbles","bubbletea","cli","command-line","component-library","cross-platform","ddd","elm-architecture","framework","go","golang","lipgloss","performance","terminal","terminal-app","terminal-ui","testing","tui","ui-framework","unicode"],"created_at":"2025-11-03T17:37:56.419Z","updated_at":"2026-01-14T11:38:21.854Z","avatar_url":"https://github.com/phoenix-tui.png","language":"Go","funding_links":[],"categories":["Command Line","Build Automation"],"sub_categories":["Advanced Console UIs"],"readme":"# Phoenix TUI Framework\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/gh_logo.png\" alt=\"Phoenix TUI Framework\" width=\"600\"/\u003e\n\u003c/p\u003e\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/phoenix-tui/phoenix)](https://github.com/phoenix-tui/phoenix)\n[![Release](https://img.shields.io/github/v/release/phoenix-tui/phoenix?include_prereleases)](https://github.com/phoenix-tui/phoenix/releases)\n[![CI](https://github.com/phoenix-tui/phoenix/actions/workflows/test.yml/badge.svg)](https://github.com/phoenix-tui/phoenix/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/phoenix-tui/phoenix)](https://goreportcard.com/report/github.com/phoenix-tui/phoenix)\n[![Coverage](https://img.shields.io/badge/coverage-91.8%25-brightgreen)](https://github.com/phoenix-tui/phoenix)\n[![License](https://img.shields.io/github/license/phoenix-tui/phoenix)](https://github.com/phoenix-tui/phoenix/blob/main/LICENSE)\n[![GoDoc](https://pkg.go.dev/badge/github.com/phoenix-tui/phoenix.svg)](https://pkg.go.dev/github.com/phoenix-tui/phoenix)\n\n\u003e **Multi-module monorepo** - 10 independent libraries. Full metrics in [CI](https://github.com/phoenix-tui/phoenix/actions).\n\n\u003e Next-generation Terminal User Interface framework for Go\n\n**Status**: ✅ v0.2.0 RELEASED 🚀\n**Organization**: [github.com/phoenix-tui](https://github.com/phoenix-tui)\n**Go Version**: 1.25+\n**Test Coverage**: **91.8%** (Excellent across all modules)\n**Performance**: 29,000 FPS (489x faster than 60 FPS target)\n**API Quality**: **9/10** (Validated against Go 2025 best practices)\n**Latest**: Theme System, Form Components, TTY Control for external processes\n\n## Why Phoenix?\n\nPhoenix rises from the ashes of legacy TUI frameworks, solving critical problems:\n\n- ✅ **Perfect Unicode/Emoji support** - No more layout bugs\n- ✅ **10x Performance** - Differential rendering, caching, zero allocations\n- ✅ **DDD Architecture** - Clean, testable, extendable\n- ✅ **Rich Component Library** - Everything you need out of the box\n- ✅ **Public Cursor API** - Full control for shell applications\n- ✅ **Easy Migration from Charm** - [Comprehensive migration guide](docs/user/MIGRATION_GUIDE.md) included\n\n## Libraries\n\nPhoenix is a modular framework with 8 independent libraries:\n\n- **phoenix/core** ✅ - Terminal primitives, Unicode/Emoji support (CORRECT width calculation!)\n- **phoenix/style** ✅ - CSS-like styling + **Theme System** (4 presets, runtime switching)\n- **phoenix/layout** ✅ - Flexbox \u0026 grid layout (Box model, responsive sizing)\n- **phoenix/tea** ✅ - Elm Architecture + **TTY Control** (run vim, shells, job control)\n- **phoenix/render** ✅ - High-performance differential renderer (29,000 FPS!)\n- **phoenix/components** ✅ - 10 UI components:\n  - TextArea | TextInput | List | Viewport | Table | Modal | Progress\n  - **NEW in v0.2.0**: Select, MultiSelect, Confirm, Form (with validation)\n- **phoenix/mouse** ✅ - Mouse events (click, scroll, drag-drop, right-click support)\n- **phoenix/clipboard** ✅ - Cross-platform clipboard (OSC 52 for SSH)\n\n## Installation\n\n### Install All Libraries (Recommended for new projects)\n\n```bash\ngo get github.com/phoenix-tui/phoenix@latest\n```\n\nThis installs the umbrella module with convenient access to all Phoenix libraries through a single import:\n\n```go\nimport \"github.com/phoenix-tui/phoenix\"\n\n// Use convenience API\nterm := phoenix.AutoDetectTerminal()\nstyle := phoenix.NewStyle().Foreground(\"#00FF00\").Bold()\np := phoenix.NewProgram(myModel, phoenix.WithAltScreen[MyModel]())\n```\n\n### Install Individual Libraries (For existing projects or selective use)\n\n```bash\ngo get github.com/phoenix-tui/phoenix/tea@latest        # Elm Architecture\ngo get github.com/phoenix-tui/phoenix/components@latest # UI Components\ngo get github.com/phoenix-tui/phoenix/style@latest      # Styling\ngo get github.com/phoenix-tui/phoenix/core@latest       # Terminal primitives\n```\n\nIndividual imports give you more control and smaller dependencies:\n\n```go\nimport (\n    tea \"github.com/phoenix-tui/phoenix/tea/api\"\n    \"github.com/phoenix-tui/phoenix/components/input/api\"\n)\n```\n\n## Quick Start\n\n### Using the Umbrella Module\n\n```bash\ngo get github.com/phoenix-tui/phoenix@latest\n```\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"os\"\n    \"github.com/phoenix-tui/phoenix\"\n    tea \"github.com/phoenix-tui/phoenix/tea/api\"\n)\n\ntype Model struct {\n    count int\n}\n\nfunc (m Model) Init() tea.Cmd { return nil }\n\nfunc (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {\n    switch msg := msg.(type) {\n    case tea.KeyMsg:\n        if msg.String() == \"q\" {\n            return m, phoenix.Quit()\n        }\n        m.count++\n    }\n    return m, nil\n}\n\nfunc (m Model) View() string {\n    // Use Phoenix convenience API for styling\n    style := phoenix.NewStyle().Foreground(\"#00FF00\").Bold()\n    return style.Render(fmt.Sprintf(\"Count: %d\\n\", m.count))\n}\n\nfunc main() {\n    p := phoenix.NewProgram(Model{}, phoenix.WithAltScreen[Model]())\n    if err := p.Run(); err != nil {\n        fmt.Fprintf(os.Stderr, \"Error: %v\\n\", err)\n        os.Exit(1)\n    }\n}\n```\n\n### Using Individual Libraries\n\n```bash\ngo get github.com/phoenix-tui/phoenix/tea@latest\n```\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"os\"\n    \"github.com/phoenix-tui/phoenix/tea/api\"\n)\n\ntype Model struct {\n    count int\n}\n\nfunc (m Model) Init() api.Cmd { return nil }\n\nfunc (m Model) Update(msg api.Msg) (Model, api.Cmd) {\n    switch msg := msg.(type) {\n    case api.KeyMsg:\n        if msg.String() == \"q\" {\n            return m, api.Quit()\n        }\n        m.count++\n    }\n    return m, nil\n}\n\nfunc (m Model) View() string {\n    return fmt.Sprintf(\"Count: %d\\nPress any key to increment, 'q' to quit\\n\", m.count)\n}\n\nfunc main() {\n    p := api.New(Model{}, api.WithAltScreen[Model]())\n    if err := p.Run(); err != nil {\n        fmt.Fprintf(os.Stderr, \"Error: %v\\n\", err)\n        os.Exit(1)\n    }\n}\n```\n\n## Documentation\n\n- **[MIGRATION_GUIDE.md](docs/user/MIGRATION_GUIDE.md)** - Migrate from Charm ecosystem (Bubbletea/Lipgloss/Bubbles)\n- **[ROADMAP.md](ROADMAP.md)** - Public roadmap (milestones, progress, dates)\n- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development guide\n- **[GoDoc](https://pkg.go.dev/github.com/phoenix-tui/phoenix)** - API reference for all modules\n\n## Development Status\n\n| Library | Status | Coverage | Week | Notes |\n|---------|--------|----------|------|-------|\n| **core** | ✅ v0.1.0 | 98.4% | 3-4 | Unicode/Emoji CORRECT! |\n| **style** | ✅ v0.1.0 | 90%+ | 5-6 | CSS-like styling |\n| **tea** | ✅ v0.1.0 | 95.7% | 7-8 | Elm Architecture |\n| **layout** | ✅ v0.1.0 | 97.9% | 9-10 | Flexbox + Box model |\n| **components** | ✅ v0.1.0 | 94.5% | 11-12 | 6 universal components |\n| **render** | ✅ v0.1.0 | **91.7%** | 13-14 | 29,000 FPS (489x faster!) |\n| **mouse** | ✅ v0.1.0 | **99.7%** | 16 | 3 critical bugs fixed! |\n| **clipboard** | ✅ v0.1.0 | 82.0% | 16 | Cross-platform + SSH |\n\n### Overall Progress\n\n```\nPhase 1: Foundation     ████████████████████  (10%)  ✅ Weeks 1-2\nPhase 2: Core Libs      ████████████████████  (30%)  ✅ Weeks 3-8\nPhase 3: Components     ████████████████████  (20%)  ✅ Weeks 9-12\nPhase 4: Advanced       ████████████████████  (15%)  ✅ Weeks 13-16\nPhase 5: Launch         ████████████████████  (25%)  ✅ Week 20 - API Polish\n                        ══════════════════════\n                        Progress: 100% (v0.1.0 STABLE!)\n```\n\n**v0.1.0 STABLE RELEASED**: API Quality 9/10, 91.8% coverage, 29,000 FPS, zero value docs complete\n\n### Completed Features\n\n**Week 3-4: phoenix/core**\n- Terminal primitives (ANSI, raw mode, capabilities)\n- Unicode/Emoji width calculation (CORRECT - fixes Charm bug!)\n- Grapheme cluster support (👋🏽 = 1 cluster, 2 cells)\n- 98.4% test coverage\n\n**Week 5-6: phoenix/style**\n- CSS-like styling (bold, italic, colors)\n- Border/padding/margin support\n- 8-stage rendering pipeline\n- Fluent builder API\n- 90%+ test coverage\n\n**Week 7-8: phoenix/tea**\n- Elm Architecture (Model-Update-View)\n- Type-safe event loop\n- Command system (Quit, Batch, Sequence, Tick)\n- Generic constraints (no interface{} casts!)\n- 95.7% test coverage\n\n**Week 9-10: phoenix/layout**\n- Box model (padding, margin, border, sizing)\n- Flexbox layout (row/column, gap, flex grow/shrink)\n- Responsive sizing\n- 97.9% test coverage (highest!)\n\n**Week 11-12: phoenix/components**\n- **TextInput** (90.0%) - Public cursor API, grapheme-aware, selection, validation\n- **List** (94.7%) - Single/multi selection, filtering, custom rendering\n- **Viewport** (94.5%) - Scrolling, follow mode, large content (10K+ lines)\n- **Table** (92.0%) - Sortable columns, custom cell renderers, navigation\n- **Modal** (96.5%) - Focus trap, buttons, dimming, keyboard shortcuts\n- **Progress** (98.5%) - Bar + 15 spinner styles\n- Average coverage: **94.5%** (exceeds 90% target!)\n\n**Week 13-14: phoenix/render**\n- Differential rendering (virtual buffer)\n- 29,000 FPS achieved (489x faster than 60 FPS target!)\n- Zero allocations in hot paths\n- **91.7% test coverage** (improved from 87.1%)\n\n**Week 16: phoenix/mouse** 🔥\n- All buttons (Left, Right, Middle, WheelUp, WheelDown)\n- Click detection (single/double/triple - automatic!)\n- Drag \u0026 drop state tracking\n- Multi-protocol (SGR, X10, URxvt)\n- Comprehensive README (588 lines)\n- **99.7% test coverage** - 6,000+ lines test code\n- **3 critical bugs found and fixed** during coverage sprint!\n\n**Week 16: phoenix/clipboard**\n- Cross-platform (Windows/macOS/Linux)\n- OSC 52 for SSH sessions (auto-detect)\n- Native APIs (user32.dll, pbcopy/pbpaste, xclip/xsel)\n- DDD architecture\n- 82% average test coverage (domain 100%)\n\n## Key Features\n\n### 1. Perfect Unicode/Emoji Support ✅\n**Problem**: Charm's Lipgloss has broken emoji width calculation ([issue #562](https://github.com/charmbracelet/lipgloss/issues/562))\n**Solution**: Phoenix uses grapheme cluster detection with correct East Asian Width (UAX #11)\n\n```go\n// Phoenix: CORRECT\ntext := \"Hello 👋 World 🌍\"\nwidth := style.Width(text)  // Returns 17 (correct!)\n\n// Charm Lipgloss: BROKEN\nwidth := lipgloss.Width(text)  // Returns 19 (wrong!)\n```\n\n### 2. 10x Performance ✅\n**Benchmark**: 29,000 FPS (489x faster than 60 FPS target)\n**Techniques**: Differential rendering, caching, zero allocations\n\n### 3. DDD Architecture ✅\n```\nlibrary/\n├── domain/        # Business logic (95%+ coverage)\n├── application/   # Use cases\n├── infrastructure/ # Technical details\n└── api/           # Public interface\n```\n\n### 4. Public Cursor API ✅\n**Problem**: Bubbles TextArea has private cursor - syntax highlighting impossible\n**Solution**: Phoenix TextInput exposes `CursorPosition()` and `ContentParts()`\n\n```go\n// Phoenix: PUBLIC API (syntax highlighting works!)\nbefore, at, after := input.ContentParts()\nhighlighted := syntax.Highlight(before) +\n               cursor.Render(at) +\n               syntax.Highlight(after)\n\n// Bubbles: PRIVATE (syntax highlighting impossible!)\n// cursor is internal field - no access\n```\n\n### 5. Mouse \u0026 Clipboard Support ✅\n**Mouse**: All buttons (Left, Right, Middle, Wheel), drag-drop, click detection\n**Clipboard**: Cross-platform (Windows/macOS/Linux), SSH support (OSC 52)\n\n### 6. Progress Component ✅\n**Available**: Progress Bar + 15 Spinner Styles (Week 11-12, 98.5% coverage)\n**Location**: `github.com/phoenix-tui/phoenix/components/progress/api`\n\nPhoenix includes a comprehensive Progress component with both bars and animated spinners:\n\n```go\nimport progress \"github.com/phoenix-tui/phoenix/components/progress/api\"\n\n// Progress Bar\nbar := progress.NewBar(100).  // Max value 100\n    SetWidth(40).\n    SetLabel(\"Downloading\").\n    SetValue(65)  // Current progress 65%\n\n// Animated Spinner (15 styles available!)\nspinner := progress.NewSpinner(progress.SpinnerDots).\n    SetLabel(\"Loading\").\n    SetFPS(10)\n\n// Example styles: SpinnerDots, SpinnerLine, SpinnerArrow, SpinnerCircle,\n// SpinnerBounce, SpinnerPulse, SpinnerGrowHorizontal, SpinnerGrowVertical, etc.\n```\n\n**Features**:\n- Progress bars with customizable width and characters\n- 15 pre-built spinner styles (dots, lines, arrows, circles, bouncing, etc.)\n- Label support for both bars and spinners\n- Configurable FPS for smooth animations\n- 98.5% test coverage\n\n**Examples**: See [examples/progress/](examples/progress/) for working demonstrations:\n- `bar_simple.go` - Basic progress bar\n- `bar_styled.go` - Styled progress bar with colors\n- `spinner_simple.go` - Animated spinner\n- `multi_progress.go` - Multiple progress indicators\n\n**Documentation**: See [components/progress/README.md](components/progress/README.md) for full API reference\n\n## What's New in v0.2.0\n\n### Released Features\n\n**TTY Control System** (Level 1, 1+, 2):\n- Run external processes like vim, nano, shells with full terminal control\n- Suspend/Resume Phoenix TUI while external process runs\n- Job control support (foreground/background process groups)\n- Platform support: Linux, macOS, Windows\n\n**Form Components**:\n- **Select** - Single-choice dropdown with keyboard navigation\n- **MultiSelect** - Multiple-choice selection with checkboxes\n- **Confirm** - Yes/No prompts with customizable buttons\n- **Form** - Complete form system with validation\n\n**Theme System**:\n- 4 built-in presets: Default, Dark, Light, HighContrast\n- Runtime theme switching\n- All 10 components support Theme API\n- Custom theme creation\n\n**See [CHANGELOG.md](CHANGELOG.md) for full v0.2.0 details**\n\n### What's Next?\n\n**v0.3.0** (Future):\n- Signals integration (reactive views - optional, hybrid approach)\n- Animation framework\n- Grid layout enhancements\n\n## Contributing\n\nPhoenix is part of an active development effort. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [GoDoc](https://pkg.go.dev/github.com/phoenix-tui/phoenix) for API documentation.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Special Thanks\n\n**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.\n\n---\n\n*Rising from the ashes of legacy TUI frameworks* 🔥\n**v0.2.0 STABLE** ⭐\n*API Quality: 9/10 | 91.8% coverage | 29,000 FPS | Theme System + Form Components + TTY Control!*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphoenix-tui%2Fphoenix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphoenix-tui%2Fphoenix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphoenix-tui%2Fphoenix/lists"}