ratatui_ruby 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8e3aed93d74250af44d1b7169dcf7d31575b8b6a24c65d40b4067edb1cf46ea
-  data.tar.gz: e5f3d70e418bc9af98a1926838030aa934b13f64d617ed5c5a1809e91d17d72a
+  metadata.gz: 4fc5e88c5e6146ec1aeae7816aeb8bea73926aaf90d5b2df75fa58d5c6490ab0
+  data.tar.gz: 90ec60b887d797c1cd8b8f06ca41506dbf8a463abc554c20b7caab8ec537b496
 SHA512:
-  metadata.gz: c1742d63643a1ebef6063097e3755e819da39354b631d70ba72ead21d48d8a9199a5421184698fb41a56ee0991a7411adfbcf125f6ec9e18aa980eeb6d4e03fe
-  data.tar.gz: 995f166470814f6ec2a0e073bc658eb52b5a5381a5c19539d4b6ef575e601eb3ac8c3b000a23b4c226b6708a5387024b71a84c43cd69a5240f538aca261a815b
+  metadata.gz: 3d6fdbb5c4c2970210f70cb0f16c0f40eca871afd6cc115cc5e744e9b85aed01b2c7209baabbb4b2e7129f6ddf460f1add31a6612070a8ef239fbb1e5e2893bd
+  data.tar.gz: ffef16474856ead4d0754dcd6f26104b795a6c2d8aac962df73d7f6c468d4fc6ad7c769a68bb97c1ad3fecc487973afbb50764c555f0a8385addf14864d5c22c

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.6.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.6.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.6.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.6.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/AGENTS.md

@@ -19,9 +19,9 @@ Architecture:
 ## Stability & Compatibility
 
 - **Project Status:** Pre-1.0. 
-- **User Base:** 0 users (internal/experimental).
-- **Breaking Changes:** Backward compatibility is **NOT** a priority at this stage. Since there are no external users, you are encouraged to refactor APIs for better ergonomics and performance even if it breaks existing code.
-- **Requirement:** All breaking changes **MUST** be explicitly documented in the [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section to ensure transparency as the project evolves toward 1.0.
+- **User Base:** First external users (as of 2026-01-03).
+- **Breaking Changes:** Backward compatibility is **NOT YET** a priority. Since there are few external users, you are encouraged to refactor APIs for better ergonomics and performance even if it breaks existing code. This will when we ship v1.0.0.
+- **Requirement:** All breaking changes **MUST** be explicitly documented in the [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section to ensure transparency as the project evolves toward 1.0. Migration guides **MUST** be included in `doc/` when we release a new minor version.
 
 ## 1. Standards
 
@@ -91,7 +91,7 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 
 ## 4. Committing
 
-- Who commits: DON'T stage (DON'T `git add`). DON'T commit. DO suggest a commit message.
+- Who commits: DON'T stage (DON'T `git add`) unless explicitly instructed. DON'T commit unless explicitly instructed. DO suggest a commit message when you finish, even if not instructed..
 - When: Before reporting the task as complete to the user, suggest the commit message.
 - What: Consider not what you remember, but EVERYTHING in the `git diff` and `git diff --cached`.
 - **Format:**

data/CHANGELOG.md

