ratatui_ruby 0.4.0 → 0.5.0

data/examples/widget_sparkline_demo/app.rb

@@ -0,0 +1,274 @@
+# 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 high-density data visualization with interactive attribute cycling.
+#
+# Users need context. A single value ("90% CPU") tells you current status, but not the trend. Full charts take up too much room.
+#
+# This demo showcases the <tt>Sparkline</tt> widget. It provides an interactive playground where you can cycle through data sets, directions, colors, and custom bar sets.
+#
+# Use it to understand how to condense history into a single line for dashboards or headers.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_sparkline_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_sparkline_demo.png
+class WidgetSparklineDemo
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      setup
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def setup
+    # Data sets with different characteristics
+    @data_sets = [
+      {
+        name: "Steady Growth",
+        data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
+      },
+      {
+        name: "With Gaps",
+        data: [5, nil, 8, nil, 6, nil, 9, nil, 7, nil, 10, nil],
+      },
+      {
+        name: "Random",
+        data: [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5, 8],
+      },
+      {
+        name: "Sawtooth",
+        data: [1, 2, 3, 4, 5, 4, 3, 2, 1, 2, 3, 4],
+      },
+      {
+        name: "Peaks",
+        data: [1, 5, 1, 8, 1, 6, 1, 9, 1, 7, 1, 10],
+      },
+    ]
+    @data_index = 0
+
+    @directions = [
+      { name: "Left to Right", direction: :left_to_right },
+      { name: "Right to Left", direction: :right_to_left },
+    ]
+    @direction_index = 0
+
+    @styles = [
+      { name: "Green", style: @tui.style(fg: :green) },
+      { name: "Yellow", style: @tui.style(fg: :yellow) },
+      { name: "Red", style: @tui.style(fg: :red) },
+      { name: "Cyan", style: @tui.style(fg: :cyan) },
+      { name: "Magenta", style: @tui.style(fg: :magenta) },
+    ]
+    @style_index = 0
+
+    @absent_symbols = [
+      { name: "None", symbol: nil },
+      { name: "Dot (·)", symbol: "·" },
+      { name: "Square (▫)", symbol: "▫" },
+      { name: "Dash (-)", symbol: "-" },
+      { name: "Underscore (_)", symbol: "_" },
+    ]
+    @absent_symbol_index = 1
+
+    @absent_styles = [
+      { name: "Default", style: nil },
+      { name: "Dark Gray", style: @tui.style(fg: :dark_gray) },
+      { name: "Dim Red", style: @tui.style(fg: :red, modifiers: [:dim]) },
+      { name: "Dim Yellow", style: @tui.style(fg: :yellow, modifiers: [:dim]) },
+    ]
+    @absent_style_index = 0
+
+    @bar_sets = [
+      { name: "Default (Block)", set: nil },
+      {
+        name: "Numbers (0-8)",
+        set: {
+          0 => "0", 1 => "1", 2 => "2", 3 => "3", 4 => "4", 5 => "5", 6 => "6", 7 => "7", 8 => "8"
+        },
+      },
+      { name: "ASCII (Heights)", set: [" ", "_", ".", "-", "=", "+", "*", "#", "@"] },
+    ]
+    @bar_set_index = 0
+
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+  end
+
+  private def render
+    @tui.draw do |frame|
+      data_set = @data_sets[@data_index]
+      direction = @directions[@direction_index][:direction]
+      style = @styles[@style_index][:style]
+      absent_symbol = @absent_symbols[@absent_symbol_index][:symbol]
+      absent_value_style = @absent_styles[@absent_style_index][:style]
+      bar_set = @bar_sets[@bar_set_index][:set]
+
+      # Use static data for clarity when cycling options
+      current_data = data_set[:data]
+
+      layout = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+
+      # Main content area with multiple sparkline examples
+      main_content_area = layout[0]
+      main_layout = @tui.layout_split(
+        main_content_area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(1),
+          @tui.constraint_length(3),
+          @tui.constraint_length(3),
+          @tui.constraint_length(3),
+          @tui.constraint_length(3),
+          @tui.constraint_fill(1),
+        ]
+      )
+
+      frame.render_widget(
+        @tui.paragraph(text: "Sparkline Widget Demo - Cycle attributes with hotkeys"),
+        main_layout[0]
+      )
+
+      # Sparkline 1: Main interactive sparkline
+      frame.render_widget(
+        @tui.sparkline(
+          data: current_data,
+          direction:,
+          style:,
+          absent_value_symbol: absent_symbol,
+          absent_value_style:,
+          bar_set:,
+          block: @tui.block(title: "Interactive Sparkline")
+        ),
+        main_layout[1]
+      )
+
+      # Sparkline 2: Same data, opposite direction
+      frame.render_widget(
+        @tui.sparkline(
+          data: current_data.reverse,
+          direction:,
+          style:,
+          absent_value_symbol: absent_symbol,
+          absent_value_style:,
+          bar_set:,
+          block: @tui.block(title: "Reversed Data")
+        ),
+        main_layout[2]
+      )
+
+      # Sparkline 3: Without absent value symbol (for comparison)
+      frame.render_widget(
+        @tui.sparkline(
+          data: current_data,
+          direction:,
+          style:,
+          bar_set:,
+          block: @tui.block(title: "Without Absent Marker")
+        ),
+        main_layout[3]
+      )
+
+      # Sparkline 4: Gap pattern responsive to absent marker controls
+      frame.render_widget(
+        @tui.sparkline(
+          data: [5, nil, 8, nil, 6, nil, 9, nil, 7, nil, 10, nil],
+          direction:,
+          style: @tui.style(fg: :blue),
+          absent_value_symbol: absent_symbol,
+          absent_value_style:,
+          bar_set:,
+          block: @tui.block(title: "Gap Pattern (Responsive)")
+        ),
+        main_layout[4]
+      )
+
+      # Bottom control panel
+      control_area = layout[1]
+      frame.render_widget(
+        @tui.block(
+          title: "Controls",
+          borders: [:all],
+          children: [
+            @tui.paragraph(
+              text: [
+                # Line 1: Data
+                @tui.text_line(spans: [
+                  @tui.text_span(content: "↑/↓", style: @hotkey_style),
+                  @tui.text_span(content: ": Data (#{@data_sets[@data_index][:name]})"),
+                ]),
+                # Line 2: View
+                @tui.text_line(spans: [
+                  @tui.text_span(content: "d", style: @hotkey_style),
+                  @tui.text_span(content: ": Direction (#{@directions[@direction_index][:name]})  "),
+                  @tui.text_span(content: "c", style: @hotkey_style),
+                  @tui.text_span(content: ": Color (#{@styles[@style_index][:name]})"),
+                ]),
+                # Line 3: Markers
+                @tui.text_line(spans: [
+                  @tui.text_span(content: "m", style: @hotkey_style),
+                  @tui.text_span(content: ": Absent Value Symbol (#{@absent_symbols[@absent_symbol_index][:name]})  "),
+                  @tui.text_span(content: "s", style: @hotkey_style),
+                  @tui.text_span(content: ": Absent Value Style (#{@absent_styles[@absent_style_index][:name]})"),
+                ]),
+                # Line 4: General
+                @tui.text_line(spans: [
+                  @tui.text_span(content: "b", style: @hotkey_style),
+                  @tui.text_span(content: ": Bar Set (#{@bar_sets[@bar_set_index][:name]})  "),
+                  @tui.text_span(content: "q", style: @hotkey_style),
+                  @tui.text_span(content: ": Quit"),
+                ]),
+              ]
+            ),
+          ]
+        ),
+        control_area
+      )
+    end
+  end
+
+  private def handle_input
+    event = @tui.poll_event
+
+    case event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "up"
+      @data_index = (@data_index - 1) % @data_sets.length
+    in type: :key, code: "down"
+      @data_index = (@data_index + 1) % @data_sets.length
+    in type: :key, code: "d"
+      @direction_index = (@direction_index + 1) % @directions.length
+    in type: :key, code: "c"
+      @style_index = (@style_index + 1) % @styles.length
+    in type: :key, code: "m"
+      @absent_symbol_index = (@absent_symbol_index + 1) % @absent_symbols.length
+    in type: :key, code: "s"
+      @absent_style_index = (@absent_style_index + 1) % @absent_styles.length
+    in type: :key, code: "b"
+      @bar_set_index = (@bar_set_index + 1) % @bar_sets.length
+    else
+      nil
+    end
+  end
+end
+
+WidgetSparklineDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_style_colors/app.rb

