ratatui_ruby 0.4.0 → 0.5.0

data/examples/widget_chart_demo/app.rb

@@ -0,0 +1,213 @@
+# 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 Cartesian plotting attributes with interactive cycling.
+#
+# Trends and patterns are invisible in raw logs. You need to see the shape of the data to understand the story it tells.
+#
+# This demo showcases the <tt>Chart</tt> widget. It provides an interactive playground where you can toggle marker types, axis alignments, and legend positions in real-time.
+#
+# Use it to understand how to visualize complex X/Y datasets and trends efficiently.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_chart_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_chart_demo.png
+class WidgetChartDemo
+  MARKERS = [
+    { name: "Dot (·)", marker: :dot },
+    { name: "Braille", marker: :braille },
+    { name: "Block (█)", marker: :block },
+    { name: "Bar", marker: :bar },
+  ].freeze
+
+  X_ALIGNMENTS = [
+    { name: "Left", alignment: :left },
+    { name: "Center", alignment: :center },
+    { name: "Right", alignment: :right },
+  ].freeze
+
+  Y_ALIGNMENTS = [
+    { name: "Left", alignment: :left },
+    { name: "Center", alignment: :center },
+    { name: "Right", alignment: :right },
+  ].freeze
+
+  LEGEND_POSITIONS = [
+    { name: "Top Right", position: :top_right },
+    { name: "Top Left", position: :top_left },
+    { name: "Bottom Right", position: :bottom_right },
+    { name: "Bottom Left", position: :bottom_left },
+  ].freeze
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      init_styles
+
+      @marker_index = 0
+      @dataset_style_index = 0
+      @x_alignment_index = 1
+      @y_alignment_index = 2
+      @legend_position_index = 0
+
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def init_styles
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+    @dataset_styles = [
+      { name: "Yellow", style: @tui.style(fg: :yellow) },
+      { name: "Green", style: @tui.style(fg: :green) },
+      { name: "Cyan", style: @tui.style(fg: :cyan) },
+      { name: "Red", style: @tui.style(fg: :red) },
+      { name: "Magenta", style: @tui.style(fg: :magenta) },
+      { name: "Bold Blue", style: @tui.style(fg: :blue, modifiers: [:bold]) },
+      { name: "Dim White", style: @tui.style(fg: :white, modifiers: [:dim]) },
+      { name: "Italic Green", style: @tui.style(fg: :green, modifiers: [:italic]) },
+      { name: "Alert (Red/White/Bar)", style: @tui.style(fg: :white, bg: :red, modifiers: [:bold]) },
+    ]
+  end
+
+  private def render
+    # Static sample data: sine wave with wider range for better visibility
+    line_data = (0..50).map do |i|
+      x = i / 5.0
+      [x, Math.sin(x)]
+    end
+
+    # Scatter: Random points
+    scatter_data = (0..20).map do |_|
+      [rand(0.0..10.0), rand(-1.0..1.0)]
+    end
+
+    style = @dataset_styles[@dataset_style_index][:style]
+    # Ensure the second dataset has a different style
+    scatter_style = @dataset_styles[(@dataset_style_index + 2) % @dataset_styles.length][:style]
+
+    datasets = [
+      @tui.dataset(
+        name: "Line",
+        data: line_data,
+        style:,
+        marker: (style.modifiers.include?(:bold) && style.bg) ? :bar : MARKERS[@marker_index][:marker],
+        graph_type: :line
+      ),
+      @tui.dataset(
+        name: "Scatter",
+        data: scatter_data,
+        style: scatter_style,
+        marker: (scatter_style.modifiers.include?(:bold) && scatter_style.bg) ? :bar : MARKERS[@marker_index][:marker],
+        graph_type: :scatter
+      ),
+    ]
+
+    chart = @tui.chart(
+      datasets:,
+      x_axis: @tui.axis(
+        title: "Time",
+        bounds: [0.0, 10.0],
+        labels: %w[0 5 10],
+        style: @tui.style(fg: :yellow),
+        labels_alignment: X_ALIGNMENTS[@x_alignment_index][:alignment]
+      ),
+      y_axis: @tui.axis(
+        title: "Amplitude",
+        bounds: [-1.0, 1.0],
+        labels: %w[-1 0 1],
+        style: @tui.style(fg: :cyan),
+        labels_alignment: Y_ALIGNMENTS[@y_alignment_index][:alignment]
+      ),
+      block: @tui.block(
+        title: "Chart Widget Demo",
+        borders: [:all]
+      ),
+      legend_position: LEGEND_POSITIONS[@legend_position_index][:position],
+      hidden_legend_constraints: [
+        @tui.constraint_min(20),
+        @tui.constraint_min(10),
+      ]
+    )
+
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            # Line 1: Markers & Colors
+            @tui.text_line(spans: [
+              @tui.text_span(content: "m", style: @hotkey_style),
+              @tui.text_span(content: ": Marker (#{MARKERS[@marker_index][:name]})  "),
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Style (#{@dataset_styles[@dataset_style_index][:name]})"),
+            ]),
+            # Line 2: Axis alignments
+            @tui.text_line(spans: [
+              @tui.text_span(content: "x", style: @hotkey_style),
+              @tui.text_span(content: ": X Align (#{X_ALIGNMENTS[@x_alignment_index][:name]})  "),
+              @tui.text_span(content: "y", style: @hotkey_style),
+              @tui.text_span(content: ": Y Align (#{Y_ALIGNMENTS[@y_alignment_index][:name]})  "),
+              @tui.text_span(content: "l", style: @hotkey_style),
+              @tui.text_span(content: ": Legend (#{LEGEND_POSITIONS[@legend_position_index][:name]})"),
+            ]),
+            # Line 3: Quit
+            @tui.text_line(spans: [
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+          ]
+        ),
+      ]
+    )
+
+    @tui.draw do |frame|
+      chart_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(5),
+        ]
+      )
+      frame.render_widget(chart, chart_area)
+      frame.render_widget(controls, controls_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: "m"
+      @marker_index = (@marker_index + 1) % MARKERS.length
+    in type: :key, code: "s"
+      @dataset_style_index = (@dataset_style_index + 1) % @dataset_styles.length
+    in type: :key, code: "x"
+      @x_alignment_index = (@x_alignment_index + 1) % X_ALIGNMENTS.length
+    in type: :key, code: "y"
+      @y_alignment_index = (@y_alignment_index + 1) % Y_ALIGNMENTS.length
+    in type: :key, code: "l"
+      @legend_position_index = (@legend_position_index + 1) % LEGEND_POSITIONS.length
+    else
+      nil
+    end
+  end
+end
+
+WidgetChartDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_gauge_demo/app.rb

@@ -0,0 +1,212 @@
+# 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 completion visualization with interactive attribute cycling.
+#
+# Long-running tasks create anxiety. Users need to know that the system is working and how much is left to do.
+#
+# This demo showcases the <tt>Gauge</tt> widget. It provides an interactive playground where you can cycle through different ratios, colors, and label templates in real-time.
+#
+# Use it to understand how to communicate progress and task status in your terminal interface.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_gauge_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_gauge_demo.png
+class WidgetGaugeDemo
+  def initialize
+    @ratio = 0.65
+    @ratios = [0.0, 0.25, 0.5, 0.65, 0.8, 0.95, 1.0]
+    @ratio_index = 3
+
+    @gauge_colors = [
+      { name: "Green", color: :green },
+      { name: "Yellow", color: :yellow },
+      { name: "Red", color: :red },
+      { name: "Cyan", color: :cyan },
+      { name: "Blue", color: :blue },
+    ]
+    @gauge_color_index = 0
+
+    @bg_styles = nil # Initialized in run when @tui is available
+    @bg_style_index = 1
+
+    @use_unicode_options = [true, false]
+    @use_unicode_index = 0
+
+    @label_modes = [
+      { name: "Percentage", template: -> (ratio) { "#{(ratio * 100).to_i}%" } },
+      { name: "Ratio (decimal)", template: -> (ratio) { format("%.2f", ratio) } },
+      { name: "Progress", template: -> (ratio) { "Progress: #{(ratio * 100).to_i}%" } },
+      { name: "None", template: -> (_ratio) { nil } },
+    ]
+    @label_mode_index = 0
+    @hotkey_style = nil # Initialized in run when @tui is available
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+
+      # Initialize styles using tui helpers
+      @bg_styles = [
+        { name: "None", style: nil },
+        { name: "Dark Gray BG", style: tui.style(fg: :dark_gray) },
+        { name: "White on Black", style: tui.style(fg: :white, bg: :black) },
+        { name: "Bold White", style: tui.style(fg: :white, modifiers: [:bold]) },
+      ]
+      @hotkey_style = tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    @ratio = @ratios[@ratio_index]
+    gauge_color = @gauge_colors[@gauge_color_index][:color]
+    bg_style = @bg_styles[@bg_style_index][:style]
+    use_unicode = @use_unicode_options[@use_unicode_index]
+    label_template = @label_modes[@label_mode_index][:template]
+
+    gauge_style = @tui.style(fg: gauge_color)
+    label = label_template.call(@ratio)
+
+    @tui.draw do |frame|
+      # Split into main content and control panel
+      main_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+
+      # Split main area into title, gauges, and spacer
+      title_area, gauge1_area, gauge2_area, gauge3_area, spacer_area = @tui.layout_split(
+        main_area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(1),
+          @tui.constraint_fill(1),
+          @tui.constraint_fill(1),
+          @tui.constraint_fill(1),
+          @tui.constraint_length(1),
+        ]
+      )
+
+      # Render title
+      title = @tui.paragraph(
+        text: "Gauge Widget Demo",
+        style: @tui.style(modifiers: [:bold])
+      )
+      frame.render_widget(title, title_area)
+
+      # Gauge 1: Main interactive gauge
+      gauge1 = @tui.gauge(
+        ratio: @ratio,
+        label:,
+        style: bg_style,
+        gauge_style:,
+        use_unicode:,
+        block: @tui.block(title: "Interactive Gauge")
+      )
+      frame.render_widget(gauge1, gauge1_area)
+
+      # Gauge 2: Inverse ratio for comparison
+      gauge2 = @tui.gauge(
+        ratio: 1.0 - @ratio,
+        label: label_template.call(1.0 - @ratio),
+        style: bg_style,
+        gauge_style:,
+        use_unicode:,
+        block: @tui.block(title: "Inverse (1.0 - ratio)")
+      )
+      frame.render_widget(gauge2, gauge2_area)
+
+      # Gauge 3: Fixed at different stages
+      gauge3 = @tui.gauge(
+        ratio: [@ratio, 0.5].max,
+        label: "Min 50%",
+        style: @tui.style(fg: :dark_gray),
+        gauge_style: @tui.style(fg: :magenta),
+        use_unicode:,
+        block: @tui.block(title: "Min Threshold (Magenta)")
+      )
+      frame.render_widget(gauge3, gauge3_area)
+
+      # Render empty spacer
+      spacer = @tui.paragraph(text: "")
+      frame.render_widget(spacer, spacer_area)
+
+      # Bottom controls panel
+      controls = @tui.block(
+        title: "Controls",
+        borders: [:all],
+        children: [
+          @tui.paragraph(
+            text: [
+              # Navigation & General
+              @tui.text_line(spans: [
+                @tui.text_span(content: "←/→", style: @hotkey_style),
+                @tui.text_span(content: ": Adjust Ratio (#{format('%.2f', @ratio)})  "),
+                @tui.text_span(content: "q", style: @hotkey_style),
+                @tui.text_span(content: ": Quit"),
+              ]),
+              # Styling
+              @tui.text_line(spans: [
+                @tui.text_span(content: "g", style: @hotkey_style),
+                @tui.text_span(content: ": Color (#{@gauge_colors[@gauge_color_index][:name]})  "),
+                @tui.text_span(content: "b", style: @hotkey_style),
+                @tui.text_span(content: ": Background (#{@bg_styles[@bg_style_index][:name]})"),
+              ]),
+              # Options
+              @tui.text_line(spans: [
+                @tui.text_span(content: "u", style: @hotkey_style),
+                @tui.text_span(content: ": Unicode (#{use_unicode ? 'On' : 'Off'})  "),
+                @tui.text_span(content: "l", style: @hotkey_style),
+                @tui.text_span(content: ": Label (#{@label_modes[@label_mode_index][:name]})"),
+              ]),
+            ]
+          ),
+        ]
+      )
+      frame.render_widget(controls, controls_area)
+    end
+  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"
+      @ratio_index = (@ratio_index + 1) % @ratios.length
+    in type: :key, code: "left"
+      @ratio_index = (@ratio_index - 1) % @ratios.length
+    in type: :key, code: "g"
+      @gauge_color_index = (@gauge_color_index + 1) % @gauge_colors.length
+    in type: :key, code: "b"
+      @bg_style_index = (@bg_style_index + 1) % @bg_styles.length
+    in type: :key, code: "u"
+      @use_unicode_index = (@use_unicode_index + 1) % @use_unicode_options.length
+    in type: :key, code: "l"
+      @label_mode_index = (@label_mode_index + 1) % @label_modes.length
+    else
+      # Ignore other events
+      nil
+    end
+  end
+end
+
+WidgetGaugeDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_layout_split/app.rb

