ratatui_ruby 0.4.0 → 0.5.0

data/examples/{quickstart_dsl → verify_quickstart_dsl}/app.rb

@@ -7,7 +7,7 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 
 require "ratatui_ruby"
 
-class QuickstartDslApp
+class VerifyQuickstartDsl
   def run
     # 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
     RatatuiRuby.run do |tui|
@@ -18,19 +18,28 @@ class QuickstartDslApp
           alignment: :center,
           block: tui.block(
             title: "My Ruby TUI App",
+            title_alignment: :center,
             borders: [:all],
-            border_color: "cyan"
+            border_color: "cyan",
+            style: { fg: "white" }
           )
         )
 
         # 3. Use RatatuiRuby methods, too.
-        tui.draw(view)
-        event = tui.poll_event
+        tui.draw do |frame|
+          frame.render_widget(view, frame.area)
+        end
 
-        break if event == "q" || event == :ctrl_c
+        # 4. Poll for events with pattern matching
+        case tui.poll_event
+        in { type: :key, code: "q" }
+          break
+        else
+          # Ignore other events
+        end
       end
     end
   end
 end
 
-QuickstartDslApp.new.run if __FILE__ == $PROGRAM_NAME
+VerifyQuickstartDsl.new.run if __FILE__ == $PROGRAM_NAME

data/examples/verify_quickstart_layout/app.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+
+class VerifyQuickstartLayout
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        tui.draw do |frame|
+          # 1. Split the screen
+          top, bottom = tui.layout_split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              tui.constraint_percentage(75),
+              tui.constraint_percentage(25),
+            ]
+          )
+
+          # 2. Render Top Widget
+          frame.render_widget(
+            tui.paragraph(
+              text: "Hello, Ratatui!",
+              alignment: :center,
+              block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+            ),
+            top
+          )
+
+          # 3. Render Bottom Widget with Styled Text
+          # We use a Line of Spans to style specific characters
+          text_line = tui.text_line(
+            spans: [
+              tui.text_span(content: "Press '"),
+              tui.text_span(
+                content: "q",
+                style: tui.style(modifiers: [:bold, :underlined])
+              ),
+              tui.text_span(content: "' to quit."),
+            ],
+            alignment: :center
+          )
+
+          frame.render_widget(
+            tui.paragraph(
+              text: text_line,
+              block: tui.block(title: "Controls", borders: [:all])
+            ),
+            bottom
+          )
+        end
+
+        case tui.poll_event
+        in { type: :key, code: "q" }
+          break
+        else
+          # Ignore other events
+        end
+      end
+    end
+  end
+end
+
+VerifyQuickstartLayout.new.run if __FILE__ == $PROGRAM_NAME

data/examples/{quickstart_lifecycle → verify_quickstart_lifecycle}/app.rb

@@ -7,33 +7,42 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 
 require "ratatui_ruby"
 
-class QuickstartLifecycleApp
+class VerifyQuickstartLifecycle
   def run
-    # Using the RatatuiRuby.run block for automatic terminal setup/teardown
-    RatatuiRuby.run do |tui|
+    # 1. Initialize the terminal
+    RatatuiRuby.init_terminal
+
+    begin
       # The Main Loop
       loop do
-        # 1. Create your UI (Immediate Mode)
+        # 2. Create your UI (Immediate Mode)
         # We define a Paragraph widget inside a Block with a title and borders.
         view = RatatuiRuby::Paragraph.new(
           text: "Hello, Ratatui! Press 'q' to quit.",
           alignment: :center,
           block: RatatuiRuby::Block.new(
             title: "My Ruby TUI App",
+            title_alignment: :center,
             borders: [:all],
-            border_color: "cyan"
+            border_color: "cyan",
+            style: { fg: "white" }
           )
         )
 
-        # 2. Draw the UI
-        tui.draw(view)
+        # 3. Draw the UI
+        RatatuiRuby.draw do |frame|
+          frame.render_widget(view, frame.area)
+        end
 
-        # 3. Poll for events
+        # 4. Poll for events
         event = RatatuiRuby.poll_event
-        break if event == "q" || event == :ctrl_c
+        break if event.key? && event.code == "q"
       end