@@ -18,6 +18,52 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.7.1] - 2026-01-03
+
+### Added
+
+### Changed
+
+### Fixed
+
+- **Block Title Styling**: `Block` title `content` now correctly renders `Text::Line` objects with styled spans. Previously, passing a styled `Line` as title content displayed its Ruby inspect representation (e.g., `#<data RatatuiRuby::Text::Line...>`) instead of the styled text.
+
+### Removed
+
+## [0.7.0] - 2026-01-03
+
+> [!WARNING]
+> v0.7.0 contains significant breaking changes. See the [Migration Guide](doc/v0.7.0_migration.md) for upgrade instructions.
+
+### Added
+
+- **Rich Text in Table Cells**: `Table` cells (rows, header, footer) now accept `Text::Span` and `Text::Line` objects for per-character styling, matching List widget capabilities.
+- **Row Wrapper**: New `Widgets::Row` class allows applying row-level styling (background color, style) and layout properties (height, top_margin, bottom_margin) to Table rows. Table rows can now be plain arrays or `Widgets::Row` objects.
+- **Cell Wrapper**: New `Widgets::Cell` class wraps table cell content with optional cell-level styling. Distinct from `Buffer::Cell` which is for buffer inspection.
+- **Line#width Method**: `Text::Line` now has a `width` instance method that calculates the display width in terminal cells using unicode-aware measurement. Useful for layout calculations with rich text.
+- **render_rich_buffer**: New `TestHelper::Snapshot#render_rich_buffer` method returns the terminal buffer as an ANSI-encoded string with escape codes for colors and modifiers. Useful for debugging, custom assertions, or programmatic inspection beyond `assert_rich_snapshot`.
+
+### Changed
+
+- **Namespace Restructure (Breaking)**: Classes reorganized to match Ratatui's module hierarchy. See [Migration Guide](doc/v0.7.0_migration.md) for details:
+  - `RatatuiRuby::Rect` → `RatatuiRuby::Layout::Rect`
+  - `RatatuiRuby::Constraint` → `RatatuiRuby::Layout::Constraint`
+  - `RatatuiRuby::Layout` → `RatatuiRuby::Layout::Layout`
+  - `RatatuiRuby::Style` → `RatatuiRuby::Style::Style`
+  - `RatatuiRuby::Paragraph` → `RatatuiRuby::Widgets::Paragraph`
+  - `RatatuiRuby::Block` → `RatatuiRuby::Widgets::Block`
+  - `RatatuiRuby::Table` → `RatatuiRuby::Widgets::Table`
+  - `RatatuiRuby::List` → `RatatuiRuby::Widgets::List`
+  - *(and all other widgets)*
+- **Session → TUI Rename (Breaking)**: `RatatuiRuby::Session` renamed to `RatatuiRuby::TUI` to better reflect its role as a facade/DSL. The `TUI` class now uses explicit factory methods (no metaprogramming) for improved IDE autocomplete support.
+- **Buffer::Cell vs Widgets::Cell (Breaking)**: `RatatuiRuby::Cell` (buffer inspection) renamed to `RatatuiRuby::Buffer::Cell`. New `RatatuiRuby::Widgets::Cell` added for table cell construction.
+- **Text::Line style field (Breaking)**: `Text::Line` now accepts a `style:` parameter for line-level styling, matching Ratatui's `Line` struct which has `style`, `alignment`, and `spans` fields.
+- **Table highlight_style → row_highlight_style (Breaking)**: `Table` parameter `highlight_style:` renamed to `row_highlight_style:` to match Ratatui's API naming convention.
+
+### Fixed
+
+### Removed
+
 ## [0.6.0] - 2026-01-03
 
 ### Added
