ratatui_ruby 0.7.2 → 0.7.3

data/doc/troubleshooting/tui_output.md

@@ -0,0 +1,76 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Terminal Output During TUI Sessions
+
+## The Problem
+
+Writing to stdout or stderr during a TUI session **corrupts the display**.
+
+When your application is running inside `RatatuiRuby.run`, the terminal is in "raw mode" and RatatuiRuby has taken control of the display buffer. Any output via `puts`, `warn`, `p`, `print`, or direct writes to `STDOUT`/`STDERR` will:
+
+1. **Corrupt the screen layout** - Characters appear in random positions
+2. **Mix with TUI output** - Text interleaves with your widgets unpredictably
+3. **Trigger escape sequence errors** - Partial ANSI codes can break rendering
+
+## Why This Happens
+
+In raw mode:
+- The terminal doesn't process newlines or carriage returns normally
+- Output bypasses the TUI's controlled buffer
+- Cursor position is undefined from the TUI's perspective
+
+## Safe Patterns
+
+### Defer output until after the TUI exits
+
+```ruby
+messages = []
+
+RatatuiRuby.run do |tui|
+  # Collect messages instead of printing them
+  messages << "Something happened"
+  
+  # ... TUI logic ...
+end
+
+# Now safe to print
+messages.each { |msg| puts msg }
+```
+
+### Use debug logging to a file
+
+```ruby
+DEBUG_LOG = File.open("/tmp/my_app_debug.log", "a")
+
+RatatuiRuby.run do |tui|
+  DEBUG_LOG.puts "Debug: something happened"
+  DEBUG_LOG.flush
+  
+  # ... TUI logic ...
+end
+```
+
+### Display messages in the TUI itself
+
+```ruby
+RatatuiRuby.run do |tui|
+  @status_message = "Something happened"
+  
+  tui.draw do |frame|
+    # Show status in the UI
+    frame.render_widget(
+      tui.paragraph(text: @status_message),
+      status_area
+    )
+  end
+end
+```
+
+## Library Behavior
+
+RatatuiRuby automatically defers its own warnings (like experimental feature notices) during TUI sessions. They are queued and printed after `restore_terminal` is called.
+
+You don't need to do anything special for library warnings—they're handled automatically.

data/examples/widget_barchart/README.md

@@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # BarChart (Bar, BarGroup) Example
 
-[![
](../../doc/images/widget_barchart.png)](app.rb)
+[![](../../doc/images/widget_barchart.png)](app.rb)
 
 Visualizes categorical data with interactive attribute cycling.
 

data/examples/widget_block/README.md

@@ -4,7 +4,7 @@
 -->
 # Block Example
 
-[![
](../../doc/images/widget_block.png)](app.rb)
+[![](../../doc/images/widget_block.png)](app.rb)
 
 This example demonstrates the versatile `Block` widget, which provides the visual container, borders, and titles for almost every other widget in `ratatui_ruby`.
 

data/examples/widget_overlay/README.md

@@ -4,7 +4,7 @@
 -->
 # Overlay Example
 
-[![
](../../doc/images/widget_overlay.png)](app.rb)
+[![](../../doc/images/widget_overlay.png)](app.rb)
 
 This example demonstrates the `Overlay` composition pattern for layering widgets with depth. Modals, notifications, and floating panels all require stacking widgets on top of each other.
 

data/ext/ratatui_ruby/Cargo.lock

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

data/ext/ratatui_ruby/Cargo.toml

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

data/ext/ratatui_ruby/src/lib.rs

