ratatui_ruby 0.3.1 → 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

@@ -0,0 +1,102 @@
+# 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 WidgetStyleColors
+  def initialize
+    @width = 80
+    @height = 24
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        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)
+      end
+    end
+  end
+
+  private def render(tui)
+    lines = []
+
+    (0...@height).each do |row|
+      spans = []
+      (0...@width).each do |col|
+        hue = (col.to_f / @width) * 360.0
+        lightness = 50.0 - ((row.to_f / @height) * 50.0)
+
+        rgb = hsl_to_rgb(hue, 100.0, lightness)
+        hex = rgb_to_hex(rgb)
+
+        span = tui.text_span(
+          content: " ",
+          style: tui.style(bg: hex)
+        )
+        spans << span
+      end
+
+      lines << tui.text_line(spans:)
+    end
+
+    tui.paragraph(
+      text: lines,
+      block: tui.block(
+        title: "Hex Color Gradient (Press 'q' or Ctrl+C to exit)",
+        borders: [:all],
+        border_type: :rounded
+      )
+    )
+  end
+
+  private def hsl_to_rgb(hue, saturation, lightness)
+    h = hue / 360.0
+    s = saturation / 100.0
+    l = lightness / 100.0
+
+    if s == 0
+      r = g = b = l
+    else
+      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))
+      g = hue_to_rgb(p, q, h)
+      b = hue_to_rgb(p, q, h - (1.0 / 3.0))
+    end
+
+    [
+      (r * 255).round,
+      (g * 255).round,
+      (b * 255).round,
+    ]
+  end
+
+  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)
+    elsif t < 1.0 / 2.0
+      q
+    elsif t < 2.0 / 3.0
+      p + ((q - p) * ((2.0 / 3.0) - t) * 6)
+    else
+      p
+    end
+  end
+
+  private def rgb_to_hex(rgb)
+    "##{rgb.map { |c| c.to_s(16).upcase.rjust(2, '0') }.join}"
+  end
+end
+
+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