ratatui_ruby 0.7.2 → 0.7.4

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

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

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

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

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

@@ -0,0 +1 @@
+Snapshot Content

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

@@ -0,0 +1,10 @@
+                                   ┌───┐
+                                 ••│DS1│
+                             ••••  └───┘
+                        •••••           
+                    ••••                
+                ••••                    
+           •••••                        
+       ••••                             
+   ••••                                 
+•••                           StyledTime

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

@@ -0,0 +1,10 @@
+                                   ┌───┐
+                                 ••│DS1│
+                             ••••  └───┘
+                        •••••           
+                    ••••                
+                ••••                    
+           •••••                        
+       ••••                             
+   ••••                                 
+•••                           StyledTime

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

@@ -0,0 +1,10 @@
+                              ┌────────┐
+                              │StyledDS│
+                             •└────────┘
+                        •••••           
+                    ••••                
+                ••••                    
+           •••••                        
+       ••••                             
+   ••••                                 
+•••                                     

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

@@ -0,0 +1,10 @@
+                              ┌────────┐
+                              │StyledDS│
+                             •└────────┘
+                        •••••           
+                    ••••                
+                ••••                    
+           •••••                        
+       ••••                             
+   ••••                                 
+•••                                     

data/lib/ratatui_ruby/test_helper/terminal.rb

@@ -48,6 +48,9 @@ module RatatuiRuby
       #     # render and test your app
       #   end
       def with_test_terminal(width = 80, height = 24, **opts)
+        # Defensive cleanup: reset any stale session state from previous test failures
+        RatatuiRuby.instance_variable_set(:@tui_session_active, false)
+
         RatatuiRuby.init_test_terminal(width, height)
         # Flush any lingering events from previous tests
         while (event = RatatuiRuby.poll_event) && !event.none?; end

data/lib/ratatui_ruby/test_helper.rb

@@ -41,7 +41,7 @@ module RatatuiRuby
   #     def test_initial_render
   #       with_test_terminal(80, 24) do
   #         MyApp.new.run_once
-  #         assert_snapshot("initial")
+  #         assert_snapshots("initial")
   #       end
   #     end
   #

data/lib/ratatui_ruby/version.rb

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

data/lib/ratatui_ruby/widgets/bar_chart.rb

@@ -156,9 +156,10 @@ module RatatuiRuby
       # [value_style]
       #   Style object for values (optional).
       # [bar_set]
-      #   Hash or Array: Custom characters for the bars.
+      #   Symbol, Hash, or Array: Custom characters for bars.
+      #   Symbols: <tt>:nine_levels</tt> (default gradient), <tt>:three_levels</tt> (simplified).
       def initialize(data:, bar_width: 3, bar_gap: 1, group_gap: 0, max: nil, style: nil, block: nil, direction: :vertical, label_style: nil, value_style: nil, bar_set: nil)
-        if bar_set
+        if bar_set && !bar_set.is_a?(Symbol)
           if bar_set.is_a?(Array) && bar_set.size == 9
             # Convert Array to Hash using BAR_KEYS order
             bar_set = BAR_KEYS.zip(bar_set).to_h

data/lib/ratatui_ruby/widgets/block.rb

@@ -189,6 +189,48 @@ module RatatuiRuby
           children:
         )
       end
+
+      # Computes the inner content area given an outer area.
+      #
+      # This method calculates where content should be placed within a block,
+      # accounting for borders and padding. Essential for layout calculations
+      # when you need to know the usable space inside a block.
+      #
+      # === Example
+      #
+      #   block = Block.new(borders: [:all], padding: 1)
+      #   outer = Layout::Rect.new(x: 0, y: 0, width: 20, height: 10)
+      #   inner = block.inner(outer)
+      #   # => Rect(x: 2, y: 2, width: 16, height: 6)
+      #
+      # [area]
+      #   The outer Rect to compute the inner area for.
+      #
+      # Returns a new Rect representing the inner content area.
+      def inner(area)
+        # Calculate border offsets
+        has_border = -> (side) { borders.include?(:all) || borders.include?(side) }
+        left_border = has_border.call(:left) ? 1 : 0
+        right_border = has_border.call(:right) ? 1 : 0
+        top_border = has_border.call(:top) ? 1 : 0
+        bottom_border = has_border.call(:bottom) ? 1 : 0
+
+        # Calculate padding offsets
+        if padding.is_a?(Array)
+          # [left, right, top, bottom]
+          pad_left, pad_right, pad_top, pad_bottom = padding
+        else
+          pad_left = pad_right = pad_top = pad_bottom = padding
+        end
+
+        # Compute inner area
+        new_x = area.x + left_border + pad_left
+        new_y = area.y + top_border + pad_top
+        new_width = [area.width - left_border - right_border - pad_left - pad_right, 0].max
+        new_height = [area.height - top_border - bottom_border - pad_top - pad_bottom, 0].max
+
+        Layout::Rect.new(x: new_x, y: new_y, width: new_width, height: new_height)
+      end
     end
   end
 end