@@ -121,7 +121,7 @@ fn init() -> Result<(), Error> {
     let m = ruby.define_module("RatatuiRuby")?;
 
     m.define_module_function("_init_terminal", function!(init_terminal, 2))?;
-    m.define_module_function("restore_terminal", function!(restore_terminal, 0))?;
+    m.define_module_function("_restore_terminal", function!(restore_terminal, 0))?;
     m.define_module_function("_draw", function!(draw, -1))?;
 
     // Register Frame class
@@ -147,7 +147,7 @@ fn init() -> Result<(), Error> {
 
     // Test backend helpers
     m.define_module_function(
-        "init_test_terminal",
+        "_init_test_terminal",
         function!(terminal::init_test_terminal, 2),
     )?;
     m.define_module_function(

data/ext/ratatui_ruby/src/rendering.rs

@@ -60,6 +60,15 @@ pub fn render_node(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Err
         "RatatuiRuby::Widgets::RatatuiMascot" => {
             widgets::ratatui_mascot::render_ratatui_mascot(frame, area, node)?;
         }
+        // Text primitives can also be rendered directly as widgets
+        "RatatuiRuby::Text::Line" => {
+            let line = crate::text::parse_line(node)?;
+            frame.render_widget(line, area);
+        }
+        "RatatuiRuby::Text::Span" => {
+            let span = crate::text::parse_span(node)?;
+            frame.render_widget(span, area);
+        }
         _ => {}
     }
     Ok(())

data/ext/ratatui_ruby/src/style.rs

@@ -171,8 +171,28 @@ pub fn parse_border_set<'a>(
 
 pub fn parse_bar_set<'a>(set_val: Value, bump: &'a Bump) -> Result<symbols::bar::Set<'a>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
-    let hash = magnus::RHash::from_value(set_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected hash for bar_set"))?;
+
+    // Check if set_val is a symbol shortcut
+    if let Ok(sym) = magnus::Symbol::from_value(set_val)
+        .ok_or::<Error>(Error::new(ruby.exception_type_error(), ""))
+    {
+        let sym_str = sym.name().unwrap_or_default();
+        return match sym_str.as_ref() {
+            "nine_levels" => Ok(symbols::bar::NINE_LEVELS),
+            "three_levels" => Ok(symbols::bar::THREE_LEVELS),
+            _ => Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("unknown bar_set symbol: :{sym_str}"),
+            )),
+        };
+    }
+
+    let hash = magnus::RHash::from_value(set_val).ok_or_else(|| {
+        Error::new(
+            ruby.exception_type_error(),
+            "expected symbol or hash for bar_set",
+        )
+    })?;
 
     let get_char = |key: &str| -> Result<Option<&'a str>, Error> {
         let mut val: Value = hash

data/ext/ratatui_ruby/src/text.rs

@@ -133,6 +133,8 @@ pub fn parse_line(value: Value) -> Result<Line<'static>, Error> {
     let spans_val: Value = value.funcall("spans", ())?;
     // v0.7.0: Extract style from the Ruby Line
     let style_val: Value = value.funcall("style", ())?;
+    // Extract alignment from the Ruby Line
+    let alignment_val: Value = value.funcall("alignment", ())?;
 
     if spans_val.is_nil() {
         return Ok(Line::from(""));
@@ -177,6 +179,30 @@ pub fn parse_line(value: Value) -> Result<Line<'static>, Error> {
         line = line.style(parse_style(style_val)?);
     }
 
+    // Apply alignment if present
+    if !alignment_val.is_nil() {
+        if let Ok(alignment_sym) = magnus::Symbol::try_convert(alignment_val) {
+            let alignment_str = alignment_sym.name().map_err(|e| {
+                Error::new(
+                    ruby.exception_type_error(),
+                    format!("Invalid alignment symbol: {e}"),
+                )
+            })?;
+            let alignment = match alignment_str.as_ref() {
+                "left" => ratatui::layout::Alignment::Left,
+                "center" => ratatui::layout::Alignment::Center,
+                "right" => ratatui::layout::Alignment::Right,
+                _ => {
+                    return Err(Error::new(
+                        ruby.exception_arg_error(),
+                        format!("Invalid alignment: {alignment_str}. Valid values: :left, :center, :right"),
+                    ));
+                }
+            };
+            line = line.alignment(alignment);
+        }
+    }
+
     Ok(line)
 }
 

data/ext/ratatui_ruby/src/widgets/chart.rs

@@ -75,6 +75,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
             "braille" => symbols::Marker::Braille,
             "block" => symbols::Marker::Block,
             "bar" => symbols::Marker::Bar,
