ratatui_ruby 0.3.1 → 0.4.0

data/lib/ratatui_ruby/event/mouse.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    # Reports a mouse interaction.
+    #
+    # Modern terminals support rich pointer input, but the protocols are complex and varied.
+    # Handling clicks, drags, and scrolls requires robust parsing.
+    #
+    # This event simplifies the complexity. It tells you exactly *what* happened (+kind+),
+    # *where* it happened (+x+, +y+), and *which* button was involved.
+    #
+    # Use this to build interactive UIs. Implement click handlers, draggable sliders, or
+    # scrollable viewports with confidence.
+    #
+    # === Example
+    #
+    #   if event.mouse? && event.down? && event.button == "left"
+    #     puts "Left click at #{event.x}, #{event.y}"
+    #   end
+    class Mouse < Event
+      # The kind of event (<tt>"down"</tt>, <tt>"up"</tt>, <tt>"drag"</tt>, <tt>"moved"</tt>, <tt>"scroll_up"</tt>, <tt>"scroll_down"</tt>).
+      #
+      #   puts event.kind # => "down"
+      attr_reader :kind
+      # X coordinate (column).
+      #
+      #   puts event.x # => 10
+      attr_reader :x
+      # Y coordinate (row).
+      #
+      #   puts event.y # => 5
+      attr_reader :y
+      # The button pressed (<tt>"left"</tt>, <tt>"right"</tt>, <tt>"middle"</tt>, <tt>"none"</tt>).
+      #
+      #   puts event.button # => "left"
+      #
+      # Can be <tt>nil</tt>, which is treated as <tt>"none"</tt>.
+      attr_reader :button
+      # List of active modifiers.
+      #
+      #   puts event.modifiers # => ["ctrl"]
+      attr_reader :modifiers
+
+      # Returns true for Mouse events.
+      #
+      #   event.mouse?  # => true
+      #   event.key?    # => false
+      #   event.resize? # => false
+      def mouse?
+        true
+      end
+
+      # Creates a new Mouse event.
+      #
+      # [kind]
+      #   Event kind (String).
+      # [x]
+      #   X coordinate (Integer).
+      # [y]
+      #   Y coordinate (Integer).
+      # [button]
+      #   Button name (String or <tt>nil</tt>).
+      # [modifiers]
+      #   List of modifiers (Array<String>).
+      def initialize(kind:, x:, y:, button:, modifiers: [])
+        @kind = kind
+        @x = x
+        @y = y
+        @button = button || "none"
+        @modifiers = modifiers.sort
+      end
+
+      # Returns true if mouse button was pressed down.
+      def down?
+        @kind == "down"
+      end
+
+      # Returns true if mouse button was released.
+      def up?
+        @kind == "up"
+      end
+
+      # Returns true if mouse is being dragged.
+      def drag?
+        @kind == "drag"
+      end
+
+      # Returns true if scroll wheel moved up.
+      def scroll_up?
+        @kind == "scroll_up"
+      end
+
+      # Returns true if scroll wheel moved down.
+      #
+      #   if event.scroll_down?
+      #     scroll_offset += 1
+      #   end
+      def scroll_down?
+        @kind == "scroll_down"
+      end
+
+      # Deconstructs the event for pattern matching.
+      #
+      #   case event
+      #   in type: :mouse, kind: "down", x:, y:
+      #     puts "Click at #{x}, #{y}"
+      #   end
+      def deconstruct_keys(keys)
+        { type: :mouse, kind: @kind, x: @x, y: @y, button: @button, modifiers: @modifiers }
+      end
+
+      ##
+      # Compares this event with another for equality.
+      def ==(other)
+        return false unless other.is_a?(Mouse)
+        kind == other.kind && x == other.x && y == other.y && button == other.button && modifiers == other.modifiers
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/paste.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    # Encapsulates pasted text.
+    #
+    # Users frequently paste text into terminals. Without specific handling, a paste appears as
+    # a flood of rapid keystrokes, often triggering accidental commands or confusing the input state.
+    #
+    # This event makes pasting safe. It groups the entire inserted block into a single atomic action.
+    #
+    # Handle this event to support bulk text insertion cleanly. Insert the +content+ directly into
+    # your field or buffer without triggering per-character logic.
+    #
+    # === Examples
+    #
+    # Using predicates:
+    #   if event.paste?
+    #     puts "Pasted: #{event.content}"
+    #   end
+    #
+    # Using pattern matching:
+    #   case event
+    #   in type: :paste, content:
+    #     puts "Pasted: #{content}"
+    #   end
+    class Paste < Event
+      # The pasted content.
+      #
+      #   puts event.content # => "https://example.com"
+      attr_reader :content
+
+      # Returns true for Paste events.
+      #
+      #   event.paste?  # => true
+      #   event.key?    # => false
+      #   event.resize? # => false
+      def paste?
+        true
+      end
+
+      # Creates a new Paste event.
+      #
+      # [content]
+      #   Pasted text (String).
+      def initialize(content:)
+        @content = content
+      end
+
+      # Deconstructs the event for pattern matching.
+      #
+      #   case event
+      #   in type: :paste, content:
+      #     puts "User pasted: #{content}"
+      #   end
+      def deconstruct_keys(keys)
+        { type: :paste, content: @content }
+      end
+
+      ##
+      # Compares this event with another for equality.
+      def ==(other)
+        return false unless other.is_a?(Paste)
+        content == other.content
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/resize.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    # Signals a change in terminal dimensions.
+    #
+    # The terminal window is dynamic, not static. The user changes its dimensions at will,
+    # usually breaking a fixed layout.
+    #
+    # This event captures the new state. It delivers the updated +width+ and +height+
+    # immediately after the change.
+    #
+    # Use these dimensions to drive your layout logic. Recalculate constraints. Reallocate space.
+    # Fill the new canvas completely to maintain a responsive design.
+    #
+    # === Examples
+    #
+    # Using predicates:
+    #   if event.resize?
+    #     puts "Resized to #{event.width}x#{event.height}"
+    #   end
+    #
+    # Using pattern matching:
+    #   case event
+    #   in type: :resize, width:, height:
+    #     puts "Resized to #{width}x#{height}"
+    #   end
+    class Resize < Event
+      # New terminal width in columns.
+      #
+      #   puts event.width # => 80
+      attr_reader :width
+
+      # New terminal height in rows.
+      #
+      #   puts event.height # => 24
+      attr_reader :height
+
+      # Returns true for Resize events.
+      #
+      #   event.resize? # => true
+      #   event.key?    # => false
+      #   event.mouse?  # => false
+      def resize?
+        true
+      end
+
+      # Creates a new Resize event.
+      #
+      # [width]
+      #   New width (Integer).
+      # [height]
+      #   New height (Integer).
+      def initialize(width:, height:)
+        @width = width
+        @height = height
+      end
+
+      # Deconstructs the event for pattern matching.
+      #
+      #   case event
+      #   in type: :resize, width:, height:
+      #     puts "Resized to #{width}x#{height}"
+      #   end
+      def deconstruct_keys(keys)
+        { type: :resize, width: @width, height: @height }
+      end
+
+      ##
+      # Compares this event with another for equality.
+      def ==(other)
+        return false unless other.is_a?(Resize)
+        width == other.width && height == other.height
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Base class for all RatatuiRuby events.
+  #
+  # Events are returned by RatatuiRuby.poll_event.
+  # All events support Ruby 3.0+ pattern matching via #deconstruct_keys.
+  #
+  # See RatatuiRuby.poll_event
+  class Event
+    # Returns true if this is a Key event.
+    def key?
+      false
+    end
+
+    # Returns true if this is a Mouse event.
+    def mouse?
+      false
+    end
+
+    # Returns true if this is a Resize event.
+    def resize?
+      false
+    end
+
+    # Returns true if this is a Paste event.
+    def paste?
+      false
+    end
+
+    # Returns true if this is a FocusGained event.
+    def focus_gained?
+      false
+    end
+
+    # Returns true if this is a FocusLost event.
+    def focus_lost?
+      false
+    end
+
+    # Responds to dynamic predicate methods for key checks.
+    # All non-Key events return false for any key predicate.
+    def method_missing(name, *args, &block)
+      if name.to_s.end_with?("?")
+        false
+      else
+        super
+      end
+    end
+
+    # Declares that this class responds to dynamic predicate methods.
+    def respond_to_missing?(name, *args)
+      name.to_s.end_with?("?") || super
+    end
+
+    # Deconstructs the event for pattern matching.
+    #
+    # Keys argument is unused but required by the protocol.
+    #
+    #   case event
+    #   in type: :key, code:
+    #     puts "Key: #{code}"
+    #   end
+    def deconstruct_keys(keys)
+      {}
+    end
+
+  end
+end
+
+require_relative "event/key"
+require_relative "event/mouse"
+require_relative "event/resize"
+require_relative "event/paste"
+require_relative "event/focus_gained"
+require_relative "event/focus_lost"

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-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).
+  
+      ##
+      # :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).
+  
+      def initialize(value:, label: nil, style: nil, value_style: nil, text_value: nil)
+        super(
+          value: Integer(value),
+          label: label,
+          style: style,
+          value_style: value_style,
+          text_value: text_value
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-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).
+  
+      def initialize(label:, bars:)
+        super
+      end
+    end
+  end
+end

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)
-    # Creates a new BarChart widget.
+    # Displays categorical data as bars.
     #
