ratatui_ruby 0.4.0 → 0.5.0

data/lib/ratatui_ruby/frame.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Provides access to the terminal buffer for rendering widgets.
+  #
+  # Rendering in immediate-mode TUIs requires knowing the terminal dimensions and
+  # placing widgets at specific positions. Without explicit control, layout
+  # calculations become duplicated between rendering and hit testing.
+  #
+  # This class exposes the terminal frame during a draw call. It provides the
+  # current area and methods to render widgets at precise locations.
+  #
+  # Use it inside a <tt>RatatuiRuby.draw</tt> block to render widgets with full
+  # control over placement.
+  #
+  # === Examples
+  #
+  # Basic usage with a single widget:
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     paragraph = RatatuiRuby::Paragraph.new(text: "Hello, world!")
+  #     frame.render_widget(paragraph, frame.area)
+  #   end
+  #
+  # Using Layout.split for multi-region layouts:
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     sidebar, main = RatatuiRuby::Layout.split(
+  #       frame.area,
+  #       direction: :horizontal,
+  #       constraints: [
+  #         RatatuiRuby::Constraint.length(20),
+  #         RatatuiRuby::Constraint.fill(1)
+  #       ]
+  #     )
+  #
+  #     frame.render_widget(sidebar_widget, sidebar)
+  #     frame.render_widget(main_widget, main)
+  #
+  #     # Store rects for hit testing — no duplication!
+  #     @regions = { sidebar: sidebar, main: main }
+  #   end
+  class Frame
+    ##
+    # :method: area
+    # :call-seq: area() -> Rect
+    #
+    # Returns the full terminal area as a Rect.
+    #
+    # The returned Rect represents the entire drawable area of the terminal.
+    # Use it as the starting point for layout calculations.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     puts "Terminal size: #{frame.area.width}x#{frame.area.height}"
+    #   end
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: render_widget
+    # :call-seq: render_widget(widget, area) -> nil
+    #
+    # Renders a widget at the specified area.
+    #
+    # Widgets in RatatuiRuby are immutable Data objects. This method takes a
+    # widget and a Rect, rendering the widget's content within that region.
+    #
+    # [widget]
+    #   The widget to render (Paragraph, Layout, List, Table, etc.).
+    # [area]
+    #   A Rect specifying where to render the widget.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     para = RatatuiRuby::Paragraph.new(text: "Content")
+    #     frame.render_widget(para, frame.area)
+    #   end
+    #
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/schema/bar_chart/bar.rb

@@ -6,7 +6,7 @@
 module RatatuiRuby
   class BarChart
     # A bar in a grouped bar chart.
-    # 
+    #
     # === Examples
     #
     #   BarChart::Bar.new(value: 10, style: Style.new(fg: :red), label: "A")
@@ -14,32 +14,32 @@ module RatatuiRuby
       ##
       # :attr_reader: value
       # The value of the bar (Integer).
-  
+
       ##
       # :attr_reader: label
       # The label of the bar (optional String).
-  
+
       ##
       # :attr_reader: style
       # The style of the bar (optional Style).
-  
+
       ##
       # :attr_reader: value_style
       # The style of the value (optional Style).
-  
+
       ##
       # :attr_reader: text_value
       # The text to display as the value (optional String).
-  
+
       def initialize(value:, label: nil, style: nil, value_style: nil, text_value: nil)
         super(
           value: Integer(value),
-          label: label,
-          style: style,
-          value_style: value_style,
-          text_value: text_value
+          label:,
+          style:,
+          value_style:,
+          text_value:
         )
       end
     end
   end
-end
+end

data/lib/ratatui_ruby/schema/bar_chart/bar_group.rb

@@ -14,14 +14,10 @@ module RatatuiRuby
       ##
       # :attr_reader: label
       # The label of the group (String).
-  
+
       ##
       # :attr_reader: bars
       # The bars in the group (Array of Bar).
-  
-      def initialize(label:, bars:)
-        super
-      end
     end
   end
 end

data/lib/ratatui_ruby/schema/bar_chart.rb

@@ -4,234 +4,234 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Displays categorical data as bars.
+  # Displays categorical data as bars.
+  #
+  # Raw tables of numbers are hard to scan. Comparing magnitudes requires mental arithmetic, which slows down decision-making.
+  #
+  # This widget visualizes the data. It renders vertical bars proportional to their value.
+  #
+  # Use it to compare server loads, sales figures, or any discrete datasets.
+  #
+  # {rdoc-image:/doc/images/widget_barchart_demo.png}[link:/examples/widget_barchart_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_barchart_demo/app.rb
+  #
+  #   # Grouped Bar Chart
+  #   BarChart.new(
+  #     data: [
+  #       BarGroup.new(label: "Q1", bars: [Bar.new(value: 40), Bar.new(value: 45)]),
+  #       BarGroup.new(label: "Q2", bars: [Bar.new(value: 50), Bar.new(value: 55)])
+  #     ],
+  #     bar_width: 5,
+  #     group_gap: 3
+  #   )
+  class BarChart < Data.define(:data, :bar_width, :bar_gap, :group_gap, :max, :style, :block, :direction, :label_style, :value_style, :bar_set)
+    ##
+    ##
+    ##
+    ##
+    # :attr_reader: data
+    # The data to display.
     #
-    # Raw tables of numbers are hard to scan. Comparing magnitudes requires mental arithmetic, which slows down decision-making.
+    # Supports multiple formats:
+    # [<tt>Hash</tt>]
+    #   Mapping labels (<tt>String</tt> or <tt>Symbol</tt>) to values (<tt>Integer</tt>).
+    # [<tt>Array</tt> of tuples]
+    #   Ordered list of <tt>["Label", Value]</tt> or <tt>["Label", Value, Style]</tt> pairs.
+    # [<tt>Array</tt> of <tt>BarChart::BarGroup</tt>]
+    #   List of <tt>BarChart::BarGroup</tt> objects for grouped charts.
     #
-    # This widget visualizes the data. It renders vertical bars proportional to their value.
+    # === Examples
+    #
+    # Hash (Simple):
+    #   { "Apples" => 10, :Oranges => 15 }
     #
-    # Use it to compare server loads, sales figures, or any discrete datasets.
+    # Array of Tuples (Ordered):
+    #   [["Mon", 20], ["Tue", 30], ["Wed", 25]]
+    #
+    # BarGroup (Grouped):
+    #   [
+    #     RatatuiRuby::BarChart::BarGroup.new(label: "Q1", bars: [
+    #       RatatuiRuby::BarChart::Bar.new(value: 50, label: "Rev"),
+    #       RatatuiRuby::BarChart::Bar.new(value: 30, label: "Cost")
+    #     ])
+    #   ]
+
+    ##
+    # :attr_reader: bar_width
+    # Width of each bar in characters.
+
+    ##
+    # :attr_reader: bar_gap
+    # Spaces between bars.
+
+    ##
+    # :attr_reader: group_gap
+    # Spaces between groups (for grouped bar charts).
+
+    ##
+    # :attr_reader: max
+    # Maximum value for the Y-axis (optional).
+    #
+    # If nil, it is calculated from the data.
+
+    ##
+    # :attr_reader: style
+    # Style for the bars.
+
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
+
+    ##
+    # :attr_reader: label_style
+    # Style for the bar labels (optional).
+
+    ##
+    # :attr_reader: value_style
+    # Style for the bar values (optional).
+
+    ##
+    # :attr_reader: bar_set
+    # Custom characters for the bars (optional).
+    #
+    # A Hash with keys defining the characters for the bars.
+    # Keys: <tt>:empty</tt>, <tt>:one_eighth</tt>, <tt>:one_quarter</tt>, <tt>:three_eighths</tt>, <tt>:half</tt>, <tt>:five_eighths</tt>, <tt>:three_quarters</tt>, <tt>:seven_eighths</tt>, <tt>:full</tt>.
+    #
+    # You can also use integers (0-8) as keys, where 0 is empty, 4 is half, and 8 is full.
+    #
+    # Alternatively, you can pass an Array of 9 strings, where index 0 is empty and index 8 is full.
     #
     # === Examples
     #
-    #   BarChart.new(
-    #     data: { "US" => 40, "EU" => 35, "AP" => 25 },
-    #     bar_width: 5,
-    #     style: Style.new(fg: :green)
-    #   )
+    #   bar_set: {
+    #     empty: " ",
+    #     one_eighth: " ",
+    #     one_quarter: "▂",
+    #     three_eighths: "▃",
+    #     half: "▄",
+    #     five_eighths: "▅",
+    #     three_quarters: "▆",
+    #     seven_eighths: "▇",
+    #     full: "█"
+    #   }
     #
-    #   # Grouped Bar Chart
-    #   BarChart.new(
-    #     data: [
-    #       BarGroup.new(label: "Q1", bars: [Bar.new(value: 40), Bar.new(value: 45)]),
-    #       BarGroup.new(label: "Q2", bars: [Bar.new(value: 50), Bar.new(value: 55)])
-    #     ],
-    #     bar_width: 5,
-    #     group_gap: 3
-    #   )
-    class BarChart < Data.define(:data, :bar_width, :bar_gap, :group_gap, :max, :style, :block, :direction, :label_style, :value_style, :bar_set)
-      ##
-      ##
-      ##
-      ##
-      # :attr_reader: data
-      # The data to display.
-      #
-      # Supports multiple formats:
-      # [<tt>Hash</tt>]
-      #   Mapping labels (<tt>String</tt> or <tt>Symbol</tt>) to values (<tt>Integer</tt>).
-      # [<tt>Array</tt> of tuples]
-      #   Ordered list of <tt>["Label", Value]</tt> or <tt>["Label", Value, Style]</tt> pairs.
-      # [<tt>Array</tt> of <tt>BarChart::BarGroup</tt>]
-      #   List of <tt>BarChart::BarGroup</tt> objects for grouped charts.
-      #
-      # === Examples
-      #
-      # Hash (Simple):
-      #   { "Apples" => 10, :Oranges => 15 }
-      #
-      # Array of Tuples (Ordered):
-      #   [["Mon", 20], ["Tue", 30], ["Wed", 25]]
-      #
-      # BarGroup (Grouped):
-      #   [
-      #     RatatuiRuby::BarChart::BarGroup.new(label: "Q1", bars: [
-      #       RatatuiRuby::BarChart::Bar.new(value: 50, label: "Rev"),
-      #       RatatuiRuby::BarChart::Bar.new(value: 30, label: "Cost")
-      #     ])
-      #   ]
-
-      ##
-      # :attr_reader: bar_width
-      # Width of each bar in characters.
-
-      ##
-      # :attr_reader: bar_gap
-      # Spaces between bars.
-
-      ##
-      # :attr_reader: group_gap
-      # Spaces between groups (for grouped bar charts).
-
-      ##
-      # :attr_reader: max
-      # Maximum value for the Y-axis (optional).
-      #
-      # If nil, it is calculated from the data.
-
-      ##
-      # :attr_reader: style
-      # Style for the bars.
-
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
-
-      ##
-      # :attr_reader: label_style
-      # Style for the bar labels (optional).
-
-      ##
-      # :attr_reader: value_style
-      # Style for the bar values (optional).
-
-      ##
-      # :attr_reader: bar_set
-      # Custom characters for the bars (optional).
-      #
-      # A Hash with keys defining the characters for the bars.
-      # Keys: <tt>:empty</tt>, <tt>:one_eighth</tt>, <tt>:one_quarter</tt>, <tt>:three_eighths</tt>, <tt>:half</tt>, <tt>:five_eighths</tt>, <tt>:three_quarters</tt>, <tt>:seven_eighths</tt>, <tt>:full</tt>.
-      #
-      # You can also use integers (0-8) as keys, where 0 is empty, 4 is half, and 8 is full.
-      #
-      # Alternatively, you can pass an Array of 9 strings, where index 0 is empty and index 8 is full.
-      #
-      # === Examples
-      #
-      #   bar_set: {
-      #     empty: " ",
-      #     one_eighth: " ",
-      #     one_quarter: "▂",
-      #     three_eighths: "▃",
-      #     half: "▄",
-      #     five_eighths: "▅",
-      #     three_quarters: "▆",
-      #     seven_eighths: "▇",
-      #     full: "█"
-      #   }
-      #
-      #   # Numeric keys (0-8)
-      #   bar_set: {
-      #     0 => " ", 1 => " ", 2 => "▂", 3 => "▃", 4 => "▄", 5 => "▅", 6 => "▆", 7 => "▇", 8 => "█"
-      #   }
-      #
-      #   # Array (9 items)
-      #   bar_set: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
-      
-      BAR_KEYS = %i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze
-
-      # Creates a new BarChart widget.
-      #
-      # [data]
-      #   Data to display. Hash, Array of arrays, or Array of BarGroup.
-      # [bar_width]
-      #   Width of each bar (Integer).
-      # [bar_gap]
-      #   Gap between bars (Integer).
-      # [group_gap]
-      #   Gap between groups (Integer).
-      # [max]
-      #   Maximum value of the bar chart (Integer).
-      # [style]
-      #   Base style for the widget (Style).
-      # [block]
-      #   Block to render around the chart (Block).
-      # [direction]
-      #   Direction of the bars (:vertical or :horizontal).
-      # [label_style]
-      #   Style object for labels (optional).
-      # [value_style]
-      #   Style object for values (optional).
-      # [bar_set]
-      #   Hash or Array: Custom characters for the bars.
-      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.is_a?(Array) && bar_set.size == 9
-            # Convert Array to Hash using BAR_KEYS order
-            bar_set = BAR_KEYS.zip(bar_set).to_h
-          else
-            bar_set = bar_set.dup
-            # Normalize numeric keys (0-8) to symbolic keys
-            BAR_KEYS.each_with_index do |key, i|
-              if val = bar_set.delete(i) || bar_set.delete(i.to_s)
-                bar_set[key] = val
-              end
+    #   # Numeric keys (0-8)
+    #   bar_set: {
+    #     0 => " ", 1 => " ", 2 => "▂", 3 => "▃", 4 => "▄", 5 => "▅", 6 => "▆", 7 => "▇", 8 => "█"
+    #   }
+    #
+    #   # Array (9 items)
+    #   bar_set: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+
+    BAR_KEYS = %i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze
+
+    # Creates a new BarChart widget.
+    #
+    # [data]
+    #   Data to display. Hash, Array of arrays, or Array of BarGroup.
+    # [bar_width]
+    #   Width of each bar (Integer).
+    # [bar_gap]
+    #   Gap between bars (Integer).
+    # [group_gap]
+    #   Gap between groups (Integer).
+    # [max]
+    #   Maximum value of the bar chart (Integer).
+    # [style]
+    #   Base style for the widget (Style).
+    # [block]
+    #   Block to render around the chart (Block).
+    # [direction]
+    #   Direction of the bars (:vertical or :horizontal).
+    # [label_style]
+    #   Style object for labels (optional).
+    # [value_style]
+    #   Style object for values (optional).
+    # [bar_set]
+    #   Hash or Array: Custom characters for the bars.
+    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.is_a?(Array) && bar_set.size == 9
+          # Convert Array to Hash using BAR_KEYS order
+          bar_set = BAR_KEYS.zip(bar_set).to_h
+        else
+          bar_set = bar_set.dup
+          # Normalize numeric keys (0-8) to symbolic keys
+          BAR_KEYS.each_with_index do |key, i|
+            if (val = bar_set.delete(i) || bar_set.delete(i.to_s))
+              bar_set[key] = val
             end
           end
         end
+      end
+
+      # Normalize data to Array of BarGroup
+      data = if data.is_a?(Hash)
+        if direction == :horizontal
+          bars = data.map do |label, value|
+            Bar.new(value:, label: label.to_s)
+          end
+          [BarGroup.new(label: "", bars:)]
+        else
+          data.map do |label, value|
+            BarGroup.new(label: label.to_s, bars: [Bar.new(value:)])
+          end
+        end
+      elsif data.is_a?(Array)
+        if data.empty?
+          []
+        elsif data.first.is_a?(BarGroup)
+          data
+        elsif data.first.is_a?(Array)
+          # Tuples
+          if direction == :horizontal
+            bars = data.map do |item|
+              label = item[0].to_s
+              value = item[1]
+              style = item[2]
+
+              bar = Bar.new(value:, label:)
+              bar = bar.with(style:) if style
+              bar
+            end
+            [BarGroup.new(label: "", bars:)]
+          else
+            data.map do |item|
+              label = item[0].to_s
+              value = item[1]
+              style = item[2]
 
-        # Normalize data to Array of BarGroup
-        data = if data.is_a?(Hash)
-                 if direction == :horizontal
-                   bars = data.map do |label, value|
-                     Bar.new(value: value, label: label.to_s)
-                   end
-                   [BarGroup.new(label: "", bars: bars)]
-                 else
-                   data.map do |label, value|
-                     BarGroup.new(label: label.to_s, bars: [Bar.new(value: value)])
-                   end
-                 end
-               elsif data.is_a?(Array)
-                 if data.empty?
-                   []
-                 elsif data.first.is_a?(BarGroup)
-                   data
-                 elsif data.first.is_a?(Array)
-                   # Tuples
-                   if direction == :horizontal
-                     bars = data.map do |item|
-                       label = item[0].to_s
-                       value = item[1]
-                       style = item[2]
-                       
-                       bar = Bar.new(value: value, label: label)
-                       bar = bar.with(style: style) if style
-                       bar
-                     end
-                     [BarGroup.new(label: "", bars: bars)]
-                   else
-                     data.map do |item|
-                       label = item[0].to_s
-                       value = item[1]
-                       style = item[2]
-                       
-                       bar = Bar.new(value: value)
-                       bar = bar.with(style: style) if style
-                       BarGroup.new(label: label, bars: [bar])
-                     end
-                   end
-                 else
-                   # Fallback
-                   data
-                 end
-               else
-                 data
-               end
-
-        super(
-          data: data,
-          bar_width: Integer(bar_width),
-          bar_gap: Integer(bar_gap),
-          group_gap: Integer(group_gap),
-          max: max.nil? ? nil : Integer(max),
-          style: style,
-          block: block,
-          direction: direction,
-          label_style: label_style,
-          value_style: value_style,
-          bar_set: bar_set
-        )
+              bar = Bar.new(value:)
+              bar = bar.with(style:) if style
+              BarGroup.new(label:, bars: [bar])
+            end
+          end
+        else
+          # Fallback
+          data
+        end
+      else
+        data
       end
+
+      super(
+        data:,
+        bar_width: Integer(bar_width),
+        bar_gap: Integer(bar_gap),
+        group_gap: Integer(group_gap),
+        max: max.nil? ? nil : Integer(max),
+        style:,
+        block:,
+        direction:,
+        label_style:,
+        value_style:,
+        bar_set:
+      )
     end
+  end
 end