@@ -322,6 +368,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[0.7.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.1
+[0.7.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.0
 [0.6.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.6.0
 [0.5.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.5.0
 [0.4.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.4.0

data/README.md

@@ -23,6 +23,8 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 > [!WARNING]
 > **ratatui_ruby** is currently in **BETA**. The API may change between minor versions.
 
+**[Why RatatuiRuby?](./doc/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](./doc/why.md) to CharmRuby, raw Rust, and Go.
+
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the [`trunk` branch](https://git.sr.ht/~kerrick/ratatui_ruby/tree/trunk) for pre-release updates.
 
 
@@ -92,12 +94,35 @@ end
 ```
 <!-- SYNC:END -->
 
+![Hello Ratatui](./doc/images/verify_readme_usage.png)
+
 For a full tutorial, see [the Quickstart](./doc/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/application_architecture.md).
 
 
+## Features
+
+**ratatui_ruby** gives you 20+ widgets out of the box:
+
+| Category | Widgets |
+|----------|---------|
+| **Data Display** | Table, List, Chart, Bar Chart, Sparkline, Calendar |
+| **Layout** | Block, Tabs, Scrollbar, Center, Overlay, Clear |
+| **Input** | Gauge, Line Gauge |
+| **Text** | Paragraph, Rich Text (Spans + Lines), Cursor |
+| **Canvas** | Shapes (Line, Circle, Rectangle, Map), Custom Drawing |
+
+Plus: flexible layouts with constraints, full keyboard/mouse/paste/resize events, snapshot testing, and hex/RGB/256-color support.
+
+
 ## Documentation
 
-For the full documentation on how to use **ratatui_ruby**, see the [documentation](./doc/index.md).  For other information, see the [wiki](https://man.sr.ht/~kerrick/ratatui_ruby).
+| Resource | Description |
+|----------|-------------|
+| [Quickstart](./doc/quickstart.md) | Get running in 5 minutes |
+| [Widget Gallery](./doc/quickstart.md#widget-demos) | Every widget with examples |
+| [Application Architecture](./doc/application_architecture.md) | Patterns for scaling your app |
+| [API Reference](./doc/index.md) | Full RDoc documentation |
+| [Wiki](https://man.sr.ht/~kerrick/ratatui_ruby) | Guides and community resources |
 
 
 ## Contributing

data/doc/application_architecture.md

@@ -44,7 +44,7 @@ Need granular control? You can initialize and restore the terminal yourself. Use
 RatatuiRuby.init_terminal
 begin
   RatatuiRuby.draw do |frame|
-    frame.render_widget(RatatuiRuby::Paragraph.new(text: "Hello"), frame.area)
+    frame.render_widget(RatatuiRuby::Widgets::Paragraph.new(text: "Hello"), frame.area)
   end
 ensure
   RatatuiRuby.restore_terminal
@@ -91,9 +91,9 @@ end
 
 Writing UI trees involves nesting many widgets.
 
-**The Problem:** Explicitly namespacing `RatatuiRuby::` for every widget (e.g., `RatatuiRuby::Paragraph.new`) is tedious. It creates visual noise that hides your layout structure.
+**The Problem:** Explicitly namespacing `RatatuiRuby::` for every widget (e.g., `RatatuiRuby::Widgets::Paragraph.new`) is tedious. It creates visual noise that hides your layout structure.
 
-**The Solution:** The Session API (`tui`) provides shorthand factories for every widget. It yields a session object to your block.
+**The Solution:** The TUI API (`tui`) provides shorthand factories for every widget. It yields a TUI object to your block.
 
 ```ruby
 RatatuiRuby.run do |tui|
@@ -147,31 +147,31 @@ RatatuiRuby.run do
   loop do
     RatatuiRuby.draw do |frame|
       # Manual split
-      rects = RatatuiRuby::Layout.split(
+      rects = RatatuiRuby::Layout::Layout.split(
         frame.area,
         direction: :horizontal,
         constraints: [
-          RatatuiRuby::Constraint.length(20),
-          RatatuiRuby::Constraint.min(0)
+          RatatuiRuby::Layout::Constraint.length(20),
+          RatatuiRuby::Layout::Constraint.min(0)
         ]
       )
 
       frame.render_widget(
-        RatatuiRuby::Paragraph.new(
+        RatatuiRuby::Widgets::Paragraph.new(
           text: RatatuiRuby::Text::Line.new(spans: [
-            RatatuiRuby::Text::Span.new(content: "Side", style: RatatuiRuby::Style.new(fg: :blue)),
+            RatatuiRuby::Text::Span.new(content: "Side", style: RatatuiRuby::Style::Style.new(fg: :blue)),
             RatatuiRuby::Text::Span.new(content: "bar")
           ]),
-          block: RatatuiRuby::Block.new(borders: [:all], title: "Nav")
+          block: RatatuiRuby::Widgets::Block.new(borders: [:all], title: "Nav")
         ),
         rects[0]
       )
 
       frame.render_widget(
-        RatatuiRuby::Paragraph.new(
+        RatatuiRuby::Widgets::Paragraph.new(
           text: "Main Content",
-          style: RatatuiRuby::Style.new(fg: :green),
-          block: RatatuiRuby::Block.new(borders: [:all], title: "Content")
+          style: RatatuiRuby::Style::Style.new(fg: :green),
+          block: RatatuiRuby::Widgets::Block.new(borders: [:all], title: "Content")
         ),
         rects[1]
       )
@@ -189,7 +189,7 @@ Building for Ruby 4.0's parallel future? Know which objects can travel between R
 
 ### Data Objects (Shareable)
 
-These are deeply frozen and `Ractor.shareable?`. Include them in TEA Models/Messages freely:
+These are deeply frozen and `Ractor.shareable?`. Include them in immutable Models/Messages freely:
 
 | Object | Source |
 |--------|--------|
@@ -203,7 +203,7 @@ These have side effects and are intentionally not shareable:
 
 | Object | Valid Usage |
 |--------|-------------|
-| `Session` | Cache in `@tui` during run loop. Don't include in Models. |
+| `TUI` | Cache in `@tui` during run loop. Don't include in Models. |
 | `Frame` | Pass to helpers during draw block. Invalid after block returns. |
 
 ```ruby
@@ -224,7 +224,7 @@ Simple scripts work well with valid linear code. Complex apps need structure.
 
 We provide these reference architectures to inspire you:
 
-### Proto-TEA (Model-View-Update)
+### Model-View-Update
 
 **Source:** [examples/app_all_events](../examples/app_all_events/README.md)
 
@@ -236,7 +236,7 @@ This pattern implements unidirectional data flow inspired by The Elm Architectur
 
 Use this when you want predictable state management and easy-to-test logic.
 
-### Proto-Kit (Component-Based)
+### Component-Based
 
 **Source:** [examples/app_color_picker](../examples/app_color_picker/README.md)
 

data/doc/application_testing.md

@@ -45,7 +45,7 @@ def test_rendering
   # Uses default 80x24 terminal
   with_test_terminal do
     # 1. Instantiate your widget
-    widget = RatatuiRuby::Paragraph.new(text: "Hello World")
+    widget = RatatuiRuby::Widgets::Paragraph.new(text: "Hello World")
     
     # 2. Render it using the Frame API
     RatatuiRuby.draw do |frame|

data/doc/async.md

@@ -0,0 +1,160 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Async Operations in TUI Applications
+
+TUI applications fetch data from APIs, run shell commands, and query databases. These operations take time. Blocking the render loop freezes the interface.
+
+You want responsive UIs. The checklist shows "Loading..." while data arrives. The interface never hangs.
+
+This guide explains async patterns that work with raw terminal mode.
+
+## The Raw Terminal Problem
+
+`RatatuiRuby.run` enters raw terminal mode:
+
+- stdin reconfigures for character-by-character input
+- stdout carries terminal escape sequences
+- External commands expecting normal terminal I/O fail
+
+### What Breaks
+
+```ruby
+# These fail inside a Thread during raw mode:
+`git ls-remote --tags origin`           # Returns empty or hangs
+IO.popen(["git", "ls-remote", ...])     # Same
+Open3.capture2("git", "ls-remote", ...) # Same
+```
+
+The commands succeed synchronously. They fail asynchronously. The difference: thread context inherits the parent's raw terminal state.
+
+### Why Threads Fail
+
+Ruby's GIL releases during I/O. But:
+
+1. Subprocesses inherit the parent's terminal state.
+2. Git/SSH try to read credentials from raw-mode stdin.
+3. The read blocks forever. Or returns empty.
+
+`GIT_TERMINAL_PROMPT=0` prevents prompts. Auth fails silently instead of hanging.
+
+## Solutions
+
+### Pre-Check Before Raw Mode
+
+Run slow operations before entering the TUI:
+
+```ruby
+def initialize
+  @data = fetch_data  # Runs before RatatuiRuby.run
+end
+```
+
+**Trade-off**: Delays startup.
+
+### Process.spawn with File Output
+
+Spawn a separate process before entering raw mode. Write results to a temp file. Poll for completion:
+
+```ruby
+class AsyncChecker
+  CACHE_FILE = File.join(Dir.tmpdir, "my_check_result.txt")
+
+  def initialize
+    @loading = true
+    @result = nil
+    @pid = Process.spawn("my-command > #{CACHE_FILE}")
+  end
+
+  def loading?
+    return false unless @loading
+
+    # Non-blocking poll
+    _pid, status = Process.waitpid2(@pid, Process::WNOHANG)
+    if status
+      @result = File.read(CACHE_FILE).strip
+      @loading = false
+    end
+    @loading
+  end
+end
+```
+
+**Key points**:
+
+- `Process.spawn` returns immediately.
+- The command runs in a separate process, not a thread.
+- Results pass through a temp file. Avoids pipe/terminal issues.
+- `Process::WNOHANG` polls without blocking.
+
+### Thread for CPU-Bound Work
+
+Ruby threads work for pure computation:
+
+```ruby
+Thread.new { @result = expensive_calculation }
+```
+
+Avoid threads for shell commands.
+
+## Ractors
+
+Ractors provide true parallelism. Trade-offs:
+
+- No mutable shared state.
+- Limited to Ractor-safe values.
+- Terminal I/O issues remain.
+
+For TUI async, `Process.spawn` solves the problem cleanly.
+
+## Pattern Summary
+
+| Approach | Use Case | Raw Mode Safe? |
+|----------|----------|----------------|
+| Sync before TUI | Fast checks (<100ms) | Yes |
+| Process.spawn + file | Shell commands, network | Yes |
+| Thread | CPU-bound Ruby code | Yes |
+| Thread + shell | Shell commands | **No** |
+
+## Real Example: Git Tag Check
+
+Check if a tag exists on the remote:
+
+```ruby
+class GitRepo
+  CACHE_FILE = File.join(Dir.tmpdir, "git_tag_pushed.txt")
+
+  def initialize
+    @version = `git describe --tags --abbrev=0`.strip
+    @tag_pushed = nil
+    @loading = true
+    @pid = Process.spawn(
+      "git ls-remote --tags origin | grep -q '#{@version}' " \
+      "&& echo true > #{CACHE_FILE} || echo false > #{CACHE_FILE}"
+    )
+  end
+
+  def loading?
+    return false unless @loading
+
+    _pid, status = Process.waitpid2(@pid, Process::WNOHANG)
+    if status
+      @tag_pushed = File.read(CACHE_FILE).strip == "true"
+      @loading = false
+    end
+    @loading
+  end
+
+  def refresh
+    # Sync version for manual refresh (user presses 'r')
+    @loading = true
+    remote_tags = `git ls-remote --tags origin`.strip
+    @tag_pushed = remote_tags.include?(@version)
+    @loading = false
+  end
+end
+```
+
+The TUI starts instantly. The tag check runs in the background. The checklist updates when the result arrives.