+    ensure
+      # 5. Restore the terminal to its original state
+      RatatuiRuby.restore_terminal
     end
   end
 end
 
-QuickstartLifecycleApp.new.run if __FILE__ == $PROGRAM_NAME
+VerifyQuickstartLifecycle.new.run if __FILE__ == $PROGRAM_NAME

data/examples/verify_readme_usage/app.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+class VerifyReadmeUsage
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        tui.draw do |frame|
+          frame.render_widget(
+            tui.paragraph(
+              text: "Hello, Ratatui! Press 'q' to quit.",
+              alignment: :center,
+              block: tui.block(
+                title: "My Ruby TUI App",
+                borders: [:all],
+                border_color: "cyan"
+              )
+            ),
+            frame.area
+          )
+        end
+        event = tui.poll_event
+        break if event == "q" || event == :ctrl_c
+      end
+    end
+  end
+end
+
+VerifyReadmeUsage.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_barchart_demo/app.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Demonstrates categorical data visualization with interactive attribute cycling.
+#
+# Raw tables of numbers are hard to scan. Comparing magnitudes requires mental arithmetic, which slows down decision-making.
+#
+# This demo showcases the <tt>BarChart</tt> widget. It provides an interactive playground where you can cycle through different data formats, styles, and orientations in real-time.
+#
+# Use it to understand how to visualize and compare discrete datasets effectively.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_barchart_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_barchart_demo.png
+class WidgetBarchartDemo
+  def initialize
+    @data_index = 0
+    @styles = nil # Initialized in run
+    @style_index = 0
+    @label_style_index = 0
+    @value_style_index = 0
+    @bar_sets = [
+      { name: "Default", set: nil },
+      { name: "Numbers (Short)", set: { 8 => "8", 7 => "7", 6 => "6", 5 => "5", 4 => "4", 3 => "3", 2 => "2", 1 => "1", 0 => "0" } },
+      { name: "Letters (Long)", set: { full: "H", seven_eighths: "G", three_quarters: "F", five_eighths: "E", half: "D", three_eighths: "C", one_quarter: "B", one_eighth: "A", empty: " " } },
+      { name: "ASCII (Heights)", set: [" ", "_", ".", "-", "=", "+", "*", "#", "@"] },
+    ]
+    @bar_set_index = 0
+    @direction = :vertical
+    @bar_width = 8
+    @bar_gap = 1
+    @group_gap = 0
+    @height_mode = :full
+    @hotkey_style = nil
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      init_styles
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def init_styles
+    @styles = [
+      { name: "Green", style: @tui.style(fg: :green) },
+      { name: "Blue", style: @tui.style(fg: :blue) },
+      { name: "Red", style: @tui.style(fg: :red) },
+      { name: "Cyan", style: @tui.style(fg: :cyan) },
+      { name: "Yellow Bold", style: @tui.style(fg: :yellow, modifiers: [:bold]) },
+      { name: "Reversed", style: @tui.style(modifiers: [:reversed]) },
+    ]
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+  end
+
+  private def current_data
+    case @data_index
+    when 0 # Simple Hash
+      {
+        "Q1" => 50,
+        "Q2" => 80,
+        "Q3" => 45,
+        "Q4" => 60,
+        "Q1'" => 55,
+        "Q2'" => 85,
+        "Q3'" => 50,
+        "Q4'" => 65,
+      }
+    when 1 # Array with styles
+      [
+        ["Mon", 120],
+        ["Tue", 150],
+        ["Wed", 130],
+        ["Thu", 160],
+        ["Fri", 140],
+        ["Sat", 110, @tui.style(fg: :red)],
+        ["Sun", 100, @tui.style(fg: :red)],
+      ]
+    when 2 # Groups
+      [
+        @tui.bar_chart_bar_group(label: "2024", bars: [
+          @tui.bar_chart_bar(value: 40, label: "Q1"),
+          @tui.bar_chart_bar(value: 45, label: "Q2"),
+          @tui.bar_chart_bar(value: 50, label: "Q3"),
+          @tui.bar_chart_bar(value: 55, label: "Q4"),
+        ]),
+        @tui.bar_chart_bar_group(label: "2025", bars: [
+          @tui.bar_chart_bar(value: 60, label: "Q1", style: @tui.style(fg: :yellow)),
+          @tui.bar_chart_bar(value: 65, label: "Q2", style: @tui.style(fg: :yellow)),
+          @tui.bar_chart_bar(value: 70, label: "Q3", style: @tui.style(fg: :yellow)),
+          @tui.bar_chart_bar(value: 75, label: "Q4", style: @tui.style(fg: :yellow)),
+        ]),
+      ]
+    end
+  end
+
+  private def data_name
+    ["Simple Hash", "Styled Array", "Groups"][@data_index]
+  end
+
+  private def render
+    @tui.draw do |frame|
+      chart_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+
+      # Handle Mini Mode
+      effective_chart_area = if @height_mode == :mini
+        mini_area, = @tui.layout_split(
+          chart_area,
+          direction: :vertical,
+          constraints: [
+            @tui.constraint_length(3),
+            @tui.constraint_fill(1),
+          ]
+        )
+        mini_area
+      else
+        chart_area
+      end
+
+      bar_chart = @tui.bar_chart(
+        data: current_data,
+        bar_width: @bar_width,
+        style: @styles[@style_index][:style],
+        bar_gap: @bar_gap,
+        group_gap: @group_gap,
+        direction: @direction,
+        label_style: @styles[@label_style_index][:style],
+        value_style: @styles[@value_style_index][:style],
+        bar_set: @bar_sets[@bar_set_index][:set],
+        block: @tui.block(
+          title: "BarChart Demo: #{data_name}",
+          borders: [:all]
+        )
+      )
+      frame.render_widget(bar_chart, effective_chart_area)
+
+      render_controls(frame, controls_area)
+    end
+  end
+
+  private def render_controls(frame, area)
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            @tui.text_line(spans: [
+              @tui.text_span(content: "d", style: @hotkey_style),
+              @tui.text_span(content: ": Data (#{data_name})  "),
+              @tui.text_span(content: "v", style: @hotkey_style),
+              @tui.text_span(content: ": Direction (#{@direction})  "),
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "w", style: @hotkey_style),
+              @tui.text_span(content: ": Width (#{@bar_width})  "),
+              @tui.text_span(content: "a", style: @hotkey_style),
+              @tui.text_span(content: ": Gap (#{@bar_gap})  "),
+              @tui.text_span(content: "g", style: @hotkey_style),
+              @tui.text_span(content: ": Group Gap (#{@group_gap})"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Style (#{@styles[@style_index][:name]})  "),
+              @tui.text_span(content: "x", style: @hotkey_style),
+              @tui.text_span(content: ": Label (#{@styles[@label_style_index][:name]})  "),
+              @tui.text_span(content: "z", style: @hotkey_style),
+              @tui.text_span(content: ": Value (#{@styles[@value_style_index][:name]})  "),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "b", style: @hotkey_style),
+              @tui.text_span(content: ": Set (#{@bar_sets[@bar_set_index][:name]})  "),
+              @tui.text_span(content: "m", style: @hotkey_style),
+              @tui.text_span(content: ": Mode (#{(@height_mode == :full) ? 'Full' : 'Mini'})"),
+            ]),
+          ]
+        ),
+      ]
+    )
+    frame.render_widget(controls, area)
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "d"
+      @data_index = (@data_index + 1) % 3
+    in type: :key, code: "v"
+      @direction = (@direction == :vertical) ? :horizontal : :vertical
+      # Adjust width default based on direction for better UX, though user can manually adjust 'w'
+      @bar_width = (@direction == :vertical) ? 8 : 1
+    in type: :key, code: "w"
+      @bar_width = (@bar_width % 10) + 1
+    in type: :key, code: "a"
+      @bar_gap = (@bar_gap + 1) % 5
+    in type: :key, code: "g"
+      @group_gap = (@group_gap + 1) % 5
+    in type: :key, code: "s"
+      @style_index = (@style_index + 1) % @styles.size
+    in type: :key, code: "x"
+      @label_style_index = (@label_style_index + 1) % @styles.size
+    in type: :key, code: "z"
+      @value_style_index = (@value_style_index + 1) % @styles.size
+    in type: :key, code: "b"
+      @bar_set_index = (@bar_set_index + 1) % @bar_sets.size
+    in type: :key, code: "m"
+      @height_mode = (@height_mode == :full) ? :mini : :full
+    else
+      # Ignore
+    end
+  end
+end
+
+WidgetBarchartDemo.new.run if __FILE__ == $0

