ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/event/key/media.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # Methods and logic for media keys.
+      module Media
+        # Returns true if this is a media key.
+        #
+        # Media keys include: play, pause, stop, track controls, volume controls.
+        # These are only available in terminals supporting the Kitty keyboard protocol.
+        #
+        #   event.media? # => true for media_play, media_pause, etc.
+        def media?
+          @kind == :media
+        end
+
+        # Handles media-specific DWIM logic for method_missing.
+        private def match_media_dwim?(key_name)
+          return false unless @kind == :media
+
+          # Allow unprefixed predicate
+          # e.g., pause? returns true for media_pause
+          if @code.start_with?("media_")
+            base_code = @code.delete_prefix("media_")
+            return true if key_name == base_code
+          end
+
+          # Bidirectional media overlaps
+          # e.g., play? and pause? both match media_play_pause
+          return true if @code == "media_play_pause" && (key_name == "play" || key_name == "pause")
+
+          # e.g., play_pause? matches media_play or media_pause
+          return true if key_name == "play_pause" && (@code == "media_play" || @code == "media_pause")
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key/modifier.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # Methods and logic for modifier keys.
+      module Modifier
+        # Returns true if CTRL is held OR if this is a left_control/right_control key event.
+        def ctrl?
+          @modifiers.include?("ctrl") || @code == "left_control" || @code == "right_control"
+        end
+
+        # Alias for {#ctrl?}.
+        alias control? ctrl?
+
+        # Returns true if ALT is held OR if this is a left_alt/right_alt key event.
+        def alt?
+          @modifiers.include?("alt") || @code == "left_alt" || @code == "right_alt"
+        end
+
+        # Alias for {#alt?}.
+        alias option? alt?
+
+        # Returns true if SHIFT is held OR if this is a left_shift/right_shift key event.
+        def shift?
+          @modifiers.include?("shift") || @code == "left_shift" || @code == "right_shift"
+        end
+
+        # Returns true if SUPER is held OR if this is a left_super/right_super key event.
+        # Also responds to platform aliases: win?, command?, cmd?, tux?
+        def super?
+          @modifiers.include?("super") || @code == "left_super" || @code == "right_super"
+        end
+
+        # Alias for {#super?}.
+        alias win? super?
+        # Alias for {#super?}.
+        alias command? super?
+        # Alias for {#super?}.
+        alias cmd? super?
+        # Alias for {#super?}.
+        alias tux? super?
+
+        # Returns true if HYPER is held OR if this is a left_hyper/right_hyper key event.
+        def hyper?
+          @modifiers.include?("hyper") || @code == "left_hyper" || @code == "right_hyper"
+        end
+
+        # Returns true if META is held OR if this is a left_meta/right_meta key event.
+        def meta?
+          @modifiers.include?("meta") || @code == "left_meta" || @code == "right_meta"
+        end
+
+        # Returns true if this is a modifier key event.
+        #
+        # Some applications need to know if an event represents a generic key
+        # press or a specific modifier key (like CTRL or ALT) being pressed on
+        # its own.
+        #
+        # This method identifies if the key event itself is a modifier key.
+        #
+        # === Example
+        #
+        #   if event.modifier?
+        #     # Handle solo modifier key press
+        #   end
+        def modifier?
+          @kind == :modifier
+        end
+
+        # Handles modifier-specific DWIM logic for method_missing.
+        private def match_modifier_dwim?(key_name, key_sym)
+          # Platform modifier aliases
+          modifier_aliases = {
+            win: "super",
+            command: "super",
+            cmd: "super",
+            tux: "super",
+          }.freeze
+
+          target_modifier = modifier_aliases[key_sym]
+          if target_modifier
+            return true if @modifiers.include?(target_modifier)
+            return true if @code == "left_#{target_modifier}" || @code == "right_#{target_modifier}"
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key/navigation.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # Methods and logic for navigation keys.
+      module Navigation
+        # Returns true if this is a standard key.
+        #
+        # Standard keys include: characters, Enter, Tab, arrow keys, navigation keys.
+        #
+        #   event.standard? # => true for "a", "enter", "up", etc.
+        def standard?
+          @kind == :standard
+        end
+
+        # Alias for {#standard?}.
+        #
+        # Provided for semantic clarity when checking if a key has no special category.
+        #
+        #   event.unmodified? # => true for standard keys like "a", "enter", "up"
+        alias unmodified? standard?
+
+        # Handles navigation-specific DWIM logic for method_missing.
+        private def match_navigation_dwim?(key_name, key_sym)
+          # DWIM: reverse_tab? matches both BackTab key and Shift+Tab combo
+          if key_name == "reverse_tab"
+            return true if @code == "back_tab"
+            return true if @code == "tab" && @modifiers.include?("shift")
+          end
+
+          # DWIM: Check explicit aliases
+          navigation_aliases = {
+            return: "enter",
+            back: "backspace",
+            del: "delete",
+            ins: "insert",
+            pgup: "page_up",
+            pageup: "page_up",
+            pgdn: "page_down",
+            pagedown: "page_down",
+          }.freeze
+
+          target_code = navigation_aliases[key_sym]
+          return true if target_code && @code == target_code && @modifiers.empty?
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key/system.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 Event
+    class Key < Event
+      # Methods and logic for system and function keys.
+      module System
+        # Returns true if this is a system key.
+        #
+        # System keys include: Esc, CapsLock, ScrollLock, NumLock, PrintScreen, Pause, Menu, KeypadBegin.
+        #
+        #   event.system? # => true for pause, esc, caps_lock, etc.
+        def system?
+          @kind == :system
+        end
+
+        # Returns true if this is a function key (F1-F24).
+        #
+        #   event.function? # => true for f1, f2, ..., f24
+        def function?
+          @kind == :function
+        end
+
+        # Handles system-specific DWIM logic for method_missing.
+        private def match_system_dwim?(key_name, key_sym)
+          system_aliases = {
+            scrlk: "scroll_lock",
+            scroll: "scroll_lock",
+            prtsc: "print_screen",
+            print: "print_screen",
+            escape: "esc",
+          }.freeze
+
+          target_code = system_aliases[key_sym]
+          return true if target_code && @code == target_code && @modifiers.empty?
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key.rb