@@ -0,0 +1,246 @@
+# 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 dynamic geometry management with interactive cycling.
+#
+# Terminal screens vary in size. Hardcoded positions break when the window resizes. You need a way to organize space dynamically.
+#
+# This demo showcases the <tt>Layout.split</tt> mechanism. It provides an interactive playground where you can toggle directions, all seven flex modes, and various constraint types (Fill, Length, Percentage, Min, Ratio) in real-time.
+#
+# Use it to understand how to build responsive, fluid terminal interfaces that adapt to any window dimensions.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_layout_split/app.rb
+#
+# rdoc-image:/doc/images/widget_layout_split.png
+class WidgetLayoutSplit
+  DIRECTIONS = [
+    { name: "Vertical", value: :vertical },
+    { name: "Horizontal", value: :horizontal },
+  ].freeze
+
+  FLEX_MODES = [
+    { name: "Legacy", value: :legacy },
+    { name: "Start", value: :start },
+    { name: "Center", value: :center },
+    { name: "End", value: :end },
+    { name: "Space Between", value: :space_between },
+    { name: "Space Around", value: :space_around },
+    { name: "Space Evenly", value: :space_evenly },
+  ].freeze
+
+  BLOCK_COLORS = %i[red green blue].freeze
+
+  def initialize
+    @direction_index = 0
+    @flex_index = 0
+    @constraint_index = 0
+    @hotkey_style = nil
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @hotkey_style = tui.style(modifiers: [:bold, :underlined])
+      @constraint_demos = build_constraint_demos
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def build_constraint_demos
+    [
+      {
+        name: "Fill (1:2:1)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_fill(1),
+            @tui.constraint_fill(2),
+            @tui.constraint_fill(1),
+          ]
+        },
+      },
+      {
+        name: "Length (10/15/10)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_length(10),
+            @tui.constraint_length(15),
+            @tui.constraint_length(10),
+          ]
+        },
+      },
+      {
+        name: "Percentage (25/50/25)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_percentage(25),
+            @tui.constraint_percentage(50),
+            @tui.constraint_percentage(25),
+          ]
+        },
+      },
+      {
+        name: "Min (5/10/5)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_min(5),
+            @tui.constraint_min(10),
+            @tui.constraint_min(5),
+          ]
+        },
+      },
+      {
+        name: "Ratio (1:4, 2:4, 1:4)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_ratio(1, 4),
+            @tui.constraint_ratio(2, 4),
+            @tui.constraint_ratio(1, 4),
+          ]
+        },
+      },
+      {
+        name: -> (dir) { (dir == :vertical) ? "Mixed (Len 3, Fill, Pct 25)" : "Mixed (Len 20, Fill, Pct 25)" },
+        constraints: -> (dir) {
+          fixed = (dir == :vertical) ? 3 : 20
+          [
+            @tui.constraint_length(fixed),
+            @tui.constraint_fill(1),
+            @tui.constraint_percentage(25),
+          ]
+        },
+      },
+    ]
+  end
+
+  private def current_direction
+    DIRECTIONS[@direction_index][:value]
+  end
+
+  private def current_flex
+    FLEX_MODES[@flex_index][:value]
+  end
+
+  private def current_constraints
+    demo = @constraint_demos[@constraint_index]
+    demo[:constraints].call(current_direction)
+  end
+
+  private def current_constraint_name
+    demo = @constraint_demos[@constraint_index]
+    name = demo[:name]
+    name.respond_to?(:call) ? name.call(current_direction) : name
+  end
+
+  private def render
+    @tui.draw do |frame|
+      # Split into main content and control panel
+      main_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+
+      render_demo_area(frame, main_area)
+      render_controls(frame, controls_area)
+    end
+  end
+
+  private def render_demo_area(frame, area)
+    # Split demo area into title and content
+    title_area, content_area = @tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_length(1),
+        @tui.constraint_fill(1),
+      ]
+    )
+
+    # Render title
+    title = @tui.paragraph(
+      text: "Layout.split Demo",
+      style: @tui.style(modifiers: [:bold])
+    )
+    frame.render_widget(title, title_area)
+
+    # Apply current layout settings to 3 colored blocks
+    block_areas = @tui.layout_split(
+      content_area,
+      direction: current_direction,
+      flex: current_flex,
+      constraints: current_constraints
+    )
+
+    block_areas.each_with_index do |block_area, i|
+      block = @tui.block(
+        title: "Block #{i + 1}",
+        borders: [:all],
+        border_color: BLOCK_COLORS[i % BLOCK_COLORS.length]
+      )
+      frame.render_widget(block, block_area)
+    end
+  end
+
+  private def render_controls(frame, area)
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            # Row 1: Direction and Flex
+            @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: "f", style: @hotkey_style),
+              @tui.text_span(content: ": Flex (#{FLEX_MODES[@flex_index][:name]})"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "c", style: @hotkey_style),
+              @tui.text_span(content: ": Constraints (#{current_constraint_name})"),
+            ]),
+            # Row 3: Quit
+            @tui.text_line(spans: [
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+          ]
+        ),
+      ]
+    )
+    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"
+      @direction_index = (@direction_index + 1) % DIRECTIONS.length
+    in type: :key, code: "f"
+      @flex_index = (@flex_index + 1) % FLEX_MODES.length
+    in type: :key, code: "c"
+      @constraint_index = (@constraint_index + 1) % @constraint_demos.length
+    else
+      nil
+    end
+  end
+end
+
+WidgetLayoutSplit.new.run if __FILE__ == $PROGRAM_NAME