ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/widgets/bar_chart.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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.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)
+      include CoerceableWidget
+
+      ##
+      ##
+      ##
+      ##
+      # :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: 2026 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: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   { "Apples" => 10, :Oranges => 15 }
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Array of Tuples (Ordered):
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   [["Mon", 20], ["Tue", 30], ["Wed", 25]]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # BarGroup (Grouped):
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 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: 2026 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]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Symbol, Hash, or Array: Custom characters for bars.
+      #   Symbols: <tt>:nine_levels</tt> (default gradient), <tt>:three_levels</tt> (simplified).
+      #--
+      # SPDX-SnippetEnd
+      #++
+      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)
+        # Normalize bar_set to Hash[Symbol, String] if provided as Array or Hash
+        bar_set = case bar_set
+                  when Symbol, nil
+                    bar_set
+                  when Array
+                    # Convert Array to Hash using BAR_KEYS order
+                    BAR_KEYS.zip(bar_set).to_h
+                  when Hash
+                    # @type var raw_hash: Hash[untyped, untyped]
+                    raw_hash = bar_set.dup
+                    normalized = {} #: Hash[Symbol, String]
+                    # Normalize numeric keys (0-8) to symbolic keys
+                    BAR_KEYS.each_with_index do |key, i|
+                      val = raw_hash.delete(i) || raw_hash.delete(i.to_s) || raw_hash.delete(key)
+                      normalized[key] = val.to_s if val
+                    end
+                    normalized
+                  else
+                    bar_set
+        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 - use type assertion for Steep
+            if direction == :horizontal
+              bars = data.map do |item|
+                tuple = item #: Array[untyped]
+                label = tuple[0].to_s
+                value = tuple[1]
+                style = tuple[2]
+
+                bar = Bar.new(value:, label:)
+                bar = bar.with(style:) if style
+                bar
+              end
+              [BarGroup.new(label: "", bars:)]
+            else
+              data.map do |item|
+                tuple = item #: Array[untyped]
+                label = tuple[0].to_s
+                value = tuple[1]
+                style = tuple[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

data/lib/ratatui_ruby/widgets/block.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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)
+      include CoerceableWidget
+
+      ##
+      # :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: 2026 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: 2026 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.to_sym
+            if (val = 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
+
+      # Computes the inner content area given an outer area.
+      #
+      # This method calculates where content should be placed within a block,
+      # accounting for borders and padding. Essential for layout calculations
+      # when you need to know the usable space inside a block.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   block = Block.new(borders: [:all], padding: 1)
+      #   outer = Layout::Rect.new(x: 0, y: 0, width: 20, height: 10)
+      #   inner = block.inner(outer)
+      #   # => Rect(x: 2, y: 2, width: 16, height: 6)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [area]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   The outer Rect to compute the inner area for.
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns a new Rect representing the inner content area.
+      def inner(area)
+        # Calculate border offsets
+        has_border = -> (side) { borders.include?(:all) || borders.include?(side) }
+        left_border = has_border.call(:left) ? 1 : 0
+        right_border = has_border.call(:right) ? 1 : 0
+        top_border = has_border.call(:top) ? 1 : 0
+        bottom_border = has_border.call(:bottom) ? 1 : 0
+
+        # Calculate padding offsets - ensure all are Integer
+        pad_left, pad_right, pad_top, pad_bottom = if padding.is_a?(Array)
+          # [left, right, top, bottom]
+          [
+            Integer(padding[0] || 0),
+            Integer(padding[1] || 0),
+            Integer(padding[2] || 0),
+            Integer(padding[3] || 0),
+          ]
+        else
+          p = Integer(padding)
+          [p, p, p, p]
+        end
+
+        # Compute inner area
+        new_x = area.x + left_border + pad_left
+        new_y = area.y + top_border + pad_top
+        new_width = [area.width - left_border - right_border - pad_left - pad_right, 0].max
+        new_height = [area.height - top_border - bottom_border - pad_top - pad_bottom, 0].max
+
+        Layout::Rect.new(x: new_x, y: new_y, width: new_width, height: new_height)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/calendar.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # Displays a monthly calendar grid.
+    #
+    # 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.png}[link:/examples/widget_calendar/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_calendar/app.rb
+    class Calendar < Data.define(:year, :month, :events, :default_style, :header_style, :block, :show_weekdays_header, :show_surrounding, :show_month_header)
+      include CoerceableWidget
+
+      ##
+      # :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.
+      # [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
+end