+            "half_block" => symbols::Marker::HalfBlock,
             _ => symbols::Marker::Dot,
         };
 
@@ -115,8 +116,12 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         let pos_sym: Symbol = legend_position_val.funcall("to_sym", ())?;
         let pos = match pos_sym.to_string().as_str() {
             "top_left" => LegendPosition::TopLeft,
+            "top" => LegendPosition::Top,
             "bottom_left" => LegendPosition::BottomLeft,
+            "bottom" => LegendPosition::Bottom,
             "bottom_right" => LegendPosition::BottomRight,
+            "left" => LegendPosition::Left,
+            "right" => LegendPosition::Right,
             _ => LegendPosition::TopRight,
         };
         chart = chart.legend_position(Some(pos));

data/lib/ratatui_ruby/style/style.rb

@@ -39,6 +39,7 @@ module RatatuiRuby
     # * <tt>:dark_gray</tt>, <tt>:light_red</tt>, <tt>:light_green</tt>,
     #   <tt>:light_yellow</tt>, <tt>:light_blue</tt>, <tt>:light_magenta</tt>,
     #   <tt>:light_cyan</tt>, <tt>:white</tt>
+    # * <tt>:reset</tt> — Restores the terminal's default color.
     #
     # ==== String
     # Represents a specific RGB color using a Hex code (<tt>"#RRGGBB"</tt>).

data/lib/ratatui_ruby/test_helper/snapshot.rb

@@ -15,9 +15,10 @@ module RatatuiRuby
     # Verifying every character of a TUI screen by hand is tedious. Snapshots let you
     # capture the screen once and compare against it in future runs.
     #
-    # This mixin provides <tt>assert_snapshot</tt> for plain text and
-    # <tt>assert_rich_snapshot</tt> for styled ANSI output. Both auto-create
-    # snapshot files on first run.
+    # This mixin provides <tt>assert_plain_snapshot</tt> for plain text,
+    # <tt>assert_rich_snapshot</tt> for styled ANSI output, and
+    # <tt>assert_snapshots</tt> (plural) for both. All auto-create snapshot
+    # files on first run.
     #
     # Use it to verify complex layouts, styles, and interactions without manual assertions.
     #
@@ -62,38 +63,46 @@ module RatatuiRuby
     #
     # Mask dynamic content (timestamps, IDs) with a normalization block:
     #
-    #   assert_snapshot("dashboard") do |lines|
+    #   assert_snapshots("dashboard") do |lines|
     #     lines.map { |l| l.gsub(/\d{4}-\d{2}-\d{2}/, "YYYY-MM-DD") }
     #   end
     #
     module Snapshot
       ##
-      # Asserts that the current screen content matches a stored snapshot.
+      # Asserts that the current screen content matches a stored plain text snapshot.
       #
-      # This method simplifies snapshot testing by automatically resolving the snapshot path
-      # relative to the test file calling this method. It assumes a "snapshots" directory
-      # exists in the same directory as the test file.
+      # Plain text snapshots capture layout but miss styling bugs: wrong colors, missing bold,
+      # invisible text on a matching background. *Prefer <tt>assert_snapshots</tt>* (plural) to catch
+      # styling regressions.
       #
-      #   # In test/test_login.rb
-      #   assert_snapshot("login_screen")
-      #   # Look for: test/snapshots/login_screen.txt
+      # Plain text snapshots are human-readable when viewed in any editor or diff tool. They
+      # pair well with rich snapshots for documentation. Use <tt>assert_snapshots</tt> to generate both.
+      #
+      #   assert_plain_snapshot("login_screen")
+      #   # Compares against: test/snapshots/login_screen.txt
       #
       #   # With normalization block
-      #   assert_snapshot("clock") do |actual|
+      #   assert_plain_snapshot("clock") do |actual|
       #     actual.map { |l| l.gsub(/\d{2}:\d{2}/, "XX:XX") }
       #   end
       #
       # [name] String name of the snapshot (without extension).
       # [msg] String optional failure message.