@@ -6,7 +6,7 @@
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
-class ColorGradientDemo
+class WidgetStyleColors
   def initialize
     @width = 80
     @height = 24
@@ -15,16 +15,16 @@ class ColorGradientDemo
   def run
     RatatuiRuby.run do |tui|
       loop do
-        render(tui)
+        tui.draw do |frame|
+          frame.render_widget(render(tui), frame.area)
+        end
         event = tui.poll_event
-        break if event&.key? && (event.ctrl_c? || event == :q)
+        break if event.key? && (event.ctrl_c? || event == :q)
       end
     end
   end
 
-  private
-
-  def render(tui)
+  private def render(tui)
     lines = []
 
     (0...@height).each do |row|
@@ -43,10 +43,10 @@ class ColorGradientDemo
         spans << span
       end
 
-      lines << tui.text_line(spans: spans)
+      lines << tui.text_line(spans:)
     end
 
-    paragraph = tui.paragraph(
+    tui.paragraph(
       text: lines,
       block: tui.block(
         title: "Hex Color Gradient (Press 'q' or Ctrl+C to exit)",
@@ -54,11 +54,9 @@ class ColorGradientDemo
         border_type: :rounded
       )
     )
-
-    tui.draw(paragraph)
   end
 
-  def hsl_to_rgb(hue, saturation, lightness)
+  private def hsl_to_rgb(hue, saturation, lightness)
     h = hue / 360.0
     s = saturation / 100.0
     l = lightness / 100.0
@@ -66,39 +64,39 @@ class ColorGradientDemo
     if s == 0
       r = g = b = l
     else
-      q = l < 0.5 ? l * (1 + s) : l + s - (l * s)
-      p = 2 * l - q
+      q = (l < 0.5) ? l * (1 + s) : l + s - (l * s)
+      p = (2 * l) - q
 
-      r = hue_to_rgb(p, q, h + 1.0 / 3.0)
+      r = hue_to_rgb(p, q, h + (1.0 / 3.0))
       g = hue_to_rgb(p, q, h)
-      b = hue_to_rgb(p, q, h - 1.0 / 3.0)
+      b = hue_to_rgb(p, q, h - (1.0 / 3.0))
     end
 
     [
       (r * 255).round,
       (g * 255).round,
-      (b * 255).round
+      (b * 255).round,
     ]
   end
 
-  def hue_to_rgb(p, q, t)
+  private def hue_to_rgb(p, q, t)
     t += 1 while t < 0
     t -= 1 while t > 1
 
     if t < 1.0 / 6.0
-      p + (q - p) * 6 * t
+      p + ((q - p) * 6 * t)
     elsif t < 1.0 / 2.0
       q
     elsif t < 2.0 / 3.0
-      p + (q - p) * (2.0 / 3.0 - t) * 6
+      p + ((q - p) * ((2.0 / 3.0) - t) * 6)
     else
       p
     end
   end
 
-  def rgb_to_hex(rgb)
+  private def rgb_to_hex(rgb)
     "##{rgb.map { |c| c.to_s(16).upcase.rjust(2, '0') }.join}"
   end
 end
 
-ColorGradientDemo.new.run if __FILE__ == $PROGRAM_NAME
+WidgetStyleColors.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_table_flex/app.rb

@@ -0,0 +1,95 @@
+# 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 structured data layout with flexible column distribution.
+#
+# Data is often multidimensional. You need to show relationships between fields (Name, Age, ID). Aligning columns manually in a monospaced environment is painful and error-prone.
+#
+# This demo showcases the <tt>Table</tt> widget's flex modes. It renders multiple tables demonstrating how data is distributed across the available space using <tt>:legacy</tt>, <tt>:space_between</tt>, and <tt>:space_around</tt> settings.
+#
+# Use it to understand how to build perfectly aligned grids for database records, logs, or file lists.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_table_flex/app.rb
+#
+# rdoc-image:/doc/images/widget_table_flex.png
+class WidgetTableFlex
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        render(tui)
+        break if handle_input(tui) == :quit
+      end
+    end
+  end
+
+  def render(tui)
+    tui.draw do |frame|
+      chunks = tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          tui.constraint_length(3),
+          tui.constraint_fill(1),
+          tui.constraint_fill(1),
+          tui.constraint_fill(1),
+        ]
+      )
+
+      frame.render_widget(
+        tui.paragraph(
+          text: "Table Flex Layout (press 'q' to quit)",
+          block: tui.block(title: "Header", borders: [:all])
+        ),
+        chunks[0]
+      )
+
+      frame.render_widget(
+        tui.table(
+          header: ["Legacy (Default)", "Table"],
+          rows: [["Item 1", "Item 2"], ["Item 3", "Item 4"]],
+          widths: [tui.constraint_length(20), tui.constraint_length(20)],
+          block: tui.block(title: "Flex: :legacy (Default)", borders: [:all])
+        ),
+        chunks[1]
+      )
+
+      frame.render_widget(
+        tui.table(
+          header: ["Space", "Between"],
+          rows: [["A", "B"], ["C", "D"]],
+          widths: [tui.constraint_length(20), tui.constraint_length(20)],
+          block: tui.block(title: "Flex: :space_between", borders: [:all]),
+          flex: :space_between
+        ),
+        chunks[2]
+      )
+
+      frame.render_widget(
+        tui.table(
+          header: ["Space", "Around"],
+          rows: [["E", "F"], ["G", "H"]],
+          widths: [tui.constraint_length(20), tui.constraint_length(20)],
+          block: tui.block(title: "Flex: :space_around", borders: [:all]),
+          flex: :space_around
+        ),
+        chunks[3]
+      )
+    end
+  end
+
+  def handle_input(tui)
+    event = tui.poll_event
+    :quit if event == "q" || event == :ctrl_c
+  end
+end
+
+WidgetTableFlex.new.run if __FILE__ == $0