data/lib/ratatui_ruby/widgets/chart.rb

@@ -56,7 +56,7 @@ module RatatuiRuby
     # [name] The name of the dataset.
     # [data] Array of arrays [[x, y], [x, y]] (Floats).
     # [style] The style of the line.
-    # [marker] Symbol (<tt>:dot</tt>, <tt>:braille</tt>, <tt>:block</tt>, <tt>:bar</tt>)
+    # [marker] Symbol (<tt>:dot</tt>, <tt>:braille</tt>, <tt>:block</tt>, <tt>:bar</tt>, <tt>:half_block</tt>)
     # [graph_type] Symbol (<tt>:line</tt>, <tt>:scatter</tt>)
     class Dataset < Data.define(:name, :data, :style, :marker, :graph_type)
       ##
@@ -81,7 +81,9 @@ module RatatuiRuby
 
       ##
       # :attr_reader: marker
-      # Marker type (<tt>:dot</tt>, <tt>:braille</tt>).
+      # Marker type (<tt>:dot</tt>, <tt>:braille</tt>, <tt>:block</tt>, <tt>:bar</tt>, <tt>:half_block</tt>).
+      #
+      # <tt>:half_block</tt> uses ▀ and ▄ characters for higher resolution than <tt>:dot</tt>.
 
       ##
       # :attr_reader: graph_type
@@ -138,7 +140,10 @@ module RatatuiRuby
 
       ##
       # :attr_reader: legend_position
-      # Position of the legend (<tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>).
+      # Position of the legend.
+      #
+      # Corners: <tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>.
+      # Edges: <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>:right</tt>.
 
       ##
       # :attr_reader: hidden_legend_constraints
@@ -151,7 +156,7 @@ module RatatuiRuby
       # [y_axis] Y Axis config.
       # [block] Wrapper (optional).
       # [style] Base style (optional).
-      # [legend_position] Symbol (<tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>).
+      # [legend_position] Symbol — corners: <tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>; edges: <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>:right</tt>.
       # [hidden_legend_constraints] Array of two Constraints [width, height] (optional).
       def initialize(datasets:, x_axis:, y_axis:, block: nil, style: nil, legend_position: nil, hidden_legend_constraints: [])
         super

data/lib/ratatui_ruby/widgets/sparkline.rb

@@ -103,9 +103,10 @@ module RatatuiRuby
       # [direction] +:left_to_right+ or +:right_to_left+ (default: +:left_to_right+).
       # [absent_value_symbol] Character for absent (nil) values (optional).
       # [absent_value_style] Style for absent (nil) values (optional).
-      # [bar_set] Hash or Array of custom characters (optional).
+      # [bar_set] Symbol, Hash, or Array of custom characters (optional).
+      #   Symbols: <tt>:nine_levels</tt> (default gradient), <tt>:three_levels</tt> (simplified).
       def initialize(data:, max: nil, style: nil, block: nil, direction: :left_to_right, absent_value_symbol: nil, absent_value_style: nil, bar_set: nil)
-        if bar_set
+        if bar_set && !bar_set.is_a?(Symbol)
           if bar_set.is_a?(Array) && bar_set.size == 9
             # Convert Array to Hash using BAR_KEYS order
             bar_set = BAR_KEYS.zip(bar_set).to_h

data/lib/ratatui_ruby.rb

@@ -42,13 +42,72 @@ end
 #
 # Use `RatatuiRuby.run` to start your application.
 module RatatuiRuby