-      def assert_snapshot(name, msg = nil, &)
+      def assert_plain_snapshot(name, msg = nil, snapshot_dir: nil, &)
         # Get the path of the test file calling this method
-        caller_path = caller_locations(1, 1).first.path
-        snapshot_dir = File.join(File.dirname(caller_path), "snapshots")
+        snapshot_dir ||= File.join(File.dirname(caller_locations(1, 1).first.path), "snapshots")
         snapshot_path = File.join(snapshot_dir, "#{name}.txt")
 
         assert_screen_matches(snapshot_path, msg, &)
       end
 
+      ##
+      # @deprecated Use {#assert_plain_snapshot} instead.
+      def assert_snapshot(name, msg = nil, &)
+        warn "assert_snapshot is deprecated; use assert_plain_snapshot instead", uplevel: 1
+        assert_plain_snapshot(name, msg, &)
+      end
+
       ##
       # Asserts that the current screen content matches the expected content.
       #
@@ -186,12 +195,17 @@ module RatatuiRuby
       end
 
       ##
-      # Asserts that the current screen content (including colors!) matches a stored ANSI snapshot.
+      # Asserts that the current screen content (including colors and styles) matches a stored ANSI snapshot.
+      #
+      # TUIs communicate meaning through colors and styles. Rich snapshots capture everything:
+      # wrong colors, missing bold, invisible text on a matching background. *Prefer <tt>assert_snapshots</tt>*
+      # (plural) to also generate human-readable plain text files for documentation.
       #
-      # Generates/Compares against a file with <tt>.ansi</tt> extension.
-      # You can <tt>cat</tt> this file to see exactly what the screen looked like.
+      # The <tt>.ansi</tt> snapshot files contain ANSI escape codes. You can <tt>cat</tt> them in a terminal
+      # to see exactly what the screen looked like.
       #
       #   assert_rich_snapshot("login_screen")
+      #   # Compares against: test/snapshots/login_screen.ansi
       #
       #   # With normalization
       #   assert_rich_snapshot("log_view") do |lines|
@@ -200,9 +214,8 @@ module RatatuiRuby
       #
       # [name] String snapshot name.
       # [msg] String optional failure message.
-      def assert_rich_snapshot(name, msg = nil)
-        caller_path = caller_locations(1, 1).first.path
-        snapshot_dir = File.join(File.dirname(caller_path), "snapshots")
+      def assert_rich_snapshot(name, msg = nil, snapshot_dir: nil)
+        snapshot_dir ||= File.join(File.dirname(caller_locations(1, 1).first.path), "snapshots")
         snapshot_path = File.join(snapshot_dir, "#{name}.ansi")
 
         actual_content = _render_buffer_with_ansi
@@ -254,6 +267,32 @@ module RatatuiRuby
         end
       end
 
+      ##
+      # Asserts both plain text and rich (ANSI-styled) snapshots match.
+      #
+      # This is the recommended snapshot assertion. It calls both <tt>assert_plain_snapshot</tt> and
+      # <tt>assert_rich_snapshot</tt> with the same name, generating <tt>.txt</tt> and <tt>.ansi</tt> files.
+      #
+      # Rich snapshots catch styling bugs that plain text misses. Plain text snapshots are
+      # human-readable in any editor or diff tool, making them valuable for documentation and
+      # code review. Together, they provide comprehensive coverage and discoverability.
+      #
+      #   assert_snapshots("login_screen")
+      #   # Creates/compares: snapshots/login_screen.txt AND snapshots/login_screen.ansi
+      #
+      #   # With normalization (masks dynamic content like timestamps)
+      #   assert_snapshots("dashboard") do |lines|
+      #     lines.map { |l| l.gsub(/\d{2}:\d{2}:\d{2}/, "HH:MM:SS") }
+      #   end
+      #
+      # [name] String snapshot name (without extension).
+      # [msg] String optional failure message.
+      def assert_snapshots(name, msg = nil, &)
+        snapshot_dir = File.join(File.dirname(caller_locations(1, 1).first.path), "snapshots")
+        assert_plain_snapshot(name, msg, snapshot_dir:, &)
+        assert_rich_snapshot(name, msg, snapshot_dir:, &)
+      end
+
       ##
       # Returns the current buffer content as an ANSI-encoded string.
       #

