bubbles 0.0.5 → 0.1.1

data/README.md

@@ -1,138 +1,659 @@
-# Bubbles
+<div align="center">
+  <h1>Bubbles for Ruby</h1>
+  <h4>TUI components for Bubble Tea</h4>
 
-[![Build Status](https://travis-ci.org/equivalent/bubbles.svg?branch=master)](https://travis-ci.org/equivalent/bubbles)
+  <p>
+    <a href="https://rubygems.org/gems/bubbles"><img alt="Gem Version" src="https://img.shields.io/gem/v/bubbles"></a>
+    <a href="https://github.com/marcoroth/bubbles-ruby/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/github/license/marcoroth/bubbles-ruby"></a>
+  </p>
 
-Daemonized file uploader that watch a folder and uploads any files files
-to AWS S3 or Local directory (e.g. mounted NAS volume). Designed for Raspberry pi zero
+  <p>Ruby implementation of <a href="https://github.com/charmbracelet/bubbles">charmbracelet/bubbles</a>.<br/>Common UI components for building terminal applications with <a href="https://github.com/marcoroth/bubbletea-ruby">Bubble Tea</a>.</p>
+</div>
 
+## Installation
 
-Notes:
+**Add to your Gemfile:**
 
-* for AWS S3 upload we use AWS-SDK [s3 put_object](http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html#put_object-instance_method) the single file upload should not exceed 5GB. I'm not planing to introduce S3 multipart uploads but Pull Requests are welcome.
+```ruby
+gem "bubbles"
+```
 
+**Or install directly:**
 
-## Installation
+```bash
+gem install bubbles
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| [Spinner](#spinner) | Loading spinners with multiple styles |
+| [CrypticSpinner](#crypticspinner) | Animated gradient spinner with cryptic characters |
+| [Progress](#progress) | Animated progress bars |
+| [Timer](#timer) | Countdown timer |
+| [Stopwatch](#stopwatch) | Elapsed time counter |
+| [TextInput](#textinput) | Single-line text input with cursor |
+| [TextArea](#textarea) | Multi-line text input |
+| [Viewport](#viewport) | Scrollable content pane |
+| [List](#list) | Interactive list with filtering |
+| [Table](#table) | Data table with columns |
+| [FilePicker](#filepicker) | File and directory browser |
+| [Paginator](#paginator) | Pagination controls |
+| [Help](#help) | Help text generator |
+| [Key](#key) | Key binding definitions |
+| [Cursor](#cursor) | Blinking cursor for inputs |
+
+## Usage
 
-Add this line to your application's Gemfile:
+### Spinner
+
+**Animated loading indicator:**
 
 ```ruby
-gem 'bubbles'
+require "bubbles"
+
+spinner = Bubbles::Spinner.new
+spinner.spinner = Bubbles::Spinners::DOT
 ```
 
-And then execute:
+**In your update method:**
+
+```ruby
+spinner, command = spinner.update(message)
+```
 
-    $ bundle
+**In your view method:**
 
-Or install it yourself as:
+```ruby
+spinner.view
+```
 
-    $ gem install bubbles
+**Available spinner styles:**
 
-## Usage
+```ruby
+Bubbles::Spinners::LINE
+Bubbles::Spinners::DOT
+Bubbles::Spinners::MINI_DOT
+Bubbles::Spinners::JUMP
+Bubbles::Spinners::PULSE
+Bubbles::Spinners::POINTS
+Bubbles::Spinners::GLOBE
+Bubbles::Spinners::MOON
+Bubbles::Spinners::MONKEY
+Bubbles::Spinners::METER
+Bubbles::Spinners::HAMBURGER
+Bubbles::Spinners::ELLIPSIS
+```
+
+### CrypticSpinner
+
+**Animated gradient spinner with cryptic characters (inspired by [Charm CLI](https://github.com/charmbracelet/crush)):**
+
+```ruby
+spinner = Bubbles::CrypticSpinner.new(
+  size: 15,
+  label: "Thinking",
+  cycle_colors: true
+)
+```
+
+**In your update method:**
+
+```ruby
+case message
+when Bubbles::CrypticSpinner::TickMessage
+  spinner, command = spinner.update(message)
+end
+```
+
+**In your view method:**
+
+```ruby
+spinner.view
+```
+
+**Custom colors (using CharmTone palette):**
+
+```ruby
+spinner = Bubbles::CrypticSpinner.new(
+  size: 15,
+  label: "Processing",
+  color_a: "#6B50FF",  # Charple (purple)
+  color_b: "#FF60FF",  # Dolly (pink)
+  label_color: "#DFDBDD",
+  cycle_colors: true
+)
+```
+
+**Multi-row (matrix style):**
+
+```ruby
+spinner = Bubbles::CrypticSpinner.new(
+  size: 40,
+  rows: 5,
+  label: "Decrypting",
+  color_a: "#00ff00",
+  color_b: "#003300",
+  cycle_colors: true
+)
+```
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `size` | 10 | Number of cycling characters |
+| `rows` | 1 | Number of rows (for matrix effect) |
+| `label` | "" | Text label after the animation |
+| `color_a` | "#6B50FF" | Start color of gradient |
+| `color_b` | "#FF60FF" | End color of gradient |
+| `label_color` | "#DFDBDD" | Color of the label text |
+| `cycle_colors` | false | Animate gradient movement |
+
+### Progress
+
+**Animated progress bar:**
+
+```ruby
+progress = Bubbles::Progress.new(width: 40)
+progress.set_percent(0.5)
+```
+
+**In your view:**
+
+```ruby
+progress.view
+```
+
+**Customization:**
+
+```ruby
+progress = Bubbles::Progress.new(
+  width: 40,
+  full: "█",
+  empty: "░",
+  show_percentage: true
+)
+progress.full_color = "212"
+progress.empty_color = "238"
+```
+
+### Timer
+
+**Countdown timer (60 seconds):**
+
+```ruby
+timer = Bubbles::Timer.new(60)
+```
+
+**Start the timer:**
+
+```ruby
+command = timer.start
+```
+
+**In update:**
+
+```ruby
+timer, command = timer.update(message)
+```
+
+**Check if done:**
+
+```ruby
+timer.timed_out?
+```
+
+**In view:**
+
+```ruby
+timer.view
+```
+
+### Stopwatch
+
+**Elapsed time counter:**
+
+```ruby
+stopwatch = Bubbles::Stopwatch.new
+```
+
+**Start/stop/toggle:**
+
+```ruby
+command = stopwatch.start
+stopwatch.stop
+command = stopwatch.toggle
+```
+
+**In view:**
+
+```ruby
+stopwatch.view
+```
+
+### TextInput
+
+**Single-line text input:**
+
+```ruby
+input = Bubbles::TextInput.new
+input.placeholder = "Enter your name..."
+input.prompt = "> "
+input.focus
+```
+
+**In update:**
+
+```ruby
+input, command = input.update(message)
+```
+
+**Get value:**
+
+```ruby
+input.value
+```
+
+**In view:**
+
+```ruby
+input.view
+```
+
+**Password mode:**
+
+```ruby
+input.echo_mode = :password
+input.echo_character = "*"
+```
+
+**With suggestions:**
+
+```ruby
+input.suggestions = ["apple", "apricot", "avocado"]
+input.show_suggestions = true
+```
+
+### TextArea
+
+**Multi-line text input:**
+
+```ruby
+textarea = Bubbles::TextArea.new(width: 60, height: 10)
+textarea.placeholder = "Type your message..."
+textarea.show_line_numbers = true
+textarea.focus
+```
+
+**In update:**
+
+```ruby
+textarea, command = textarea.update(message)
+```
+
+**Get value:**
+
+```ruby
+textarea.value
+```
+
+**Position info:**
+
+```ruby
+textarea.row
+textarea.col
+textarea.line_count
+```
+
+### Viewport
+
+**Scrollable content pane:**
 
-##### The easy way
+```ruby
+viewport = Bubbles::Viewport.new(width: 80, height: 20)
+viewport.content = long_text
+```
 
-Gem by default looks into to two locations for configuration file. So
-either create `~/.bubbles/config` or `/var/lib/bubbles/config.yml`
+**In update (handles scroll keys):**
+
+```ruby
+viewport, command = viewport.update(message)
+```
 
-> note: make sure you have correct read access permission so that ruby
-> can read that file
+**Scroll info:**
 
-...with content similar to this:
+```ruby
+viewport.scroll_percent
+viewport.at_top?
+viewport.at_bottom?
+```
 
-```yml
-s3_access_key_id:  xxxxxxxxxxxxxxxxxxxx
-s3_secret_access_key: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
-s3_bucket: bucket_name
-s3_region: eu-west-1
+**In view:**
 
-source_dir: /home/myuser/source_folder
-processing_dir: /home/myuser/processing_folder
+```ruby
+viewport.view
 ```
 
-Now all is left is to lunch bubbles with  `bubbles` or `bundle exec bubbles`
+**Programmatic scrolling:**
 
-> note: files in `source_folder` will get removed after successful upload 
+```ruby
+viewport.scroll_down(5)
+viewport.scroll_up(5)
+viewport.page_down
+viewport.page_up
+viewport.goto_top
+viewport.goto_bottom
+```
 
-##### More advanced config
+### List
 
+**Interactive list with filtering:**
 
-```yml
-source_dir: /var/myuser/source_folder              # source from where to pick up files
-processing_dir: /home/myuser/processing_folder
+```ruby
+items = [
+  { title: "Item 1", description: "First item" },
+  { title: "Item 2", description: "Second item" }
+]
 
-log_level: 0                                       # debug log level
-log_path: /var/log/bubbles.log                     # default is STDOOT
+list = Bubbles::List.new(items, width: 40, height: 10)
+list.title = "My List"
+```
 
-sleep_interval: 1                                  # sleep between next command
-num_of_files_to_schedule: 1                        # how many files schedule for processing at the same time
+**In update:**
 
-uploaders:
-  - 'Bubbles::Uploaders::S3EnsureConnection'       # this will check if s3 connection can be established
-  - 'Bubbles::Uploaders::S3'                       # by default only S3 uploader is used
-  - 'Bubbles::Uploaders::LocalDir'
+```ruby
+list, command = list.update(message)
+```
 
-s3_access_key_id:  xxxxxxxxxxxxxxxxxxxx
-s3_secret_access_key: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
-s3_bucket: bucket_name
-s3_region: eu-west-1
-s3_path: foo_folder/bar_folder/car_folder          # will upload to s3://bucket/foo_folder/bar_folder/car_folder
-s3_acl: private                                    # # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
+**Get selection:**
 
-local_dir_uploader_path: /mnt/network_smb_storage/
-local_dir_metadata_file_path: /var/log/uploads_metadata.yaml
+```ruby
+list.selected_item
 ```
 
-> Look into [lib/bubbles/config.rb](https://github.com/equivalent/bubbles/blob/master/lib/bubbles/config.rb) for more details.
+**Filter state:**
 
-##### Full Ruby way
+```ruby
+list.filter_state
+```
 
-You can create custom ruby file and you initialize custom
-`Bubbles::Config.new` instance and set all the options you want there:
+**Styling:**
 
 ```ruby
-# ~/my_bubbles_runner.rb
-require 'bubbles'
+list.title_style = Lipgloss::Style.new.bold(true).foreground("212")
+list.selected_item_style = Lipgloss::Style.new.foreground("212")
+list.item_style = Lipgloss::Style.new.foreground("252")
+```
+
+### Table
+
+**Data table with columns:**
 
-c = Bubbles::Config.new
+```ruby
+columns = [
+  { title: "Name", width: 20 },
+  { title: "Age", width: 5 },
+  { title: "City", width: 15 }
+]
+
+rows = [
+  ["Alice", "30", "New York"],
+  ["Bob", "25", "London"]
+]
+
+table = Bubbles::Table.new(columns: columns, rows: rows, height: 10)
+```
 
-c.log_level = 0
-c.source_dir = /var/myuser/source_folder
-c.processing_dir = /var/myuser/processing_folder
-c.uploader_classes = [Bubbles::Uploaders::S3, Bubbles::Uploaders::LocalDir]
-c.local_dir_uploader_path = /mnt/network_smb_storage
-c.s3_region = 'eu-west-1'
-c.s3_bucket = 'mybckt'
-c.s3_access_key_id     = 'xxxxxxxxxxx'
-c.s3_secret_access_key = 'yyyyyyyyyyy'
+**In update:**
 
-# ...
+```ruby
+table, command = table.update(message)
+```
 
-command_queue = Bubbles::CommandQueue.new(config: c)
-command_queue << Bubbles::DirWatcher.new(config: c, command_queue: command_queue)
+**Get selection:**
 
-loop do
-  command_queue.call_next
-  sleep c.sleep_interval
+```ruby
+table.selected_row
+table.selected_row_data
+```
+
+**Styling:**
+
+```ruby
+table.header_style = Lipgloss::Style.new.bold(true).foreground("212")
+table.cell_style = Lipgloss::Style.new.padding_left(1)
+table.selected_style = Lipgloss::Style.new.bold(true).background("57")
+```
+
+### FilePicker
+
+**File and directory browser:**
+
+```ruby
+picker = Bubbles::FilePicker.new(directory: ".")
+picker.height = 15
+picker.show_hidden = false
+picker.allowed_types = ["rb", "txt"]
+```
+
+**In update:**
+
+```ruby
+picker, command = picker.update(message)
+```
+
+**Check for selection:**
+
+```ruby
+if picker.did_select_file?
+  selected_path = picker.path
 end
 ```
 
-..and execute:
+**Options:**
+
+```ruby
+picker.show_permissions = true
+picker.show_size = true
+picker.dir_allowed = false
+picker.file_allowed = true
+```
+
+### Paginator
 
-```sh
-ruby my_bubbles_runner.rb
-# or
-bundle exec ruby my_bubbles_runner.rb
+**Pagination controls:**
+
+```ruby
+paginator = Bubbles::Paginator.new(type: Bubbles::Paginator::DOTS)
+paginator.per_page = 10
+paginator.update_total_pages(100)
 ```
 
-> Look into [lib/bubbles/config.rb](https://github.com/equivalent/bubbles/blob/master/lib/bubbles/config.rb) for more details.
+**Navigation:**
+
+```ruby
+paginator.next_page
+paginator.prev_page
+```
+
+**Get slice bounds for your data:**
+
+```ruby
+start_index, end_index = paginator.slice_bounds(items.length)
+visible_items = items[start_index...end_index]
+```
+
+**In view:**
+
+```ruby
+paginator.view
+```
+
+**Types:**
+
+```ruby
+Bubbles::Paginator::ARABIC
+Bubbles::Paginator::DOTS
+```
+
+### Help
+
+**Help text generator:**
+
+```ruby
+help = Bubbles::Help.new
+
+bindings = [
+  Bubbles::Key.binding(keys: ["up", "k"], help: ["↑/k", "up"]),
+  Bubbles::Key.binding(keys: ["down", "j"], help: ["↓/j", "down"]),
+  Bubbles::Key.binding(keys: ["q"], help: ["q", "quit"])
+]
+
+help.short_help_view(bindings)
+```
+
+### Key
+
+**Key binding definitions:**
+
+```ruby
+quit_binding = Bubbles::Key.binding(
+  keys: ["q", "ctrl+c"],
+  help: ["q", "quit"]
+)
+```
+
+**Check if a key matches:**
+
+```ruby
+Bubbles::Key.matches?(message, quit_binding)
+```
+
+### Cursor
+
+**Blinking cursor for inputs:**
+
+```ruby
+cursor = Bubbles::Cursor.new
+cursor.char = "_"
+cursor.focus
+```
+
+**Set cursor mode:**
+
+```ruby
+cursor.set_mode(:blink)
+cursor.set_mode(:static)
+cursor.set_mode(:hide)
+```
+
+**In update:**
+
+```ruby
+cursor, command = cursor.update(message)
+```
+
+**In view:**
+
+```ruby
+cursor.view
+```
+
+## Complete Example
+
+```ruby
+require "bubbletea"
+require "lipgloss"
+require "bubbles"
+
+class MyApp
+  include Bubbletea::Model
+
+  def initialize
+    @spinner = Bubbles::Spinner.new
+    @spinner.spinner = Bubbles::Spinners::DOT
+  end
+
+  def init
+    [self, @spinner.tick]
+  end
+
+  def update(message)
+    case message
+    when Bubbletea::KeyMessage
+      return [self, Bubbletea.quit] if message.to_s == "q"
+    end
+
+    @spinner, command = @spinner.update(message)
+    [self, command]
+  end
+
+  def view
+    "#{@spinner.view} Loading...\n\nPress q to quit"
+  end
+end
+
+Bubbletea.run(MyApp.new)
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-To install this gem onto your local machine, run `bundle exec rake install`.
+**Requirements:**
+- Ruby 3.2+
+- [bubbletea-ruby](https://github.com/marcoroth/bubbletea-ruby)
+- [lipgloss-ruby](https://github.com/marcoroth/lipgloss-ruby) (optional, for styling)
+
+**Install dependencies:**
+
+```bash
+bundle install
+```
+
+**Run tests:**
+
+```bash
+bundle exec rake test
+```
+
+**Run demos:**
+
+```bash
+./demo/spinner
+./demo/cryptic_spinner
+./demo/progress
+./demo/textinput
+./demo/textarea
+./demo/viewport
+./demo/list
+./demo/table
+./demo/filepicker
+./demo/timer
+./demo/stopwatch
+./demo/paginator
+./demo/help
+./demo/cursor
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/equivalent/bubbles.
+Bug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/bubbles-ruby.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.
+
+## Acknowledgments
+
+This gem is a Ruby implementation of [charmbracelet/bubbles](https://github.com/charmbracelet/bubbles), part of the excellent [Charm](https://charm.sh) ecosystem. Charm Ruby is not affiliated with or endorsed by Charmbracelet, Inc.
+
+---
+
+Part of [Charm Ruby](https://charm-ruby.dev).
+
+<a href="https://charm-ruby.dev"><img alt="Charm Ruby" src="https://marcoroth.dev/images/heros/glamorous-christmas.png" width="400"></a>
 
+[Lipgloss](https://github.com/marcoroth/lipgloss-ruby) • [Bubble Tea](https://github.com/marcoroth/bubbletea-ruby) • [Bubbles](https://github.com/marcoroth/bubbles-ruby) • [Glamour](https://github.com/marcoroth/glamour-ruby) • [Huh?](https://github.com/marcoroth/huh-ruby) • [Harmonica](https://github.com/marcoroth/harmonica-ruby) • [Bubblezone](https://github.com/marcoroth/bubblezone-ruby) • [Gum](https://github.com/marcoroth/gum-ruby) • [ntcharts](https://github.com/marcoroth/ntcharts-ruby)
 
+The terminal doesn't have to be boring.