ratatui_ruby 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9da9703e1573d331115fd1635c1bf0564a6482c8d3d140c7b68230b56da8311
-  data.tar.gz: 41efa864847825eed6d28ee3b9292e923b3f3c97ce28841892a65123df72c16e
+  metadata.gz: 4fc5e88c5e6146ec1aeae7816aeb8bea73926aaf90d5b2df75fa58d5c6490ab0
+  data.tar.gz: 90ec60b887d797c1cd8b8f06ca41506dbf8a463abc554c20b7caab8ec537b496
 SHA512:
-  metadata.gz: efc0e59765a7cfea0108fa79335ae79d4b0bcdb2c9eff93f6e1f5d83dca04724484ce322b45a6d3e6d6cf45f80868a998c9684a8362c3e11b9e1ff02e30eade1
-  data.tar.gz: be4afb8fe1b4bf7ed1ed4757521f8b90f68ca11c101aa69b184eae2de6807a2efa8a59fc2c19d0c47d3ed28f6afd89c906ba6480e824146b2b4ea8e7bc7211fa
+  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.7.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.7.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.7.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.7.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/CHANGELOG.md

@@ -18,6 +18,18 @@ 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]
@@ -356,6 +368,7 @@ 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

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.

data/doc/debugging.md

@@ -0,0 +1,71 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Debugging TUI Applications
+
+TUI applications run in raw terminal mode. stderr and stdout carry terminal escape sequences. Using `puts` or `warn` inside the render loop corrupts the display.
+
+This creates a problem: how do you inspect variables and trace execution?
+
+Write debug output to files. Tail them in a separate terminal.
+
+## File-Based Logging
+
+Create timestamped log files to avoid overwrites:
+
+```ruby
+FileUtils.mkdir_p(File.join(Dir.tmpdir, "my_debug"))
+timestamp = Time.now.strftime('%Y%m%d_%H%M%S_%N')
+File.write(
+  File.join(Dir.tmpdir, "my_debug", "#{timestamp}.log"),
+  "variable=#{value.inspect}\n"
+)
+```
+
+Or append to a single file:
+
+```ruby
+File.write("/tmp/debug.log", "#{Time.now}: #{message}\n", mode: "a")
+```
+
+Tail the logs in a separate terminal:
+
+```bash
+# Single file
+tail -f /tmp/debug.log
+
+# Directory of timestamped files
+watch -n 0.5 'ls -la /tmp/my_debug/ && cat /tmp/my_debug/*.log'
+```
+
+## REPL Debugging with `__FILE__` Guards
+
+Unit tests verify correctness. But during exploratory debugging, you want to poke at objects interactively. Loading the full TUI just to inspect one object is slow.
+
+Wrap your main execution in a guard:
+
+```ruby
+if __FILE__ == $PROGRAM_NAME
+  MyApp.new.run
+end
+```
+
+Now load the file and interact with classes directly:
+
+```bash
+ruby -e 'load "./bin/my_tui"; obj = MyClass.new; sleep 1; puts obj.result'
+```
+
+This exercises domain logic without entering raw terminal mode. Use it for exploratory debugging. Write tests using the [TestHelper](application_testing.md) for regression coverage.
+
+## Isolating Terminal Issues
+
+Something works in a `ruby -e` script but fails in the TUI. Common causes:
+
+1. **Thread context.** Ruby threads share the process's terminal state.
+2. **Raw mode.** External commands fail when stdin/stdout are reconfigured.
+3. **SSH/Git auth.** Commands that prompt for credentials hang or return empty.
+
+See [Async Operations](async.md) for solutions.

data/ext/ratatui_ruby/Cargo.lock

