{"id":29600723,"url":"https://github.com/pseudomuto/gooey","last_synced_at":"2025-07-20T12:36:46.879Z","repository":{"id":305319837,"uuid":"1019079799","full_name":"pseudomuto/gooey","owner":"pseudomuto","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-19T12:33:37.000Z","size":128,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-19T16:03:54.243Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/pseudomuto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-13T17:33:58.000Z","updated_at":"2025-07-19T12:33:41.000Z","dependencies_parsed_at":"2025-07-19T16:04:02.013Z","dependency_job_id":"ff3b48fe-cdbe-4213-9f42-560ee3da2604","html_url":"https://github.com/pseudomuto/gooey","commit_stats":null,"previous_names":["pseudomuto/gooey"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pseudomuto/gooey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fgooey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fgooey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fgooey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fgooey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pseudomuto","download_url":"https://codeload.github.com/pseudomuto/gooey/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fgooey/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266106672,"owners_count":23877390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-07-20T12:36:36.432Z","updated_at":"2025-07-20T12:36:46.870Z","avatar_url":"https://github.com/pseudomuto.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gooey\n\n[![CI](https://github.com/pseudomuto/gooey/workflows/CI/badge.svg)](https://github.com/pseudomuto/gooey/actions)\n[![codecov](https://codecov.io/gh/pseudomuto/gooey/branch/main/graph/badge.svg)](https://codecov.io/gh/pseudomuto/gooey)\n[![Go Reference](https://pkg.go.dev/badge/github.com/pseudomuto/gooey.svg)](https://pkg.go.dev/github.com/pseudomuto/gooey)\n[![Go Report Card](https://goreportcard.com/badge/github.com/pseudomuto/gooey)](https://goreportcard.com/report/github.com/pseudomuto/gooey)\n\nA Go CLI UI library inspired by [Shopify's cli-ui](https://github.com/Shopify/cli-ui), providing beautiful terminal interfaces for command-line applications.\n\n## Features\n\n- **Frame Components**: Create bordered content areas with nested frame support\n- **Progress Components**: Interactive progress bars with extensible renderers, adaptive width calculation, real-time updates, and seamless frame integration\n- **Spinner Components**: Animated loading indicators with automatic color rotation (Red→Blue→Cyan→Magenta), multiple animation styles, and real-time message updates\n- **SpinGroup Components**: Coordinated execution of multiple sequential tasks with individual spinners and status tracking\n- **ANSI Color Support**: Rich color and styling with template-based formatting\n- **Multiple Frame Styles**: Box and bracket frame styles\n- **Automatic Formatting**: Smart content alignment and border management\n- **Terminal Width Detection**: Responsive layouts that adapt to terminal size\n- **Template Processing**: Enhanced syntax supporting `{{bold+cyan:text}}`, `{{check:text}}`, and `{{icon+color:text}}` combinations\n- **Icon System**: Comprehensive icon sets for status, tasks, checklists, and spinners\n- **Terminal Control**: Cursor movement, screen clearing, and visibility controls\n\n## Installation\n\n```bash\ngo get github.com/pseudomuto/gooey\n```\n\n## Quick Start\n\nSee the [examples directory](./examples) for working code examples of all components.\n\n## API Reference\n\n### Frame Methods\n\n- `frame.Open(title string, options ...FrameOption) *Frame` - Create and open a new frame\n- `frame.Close()` - Close the current frame with timing information\n- `frame.Print(format string, args ...any)` - Print formatted content without newline\n- `frame.Println(format string, args ...any)` - Print formatted content with newline\n- `frame.Divider(text string)` - Add a divider line with optional text\n- `frame.ReplaceLine(format string, args ...any)` - Replace the last line with new content (enables single-line updates)\n\n### Frame Options\n\n- `frame.WithColor(color ansi.Color)` - Set frame border color\n- `frame.WithStyle(style FrameStyle)` - Set frame style (Box or Bracket)\n- `frame.WithOutput(w io.Writer)` - Set custom output writer\n\n### Frame Styles\n\n- `frame.Box` - Full box borders with complete enclosure\n- `frame.Bracket` - Simple bracket-style markers\n\n### Progress Methods\n\n- `progress.New(title string, total int, options ...ProgressOption) *Progress` - Create and initialize a new progress bar\n- `progress.Update(current int, message string)` - Update progress value and optional message\n- `progress.Increment(message string)` - Increment progress by 1 with optional message\n- `progress.Complete(message string)` - Mark progress as 100% complete with final message\n\n#### Progress Getters\n\n- `progress.Current() int` - Get current progress value\n- `progress.Total() int` - Get total progress value\n- `progress.Percentage() float64` - Get completion percentage\n- `progress.IsCompleted() bool` - Check if progress is completed\n- `progress.Elapsed() time.Duration` - Get elapsed time since creation\n- `progress.Message() string` - Get current progress message\n- `progress.Title() string` - Get progress bar title\n- `progress.Color() ansi.Color` - Get progress bar color\n- `progress.Width() int` - Get progress bar width\n- `progress.AvailableWidth() int` - Get calculated available width for progress bar\n\n### Progress Options\n\n- `progress.WithColor(color ansi.Color)` - Set progress bar color\n- `progress.WithRenderer(renderer ProgressRenderer)` - Set custom renderer for unlimited styling\n- `progress.WithWidth(width int)` - Set progress bar width in characters\n- `progress.WithOutput(w io.Writer)` - Set custom output writer\n\n### Built-in Progress Renderers\n\n- `progress.Bar` - Full progress bar with filled/empty characters (default)\n- `progress.Minimal` - Minimal display with just percentage and message\n- `progress.Dots` - Dot-based progress indicator\n\n### Custom Progress Renderers\n\nImplement the `ProgressRenderer` interface for custom styling or use `RenderFunc` for inline custom renderers.\n\n### Spinner Methods\n\n- `spinner.New(message string, options ...SpinnerOption) *Spinner` - Create and initialize a new animated spinner\n- `spinner.Start()` - Start the spinner animation in a background goroutine\n- `spinner.Stop()` - Stop the spinner animation and show successful completion with green checkmark\n- `spinner.Fail()` - Stop the spinner animation and show failure with red crossmark\n- `spinner.UpdateMessage(message string)` - Update the spinner message while running\n- `spinner.IsRunning() bool` - Check if the spinner is currently animating\n- `spinner.Message() string` - Get the current spinner message\n- `spinner.Color() ansi.Color` - Get the spinner's configured color\n- `spinner.CurrentColor(frame int) ansi.Color` - Get the color for a specific animation frame (handles rotation)\n- `spinner.Elapsed() time.Duration` - Get elapsed time since spinner started\n- `spinner.ShowElapsed() bool` - Check if elapsed time will be shown on completion\n- `spinner.State() SpinnerState` - Get the current completion state (SpinnerCompleted or SpinnerFailed)\n\n### Spinner Options\n\n- `spinner.WithColor(color ansi.Color)` - Set fixed color (overrides automatic rotation)\n- `spinner.WithRenderer(renderer SpinnerRenderer)` - Set custom animation renderer\n- `spinner.WithInterval(interval time.Duration)` - Set animation frame interval (default: 100ms)\n- `spinner.WithOutput(w io.Writer)` - Set custom output writer\n- `spinner.WithShowElapsed(show bool)` - Control whether elapsed time is displayed on completion (default: true)\n\n### Built-in Spinner Renderers\n\n- `spinner.Dots` - 8-frame braille spinner animation (⠋⠙⠹⠸⠼⠴⠦⠧)\n- `spinner.Clock` - 4-frame subset for slower animation\n- `spinner.Arrow` - Directional arrows rotating (→↓←↑)\n\n### Custom Spinner Renderers\n\nImplement the `SpinnerRenderer` interface for custom animations or use `RenderFunc` for inline custom renderers.\n\n### SpinGroup Methods\n\n- `spinner.NewSpinGroup(title string, options ...SpinGroupOption) *SpinGroup` - Create a new spin group for sequential task execution\n- `spinGroup.AddTask(name string, taskFunc func() error) int` - Add a task to the group and return its ID\n- `spinGroup.Start()` - Start executing all tasks sequentially\n- `spinGroup.Stop()` - Stop the spin group execution\n- `spinGroup.Wait()` - Wait for all tasks to complete\n\n### SpinGroup Options\n\n- `spinner.WithSpinGroupOutput(w io.Writer)` - Set custom output writer for the spin group\n\n### Task Status Types\n\n- `spinner.TaskPending` - Task has not yet started\n- `spinner.TaskRunning` - Task is currently executing\n- `spinner.TaskCompleted` - Task finished successfully\n- `spinner.TaskFailed` - Task failed with an error\n\n\n## Examples\n\nRun the examples to see all features in action:\n\n```bash\n# Frame component examples\ncd examples/frame\ngo run .\n\n# Progress component examples\ncd examples/progress\ngo run .\n\n# Spinner component examples\ncd examples/spinner\ngo run .\n\n# SpinGroup component examples\ncd examples/spingroup\ngo run .\n```\n\nThe frame examples demonstrate:\n- Basic frame usage\n- Nested frames with color inheritance\n- Different frame styles\n- Dividers and formatting\n- ANSI template processing\n- Complex nested layouts\n- Icon usage and status indicators\n- Terminal control sequences\n\nThe progress examples demonstrate:\n- Basic progress bar creation and updates\n- Built-in progress renderers (Bar, Minimal, Dots)\n- Custom renderers with ProgressRenderer interface and RenderFunc\n- Custom colors and widths\n- Increment and completion methods\n- Real-time progress updates with messages  \n- Seamless integration with frames using single-line updates\n- Flexible three-section layout using proportional column system\n- Advanced styling with emoji and time-based custom renderers\n\nThe spinner examples demonstrate:\n- Basic spinner animations with automatic color rotation (Red→Blue→Cyan→Magenta)\n- Built-in spinner renderers (Dots, Clock, Arrow)\n- Custom renderers with SpinnerRenderer interface and RenderFunc\n- Fixed color override with WithColor option\n- Real-time message updates while spinning\n- **Dual completion modes**: successful completion with green checkmark (✓) and failure with red crossmark (✗)\n- **State management**: explicit tracking of completion status with SpinnerState\n- Seamless integration with frames using single-line updates\n- Custom animation intervals and timing control\n- Thread-safe operations and proper resource cleanup\n\nThe SpinGroup examples demonstrate:\n- Sequential task execution with coordinated spinners\n- Task status tracking (Pending, Running, Completed, Failed)\n- Error handling and failure reporting\n- Frame integration for organized display\n- Context-based control and cancellation\n- Thread-safe operations with concurrent access\n\n## Architecture\n\n### Core Packages\n\n- **`ansi`** - ANSI color codes, styles, template formatting, icons, and terminal control sequences\n- **`frame`** - Frame component for bordered content areas with nested frame support\n- **`progress`** - Progress component for interactive progress bars with extensible renderers\n- **`spinner`** - Spinner component for animated loading indicators and sequential task management\n\n### Design Principles\n\n- **io.Writer Interface**: All components implement standard Go interfaces\n- **Functional Options**: Flexible configuration using the options pattern\n- **Renderer Pattern**: Extensible styling through interface-based renderers\n- **Template Processing**: Rich text formatting with `{{style+color:text}}` syntax\n- **Responsive Design**: Automatic adaptation to terminal width\n- **Color Inheritance**: Nested components inherit parent colors appropriately\n- **Single-Line Updates**: Progress components update in place within frames for clean real-time feedback\n- **Flexible Layout System**: Multi-column layouts with proportional width allocation and minimum constraints\n\n## Development\n\n### Prerequisites\n\n- Go 1.24.4 or later\n- [Task](https://taskfile.dev/) for build automation\n\n### Commands\n\n```bash\n# Run tests\ntask test\n\n# Run linter\ntask lint\n\n# Build project\ngo build\n\n# Run specific test\ngo test ./frame -run TestFrameBasic\n\n# Tidy dependencies\ngo mod tidy\n```\n\n### Testing\n\nTests use buffer-based output verification to capture and validate terminal output.\n\n## Contributing\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Follow existing patterns**:\n   - Use the `ansi` package for all formatting\n   - Implement `io.Writer` for output components\n   - Use functional options for configuration\n   - Add comprehensive tests with buffer verification\n4. **Run tests and linting**: `task test \u0026\u0026 task lint`\n5. **Commit changes**: `git commit -m 'Add amazing feature'`\n6. **Push to branch**: `git push origin feature/amazing-feature`\n7. **Open a Pull Request**\n\n### Code Style\n\n- Follow standard Go conventions\n- Use dot imports for tests: `import . \"github.com/pseudomuto/gooey/ansi\"`\n- Test both visual output and behavior\n- Document public APIs with godoc comments\n- Maintain consistency with existing component patterns\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Inspiration\n\nThis library is inspired by [Shopify's cli-ui](https://github.com/Shopify/cli-ui) Ruby gem, adapted for Go with idiomatic patterns and enhanced terminal capabilities.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpseudomuto%2Fgooey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpseudomuto%2Fgooey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpseudomuto%2Fgooey/lists"}