data/lib/ratatui_ruby/test_helper/snapshots/axis_labels_alignment.ansi

@@ -0,0 +1,24 @@
+┌Aligned Chart─────────────────────────────────────────────────────────────────┐
+│10│Value                                                              ┌──────┐│
+│  │                                                                   │TestDS││
+│  │                                                                 ••└──────┘│
+│  │                                                             ••••          │
+│  │                                                         ••••              │
+│  │                                                     ••••                  │
+│  │                                                 ••••                      │
+│  │                                             ••••                          │
+│  │                                         ••••                              │
+│  │                                      •••                                  │
+│ 5│                                  ••••                                     │
+│  │                              ••••                                         │
+│  │                          ••••                                             │
+│  │                      ••••                                                 │
+│  │                  ••••                                                     │
+│  │              ••••                                                         │
+│  │          ••••                                                             │
+│  │      ••••                                                                 │
+│  │  ••••                                                                     │
+│ 0│••                                                                     Time│
+│  └───────────────────────────────────────────────────────────────────────────│
+│ 0                                      5                                   10│
+└──────────────────────────────────────────────────────────────────────────────┘

data/lib/ratatui_ruby/test_helper/snapshots/axis_labels_alignment.txt

@@ -0,0 +1,24 @@
+┌Aligned Chart─────────────────────────────────────────────────────────────────┐
+│10│Value                                                              ┌──────┐│
+│  │                                                                   │TestDS││
+│  │                                                                 ••└──────┘│
+│  │                                                             ••••          │
+│  │                                                         ••••              │
+│  │                                                     ••••                  │
+│  │                                                 ••••                      │
+│  │                                             ••••                          │
+│  │                                         ••••                              │
+│  │                                      •••                                  │
+│ 5│                                  ••••                                     │
+│  │                              ••••                                         │
+│  │                          ••••                                             │
+│  │                      ••••                                                 │
+│  │                  ••••                                                     │
+│  │              ••••                                                         │
+│  │          ••••                                                             │
+│  │      ••••                                                                 │
+│  │  ••••                                                                     │
+│ 0│••                                                                     Time│
+│  └───────────────────────────────────────────────────────────────────────────│
+│ 0                                      5                                   10│
+└──────────────────────────────────────────────────────────────────────────────┘

data/lib/ratatui_ruby/test_helper/snapshots/barchart_styled_label.ansi

@@ -0,0 +1,5 @@
+█████               
+█████               
+█████               
+██5██               
+Group               

data/lib/ratatui_ruby/test_helper/snapshots/barchart_styled_label.txt

@@ -0,0 +1,5 @@
+█████               
+█████               
+█████               
+██5██               
+Group               

data/lib/ratatui_ruby/test_helper/snapshots/chart_rendering.ansi

@@ -0,0 +1,24 @@
+┌Test Chart────────────────────────────────────────────────────────────────────┐
+│10│Value                                                              ┌──────┐│
+│  │                                                                   │TestDS││
+│  │                                                                 ••└──────┘│
+│  │                                                             ••••          │
+│  │                                                         ••••              │
+│  │                                                     ••••                  │
+│  │                                                 ••••                      │
+│  │                                             ••••                          │
+│  │                                         ••••                              │
+│  │                                      •••                                  │
+│  │                                  ••••                                     │
+│  │                              ••••                                         │
+│  │                          ••••                                             │
+│  │                      ••••                                                 │
+│  │                  ••••                                                     │
+│  │              ••••                                                         │
+│  │          ••••                                                             │
+│  │      ••••                                                                 │
+│  │  ••••                                                                     │
+│0 │••                                                                     Time│
+│  └───────────────────────────────────────────────────────────────────────────│
+│  0                                                                         10│
+└──────────────────────────────────────────────────────────────────────────────┘

data/lib/ratatui_ruby/test_helper/snapshots/chart_rendering.txt

