ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/event/mouse.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   if event.mouse? && event.down? && event.button == "left"
+    #     puts "Left click at #{event.x}, #{event.y}"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    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>).
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   puts event.button # => "left"
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # 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.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.mouse?  # => true
+      #   event.key?    # => false
+      #   event.resize? # => false
+      #--
+      # SPDX-SnippetEnd
+      #++
+      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.freeze
+        @x = x
+        @y = y
+        @button = (button || "none").freeze
+        @modifiers = modifiers.map(&:freeze).sort.freeze
+      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
+
+      alias mouse_down? down?
+      alias mouse_up? up?
+
+      # 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.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if event.scroll_down?
+      #     scroll_offset += 1
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def scroll_down?
+        @kind == "scroll_down"
+      end
+
+      # Returns true if event involves the left mouse button.
+      def left?
+        @button == "left"
+      end
+
+      # Returns true if event involves the right mouse button.
+      def right?
+        @button == "right"
+      end
+
+      # Returns true if event involves the middle mouse button.
+      def middle?
+        @button == "middle"
+      end
+
+      alias left_button? left?
+      alias right_button? right?
+      alias middle_button? middle?
+
+      # Deconstructs the event for pattern matching.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   case event
+      #   in type: :mouse, kind: "down", x:, y:
+      #     puts "Click at #{x}, #{y}"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def deconstruct_keys(keys)
+        { type: :mouse, kind: @kind, x: @x, y: @y, button: @button, modifiers: @modifiers }
+      end
+
+      ##
+      # Converts the event to a Symbol representation.
+      #
+      # The format varies by event type:
+      #
+      # [Left Button]
+      #   <tt>:mouse_left_down</tt>, <tt>:mouse_left_up</tt>, <tt>:mouse_left_drag</tt>
+      # [Right Button]
+      #   <tt>:mouse_right_down</tt>, <tt>:mouse_right_up</tt>, <tt>:mouse_right_drag</tt>
+      # [Middle Button]
+      #   <tt>:mouse_middle_down</tt>, <tt>:mouse_middle_up</tt>, <tt>:mouse_middle_drag</tt>
+      # [Scroll]
+      #   <tt>:scroll_up</tt>, <tt>:scroll_down</tt>
+      # [Move]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   <tt>:mouse_moved</tt>
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event = Event::Mouse.new(kind: "down", x: 10, y: 5, button: "left")
+      #   event.to_sym  # => :mouse_left_down
+      #
+      #   scroll = Event::Mouse.new(kind: "scroll_up", x: 0, y: 0, button: "none")
+      #   scroll.to_sym # => :scroll_up
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def to_sym
+        if @kind.start_with?("scroll")
+          @kind.to_sym
+        elsif @button == "none"
+          :"mouse_#{@kind}"
+        else
+          :"mouse_#{@button}_#{@kind}"
+        end
+      end
+
+      ##
+      # Compares the event with another object.
+      #
+      # - If +other+ is a +Symbol+, compares against #to_sym.
+      # - If +other+ is a +Mouse+, compares as a value object.
+      # - Otherwise, returns +false+.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if event == :mouse_left_down
+      #     handle_click(event)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def ==(other)
+        case other
+        when Symbol then to_sym == other
+        when Mouse then kind == other.kind && x == other.x && y == other.y && button == other.button && modifiers == other.modifiers
+        else false
+        end
+      end
+
+      alias wheel_up? scroll_up?
+      alias wheel_down? scroll_down?
+
+      # Returns true for any scroll event.
+      #
+      #   event.scroll? # => true for scroll_up or scroll_down
+      def scroll?
+        scroll_up? || scroll_down?
+      end
+
+      alias primary? left?
+      alias secondary? right?
+      alias context_menu? right?
+      alias aux? middle?
+      alias auxiliary? aux?
+
+      # Returns true for mouse movement without button press.
+      #
+      #   event.moved? # => true for moved (no button)
+      def moved?
+        @kind == "moved"
+      end
+
+      alias hover? moved?
+      alias hovering? moved?
+      alias move? moved?
+      alias dragging? drag?
+
+      alias release? up?
+      alias released? up?
+      alias press? down?
+      alias pressed? down?
+    end
+  end
+end

