ratatui_ruby 0.9.0 → 0.10.0

data/doc/troubleshooting/debugging.md

@@ -1,101 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Debugging TUI Applications
-
-TUI applications run in raw terminal mode. stderr and stdout carry terminal escape sequences. Using `puts` or `warn` inside the render loop corrupts the display.
-
-This creates a problem: how do you inspect variables and trace execution?
-
-Write debug output to files. Tail them in a separate terminal.
-
-## File-Based Logging
-
-Create timestamped log files to avoid overwrites:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-FileUtils.mkdir_p(File.join(Dir.tmpdir, "my_debug"))
-timestamp = Time.now.strftime('%Y%m%d_%H%M%S_%N')
-File.write(
-  File.join(Dir.tmpdir, "my_debug", "#{timestamp}.log"),
-  "variable=#{value.inspect}\n"
-)
-```
-<!-- SPDX-SnippetEnd -->
-
-Or append to a single file:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-File.write("/tmp/debug.log", "#{Time.now}: #{message}\n", mode: "a")
-```
-<!-- SPDX-SnippetEnd -->
-
-Tail the logs in a separate terminal:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-# Single file
-tail -f /tmp/debug.log
-
-# Directory of timestamped files
-watch -n 0.5 'ls -la /tmp/my_debug/ && cat /tmp/my_debug/*.log'
-```
-<!-- SPDX-SnippetEnd -->
-
-## REPL Debugging with `__FILE__` Guards
-
-Unit tests verify correctness. But during exploratory debugging, you want to poke at objects interactively. Loading the full TUI just to inspect one object is slow.
-
-Wrap your main execution in a guard:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-if __FILE__ == $PROGRAM_NAME
-  MyApp.new.run
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-Now load the file and interact with classes directly:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby -e 'load "./bin/my_tui"; obj = MyClass.new; sleep 1; puts obj.result'
-```
-<!-- SPDX-SnippetEnd -->
-
-This exercises domain logic without entering raw terminal mode. Use it for exploratory debugging. Write tests using the [TestHelper](application_testing.md) for regression coverage.
-
-## Isolating Terminal Issues
-
-Something works in a `ruby -e` script but fails in the TUI. Common causes:
-
-1. **Thread context.** Ruby threads share the process's terminal state.
-2. **Raw mode.** External commands fail when stdin/stdout are reconfigured.
-3. **SSH/Git auth.** Commands that prompt for credentials hang or return empty.
-
-See [Async Operations](async.md) for solutions.

data/lib/ratatui_ruby/schema/bar_chart/bar.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  class BarChart
-    # A bar in a grouped bar chart.
-    #
-    # === Examples
-    #
-    #   BarChart::Bar.new(value: 10, style: Style.new(fg: :red), label: "A")
-    class Bar < Data.define(:value, :label, :style, :value_style, :text_value)
-      ##
-      # :attr_reader: value
-      # The value of the bar (Integer).
-
-      ##
-      # :attr_reader: label
-      # The label of the bar (optional String, Text::Span, or Text::Line for rich styling).
-
-      ##
-      # :attr_reader: style
-      # The style of the bar (optional Style).
-
-      ##
-      # :attr_reader: value_style
-      # The style of the value (optional Style).
-
-      ##
-      # :attr_reader: text_value
-      # The text to display as the value (optional String, Text::Span, or Text::Line for rich styling).
-
-      def initialize(value:, label: nil, style: nil, value_style: nil, text_value: nil)
-        super(
-          value: Integer(value),
-          label:,
-          style:,
-          value_style:,
-          text_value:
-        )
-      end
-    end
-  end
-end

data/lib/ratatui_ruby/schema/bar_chart/bar_group.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  class BarChart
-    # A group of bars in a grouped bar chart.
-    #
-    # === Examples
-    #
-    #   BarChart::BarGroup.new(label: "Q1", bars: [BarChart::Bar.new(value: 10), BarChart::Bar.new(value: 20)])
-    class BarGroup < Data.define(:label, :bars)
-      ##
-      # :attr_reader: label
-      # The label of the group (String).
-
-      ##
-      # :attr_reader: bars
-      # The bars in the group (Array of Bar).
-    end
-  end
-end

data/lib/ratatui_ruby/schema/bar_chart.rb

