ratatui_ruby 0.3.1 → 0.5.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/none.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    # {Null object}[https://en.wikipedia.org/wiki/Null_object_pattern] for absent events.
+    #
+    # Event loops poll for input 60 times per second. Usually nothing is happening.
+    # If <tt>RatatuiRuby.poll_event</tt> returned <tt>nil</tt>, you would need
+    # nil-checks: <tt>event&.key?</tt>, <tt>next unless event</tt>.
+    #
+    # This class eliminates that friction. It responds to every predicate with
+    # <tt>false</tt>. Call <tt>none?</tt> to detect it explicitly. Pattern-match on
+    # <tt>type: :none</tt> for exhaustive dispatch.
+    #
+    # Use it to simplify your event loop. No guards. Optional `else` clauses.
+    #
+    # See Martin Fowler's {Special Case}[https://martinfowler.com/eaaCatalog/specialCase.html] pattern.
+    #
+    # === Predicate Example
+    #
+    #   event = RatatuiRuby.poll_event
+    #   break if event.ctrl_c?
+    #   redraw if event.none?
+    #
+    # === Pattern Matching Example
+    #
+    #   redraw if RatatuiRuby.poll_event in type: :none
+    class None < Event
+      # Returns true for None events.
+      def none?
+        true
+      end
+
+      # Deconstructs the event for pattern matching.
+      def deconstruct_keys(keys)
+        { type: :none }
+      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,131 @@
+# 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 represent terminal input: keyboard, mouse, resize, paste, focus changes.
+  # Returned by RatatuiRuby.poll_event. All events support Ruby 3.0+ pattern matching.
+  #
+  # == Event Types
+  #
+  # * <tt>Key</tt> — keyboard input
+  # * <tt>Mouse</tt> — mouse clicks, movement, wheel
+  # * <tt>Resize</tt> — terminal resized
+  # * <tt>Paste</tt> — clipboard paste
+  # * <tt>FocusGained</tt> — terminal gained focus
+  # * <tt>FocusLost</tt> — terminal lost focus
+  # * <tt>None</tt> — no event available (Null Object)
+  #
+  # == Pattern Matching (Exhaustive)
+  #
+  # Use <tt>case...in</tt> to dispatch on every possible event type. This ensures
+  # you handle every case without needing an +else+ clause:
+  #
+  #   case RatatuiRuby.poll_event
+  #   in { type: :key, code: "q" }
+  #     break
+  #   in { type: :key, code: code, modifiers: }
+  #     handle_key(code, modifiers)
+  #   in { type: :mouse, kind: "down", x:, y: }
+  #     handle_click(x, y)
+  #   in { type: :mouse, kind:, x:, y: }
+  #     # handle other mouse activities
+  #   in { type: :resize, width:, height: }
+  #     handle_resize(width, height)
+  #   in { type: :paste, content: }
+  #     handle_paste(content)
+  #   in { type: :focus_gained }
+  #     handle_focus_gain
+  #   in { type: :focus_lost }
+  #     handle_focus_loss
+  #   in { type: :none }
+  #     # Idle
+  #   end
+  #
+  # == Predicates
+  #
+  # Check event types with predicates without pattern matching:
+  #
+  #   event = RatatuiRuby.poll_event
+  #   if event.key?
+  #     puts "Key pressed"
+  #   elsif event.none?
+  #     # Idle
+  #   elsif event.mouse?
+  #     puts "Mouse event"
+  #   end
+  class Event
+    # Returns true if this is a None event.
+    def none?
+      false
+    end
+
+    # 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/none"
+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/frame.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Provides access to the terminal buffer for rendering widgets.
+  #
+  # Rendering in immediate-mode TUIs requires knowing the terminal dimensions and
+  # placing widgets at specific positions. Without explicit control, layout
+  # calculations become duplicated between rendering and hit testing.
+  #
+  # This class exposes the terminal frame during a draw call. It provides the
+  # current area and methods to render widgets at precise locations.
+  #
+  # Use it inside a <tt>RatatuiRuby.draw</tt> block to render widgets with full
+  # control over placement.
+  #
+  # === Examples
+  #
+  # Basic usage with a single widget:
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     paragraph = RatatuiRuby::Paragraph.new(text: "Hello, world!")
+  #     frame.render_widget(paragraph, frame.area)
+  #   end
+  #
+  # Using Layout.split for multi-region layouts:
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     sidebar, main = RatatuiRuby::Layout.split(
+  #       frame.area,
+  #       direction: :horizontal,
+  #       constraints: [
+  #         RatatuiRuby::Constraint.length(20),
+  #         RatatuiRuby::Constraint.fill(1)
+  #       ]
+  #     )
+  #
+  #     frame.render_widget(sidebar_widget, sidebar)
+  #     frame.render_widget(main_widget, main)
+  #
+  #     # Store rects for hit testing — no duplication!
+  #     @regions = { sidebar: sidebar, main: main }
+  #   end
+  class Frame
+    ##
+    # :method: area
+    # :call-seq: area() -> Rect
+    #
+    # Returns the full terminal area as a Rect.
+    #
+    # The returned Rect represents the entire drawable area of the terminal.
+    # Use it as the starting point for layout calculations.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     puts "Terminal size: #{frame.area.width}x#{frame.area.height}"
+    #   end
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: render_widget
+    # :call-seq: render_widget(widget, area) -> nil
+    #
+    # Renders a widget at the specified area.
+    #
+    # Widgets in RatatuiRuby are immutable Data objects. This method takes a
+    # widget and a Rect, rendering the widget's content within that region.
+    #
+    # [widget]
+    #   The widget to render (Paragraph, Layout, List, Table, etc.).
+    # [area]
+    #   A Rect specifying where to render the widget.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     para = RatatuiRuby::Paragraph.new(text: "Content")
+    #     frame.render_widget(para, frame.area)
+    #   end
+    #
+    # (Native method implemented in Rust)
+  end
+end

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:,
+          style:,
+          value_style:,
+          text_value:
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# 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).
+    end
+  end
+end