bubbles

A Crystal port of Charmbracelet's Bubbles TUI components library
Terminal UI components for building interactive command-line applications

Architecture · Development · Guidelines · Testing · PR Workflow · Porting Parity · Upgrading

Bubbles are self-contained, reusable UI components that float together to create rich terminal interfaces.

Quick Start

1. Add the dependency to your shard.yml:

   dependencies:
     bubbles:
       github: dsisnero/bubbles
   

2. Run shards install

3. Use in your Crystal code:

   require "bubbles"
   
   # Use individual components as needed
   spinner = Bubbles::Spinner.new
   text_input = Bubbles::TextInput.new
   

Features

The bubbles library includes various UI components for terminal applications:

• Spinner - Animated spinners for indicating progress
• Text Input - Single-line text input fields
• Text Area - Multi-line text input areas
• List - Interactive lists with selection
• Table - Data tables with sorting and pagination
• Viewport - Scrollable viewport for content
• Progress - Progress bars for long-running operations
• File Picker - File and directory selection dialogs
• Help - Context-sensitive help displays
• Cursor - Terminal cursor manipulation utilities
• Key - Keyboard input handling and key mapping
• Paginator - Content pagination controls
• Timer - Time-based utilities
• Stopwatch - Timing utilities

Note: This is a work in progress. Not all components have been ported yet.

Development

make install    # Install dependencies
make format     # Check code formatting
make lint       # Run linter (ameba)
make test       # Run tests
rumdl fmt docs/ *.md  # Format markdown documentation

See Development Guide for full setup instructions.

Documentation

Porting Guidelines

This is a Crystal port of Go code. All logic should match the Go implementation exactly, differing only in Crystal language idioms and standard library usage.

• The Go code in vendor/bubbles/ is the source of truth
• Port Go tests to Crystal specs to verify behavior
• Use Crystal's type system and idioms where appropriate
• Follow Crystal naming conventions (snake_case for methods, CamelCase for classes)

Contributing

1. Create an issue: /forge-create-issue
2. Implement: /forge-implement-issue <number>
3. Self-review: /forge-reflect-pr
4. Address feedback: /forge-address-pr-feedback
5. Update changelog: /forge-update-changelog

License

MIT (same as the original Go library)

Acknowledgments

• Charmbracelet for the original Go implementation
• The Bubble Tea ecosystem for inspiring terminal UI development