ratatui_ruby 0.3.1 → 0.5.0

data/examples/app_table_select/app.rb

@@ -0,0 +1,201 @@
+#!/usr/bin/env ruby
+# 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 "bundler/setup"
+require "ratatui_ruby"
+
+# Sample process data
+PROCESSES = [
+  { pid: 1234, name: "ruby", cpu: 15.2 },
+  { pid: 5678, name: "postgres", cpu: 8.7 },
+  { pid: 9012, name: "nginx", cpu: 3.1 },
+  { pid: 3456, name: "redis", cpu: 12.4 },
+  { pid: 7890, name: "sidekiq", cpu: 22.8 },
+  { pid: 2345, name: "webpack", cpu: 45.3 },
+  { pid: 6789, name: "node", cpu: 18.9 },
+].freeze
+
+class AppTableSelect
+  attr_reader :selected_index, :selected_col, :current_style_index, :column_spacing, :highlight_spacing, :column_highlight_style, :cell_highlight_style
+
+  HIGHLIGHT_SPACINGS = [
+    { name: "When Selected", spacing: :when_selected },
+    { name: "Always", spacing: :always },
+    { name: "Never", spacing: :never },
+  ].freeze
+
+  def initialize
+    @selected_index = 1
+    @selected_col = 1
+    @current_style_index = 0
+    @column_spacing = 1
+    @highlight_spacing_index = 0
+    @show_column_highlight = true
+    @show_cell_highlight = true
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      setup_styles
+      loop do
+        @tui.draw do |frame|
+          render(frame)
+        end
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def setup_styles
+    @styles = [
+      { name: "Cyan", style: @tui.style(fg: :cyan) },
+      { name: "Red", style: @tui.style(fg: :red) },
+      { name: "Green", style: @tui.style(fg: :green) },
+      { name: "Blue on White", style: @tui.style(fg: :blue, bg: :white) },
+      { name: "Magenta", style: @tui.style(fg: :magenta, modifiers: [:bold]) },
+    ]
+    @column_highlight_style = @tui.style(fg: :magenta)
+    @cell_highlight_style = @tui.style(fg: :white, bg: :red, modifiers: [:bold])
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+  end
+
+  private def render(frame)
+    # Create table rows from process data
+    rows = PROCESSES.map { |p| [p[:pid].to_s, p[:name], "#{p[:cpu]}%"] }
+
+    # Define column widths
+    widths = [
+      @tui.constraint_length(8),
+      @tui.constraint_length(15),
+      @tui.constraint_length(10),
+    ]
+
+    # Create highlight style (yellow text)
+    highlight_style = @tui.style(fg: :yellow)
+
+    current_style_entry = @styles[@current_style_index]
+    current_spacing_entry = HIGHLIGHT_SPACINGS[@highlight_spacing_index]
+    selection_label = @selected_index.nil? ? "none" : @selected_index.to_s
+
+    # Main table
+    table = @tui.table(
+      header: ["PID", "Name", "CPU"],
+      rows:,
+      widths:,
+      selected_row: @selected_index,
+      selected_column: @selected_col,
+      highlight_style:,
+      highlight_symbol: "> ",
+      highlight_spacing: current_spacing_entry[:spacing],
+      column_highlight_style: @show_column_highlight ? @column_highlight_style : nil,
+      cell_highlight_style: @show_cell_highlight ? @cell_highlight_style : nil,
+      style: current_style_entry[:style],
+      column_spacing: @column_spacing,
+      block: @tui.block(
+        title: "Processes",
+        borders: :all
+      ),
+      footer: ["Total: #{PROCESSES.length}", "Total CPU: #{PROCESSES.sum { |p| p[:cpu] }}%", ""]
+    )
+
+    # Bottom control panel
+    control_panel = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            # Line 1: Navigation
+            @tui.text_line(spans: [
+              @tui.text_span(content: "↑/↓", style: @hotkey_style),
+              @tui.text_span(content: ": Nav Row  "),
+              @tui.text_span(content: "←/→", style: @hotkey_style),
+              @tui.text_span(content: ": Nav Col  "),
+              @tui.text_span(content: "x", style: @hotkey_style),
+              @tui.text_span(content: ": Toggle Row (#{selection_label})  "),
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+            # Line 2: Table Controls
+            @tui.text_line(spans: [
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Style (#{current_style_entry[:name]})  "),
+              @tui.text_span(content: "p", style: @hotkey_style),
+              @tui.text_span(content: ": Spacing (#{current_spacing_entry[:name]})  "),
+            ]),
+            # Line 3: More Controls
+            @tui.text_line(spans: [
+              @tui.text_span(content: ": Col Space (#{@column_spacing})  "),
+              @tui.text_span(content: "c", style: @hotkey_style),
+              @tui.text_span(content: ": Col Highlight (#{@show_column_highlight ? 'On' : 'Off'})  "),
+              @tui.text_span(content: "z", style: @hotkey_style),
+              @tui.text_span(content: ": Cell Highlight (#{@show_cell_highlight ? 'On' : 'Off'})"),
+            ]),
+          ]
+        ),
+      ]
+    )
+
+    # Layout
+    layout = @tui.layout_split(
+      frame.area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_fill(1),
+        @tui.constraint_length(5),
+      ]
+    )
+
+    frame.render_widget(table, layout[0])
+    frame.render_widget(control_panel, layout[1])
+  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: "down" | "j"
+      @selected_index = ((@selected_index || -1) + 1) % PROCESSES.length
+    in type: :key, code: "up" | "k"
+      @selected_index = (@selected_index || 0) - 1
+      @selected_index = PROCESSES.length - 1 if @selected_index.negative?
+    in type: :key, code: "right" | "l"
+      @selected_col = ((@selected_col || -1) + 1) % 3 # 3 columns
+    in type: :key, code: "left" | "h"
+      # 'h' is already used for highlight spacing, but let's override it or ignore vim keys for left/right?
+      # Actually 'h' is used for spacing in this demo. Let's just use arrows for cols.
+      # Or map 'h' to left if user meant vim keys.
+      # The demo uses 'h' for "Spacing". Let's change Spacing key to 'p' (property/padding?) or something else.
+      # Or just stick to arrows for columns to avoid conflict.
+      @selected_col = (@selected_col || 0) - 1
+      @selected_col = 2 if @selected_col.negative?
+    in type: :key, code: "s"
+      @current_style_index = (@current_style_index + 1) % @styles.length
+    in type: :key, code: "+"
+      @column_spacing += 1
+    in type: :key, code: "-"
+      @column_spacing = [@column_spacing - 1, 0].max
+    in type: :key, code: "p"
+      @highlight_spacing_index = (@highlight_spacing_index + 1) % HIGHLIGHT_SPACINGS.length
+    in type: :key, code: "x"
+      @selected_index = @selected_index.nil? ? 0 : nil
+    in type: :key, code: "c"
+      @show_column_highlight = !@show_column_highlight
+    in type: :key, code: "z"
+      @show_cell_highlight = !@show_cell_highlight
+    else
+      nil
+    end
+  end
+end
+
+if __FILE__ == $0
+  AppTableSelect.new.run
+end