@@ -3,6 +3,12 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+require_relative "key/character"
+require_relative "key/media"
+require_relative "key/modifier"
+require_relative "key/navigation"
+require_relative "key/system"
+
 module RatatuiRuby
   class Event
     # Captures a keyboard interaction.
@@ -33,7 +39,34 @@ module RatatuiRuby
     #   in type: :key, code: "c", modifiers: ["ctrl"]
     #     exit
     #   end
+    #
+    # === Terminal Compatibility
+    #
+    # Some key combinations never reach your application. Terminal emulators intercept them for
+    # built-in features like tab switching. Common culprits:
+    #
+    # * Ctrl+PageUp/PageDown (tab switching in Terminal.app, iTerm2)
+    # * Ctrl+Tab (tab switching)
+    # * Cmd+key combinations (macOS system shortcuts)
+    #
+    # If modifiers appear missing, test with a different terminal. Kitty, WezTerm, and Alacritty
+    # pass more keys through. See <tt>doc/terminal_limitations.md</tt> for details.
+    #
+    # === Enhanced Keys (Kitty Protocol)
+    #
+    # Terminals supporting the Kitty keyboard protocol report additional keys:
+    #
+    # * Media keys: <tt>:play</tt>, <tt>:play_pause</tt>, <tt>:track_next</tt>, <tt>:mute_volume</tt>
+    # * Individual modifiers: <tt>:left_shift</tt>, <tt>:right_control</tt>, <tt>:left_super</tt>
+    #
+    # These keys will not work in Terminal.app, iTerm2, or GNOME Terminal.
     class Key < Event
+      include Character
+      include Media
+      include Modifier
+      include Navigation
+      include System
+
       # The key code (e.g., <tt>"a"</tt>, <tt>"enter"</tt>, <tt>"up"</tt>).
       #
       #   puts event.code # => "enter"
@@ -44,6 +77,15 @@ module RatatuiRuby
       #   puts event.modifiers # => ["ctrl", "shift"]
       attr_reader :modifiers
 
+      # The category of the key.
+      #
+      # One of: <tt>:standard</tt>, <tt>:function</tt>, <tt>:media</tt>, <tt>:modifier</tt>, <tt>:system</tt>.
+      #
+      # This allows grouping keys by their logical type without parsing the code string.
+      #
+      #   event.kind # => :media
+      attr_reader :kind
+
       # Returns true for Key events.
       #
       #   event.key?    # => true
@@ -59,17 +101,21 @@ module RatatuiRuby
       #   The key code (String).
       # [modifiers]
       #   List of modifiers (Array<String>).
-      def initialize(code:, modifiers: [])
-        @code = code
-        @modifiers = modifiers.sort
+      # [kind]
+      #   The key category (Symbol). One of: <tt>:standard</tt>, <tt>:function</tt>,
+      #   <tt>:media</tt>, <tt>:modifier</tt>, <tt>:system</tt>. Defaults to <tt>:standard</tt>.
+      def initialize(code:, modifiers: [], kind: :standard)
+        @code = code.freeze
+        @modifiers = modifiers.map(&:freeze).sort.freeze
+        @kind = kind
       end
 
       # Compares the event with another object.
       #
       # - If +other+ is a +Symbol+, compares against #to_sym.
       # - If +other+ is a +String+, compares against #to_s.