@@ -0,0 +1,24 @@
+┌Test Chart────────────────────────────────────────────────────────────────────┐
+│10│Value                                                              ┌──────┐│
+│  │                                                                   │TestDS││
+│  │                                                                 ••└──────┘│
+│  │                                                             ••••          │
+│  │                                                         ••••              │
+│  │                                                     ••••                  │
+│  │                                                 ••••                      │
+│  │                                             ••••                          │
+│  │                                         ••••                              │
+│  │                                      •••                                  │
+│  │                                  ••••                                     │
+│  │                              ••••                                         │
+│  │                          ••••                                             │
+│  │                      ••••                                                 │
+│  │                  ••••                                                     │
+│  │              ••••                                                         │
+│  │          ••••                                                             │
+│  │      ••••                                                                 │
+│  │  ••••                                                                     │
+│0 │••                                                                     Time│
+│  └───────────────────────────────────────────────────────────────────────────│
+│  0                                                                         10│
+└──────────────────────────────────────────────────────────────────────────────┘

data/lib/ratatui_ruby/test_helper/snapshots/half_block_marker.ansi

@@ -0,0 +1,12 @@
+                          ┌──┐
+                         ▄│HB│
+                       ▄▀ └──┘
+                    ▄▀▀       
+                  ▄▀          
+               ▄▀▀            
+            ▄▄▀               
+          ▄▀                  
+       ▄▄▀                    
+     ▄▀                       
+  ▄▄▀                         
+▄▀                            

data/lib/ratatui_ruby/test_helper/snapshots/half_block_marker.txt

@@ -0,0 +1,12 @@
+                          ┌──┐
+                         ▄│HB│
+                       ▄▀ └──┘
+                    ▄▀▀       
+                  ▄▀          
+               ▄▀▀            
+            ▄▄▀               
+          ▄▀                  
+       ▄▄▀                    
+     ▄▀                       
+  ▄▄▀                         
+▄▀                            

data/lib/ratatui_ruby/test_helper/snapshots/legend_position_bottom.ansi

@@ -0,0 +1,12 @@
+                            ••
+                          ••  
+                       •••    
+                    •••       
+                  ••          
+               •••            
+            •••               
+          ••                  
+       •••                    
+    •••      ┌──┐             
+  ••         │DS│             
+••           └──┘             

data/lib/ratatui_ruby/test_helper/snapshots/legend_position_bottom.txt

@@ -0,0 +1,12 @@
+                            ••
+                          ••  
+                       •••    
+                    •••       
+                  ••          
+               •••            
+            •••               
+          ••                  
+       •••                    
+    •••      ┌──┐             
+  ••         │DS│             
+••           └──┘             

data/lib/ratatui_ruby/test_helper/snapshots/legend_position_left.ansi

@@ -0,0 +1,12 @@
+                            ••
+                          ••  
+                       •••    
+                    •••       
+┌──┐              ••          
+│DS│           •••            
+└──┘        •••               
+          ••                  
+       •••                    
+    •••                       
+  ••                          
+••                            

data/lib/ratatui_ruby/test_helper/snapshots/legend_position_left.txt

@@ -0,0 +1,12 @@
+                            ••
+                          ••  
+                       •••    
+                    •••       
+┌──┐              ••          
+│DS│           •••            
+└──┘        •••               
+          ••                  
+       •••                    
+    •••                       
+  ••                          
+••                            

data/lib/ratatui_ruby/test_helper/snapshots/legend_position_right.ansi

@@ -0,0 +1,12 @@
+                            ••
+                          ••  
+                       •••    
+                    •••       
+                  ••      ┌──┐
+               •••        │DS│
+            •••           └──┘
+          ••                  
+       •••                    
+    •••                       
+  ••                          
+••                            

data/lib/ratatui_ruby/test_helper/snapshots/legend_position_right.txt

@@ -0,0 +1,12 @@
+                            ••
+                          ••  
+                       •••    
+                    •••       
+                  ••      ┌──┐
+               •••        │DS│
+            •••           └──┘
+          ••                  
+       •••                    
+    •••                       
+  ••                          
+••