@@ -1,287 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Displays categorical data as bars.
-  #
-  # Raw tables of numbers are hard to scan. Comparing magnitudes requires mental arithmetic, which slows down decision-making.
-  #
-  # This widget visualizes the data. It renders vertical bars proportional to their value.
-  #
-  # Use it to compare server loads, sales figures, or any discrete datasets.
-  #
-  # {rdoc-image:/doc/images/widget_barchart.png}[link:/examples/widget_barchart/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2026 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   ruby examples/widget_barchart/app.rb
-  #
-  #   # Grouped Bar Chart
-  #   BarChart.new(
-  #     data: [
-  #       BarGroup.new(label: "Q1", bars: [Bar.new(value: 40), Bar.new(value: 45)]),
-  #       BarGroup.new(label: "Q2", bars: [Bar.new(value: 50), Bar.new(value: 55)])
-  #     ],
-  #     bar_width: 5,
-  #     group_gap: 3
-  #   )
-  #--
-  # SPDX-SnippetEnd
-  #++
-  class BarChart < Data.define(:data, :bar_width, :bar_gap, :group_gap, :max, :style, :block, :direction, :label_style, :value_style, :bar_set)
-    ##
-    ##
-    ##
-    ##
-    # :attr_reader: data
-    # The data to display.
-    #
-    # Supports multiple formats:
-    # [<tt>Hash</tt>]
-    #   Mapping labels (<tt>String</tt> or <tt>Symbol</tt>) to values (<tt>Integer</tt>).
-    # [<tt>Array</tt> of tuples]
-    #   Ordered list of <tt>["Label", Value]</tt> or <tt>["Label", Value, Style]</tt> pairs.
-    # [<tt>Array</tt> of <tt>BarChart::BarGroup</tt>]
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   List of <tt>BarChart::BarGroup</tt> objects for grouped charts.
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # === Examples
-    #
-    # Hash (Simple):
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   { "Apples" => 10, :Oranges => 15 }
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # Array of Tuples (Ordered):
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   [["Mon", 20], ["Tue", 30], ["Wed", 25]]
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # BarGroup (Grouped):
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   [
-    #     RatatuiRuby::BarChart::BarGroup.new(label: "Q1", bars: [
-    #       RatatuiRuby::BarChart::Bar.new(value: 50, label: "Rev"),
-    #       RatatuiRuby::BarChart::Bar.new(value: 30, label: "Cost")
-    #     ])
-    #   ]
-    #--
-    # SPDX-SnippetEnd
-    #++
-
-    ##
-    # :attr_reader: bar_width
-    # Width of each bar in characters.
-
-    ##
-    # :attr_reader: bar_gap
-    # Spaces between bars.
-
-    ##
-    # :attr_reader: group_gap
-    # Spaces between groups (for grouped bar charts).
-
-    ##
-    # :attr_reader: max
-    # Maximum value for the Y-axis (optional).
-    #
-    # If nil, it is calculated from the data.
-
-    ##
-    # :attr_reader: style
-    # Style for the bars.
-
-    ##
-    # :attr_reader: block
-    # Optional wrapping block.
-
-    ##
-    # :attr_reader: label_style
-    # Style for the bar labels (optional).
-
-    ##
-    # :attr_reader: value_style
-    # Style for the bar values (optional).
-
-    ##
-    # :attr_reader: bar_set
-    # Custom characters for the bars (optional).
-    #
-    # A Hash with keys defining the characters for the bars.
-    # Keys: <tt>:empty</tt>, <tt>:one_eighth</tt>, <tt>:one_quarter</tt>, <tt>:three_eighths</tt>, <tt>:half</tt>, <tt>:five_eighths</tt>, <tt>:three_quarters</tt>, <tt>:seven_eighths</tt>, <tt>:full</tt>.
-    #
-    # You can also use integers (0-8) as keys, where 0 is empty, 4 is half, and 8 is full.
-    #
-    # Alternatively, you can pass an Array of 9 strings, where index 0 is empty and index 8 is full.
-    #
-    # === Examples
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   bar_set: {
-    #     empty: " ",
-    #     one_eighth: " ",
-    #     one_quarter: "▂",
-    #     three_eighths: "▃",
-    #     half: "▄",
-    #     five_eighths: "▅",
-    #     three_quarters: "▆",
-    #     seven_eighths: "▇",
-    #     full: "█"
-    #   }
-    #
-    #   # Numeric keys (0-8)
-    #   bar_set: {
-    #     0 => " ", 1 => " ", 2 => "▂", 3 => "▃", 4 => "▄", 5 => "▅", 6 => "▆", 7 => "▇", 8 => "█"
-    #   }
-    #
-    #   # Array (9 items)
-    #   bar_set: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
-    #--
-    # SPDX-SnippetEnd
-    #++
-
-    BAR_KEYS = %i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze
-
-    # Creates a new BarChart widget.
-    #
-    # [data]
-    #   Data to display. Hash, Array of arrays, or Array of BarGroup.
-    # [bar_width]
-    #   Width of each bar (Integer).
-    # [bar_gap]
-    #   Gap between bars (Integer).
-    # [group_gap]
-    #   Gap between groups (Integer).
-    # [max]
-    #   Maximum value of the bar chart (Integer).
-    # [style]
-    #   Base style for the widget (Style).
-    # [block]
-    #   Block to render around the chart (Block).
-    # [direction]
-    #   Direction of the bars (:vertical or :horizontal).
-    # [label_style]
-    #   Style object for labels (optional).
-    # [value_style]
-    #   Style object for values (optional).
-    # [bar_set]
-    #   Hash or Array: Custom characters for the bars.
-    def initialize(data:, bar_width: 3, bar_gap: 1, group_gap: 0, max: nil, style: nil, block: nil, direction: :vertical, label_style: nil, value_style: nil, bar_set: nil)
-      if bar_set
-        if bar_set.is_a?(Array) && bar_set.size == 9
-          # Convert Array to Hash using BAR_KEYS order
-          bar_set = BAR_KEYS.zip(bar_set).to_h
-        else
-          bar_set = bar_set.dup
-          # Normalize numeric keys (0-8) to symbolic keys
-          BAR_KEYS.each_with_index do |key, i|
-            if (val = bar_set.delete(i) || bar_set.delete(i.to_s))
-              bar_set[key] = val
-            end
-          end
-        end
-      end
-
-      # Normalize data to Array of BarGroup
-      data = if data.is_a?(Hash)
-        if direction == :horizontal
-          bars = data.map do |label, value|
-            Bar.new(value:, label: label.to_s)
-          end
-          [BarGroup.new(label: "", bars:)]
-        else
-          data.map do |label, value|
-            BarGroup.new(label: label.to_s, bars: [Bar.new(value:)])
-          end
-        end
-      elsif data.is_a?(Array)
-        if data.empty?
-          []
-        elsif data.first.is_a?(BarGroup)
-          data
-        elsif data.first.is_a?(Array)
-          # Tuples
-          if direction == :horizontal
-            bars = data.map do |item|
-              label = item[0].to_s
-              value = item[1]
-              style = item[2]
-
-              bar = Bar.new(value:, label:)
-              bar = bar.with(style:) if style
-              bar
-            end
-            [BarGroup.new(label: "", bars:)]
-          else
-            data.map do |item|
-              label = item[0].to_s
-              value = item[1]
-              style = item[2]
-
-              bar = Bar.new(value:)
-              bar = bar.with(style:) if style
-              BarGroup.new(label:, bars: [bar])
-            end
-          end
-        else
-          # Fallback
-          data
-        end
-      else
-        data
-      end
-
-      super(
-        data:,
-        bar_width: Integer(bar_width),
-        bar_gap: Integer(bar_gap),
-        group_gap: Integer(group_gap),
-        max: max.nil? ? nil : Integer(max),
-        style:,
-        block:,
-        direction:,
-        label_style:,
-        value_style:,
-        bar_set:
-      )
-    end
-  end
-end

data/lib/ratatui_ruby/schema/block.rb

@@ -1,198 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Defines the visual container for a widget.
-  #
-  # Widgets often float in void. Without boundaries, interfaces become a chaotic mess of text. Users need structure to parse information.
-  #
-  # This widget creates that structure. It wraps content in borders. It labels sections with titles. It paints the background.
-  #
-  # Use blocks to define distinct areas. Group related information. Create a visual hierarchy that guides the user's eye.
-  #
-  # {rdoc-image:/doc/images/widget_box.png}[link:/examples/widget_box/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #   ruby examples/widget_box/app.rb
-  class Block < Data.define(:title, :titles, :title_alignment, :title_style, :borders, :border_style, :border_type, :border_set, :style, :padding, :children)
-    ##
-    # :attr_reader: title
-    # The main title displayed on the top border.
-    #
-    # === Example
-    #
-    #   Block.new(title: "Main").title # => "Main"
-
-    ##
-    # :attr_reader: titles
-    # Additional titles for complex labeling.
-    #
-    # Each title can be a <tt>String</tt> or a <tt>Hash</tt> with keys <tt>:content</tt>, <tt>:alignment</tt>, <tt>:position</tt> (<tt>:top</tt> or <tt>:bottom</tt>), and <tt>:style</tt>.
-    #
-    # === Example
-    #
-    #   Block.new(titles: ["Top", { content: "Bottom", position: :bottom }]).titles
-
-    ##
-    # :attr_reader: title_alignment
-    # Alignment of the main title.
-    #
-    # One of <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
-    #
-    # === Example
-    #
-    #   Block.new(title_alignment: :center).title_alignment # => :center
-
-    ##
-    # :attr_reader: title_style
-    # Style applied to all titles if not overridden.
-    #
-    # === Example
-    #
-    #   Block.new(title_style: Style.new(fg: :red)).title_style
-
-    ##
-    # :attr_reader: borders
-    # Visible borders.
-    #
-    # An array containing any of <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>:right</tt>, or <tt>:all</tt>.
-    #
-    # === Example
-    #
-    #   Block.new(borders: [:left, :right]).borders # => [:left, :right]
-
-    ##
-    # :attr_reader: border_style
-    # Full style (colors/modifiers) for the border lines.
-    #
-    # A Style object or Hash with <tt>:fg</tt>, <tt>:bg</tt>, and <tt>:modifiers</tt>.
-    # This allows borders to be bold, italic, colored, etc.
-
-    ##
-    # :attr_reader: border_type
-    # Visual style of the border lines.
-    #
-    # One of <tt>:plain</tt>, <tt>:rounded</tt>, <tt>:double</tt>, <tt>:thick</tt>, etc.
-
-    ##
-    # :attr_reader: border_set
-    # Custom characters for the border lines.
-    #
-    # A Hash with keys defining the characters for the borders.
-    # Keys: <tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>,
-    # <tt>:vertical_left</tt>, <tt>:vertical_right</tt>, <tt>:horizontal_top</tt>, <tt>:horizontal_bottom</tt>.
-    #
-    # Providing this overrides <tt>border_type</tt>.
-    #
-    #
-    # === Example
-    #
-    #   Block.new(border_set: { top_left: "1", top_right: "2", bottom_left: "3", bottom_right: "4", vertical_left: "5", vertical_right: "6", horizontal_top: "7", horizontal_bottom: "8" })
-
-    ##
-    # :attr_reader: style
-    # Base style (colors/modifiers) for the block content.
-
-    ##
-    # :attr_reader: padding
-    # Inner padding.
-    #
-    # Can be a single <tt>Integer</tt> (uniform) or a 4-element <tt>Array</tt> (left, right, top, bottom).
-    #
-    # === Example
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Block.new(padding: 2).padding # => 2
-    #   Block.new(padding: [1, 1, 0, 0]).padding # => [1, 1, 0, 0]
-    #--
-    # SPDX-SnippetEnd
-    #++
-
-    ##
-    # :attr_reader: children
-    # Widgets to render inside the block (optional).
-    #
-    # When provided, each child widget is rendered within the block's area.
-    #
-    # === Example
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Block.new(
-    #     title: "Content",
-    #     borders: [:all],
-    #     children: [Paragraph.new(text: "Hello")]
-    #   )
-    #--
-    # SPDX-SnippetEnd
-    #++
-
-    # Creates a new Block.
-    #
-    # [title]
-    #   Main title string (optional).
-    # [titles]
-    #   Array of additional titles (optional).
-    # [title_alignment]
-    #   Alignment symbol: <tt>:left</tt> (default), <tt>:center</tt>, <tt>:right</tt>.
-    # [title_style]
-    #   Base style for all titles (optional).
-    # [borders]
-    #   Array of borders to show: <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>:right</tt>, or <tt>:all</tt> (default).
-    # [border_style]
-    #   Style object or Hash for the border lines.
-    # [border_type]
-    #   Symbol: <tt>:plain</tt> (default), <tt>:rounded</tt>, <tt>:double</tt>, <tt>:thick</tt>, <tt>:hidden</tt>, <tt>:quadrant_inside</tt>, <tt>:quadrant_outside</tt>.
-    # [border_set]
-    #   Hash: Custom characters for the border lines. Unique characters are interned (leaked) permanently, so avoid infinite dynamic variations.
-    # [style]
-    #   Style object or Hash for the block's content area.
-    # [padding]
-    #   Integer (uniform) or Array[4] (left, right, top, bottom).
-    # [children]
-    #   Array of widgets to render inside the block (optional).
-    def initialize(title: nil, titles: [], title_alignment: nil, title_style: nil, borders: [:all], border_style: nil, border_type: nil, border_set: nil, style: nil, padding: 0, children: [])
-      if border_set
-        border_set = border_set.dup
-        %i[top_left top_right bottom_left bottom_right vertical_left vertical_right horizontal_top horizontal_bottom].each do |long_key|
-          short_key = long_key.to_s.split("_").map { |s| s[0] }.join
-          if (val = border_set.delete(short_key.to_sym) || border_set.delete(short_key))
-            border_set[long_key] = val
-          end
-        end
-      end
-      coerced_padding = if padding.is_a?(Array)
-        padding.map { |v| Integer(v) }
-      else
-        Integer(padding)
-      end
-      super(
-        title:,
-        titles:,
-        title_alignment:,
-        title_style:,
-        borders:,
-        border_style:,
-        border_type:,
-        border_set:,
-        style:,
-        padding: coerced_padding,
-        children:
-      )
-    end
-  end
-end