-      # - Otherwise, performs standard equality check.
-      # - Otherwise, compares internal state (code + modifiers).
+      # - If +other+ is a +Key+, compares as a value object.
+      # - Otherwise, compares using standard equality.
       def ==(other)
         case other
         when Symbol
@@ -91,9 +137,25 @@ module RatatuiRuby
       # === Supported Keys
       #
       # [Standard]
-      #   <tt>:enter</tt>, <tt>:backspace</tt>, <tt>:tab</tt>, <tt>:esc</tt>, <tt>:page_up</tt>, <tt>:page_down</tt>, <tt>:home</tt>, <tt>:end</tt>, <tt>:delete</tt>, <tt>:insert</tt>, <tt>:f1</tt>..<tt>:f12</tt>
+      #   <tt>:enter</tt>, <tt>:backspace</tt>, <tt>:tab</tt>, <tt>:back_tab</tt>, <tt>:esc</tt>, <tt>:null</tt>
       # [Navigation]
-      #   <tt>:up</tt>, <tt>:down</tt>, <tt>:left</tt>, <tt>:right</tt>
+      #   <tt>:up</tt>, <tt>:down</tt>, <tt>:left</tt>, <tt>:right</tt>, <tt>:home</tt>, <tt>:end</tt>,
+      #   <tt>:page_up</tt>, <tt>:page_down</tt>, <tt>:insert</tt>, <tt>:delete</tt>
+      # [Function Keys]
+      #   <tt>:f1</tt> through <tt>:f12</tt> (and beyond, e.g. <tt>:f24</tt>)
+      # [Lock Keys]
+      #   <tt>:caps_lock</tt>, <tt>:scroll_lock</tt>, <tt>:num_lock</tt>
+      # [System Keys]
+      #   <tt>:print_screen</tt>, <tt>:pause</tt>, <tt>:menu</tt>, <tt>:keypad_begin</tt>
+      # [Media Keys]
+      #   <tt>:play</tt>, <tt>:media_pause</tt>, <tt>:play_pause</tt>, <tt>:reverse</tt>, <tt>:stop</tt>,
+      #   <tt>:fast_forward</tt>, <tt>:rewind</tt>, <tt>:track_next</tt>, <tt>:track_previous</tt>,
+      #   <tt>:record</tt>, <tt>:lower_volume</tt>, <tt>:raise_volume</tt>, <tt>:mute_volume</tt>
+      # [Modifier Keys]
+      #   <tt>:left_shift</tt>, <tt>:left_control</tt>, <tt>:left_alt</tt>, <tt>:left_super</tt>,
+      #   <tt>:left_hyper</tt>, <tt>:left_meta</tt>, <tt>:right_shift</tt>, <tt>:right_control</tt>,
+      #   <tt>:right_alt</tt>, <tt>:right_super</tt>, <tt>:right_hyper</tt>, <tt>:right_meta</tt>,
+      #   <tt>:iso_level3_shift</tt>, <tt>:iso_level5_shift</tt>
       # [Characters]
       #   <tt>:a</tt>, <tt>:b</tt>, <tt>:1</tt>, <tt>:space</tt>, etc.
       #
@@ -108,7 +170,7 @@ module RatatuiRuby
         if mods.empty?
           @code.to_sym
         else
-          "#{mods}_#{@code}".to_sym
+          :"#{mods}_#{@code}"
         end
       end
 
@@ -131,46 +193,7 @@ module RatatuiRuby
 
       # Returns inspection string.
       def inspect
-        "#<#{self.class} code=#{@code.inspect} modifiers=#{@modifiers.inspect}>"
-      end
-
-      # Returns true if CTRL is held.
-      def ctrl?
-        @modifiers.include?("ctrl")
-      end
-
-      # Returns true if ALT is held.
-      def alt?
-        @modifiers.include?("alt")
-      end
-
-      # Returns true if SHIFT is held.
-      def shift?
-        @modifiers.include?("shift")
-      end
-
-      # Returns true if the key represents a single printable character.
-      #
-      #   RatatuiRuby::Event::Key.new(code: "a").text?       # => true
-      #   RatatuiRuby::Event::Key.new(code: "enter").text?   # => false
-      #   RatatuiRuby::Event::Key.new(code: "space").text?   # => false ("space" is not 1 char, " " is)
-      def text?
-        @code.length == 1
-      end
-
-      # Returns the key as a printable character (if applicable).
-      #
-      # [Printable Characters]
-      #   Returns the character itself (e.g., <tt>"a"</tt>, <tt>"1"</tt>, <tt>" "</tt>).
-      # [Special Keys]
-      #   Returns an empty string (e.g., <tt>"enter"</tt>, <tt>"up"</tt>, <tt>"f1"</tt>).
-      #
-      # This is equivalent to +to_s+.
-      #
-      #   RatatuiRuby::Event::Key.new(code: "a").char      # => "a"
-      #   RatatuiRuby::Event::Key.new(code: "enter").char  # => ""
-      def char
-        to_s
+        "#<#{self.class} code=#{@code.inspect} modifiers=#{@modifiers.inspect} kind=#{@kind.inspect}>"
       end
 
       # Supports dynamic key predicate methods via method_missing.