data/examples/{block_padding → widget_block_padding}/app.rb

@@ -7,7 +7,7 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
 # A demo showing Block padding capabilities
-class BlockPaddingApp
+class WidgetBlockPadding
   def run
     RatatuiRuby.run do |tui|
       loop do
@@ -38,18 +38,22 @@ class BlockPaddingApp
           text: "Press 'q' to quit."
         )
 
-        # Layout
-        layout = RatatuiRuby::Layout.new(
-          direction: :vertical,
-          constraints: [
-            RatatuiRuby::Constraint.length(10), # Uniform Padding
-            RatatuiRuby::Constraint.length(10), # Directional Padding
-            RatatuiRuby::Constraint.min(0)
-          ],
-          children: [para1, para2, para3]
-        )
+        tui.draw do |frame|
+          # Layout
+          areas = RatatuiRuby::Layout.split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              RatatuiRuby::Constraint.length(10), # Uniform Padding
+              RatatuiRuby::Constraint.length(10), # Directional Padding
+              RatatuiRuby::Constraint.min(0),
+            ]
+          )
 
-        tui.draw(layout)
+          frame.render_widget(para1, areas[0])
+          frame.render_widget(para2, areas[1])
+          frame.render_widget(para3, areas[2])
+        end
 
         event = tui.poll_event
         break if event == "q" || event == :ctrl_c
