bubbles 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 268469699924c6a01e8093ac8213509c95cfcdc8
-  data.tar.gz: 5caf988b1600e68ce86a37a7f3ba04ad89b2a912
+SHA256:
+  metadata.gz: d64710274a0d2e55de7efb197eee82f4e8506cd47b345baffecda3f45c08958d
+  data.tar.gz: bacbc6bbbe38cf7db3bcd7c2492bccfb2965f472e1f4c2d1e27c80d492a3834a
 SHA512:
-  metadata.gz: cd4b0257ecf635009040d9bafe01acd81793dc96391023011b7239f7d80260958a1c24fd938050128888a4ad59cee80a05d4cb661aba26ea44c1b36d7703bc58
-  data.tar.gz: c305cd6f10835ec81fcfac0fcec0794e6d083d118d4106a01dc3a092225bdad1f34f7fc8d8bc2bfdac007a8e441b496a7d510b7c58b90665f0a1ac7ab66bcb55
+  metadata.gz: 9c8e0205d20ca9ebc1a7c3e18945b9e7d652200e27927d9292bca08a94716b85438fd8681b0efdbb5e099799457c56eb3cc19506b2922511000b6c228c0a5b11
+  data.tar.gz: 41ee83520438881adb482b5386b7cc6908d82bb4164829ca1a09f089a8ec420f3115264cefe73d4ac3f8e692d2fa4d5b4613d9d371a68b3496700e0973aa4bc1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Marco Roth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,138 +1,582 @@
-# 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 |
+| [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
+
+### Spinner
+
+**Animated loading indicator:**
+
+```ruby
+require "bubbles"
+
+spinner = Bubbles::Spinner.new
+spinner.spinner = Bubbles::Spinners::DOTS
+```
 
-Add this line to your application's Gemfile:
+**In your update method:**
 
 ```ruby
-gem 'bubbles'
+spinner, command = spinner.update(message)
 ```
 
-And then execute:
+**In your view method:**
 
-    $ bundle
+```ruby
+spinner.view
+```
 
-Or install it yourself as:
+**Available spinner styles:**
 
-    $ gem install bubbles
+```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
+```
 
-## Usage
+### Progress
+
+**Animated progress bar:**
+
+```ruby
+progress = Bubbles::Progress.new(width: 40)
+progress.set_percent(0.5)
+```
+
+**In your view:**
+
+```ruby
+progress.view
+```
+
+**Customization:**
 
-##### The easy way
+```ruby
+progress = Bubbles::Progress.new(
+  width: 40,
+  full: "█",
+  empty: "░",
+  show_percentage: true
+)
+progress.full_color = "212"
+progress.empty_color = "238"
+```
 
-Gem by default looks into to two locations for configuration file. So
-either create `~/.bubbles/config` or `/var/lib/bubbles/config.yml`
+### Timer
 
-> note: make sure you have correct read access permission so that ruby
-> can read that file
+**Countdown timer (60 seconds):**
 
-...with content similar to this:
+```ruby
+timer = Bubbles::Timer.new(60)
+```
+
+**Start the timer:**
+
+```ruby
+command = timer.start
+```
 
-```yml
-s3_access_key_id:  xxxxxxxxxxxxxxxxxxxx
-s3_secret_access_key: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
-s3_bucket: bucket_name
-s3_region: eu-west-1
+**In update:**
 
-source_dir: /home/myuser/source_folder
-processing_dir: /home/myuser/processing_folder
+```ruby
+timer, command = timer.update(message)
 ```
 
-Now all is left is to lunch bubbles with  `bubbles` or `bundle exec bubbles`
+**Check if done:**
 
-> note: files in `source_folder` will get removed after successful upload 
+```ruby
+timer.timed_out?
+```
 
-##### More advanced config
+**In view:**
+
+```ruby
+timer.view
+```
 
+### Stopwatch
 
-```yml
-source_dir: /var/myuser/source_folder              # source from where to pick up files
-processing_dir: /home/myuser/processing_folder
+**Elapsed time counter:**
 
-log_level: 0                                       # debug log level
-log_path: /var/log/bubbles.log                     # default is STDOOT
+```ruby
+stopwatch = Bubbles::Stopwatch.new
+```
 
-sleep_interval: 1                                  # sleep between next command
-num_of_files_to_schedule: 1                        # how many files schedule for processing at the same time
+**Start/stop/toggle:**
 
-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
+command = stopwatch.start
+stopwatch.stop
+command = stopwatch.toggle
+```
 
-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
+**In view:**
 
-local_dir_uploader_path: /mnt/network_smb_storage/
-local_dir_metadata_file_path: /var/log/uploads_metadata.yaml
+```ruby
+stopwatch.view
 ```
 
-> Look into [lib/bubbles/config.rb](https://github.com/equivalent/bubbles/blob/master/lib/bubbles/config.rb) for more details.
+### TextInput
+
+**Single-line text input:**
 
-##### Full Ruby way
+```ruby
+input = Bubbles::TextInput.new
+input.placeholder = "Enter your name..."
+input.prompt = "> "
+input.focus
+```
 
-You can create custom ruby file and you initialize custom
-`Bubbles::Config.new` instance and set all the options you want there:
+**In update:**
 
 ```ruby
-# ~/my_bubbles_runner.rb
-require 'bubbles'
+input, command = input.update(message)
+```
 
-c = Bubbles::Config.new
+**Get value:**
 
-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'
+```ruby
+input.value
+```
 
-# ...
+**In view:**
+
+```ruby
+input.view
+```
 
-command_queue = Bubbles::CommandQueue.new(config: c)
-command_queue << Bubbles::DirWatcher.new(config: c, command_queue: command_queue)
+**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:**
+
+```ruby
+viewport = Bubbles::Viewport.new(width: 80, height: 20)
+viewport.content = long_text
+```
+
+**In update (handles scroll keys):**
+
+```ruby
+viewport, command = viewport.update(message)
+```
+
+**Scroll info:**
+
+```ruby
+viewport.scroll_percent
+viewport.at_top?
+viewport.at_bottom?
+```
+
+**In view:**
+
+```ruby
+viewport.view
+```
+
+**Programmatic scrolling:**
+
+```ruby
+viewport.scroll_down(5)
+viewport.scroll_up(5)
+viewport.page_down
+viewport.page_up
+viewport.goto_top
+viewport.goto_bottom
+```
+
+### List
+
+**Interactive list with filtering:**
+
+```ruby
+items = [
+  { title: "Item 1", description: "First item" },
+  { title: "Item 2", description: "Second item" }
+]
+
+list = Bubbles::List.new(items, width: 40, height: 10)
+list.title = "My List"
+```
+
+**In update:**
+
+```ruby
+list, command = list.update(message)
+```
 
-loop do
-  command_queue.call_next
-  sleep c.sleep_interval
+**Get selection:**
+
+```ruby
+list.selected_item
+```
+
+**Filter state:**
+
+```ruby
+list.filter_state
+```
+
+**Styling:**
+
+```ruby
+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:**
+
+```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)
+```
+
+**In update:**
+
+```ruby
+table, command = table.update(message)
+```
+
+**Get selection:**
+
+```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
+
+**Pagination controls:**
+
+```ruby
+paginator = Bubbles::Paginator.new(type: Bubbles::Paginator::DOTS)
+paginator.per_page = 10
+paginator.update_total_pages(100)
+```
+
+**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)
+```
 
-```sh
-ruby my_bubbles_runner.rb
-# or
-bundle exec ruby my_bubbles_runner.rb
+### Cursor
+
+**Blinking cursor for inputs:**
+
+```ruby
+cursor = Bubbles::Cursor.new
+cursor.char = "_"
+cursor.focus
 ```
 
-> Look into [lib/bubbles/config.rb](https://github.com/equivalent/bubbles/blob/master/lib/bubbles/config.rb) for more details.
+**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::DOTS
+  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/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.