data/lib/ratatui_ruby/event/none.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   event = RatatuiRuby.poll_event
+    #   break if event.ctrl_c?
+    #   redraw if event.none?
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # === 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,130 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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:
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   if event.paste?
+    #     puts "Pasted: #{event.content}"
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # Using pattern matching:
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   case event
+    #   in type: :paste, content:
+    #     puts "Pasted: #{content}"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Paste < Event
+      # The pasted content.
+      #
+      #   puts event.content # => "https://example.com"
+      attr_reader :content
+
+      # Returns true for Paste events.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.paste?  # => true
+      #   event.key?    # => false
+      #   event.resize? # => false
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def paste?
+        true
+      end
+      alias clipboard? paste?
+      alias pasteboard? paste?
+      alias pasted? paste?
+
+      # Creates a new Paste event.
+      #
+      # [content]
+      #   Pasted text (String).
+      def initialize(content:)
+        @content = content.freeze
+      end
+
+      # Deconstructs the event for pattern matching.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   case event
+      #   in type: :paste, content:
+      #     puts "User pasted: #{content}"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      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
+
+      # Returns true if the pasted content is empty.
+      def empty?
+        @content.empty?
+      end
+
+      # Returns true if the pasted content is empty or whitespace-only.
+      def blank?
+        @content.strip.empty?
+      end
+
+      # Returns true if the pasted content spans multiple lines.
+      def multiline?
+        @content.include?("\n")
+      end
+      alias multi_line? multiline?
+
+      # Returns true if the pasted content is a single line.
+      def single_line?
+        !multiline?
+      end
+      alias singleline? single_line?
+    end
+  end
+end

data/lib/ratatui_ruby/event/resize.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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:
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   if event.resize?
+    #     puts "Resized to #{event.width}x#{event.height}"
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # Using pattern matching:
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   case event
+    #   in type: :resize, width:, height:
+    #     puts "Resized to #{width}x#{height}"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    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.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.resize? # => true
+      #   event.key?    # => false
+      #   event.mouse?  # => false
+      #--
+      # SPDX-SnippetEnd
+      #++
+      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.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   case event
+      #   in type: :resize, width:, height:
+      #     puts "Resized to #{width}x#{height}"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def deconstruct_keys(keys)
+        { type: :resize, width: @width, height: @height }
+      end
+
+      ##
+      # Converts the event to a Symbol representation.
+      #
+      # Always returns <tt>:resize</tt>.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event = Event::Resize.new(width: 80, height: 24)
+      #   event.to_sym # => :resize
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def to_sym
+        :resize
+      end
+
+      ##
+      # Compares the event with another object.
+      #
+      # - If +other+ is a +Symbol+, compares against #to_sym.
+      # - If +other+ is a +Resize+, compares as a value object.
+      # - Otherwise, returns +false+.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if event == :resize
+      #     handle_resize(event)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def ==(other)
+        case other
+        when Symbol then to_sym == other
+        when Resize then width == other.width && height == other.height
+        else false
+        end
+      end
+
+      # Returns true. Unix <tt>SIGWINCH</tt> triggers terminal resize.
+      #
+      #   event.sigwinch? # => true
+      def sigwinch?
+        true
+      end
+
+      alias winch? sigwinch?
+      alias sig_winch? sigwinch?
+
+      alias terminal_resize? resize?
+      alias window_resize? resize?
+      alias window_change? resize?
+      alias viewport_resize? resize?
+      alias viewport_change? resize?
+      alias size_change? resize?
+      alias resized? resize?
+
+      VT100_WIDTH = 80 # :nodoc:
+      VT100_HEIGHT = 24 # :nodoc:
+
+      # Returns true if width exceeds height.
+      #
+      #   Event::Resize.new(width: 120, height: 24).landscape? # => true
+      def landscape?
+        @width > @height
+      end
+
+      # Returns true if height exceeds or equals width.
+      #
+      #   Event::Resize.new(width: 40, height: 80).portrait? # => true
+      def portrait?
+        @height >= @width
+      end
+
+      # Returns true if dimensions are exactly 80x24.
+      #
+      #   Event::Resize.new(width: 80, height: 24).vt100? # => true
+      def vt100?
+        @width == VT100_WIDTH && @height == VT100_HEIGHT
+      end
+
+      # Returns true if both dimensions meet or exceed 80x24.
+      #
+      #   Event::Resize.new(width: 120, height: 40).at_least_vt100? # => true
+      def at_least_vt100?
+        @width >= VT100_WIDTH && @height >= VT100_HEIGHT
+      end
+
+      # Returns true if both dimensions exceed 80x24.
+      #
+      #   Event::Resize.new(width: 81, height: 25).over_vt100? # => true
+      def over_vt100?
+        @width > VT100_WIDTH && @height > VT100_HEIGHT
+      end
+
+      # Returns true if either dimension falls below VT100 standard.
+      #
+      #   Event::Resize.new(width: 60, height: 24).cramped? # => true
+      def cramped?
+        @width < VT100_WIDTH || @height < VT100_HEIGHT
+      end
+
+      alias constrained? cramped?
+    end
+  end
+end