ratatui_ruby 0.6.0 → 0.7.0

data/lib/ratatui_ruby/tui/widget_factories.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class TUI
+    # Widget factory methods for Session.
+    #
+    # Provides convenient access to all Widgets::* classes without
+    # fully qualifying the class names. This is the largest mixin,
+    # covering all renderable UI components.
+    module WidgetFactories
+      # Creates a Widgets::Block.
+      # @return [Widgets::Block]
+      def block(...)
+        Widgets::Block.new(...)
+      end
+
+      # Creates a Widgets::Paragraph.
+      # @return [Widgets::Paragraph]
+      def paragraph(...)
+        Widgets::Paragraph.new(...)
+      end
+
+      # Creates a Widgets::List.
+      # @return [Widgets::List]
+      def list(...)
+        Widgets::List.new(...)
+      end
+
+      # Creates a Widgets::ListItem.
+      # @return [Widgets::ListItem]
+      def list_item(...)
+        Widgets::ListItem.new(...)
+      end
+
+      # Creates a Widgets::Table.
+      # @return [Widgets::Table]
+      def table(...)
+        Widgets::Table.new(...)
+      end
+
+      # Creates a Widgets::Row (for Table rows).
+      # @return [Widgets::Row]
+      def row(...)
+        Widgets::Row.new(...)
+      end
+
+      # Creates a Widgets::Row (alias for table row).
+      # @return [Widgets::Row]
+      def table_row(...)
+        Widgets::Row.new(...)
+      end
+
+      # Creates a Widgets::Cell (for Table cells).
+      # @return [Widgets::Cell]
+      def table_cell(...)
+        Widgets::Cell.new(...)
+      end
+
+      # Creates a Widgets::Tabs.
+      # @return [Widgets::Tabs]
+      def tabs(...)
+        Widgets::Tabs.new(...)
+      end
+
+      # Creates a Widgets::Gauge.
+      # @return [Widgets::Gauge]
+      def gauge(...)
+        Widgets::Gauge.new(...)
+      end
+
+      # Creates a Widgets::LineGauge.
+      # @return [Widgets::LineGauge]
+      def line_gauge(...)
+        Widgets::LineGauge.new(...)
+      end
+
+      # Creates a Widgets::Sparkline.
+      # @return [Widgets::Sparkline]
+      def sparkline(...)
+        Widgets::Sparkline.new(...)
+      end
+
+      # Creates a Widgets::BarChart.
+      # @return [Widgets::BarChart]
+      def bar_chart(...)
+        Widgets::BarChart.new(...)
+      end
+
+      # Creates a Widgets::BarChart::Bar.
+      # @return [Widgets::BarChart::Bar]
+      def bar(...)
+        Widgets::BarChart::Bar.new(...)
+      end
+
+      # Creates a Widgets::BarChart::BarGroup.
+      # @return [Widgets::BarChart::BarGroup]
+      def bar_group(...)
+        Widgets::BarChart::BarGroup.new(...)
+      end
+
+      # Creates a Widgets::BarChart::Bar (alias).
+      # @return [Widgets::BarChart::Bar]
+      def bar_chart_bar(...)
+        Widgets::BarChart::Bar.new(...)
+      end
+
+      # Creates a Widgets::BarChart::BarGroup (alias).
+      # @return [Widgets::BarChart::BarGroup]
+      def bar_chart_bar_group(...)
+        Widgets::BarChart::BarGroup.new(...)
+      end
+
+      # Creates a Widgets::Chart.
+      # @return [Widgets::Chart]
+      def chart(...)
+        Widgets::Chart.new(...)
+      end
+
+      # Creates a Widgets::Dataset.
+      # @return [Widgets::Dataset]
+      def dataset(...)
+        Widgets::Dataset.new(...)
+      end
+
+      # Creates a Widgets::Axis.
+      # @return [Widgets::Axis]
+      def axis(...)
+        Widgets::Axis.new(...)
+      end
+
+      # Creates a Widgets::Scrollbar.
+      # @return [Widgets::Scrollbar]
+      def scrollbar(...)
+        Widgets::Scrollbar.new(...)
+      end
+
+      # Creates a Widgets::Calendar.
+      # @return [Widgets::Calendar]
+      def calendar(...)
+        Widgets::Calendar.new(...)
+      end
+
+      # Creates a Widgets::Canvas.
+      # @return [Widgets::Canvas]
+      def canvas(...)
+        Widgets::Canvas.new(...)
+      end
+
+      # Creates a Widgets::Clear.
+      # @return [Widgets::Clear]
+      def clear(...)
+        Widgets::Clear.new(...)
+      end
+
+      # Creates a Widgets::Cursor.
+      # @return [Widgets::Cursor]
+      def cursor(...)
+        Widgets::Cursor.new(...)
+      end
+
+      # Creates a Widgets::Overlay.
+      # @return [Widgets::Overlay]
+      def overlay(...)
+        Widgets::Overlay.new(...)
+      end
+
+      # Creates a Widgets::Center.
+      # @return [Widgets::Center]
+      def center(...)
+        Widgets::Center.new(...)
+      end
+
+      # Creates a Widgets::RatatuiLogo.
+      # @return [Widgets::RatatuiLogo]
+      def ratatui_logo(...)
+        Widgets::RatatuiLogo.new(...)
+      end
+
+      # Creates a Widgets::RatatuiMascot.
+      # @return [Widgets::RatatuiMascot]
+      def ratatui_mascot(...)
+        Widgets::RatatuiMascot.new(...)
+      end
+
+      # Creates a Widgets::Shape::Label.
+      # @return [Widgets::Shape::Label]
+      def shape_label(...)
+        Widgets::Shape::Label.new(...)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tui.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "tui/core"
+require_relative "tui/layout_factories"
+require_relative "tui/style_factories"
+require_relative "tui/widget_factories"
+require_relative "tui/text_factories"
+require_relative "tui/state_factories"
+require_relative "tui/canvas_factories"
+require_relative "tui/buffer_factories"
+
+module RatatuiRuby
+  # Manages the terminal lifecycle and provides a concise API for the render loop.
+  #
+  # Writing a TUI loop involves repetitive boilerplate. You constantly instantiate widgets
+  # (<tt>RatatuiRuby::Widgets::Paragraph.new</tt>) and call global methods (<tt>RatatuiRuby.draw</tt>).
+  # This is verbose and hard to read.
+  #
+  # The Session object simplifies this. It acts as a factory and a facade. It provides short helper
+  # methods for every widget and delegates core commands to the main module.
+  #
+  # Use it within <tt>RatatuiRuby.run</tt> to build your interface cleanly.
+  #
+  # == Thread/Ractor Safety
+  #
+  # Session is an *I/O handle*, not a data object. It has side effects (draw,
+  # poll_event) and is intentionally *not* Ractor-shareable. Caching it in
+  # instance variables (<tt>@tui = tui</tt>) during your application's run loop
+  # is fine. However, do not include it in immutable Models/Messages or
+  # pass it to other Ractors.
+  #
+  # == Included Mixins
+  #
+  # [Core] Terminal operations: draw, poll_event, get_cell_at, draw_cell.
+  # [LayoutFactories] Layout helpers: rect, constraint_*, layout, layout_split.
+  # [StyleFactories] Style helpers: style.
+  # [WidgetFactories] Widget creation: block, paragraph, list, table, etc.
+  # [TextFactories] Text helpers: span, line, text_width.
+  # [StateFactories] State objects: list_state, table_state, scrollbar_state.
+  # [CanvasFactories] Canvas shapes: shape_map, shape_line, shape_point, etc.
+  # [BufferFactories] Buffer inspection: cell.
+  #
+  # === Examples
+  #
+  # ==== Basic Usage (Recommended)
+  #
+  #   RatatuiRuby.run do |tui|
+  #     loop do
+  #       tui.draw \
+  #         tui.paragraph \
+  #             text: "Hello, Ratatui! Press 'q' to quit.",
+  #             alignment: :center,
+  #             block: tui.block(
+  #               title: "My Ruby TUI App",
+  #               borders: [:all],
+  #               border_color: "cyan"
+  #             )
+  #       event = tui.poll_event
+  #       break if event == "q" || event == :ctrl_c
+  #     end
+  #   end
+  class TUI
+    include Core
+    include LayoutFactories
+    include StyleFactories
+    include WidgetFactories
+    include TextFactories
+    include StateFactories
+    include CanvasFactories
+    include BufferFactories
+  end
+end

data/lib/ratatui_ruby/version.rb

@@ -6,5 +6,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    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
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    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
+end

data/lib/ratatui_ruby/widgets/bar_chart.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # 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_demo.png}[link:/examples/widget_barchart_demo/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_barchart_demo/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
+    #   )
+    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>]
+      #   List of <tt>BarChart::BarGroup</tt> objects for grouped charts.
+      #
+      # === Examples
+      #
+      # Hash (Simple):
+      #   { "Apples" => 10, :Oranges => 15 }
+      #
+      # Array of Tuples (Ordered):
+      #   [["Mon", 20], ["Tue", 30], ["Wed", 25]]
+      #
+      # BarGroup (Grouped):
+      #   [
+      #     RatatuiRuby::BarChart::BarGroup.new(label: "Q1", bars: [
+      #       RatatuiRuby::BarChart::Bar.new(value: 50, label: "Rev"),
+      #       RatatuiRuby::BarChart::Bar.new(value: 30, label: "Cost")
+      #     ])
+      #   ]
+
+      ##
+      # :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
+      #
+      #   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: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+
+      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
+end