data/examples/widget_tabs_demo/app.rb

@@ -0,0 +1,167 @@
+# 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 view segregation with interactive tab navigation.
+#
+# Screen real estate is limited. You cannot show everything at once. Segregating content into views is necessary for complex apps.
+#
+# This demo showcases the <tt>Tabs</tt> widget. It provides an interactive playground where you can select tabs, cycle through dividers and styles, and adjust padding in real-time.
+#
+# Use it to understand how to build major mode switches or context navigation for your interface.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_tabs_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_tabs_demo.png
+class WidgetTabsDemo
+  def initialize
+    @selected_tab = 0
+    @tabs = ["Revenue", "Traffic", "Errors", "Quarterly"]
+    @highlight_styles = nil
+    @highlight_style_index = 0
+    @divider_index = 0
+    @dividers = [" | ", " • ", " > ", " / "]
+    @base_styles = nil
+    @base_style_index = 0
+    @padding_left = 0
+    @padding_right = 0
+    @width_constraint_index = 0
+    @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
+    @highlight_styles = [
+      { name: "Yellow Bold", style: @tui.style(fg: :yellow, modifiers: [:bold]) },
+      { name: "Italic Blue on White", style: @tui.style(fg: :blue, bg: :white, modifiers: [:italic]) },
+      { name: "Underlined Red", style: @tui.style(fg: :red, modifiers: [:underlined]) },
+      { name: "Reversed", style: @tui.style(modifiers: [:reversed]) },
+    ]
+    @base_styles = [
+      { name: "Default", style: nil },
+      { name: "White on Gray", style: @tui.style(fg: :white, bg: :dark_gray) },
+      { name: "White on Blue", style: @tui.style(fg: :white, bg: :blue) },
+      { name: "Italic", style: @tui.style(modifiers: [:italic]) },
+    ]
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+  end
+
+  private def render
+    @tui.draw do |frame|
+      main_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(5),
+        ]
+      )
+
+      # Center the tabs vertically in the main area
+      tabs_area, = @tui.layout_split(
+        main_area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(3),
+        ]
+      )
+
+      tabs = @tui.tabs(
+        titles: @tabs,
+        selected_index: @selected_tab,
+        block: @tui.block(title: "Tabs Demo", borders: [:all]),
+        divider: @dividers[@divider_index],
+        highlight_style: @highlight_styles[@highlight_style_index][:style],
+        style: @base_styles[@base_style_index][:style],
+        padding_left: @padding_left,
+        padding_right: @padding_right
+      )
+      frame.render_widget(tabs, tabs_area)
+
+      render_controls(frame, controls_area, tabs.width)
+    end
+  end
+
+  private def render_controls(frame, area, current_width)
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            @tui.text_line(spans: [
+              @tui.text_span(content: "←/→", style: @hotkey_style),
+              @tui.text_span(content: ": Select Tab  "),
+              @tui.text_span(content: "h/l", style: @hotkey_style),
+              @tui.text_span(content: ": Pad Left (#{@padding_left})  "),
+              @tui.text_span(content: "j/k", style: @hotkey_style),
+              @tui.text_span(content: ": Pad Right (#{@padding_right})  "),
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "d", style: @hotkey_style),
+              @tui.text_span(content: ": Divider (#{@dividers[@divider_index]})  "),
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Highlight (#{@highlight_styles[@highlight_style_index][:name]})  "),
+              @tui.text_span(content: "b", style: @hotkey_style),
+              @tui.text_span(content: ": Base Style (#{@base_styles[@base_style_index][:name]})  "),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "Width: #{current_width}"),
+            ]),
+          ]
+        ),
+      ]
+    )
+    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: "right"
+      @selected_tab = (@selected_tab + 1) % @tabs.size
+    in type: :key, code: "left"
+      @selected_tab = (@selected_tab - 1) % @tabs.size
+    in type: :key, code: "d"
+      @divider_index = (@divider_index + 1) % @dividers.size
+    in type: :key, code: "s"
+      @highlight_style_index = (@highlight_style_index + 1) % @highlight_styles.size
+    in type: :key, code: "b"
+      @base_style_index = (@base_style_index + 1) % @base_styles.size
+    in type: :key, code: "h"
+      @padding_left = [@padding_left - 1, 0].max
+    in type: :key, code: "l"
+      @padding_left += 1
+    in type: :key, code: "j"
+      @padding_right = [@padding_right - 1, 0].max
+    in type: :key, code: "k"
+      @padding_right += 1
+    else
+      # Ignore other events
+    end
+  end
+end
+
+WidgetTabsDemo.new.run if __FILE__ == $0

data/ext/ratatui_ruby/Cargo.lock

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

data/ext/ratatui_ruby/Cargo.toml

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