-  # Generic error class for RatatuiRuby.
+  # Base error class for RatatuiRuby.
+  #
+  # All library-specific exceptions inherit from this class.
+  # Catch this to handle any RatatuiRuby error generically.
+  #
+  # === Example
+  #
+  #   begin
+  #     RatatuiRuby.run { |tui| ... }
+  #   rescue RatatuiRuby::Error => e
+  #     puts "RatatuiRuby error: #{e.message}"
+  #   end
   class Error < StandardError
-    # Raised when a terminal operation fails (e.g., I/O error, backend failure).
+    # Operational failure during terminal I/O.
+    #
+    # Terminals are finnicky. I/O can fail. Backends can crash.
+    # These are runtime problems outside your control.
+    #
+    # This error signals the terminal operation itself failed.
+    # The library tried to do something with the terminal and couldn't.
+    #
+    # Catch this to handle terminal failures gracefully.
+    #
+    # === Example
+    #
+    #   begin
+    #     RatatuiRuby.init_terminal
+    #   rescue RatatuiRuby::Error::Terminal => e
+    #     puts "Terminal failed: #{e.message}"
+    #   end
     class Terminal < Error; end
 
-    # Raised when an API safety contract is violated (e.g., accessing a Frame outside its valid scope).
+    # Object lifetime violation.
+    #
+    # Some objects are only valid during specific scopes.
+    # Using them after their scope ends causes undefined behavior.
+    #
+    # This error prevents use-after-scope bugs.
+    # The object you're accessing is no longer valid.
+    #
+    # To resolve, ensure scoped objects are used only within their
+    # valid lifetime (e.g., inside the block where they're created).
+    #
+    # === Example
+    #
+    #   stored_frame = nil
+    #   RatatuiRuby.draw { |frame| stored_frame = frame }
+    #   stored_frame.area  # => raises Error::Safety
     class Safety < Error; end
+
+    # State invariant violation.
+    #
+    # The library has rules about valid state transitions.
+    # Calling methods in the wrong order or state breaks invariants.
+    #
+    # This error signals you violated a state machine contract.
+    # The program state doesn't allow this operation right now.
+    #
+    # To resolve, check `terminal_active?` or restructure the
+    # code to ensure methods are called in the expected order.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.init_terminal
+    #   RatatuiRuby.init_terminal  # => raises Error::Invariant
+    class Invariant < Error; end
   end
 
   ##
@@ -58,23 +117,64 @@ module RatatuiRuby
   # [focus_events] whether to enable focus gain/loss events (default: true).
   # [bracketed_paste] whether to enable bracketed paste mode (default: true).
   def self.init_terminal(focus_events: true, bracketed_paste: true)
+    if @tui_session_active
+      raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
+    end
+    @tui_session_active = true
     _init_terminal(focus_events, bracketed_paste)
   end
 
   @experimental_warnings = true
+  @tui_session_active = false
+  @deferred_warnings = []
+
+  ##
+  # Whether a TUI session is currently active.
+  #
+  # Writing to stdout/stderr during a TUI session corrupts the display.
+  # Use this to defer logging, warnings, or debug output until
+  # after the session ends.
+  #
+  # === Example
+  #
+  #   def log(message)
+  #     if RatatuiRuby.terminal_active?
+  #       @deferred_logs << message
+  #     else
+  #       puts message
+  #     end
+  #   end
+  def self.terminal_active?
+    @tui_session_active
+  end
+
   class << self
     ##
     # :attr_accessor: experimental_warnings
     # Whether to show warnings when using experimental features (default: true).
     attr_accessor :experimental_warnings
+
+    private def queue_warning(message)
+      @deferred_warnings << message
+    end
+
+    private def flush_warnings
+      return if @deferred_warnings.empty?
+      @deferred_warnings.each { |msg| warn msg }
+      @deferred_warnings.clear
+    end
   end
 
   ##
-  # :singleton-method: restore_terminal
   # Restores the terminal to its original state.
   # Leaves alternate screen and disables raw mode.
-  #
-  # (Native method implemented in Rust)
+  # Also flushes any deferred warnings that were queued during the session.
+  def self.restore_terminal
+    _restore_terminal
+  ensure
+    @tui_session_active = false
+    flush_warnings
+  end
 
   ##
   # :singleton-method: inject_test_event
@@ -98,12 +198,31 @@ module RatatuiRuby
     @warned_features ||= {}
     return if @warned_features[feature_name]
 
