ratatui_ruby 0.3.1 → 0.5.0

data/lib/ratatui_ruby/schema/bar_chart.rb

@@ -4,25 +4,234 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that displays numeric data as a bar chart.
-  #
-  # [data] A hash of { "Label" => value (Integer) }.
-  # [bar_width] The width of each bar in the chart.
-  # [bar_gap] The gap between bars.
-  # [max] Optional maximum value for the Y-axis.
-  # [style] Optional style for the bars.
-  # [block] Optional block widget to wrap the chart.
-  class BarChart < Data.define(:data, :bar_width, :bar_gap, :max, :style, :block)
+  # 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] A hash of { "Label" => value (Integer) }.
-    # [bar_width] The width of each bar in the chart.
-    # [bar_gap] The gap between bars.
-    # [max] Optional maximum value for the Y-axis.
-    # [style] Optional style for the bars.
-    # [block] Optional block widget to wrap the chart.
-    def initialize(data:, bar_width: 3, bar_gap: 1, max: nil, style: nil, block: nil)
-      super
+    # [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

@@ -4,20 +4,187 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that wraps other widgets with a border and/or a title.
+  # Defines the visual container for a widget.
   #
-  # [title] The title string to display on the border.
-  # [borders] An array of symbols representing which borders to display:
-  #           [:top, :bottom, :left, :right, :all, :none]
-  # [border_color] The color of the border (e.g., "red", "#ff0000").
-  class Block < Data.define(:title, :borders, :border_color)
+  # 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_demo.png}[link:/examples/widget_box_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_box_demo/app.rb
+  class Block < Data.define(:title, :titles, :title_alignment, :title_style, :borders, :border_color, :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_color
+    # Color of the border lines.
+    #
+    # Deprecated: Use <tt>border_style:</tt> instead for full style support.
+
+    ##
+    # :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. If both <tt>border_color</tt>
+    # and <tt>border_style</tt> are provided, <tt>border_style</tt> takes precedence.
+
+    ##
+    # :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
+    #
+    #   Block.new(padding: 2).padding # => 2
+    #   Block.new(padding: [1, 1, 0, 0]).padding # => [1, 1, 0, 0]
+
+    ##
+    # :attr_reader: children
+    # Widgets to render inside the block (optional).
+    #
+    # When provided, each child widget is rendered within the block's area.
+    #
+    # === Example
+    #
+    #   Block.new(
+    #     title: "Content",
+    #     borders: [:all],
+    #     children: [Paragraph.new(text: "Hello")]
+    #   )
+
     # Creates a new Block.
     #
-    # [title] The title string to display on the border.
-    # [borders] An array of symbols representing which borders to display.
-    # [border_color] The color of the border.
-    def initialize(title: nil, borders: [:all], border_color: nil)
-      super
+    # [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_color]
+    #   Color string or symbol (e.g., <tt>:red</tt>). Deprecated: use <tt>border_style</tt> instead.
+    # [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_color: nil, 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_color:,
+        border_style:,
+        border_type:,
+        border_set:,
+        style:,
+        padding: coerced_padding,
+        children:
+      )
     end
   end
 end

data/lib/ratatui_ruby/schema/calendar.rb

@@ -4,23 +4,79 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A Monthly Calendar widget.
+  # Displays a monthly calendar grid.
   #
-  # [year] Integer (e.g., 2025)
-  # [month] Integer (1-12)
-  # [day_style] Style (Style for regular days)
-  # [header_style] Style (Style for the month title)
-  # [block] Block
-  class Calendar < Data.define(:year, :month, :day_style, :header_style, :block)
+  # Dates are complex. Rendering them in a grid requires calculation of leap years, month lengths, and day-of-week offsets.
+  # Use this widget to skip the boilerplate.
+  #
+  # This widget renders a standard monthly view. It highlights the current date. It structures time.
+  #
+  # Use it for date pickers, schedulers, or logs.
+  #
+  # {rdoc-image:/doc/images/widget_calendar_demo.png}[link:/examples/widget_calendar_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_calendar_demo/app.rb
+  class Calendar < Data.define(:year, :month, :events, :default_style, :header_style, :block, :show_weekdays_header, :show_surrounding, :show_month_header)
+    ##
+    # :attr_reader: year
+    # The year to display (Integer).
+
+    ##
+    # :attr_reader: month
+    # The month to display (1–12).
+
+    ##
+    # :attr_reader: events
+    # A Hash mapping Dates to Styles for event highlighting.
+    # Keys must be `Date` objects (or objects responding to `day`, `month`, `year`).
+    # Values must be `Style` objects.
+
+    ##
+    # :attr_reader: default_style
+    # Style for the days.
+
+    ##
+    # :attr_reader: header_style
+    # Style for the month name header.
+
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
+
+    ##
+    # :attr_reader: show_weekdays_header
+    # Whether to show the weekday header (Mon, Tue, etc.).
+
+    ##
+    # :attr_reader: show_surrounding
+    # Style for dates from surrounding months. If <tt>nil</tt>, surrounding dates are hidden.
+
     # Creates a new Calendar.
     #
-    # [year] Integer (e.g., 2025)
-    # [month] Integer (1-12)
-    # [day_style] Style (Style for regular days)
-    # [header_style] Style (Style for the month title)
-    # [block] Block
-    def initialize(year:, month:, day_style: nil, header_style: nil, block: nil)
-      super
+    # [year] Integer.
+    # [month] Integer.
+    # [events] Hash<Date, Style>. Optional.
+    # [default_style] Style.
+    # [header_style] Style.
+    # [block] Block.
+    # [show_weekdays_header] Boolean. Whether to show the weekday header.
+    # [show_surrounding] <tt>Style</tt> or <tt>nil</tt>. Style for surrounding month dates.
+    def initialize(year:, month:, events: {}, default_style: nil, header_style: nil, block: nil, show_weekdays_header: true, show_surrounding: nil, show_month_header: false)
+      super(
+        year: Integer(year),
+        month: Integer(month),
+        events:,
+        default_style:,
+        header_style:,
+        block:,
+        show_weekdays_header:,
+        show_surrounding:,
+        show_month_header:
+      )
     end
   end
 end