-    # [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
+    # 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.
+    #
+    # === Examples
+    #
+    #   BarChart.new(
+    #     data: { "US" => 40, "EU" => 35, "AP" => 25 },
+    #     bar_width: 5,
+    #     style: Style.new(fg: :green)
+    #   )
+    #
+    #   # 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: value, label: label.to_s)
+                   end
+                   [BarGroup.new(label: "", bars: bars)]
+                 else
+                   data.map do |label, value|
+                     BarGroup.new(label: label.to_s, bars: [Bar.new(value: 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: value, label: label)
+                       bar = bar.with(style: style) if style
+                       bar
+                     end
+                     [BarGroup.new(label: "", bars: bars)]
+                   else
+                     data.map do |item|
+                       label = item[0].to_s
+                       value = item[1]
+                       style = item[2]
+                       
+                       bar = Bar.new(value: value)
+                       bar = bar.with(style: style) if style
+                       BarGroup.new(label: label, bars: [bar])
+                     end
+                   end
+                 else
+                   # Fallback
+                   data
+                 end
+               else
+                 data
+               end
+
+        super(
+          data: data,
+          bar_width: Integer(bar_width),
+          bar_gap: Integer(bar_gap),
+          group_gap: Integer(group_gap),
+          max: max.nil? ? nil : Integer(max),
+          style: style,
+          block: block,
+          direction: direction,
+          label_style: label_style,
+          value_style: value_style,
+          bar_set: bar_set
+        )
+      end
     end
-  end
 end