@@ -184,12 +207,47 @@ module RatatuiRuby
       #
       # The method name is converted to a symbol and compared against the event.
       # This works for any key code or modifier+key combination.
+      #
+      # === Smart Predicates (DWIM)
+      #
+      # For convenience, generic predicates match both system and media variants:
+      #
+      #   event.pause?      # => true for BOTH system "pause" AND "media_pause"
+      #   event.play?       # => true for "media_play"
+      #   event.stop?       # => true for "media_stop"
+      #
+      # This "Do What I Mean" behavior reduces boilerplate when you just want to
+      # respond to a conceptual action (e.g., "pause the playback") regardless of
+      # whether the user pressed a keyboard key or a media button.
+      #
+      # For strict matching, use the full predicate or compare the code directly:
+      #
+      #   event.media_pause?  # => true ONLY for media pause
+      #   event.code == "pause"  # => true ONLY for system pause
       def method_missing(name, *args, &block)
         if name.to_s.end_with?("?")
-          key_sym = name.to_s[0...-1].to_sym
-          return self == key_sym
+          key_name = name.to_s[0...-1]
+          key_sym = key_name.to_sym
+
+          # Fast path: Exact match (e.g., media_pause? for media_pause)
+          return true if self == key_sym
+
+          # Delegate category-specific DWIM logic to mixins
+          return true if match_media_dwim?(key_name)
+          return true if match_modifier_dwim?(key_name, key_sym)
+          return true if match_navigation_dwim?(key_name, key_sym)
+          return true if match_system_dwim?(key_name, key_sym)
+
+          # DWIM: Universal underscore-insensitivity
+          # Normalize both predicate and code by stripping underscores
+          normalized_predicate = key_name.delete("_")
+          normalized_code = @code.delete("_")
+          return true if normalized_predicate == normalized_code && @modifiers.empty?
+
+          false
+        else
+          super
         end
-        super
       end
 
       # Declares that this class responds to dynamic predicate methods.
@@ -202,9 +260,11 @@ module RatatuiRuby
       #   case event
       #   in type: :key, code: "c", modifiers: ["ctrl"]
       #     puts "Ctrl+C pressed"
+      #   in type: :key, kind: :media
+      #     puts "Media key pressed"
       #   end
       def deconstruct_keys(keys)
-        { type: :key, code: @code, modifiers: @modifiers }
+        { type: :key, code: @code, modifiers: @modifiers, kind: @kind }
       end
     end
   end

data/lib/ratatui_ruby/event/mouse.rb

@@ -67,11 +67,11 @@ module RatatuiRuby
       # [modifiers]
       #   List of modifiers (Array<String>).
       def initialize(kind:, x:, y:, button:, modifiers: [])
-        @kind = kind
+        @kind = kind.freeze
         @x = x
         @y = y
-        @button = button || "none"
-        @modifiers = modifiers.sort
+        @button = (button || "none").freeze
+        @modifiers = modifiers.map(&:freeze).sort.freeze
       end
 
       # Returns true if mouse button was pressed down.

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

@@ -47,7 +47,7 @@ module RatatuiRuby
       # [content]
       #   Pasted text (String).
       def initialize(content:)
-        @content = content
+        @content = content.freeze
       end
 
       # Deconstructs the event for pattern matching.

data/lib/ratatui_ruby/event.rb

@@ -6,11 +6,63 @@
 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.
+  # Events represent terminal input: keyboard, mouse, resize, paste, focus changes.
+  # Returned by RatatuiRuby.poll_event. All events support Ruby 3.0+ pattern matching.
   #
-  # See RatatuiRuby.poll_event
+  # == 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
@@ -67,10 +119,10 @@ module RatatuiRuby
     def deconstruct_keys(keys)
       {}
     end
-
   end
 end
 
+require_relative "event/none"
 require_relative "event/key"
 require_relative "event/mouse"
 require_relative "event/resize"