data/examples/verify_quickstart_dsl/app.rb

@@ -0,0 +1,45 @@
+# 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 VerifyQuickstartDsl
+  def run
+    # 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
+    RatatuiRuby.run do |tui|
+      loop do
+        # 2. Create your UI with methods instead of classes.
+        view = tui.paragraph(
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: tui.block(
+            title: "My Ruby TUI App",
+            title_alignment: :center,
+            borders: [:all],
+            border_color: "cyan",
+            style: { fg: "white" }
+          )
+        )
+
+        # 3. Use RatatuiRuby methods, too.
+        tui.draw do |frame|
+          frame.render_widget(view, frame.area)
+        end
+
+        # 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
+
+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/verify_quickstart_lifecycle/app.rb

@@ -0,0 +1,48 @@
+# 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 VerifyQuickstartLifecycle
+  def run
+    # 1. Initialize the terminal
+    RatatuiRuby.init_terminal
+
+    begin
+      # The Main Loop
+      loop do
+        # 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",
+            style: { fg: "white" }
+          )
+        )
+
+        # 3. Draw the UI
+        RatatuiRuby.draw do |frame|
+          frame.render_widget(view, frame.area)
+        end
+
+        # 4. Poll for events
+        event = RatatuiRuby.poll_event
+        break if event.key? && event.code == "q"
+      end
+    ensure
+      # 5. Restore the terminal to its original state
+      RatatuiRuby.restore_terminal
+    end
+  end
+end
+
+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