@@ -59,5 +63,5 @@ class BlockPaddingApp
 end
 
 if __FILE__ == $0
-  BlockPaddingApp.new.run
+  WidgetBlockPadding.new.run
 end

data/examples/{block_titles → widget_block_titles}/app.rb

@@ -1,10 +1,14 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
 # Initialize the terminal
-class BlockTitlesApp
+class WidgetBlockTitles
   def run
     RatatuiRuby.run do |tui|
       loop do
@@ -13,7 +17,7 @@ class BlockTitlesApp
           tui.block(
             titles: [
               { content: "Top Left", alignment: :left, position: :top },
-              { content: "Top Right", alignment: :right, position: :top }
+              { content: "Top Right", alignment: :right, position: :top },
             ],
             borders: [:all],
             border_color: "cyan"
@@ -22,32 +26,36 @@ class BlockTitlesApp
             titles: [
               { content: "Bottom Left", alignment: :left, position: :bottom },
               { content: "Bottom Center", alignment: :center, position: :bottom },
-              { content: "Bottom Right", alignment: :right, position: :bottom }
+              { content: "Bottom Right", alignment: :right, position: :bottom },
             ],
             borders: [:all],
             border_color: "magenta"
           ),
           tui.block(
             titles: [
-                "Simple String Title (Top Left Default)",
-                { content: "Mixed Title", alignment: :center, position: :bottom }
+              "Simple String Title (Top Left Default)",
+              { content: "Mixed Title", alignment: :center, position: :bottom },
             ],
             borders: [:all],
             border_color: "green"
-          )
+          ),
         ]
 
-        layout = tui.layout(
-          direction: :vertical,
-          constraints: [
-            tui.constraint(:length, 10),
-            tui.constraint(:length, 10),
-            tui.constraint(:length, 10)
-          ],
-          children: blocks
-        )
+        tui.draw do |frame|
+          layout = tui.layout_split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              tui.constraint(:length, 10),
+              tui.constraint(:length, 10),
+              tui.constraint(:length, 10),
+            ]
+          )
 
-        tui.draw(layout)
+          layout.each_with_index do |area, i|
+            frame.render_widget(blocks[i], area) if blocks[i]
+          end
+        end
 
         event = tui.poll_event
         break if event == "q" || event == :ctrl_c
@@ -57,5 +65,5 @@ class BlockTitlesApp
 end
 
 if __FILE__ == $0
-  BlockTitlesApp.new.run
+  WidgetBlockTitles.new.run
 end