@@ -1012,7 +1012,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "0.7.0"
+version = "0.7.1"
 dependencies = [
  "bumpalo",
  "lazy_static",

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "0.7.0"
+version = "0.7.1"
 edition = "2021"
 
 [lib]

data/ext/ratatui_ruby/src/style.rs

@@ -12,6 +12,8 @@ use ratatui::{
     widgets::{Block, BorderType, Borders, Padding},
 };
 
+use crate::text::parse_line;
+
 pub fn parse_color(color_str: &str) -> Option<Color> {
     // Try standard ratatui parsing first (named colors, indexed, etc.)
     if let Ok(color) = color_str.parse::<Color>() {
@@ -274,15 +276,22 @@ fn parse_titles(block_val: Value, mut block: Block<'_>) -> Result<Block<'_>, Err
                 let index = isize::try_from(i)
                     .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
                 let title_item: Value = titles_array.entry(index)?;
-                let mut content = String::new();
                 let mut alignment = Alignment::Left;
                 let mut is_bottom = false;
                 let mut style = Style::default();
+                let mut line: Option<Line<'static>> = None;
 
                 if let Some(hash) = magnus::RHash::from_value(title_item) {
                     if let Ok(v) = hash.lookup::<_, Value>(ruby.to_symbol("content")) {
                         if !v.is_nil() {
-                            content = v.funcall("to_s", ())?;
+                            // First, try to parse as a Line object (preserves styling)
+                            if let Ok(parsed_line) = parse_line(v) {
+                                line = Some(parsed_line);
+                            } else {
+                                // Fallback to string
+                                let content: String = v.funcall("to_s", ())?;
+                                line = Some(Line::from(content));
+                            }
                         }
                     }
                     if let Ok(v) = hash.lookup::<_, Value>(ruby.to_symbol("alignment")) {
@@ -307,15 +316,22 @@ fn parse_titles(block_val: Value, mut block: Block<'_>) -> Result<Block<'_>, Err
                         }
                     }
                 } else {
-                    content = title_item.funcall("to_s", ())?;
+                    let content: String = title_item.funcall("to_s", ())?;
+                    line = Some(Line::from(content));
                 }
 
-                let line = Line::from(content).alignment(alignment).style(style);
-                block = if is_bottom {
-                    block.title_bottom(line)
-                } else {
-                    block.title_top(line)
-                };
+                if let Some(mut l) = line {
+                    l = l.alignment(alignment);
+                    // Only apply style if the line doesn't already have styled spans
+                    if style != Style::default() {
+                        l = l.style(style);
+                    }
+                    block = if is_bottom {
+                        block.title_bottom(l)
+                    } else {
+                        block.title_top(l)
+                    };
+                }
             }
         }
     }

data/lib/ratatui_ruby/version.rb

@@ -6,5 +6,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

data/tasks/bump/changelog.rb

@@ -34,4 +34,12 @@ class Changelog
     File.write(@path, "#{header}#{UnreleasedSection.fresh}\n\n#{history}\n#{links}")
     nil
   end
+
+  def commit_message(version)
+    content = File.read(@path)
+    unreleased = UnreleasedSection.parse(content)
+    return nil unless unreleased
+
+    "chore: release v#{version}\n\n#{unreleased.commit_body}"
+  end
 end

data/tasks/bump/ruby_gem.rb

@@ -17,19 +17,31 @@ class RubyGem
 
   def bump(segment)
     target = version.next(segment)
+    commit_message = @changelog.commit_message(target)
 
     puts "Bumping #{segment}: #{version} -> #{target}"
     @changelog.release(target)
     @manifests.each { |manifest| manifest.write(target) }
     @lockfile.refresh
+
+    puts_commit_message(commit_message)
   end
 
   def set(version_string)
     target = SemVer.parse(version_string)
+    commit_message = @changelog.commit_message(target)
 
     puts "Setting version: #{version} -> #{target}"
     @changelog.release(target)
     @manifests.each { |manifest| manifest.write(target) }
     @lockfile.refresh
+
+    puts_commit_message(commit_message)
+  end
+
+  private def puts_commit_message(message)
+    puts "=" * 80
+    puts message
+    puts "=" * 80
   end
 end

data/tasks/bump/unreleased_section.rb

@@ -4,6 +4,7 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 require "date"
+require "rdoc"
 
 # UnreleasedSection manages the [Unreleased] section of the changelog.
 class UnreleasedSection
@@ -35,4 +36,19 @@ class UnreleasedSection
   def to_s
     @content
   end
+
+  def commit_body
+    formatter = Class.new { include RDoc::Text }.new
+    @content
+      .sub(/^## \[Unreleased\].*$/, "")
+      .gsub(/^### (Added|Changed|Fixed|Removed)\n*$/, "")
+      .gsub(/^- \*\*([^*]+)\*\*:/, '\1:')
+      .gsub(/`([^`]+)`/, '\1')
+      .strip
+      .lines
+      .map { |line| line.gsub(/^- /, "").strip }
+      .reject(&:empty?)
+      .map { |line| formatter.wrap(line, 72) }
+      .join("\n\n")
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Kerrick Long
@@ -107,6 +107,7 @@ files:
 - Rakefile
 - doc/application_architecture.md
 - doc/application_testing.md
+- doc/async.md
 - doc/contributors/architectural_overhaul/chat_conversations.md
 - doc/contributors/architectural_overhaul/implementation_plan.md
 - doc/contributors/architectural_overhaul/task.md
@@ -118,6 +119,7 @@ files:
 - doc/contributors/index.md
 - doc/contributors/v1.0.0_blockers.md
 - doc/custom.css
+- doc/debugging.md
 - doc/event_handling.md
 - doc/images/app_all_events.png
 - doc/images/app_color_picker.png