-    warn "WARNING: #{feature_name} is an experimental feature and may change in future versions. Disable this warning with RatatuiRuby.experimental_warnings = false."
+    message = "WARNING: #{feature_name} is an experimental feature and may change in future versions. Disable this warning with RatatuiRuby.experimental_warnings = false."
+    if terminal_active?
+      queue_warning(message)
+    else
+      warn message
+    end
     @warned_features[feature_name] = true
   end
 
-  # (Native method _init_terminal implemented in Rust)
-  private_class_method :_init_terminal
+  ##
+  # Initializes a test terminal for unit testing.
+  # Sets session active state like init_terminal.
+  #
+  # [width] Integer width of the test terminal.
+  # [height] Integer height of the test terminal.
+  def self.init_test_terminal(width, height)
+    if @tui_session_active
+      raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
+    end
+    @tui_session_active = true
+    _init_test_terminal(width, height)
+  end
+
+  # (Native methods implemented in Rust)
+  private_class_method :_init_terminal, :_restore_terminal, :_init_test_terminal
 
   ##
   # Draws the given UI node tree to the terminal.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.7.4
 platform: ruby
 authors:
 - Kerrick Long
@@ -117,6 +117,8 @@ files:
 - doc/contributors/developing_examples.md
 - doc/contributors/documentation_style.md
 - doc/contributors/index.md
+- doc/contributors/upstream_requests/tab_rects.md
+- doc/contributors/upstream_requests/title_rects.md
 - doc/contributors/v1.0.0_blockers.md
 - doc/custom.css
 - doc/getting_started/quickstart.md
@@ -160,6 +162,7 @@ files:
 - doc/migration/v0_7_0.md
 - doc/troubleshooting/debugging.md
 - doc/troubleshooting/terminal_limitations.md
+- doc/troubleshooting/tui_output.md
 - examples/app_all_events/README.md
 - examples/app_all_events/app.rb
 - examples/app_all_events/model/app_model.rb
@@ -351,6 +354,27 @@ files:
 - lib/ratatui_ruby/test_helper.rb
 - lib/ratatui_ruby/test_helper/event_injection.rb
 - lib/ratatui_ruby/test_helper/snapshot.rb
+- lib/ratatui_ruby/test_helper/snapshots/axis_labels_alignment.ansi
+- lib/ratatui_ruby/test_helper/snapshots/axis_labels_alignment.txt
+- lib/ratatui_ruby/test_helper/snapshots/barchart_styled_label.ansi
+- lib/ratatui_ruby/test_helper/snapshots/barchart_styled_label.txt
+- lib/ratatui_ruby/test_helper/snapshots/chart_rendering.ansi
+- lib/ratatui_ruby/test_helper/snapshots/chart_rendering.txt
+- lib/ratatui_ruby/test_helper/snapshots/half_block_marker.ansi
+- lib/ratatui_ruby/test_helper/snapshots/half_block_marker.txt
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_bottom.ansi
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_bottom.txt
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_left.ansi
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_left.txt
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_right.ansi
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_right.txt
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_top.ansi
+- lib/ratatui_ruby/test_helper/snapshots/legend_position_top.txt
+- lib/ratatui_ruby/test_helper/snapshots/my_snapshot.txt
+- lib/ratatui_ruby/test_helper/snapshots/styled_axis_title.ansi
+- lib/ratatui_ruby/test_helper/snapshots/styled_axis_title.txt
+- lib/ratatui_ruby/test_helper/snapshots/styled_dataset_name.ansi
+- lib/ratatui_ruby/test_helper/snapshots/styled_dataset_name.txt
 - lib/ratatui_ruby/test_helper/style_assertions.rb
 - lib/ratatui_ruby/test_helper/terminal.rb
 - lib/ratatui_ruby/test_helper/test_doubles.rb
@@ -531,7 +555,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://sr.ht/~kerrick/ratatui_ruby/
   bug_tracker_uri: https://todo.sr.ht/~kerrick/ratatui_ruby
-  changelog_uri: https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/CHANGELOG.md
+  changelog_uri: https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/CHANGELOG.md
   mailing_list_uri: https://lists.sr.ht/~kerrick/ratatui_ruby-discuss
   source_code_uri: https://git.sr.ht/~kerrick/ratatui_ruby
   documentation_uri: https://git.sr.ht/~kerrick/ratatui_ruby/tree/HEAD/doc/index.md