ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/event/focus_lost.rb

@@ -0,0 +1,127 @@
+# 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 that the application is in the background.
+    #
+    # The user has switched context. Your application is no longer the primary focus.
+    #
+    # This event warns of inactivity. It fires when the terminal window loses focus.
+    #
+    # Respond by conserving resources. Pause animations. Stop heavy polling. dim the UI to
+    # indicate a background state.
+    #
+    # Only supported by some terminals (e.g. iTerm2, Kitty, newer xterm).
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   if event.focus_lost?
+    #     puts "Focus lost"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class FocusLost < Event
+      # Returns true for FocusLost events.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.focus_lost? # => true
+      #   event.key?        # => false
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def focus_lost?
+        true
+      end
+
+      # Deconstructs the event for pattern matching.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   case event
+      #   in type: :focus_lost
+      #     puts "Application lost focus"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def deconstruct_keys(keys)
+        { type: :focus_lost }
+      end
+
+      ##
+      # Compares this event with another for equality.
+      def ==(other)
+        other.is_a?(FocusLost)
+      end
+
+      # =========================================================================
+      # DWIM Predicates
+      # =========================================================================
+
+      # Returns true. The terminal has lost focus (blur).
+      #
+      #   event.blur? # => true
+      def blur?
+        true
+      end
+      alias blurred? blur?
+
+      # Returns true. The application lost focus.
+      #
+      #   event.lost? # => true
+      def lost?
+        true
+      end
+      alias unfocused? lost?
+
+      # Returns false. This is not a focus gained event.
+      #
+      #   event.focus? # => false
+      def focus?
+        false
+      end
+      alias focused? focus?
+
+      # Returns false. This is not a gained event.
+      #
+      #   event.gained? # => false
+      def gained?
+        false
+      end
+
+      # Returns true. The application is inactive.
+      #
+      #   event.inactive? # => true
+      def inactive?
+        true
+      end
+      alias background? inactive?
+
+      # Returns false. The application is not active.
+      #
+      #   event.active? # => false
+      def active?
+        false
+      end
+      alias foreground? active?
+    end
+  end
+end

data/lib/ratatui_ruby/event/key/character.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
+    class Key < Event
+      # Methods for handling printable characters.
+      module Character
+        # Returns true if the key represents a single printable character.
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   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)
+        #--
+        # SPDX-SnippetEnd
+        #++
+        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]
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   Returns <tt>nil</tt> (e.g., <tt>"enter"</tt>, <tt>"up"</tt>, <tt>"f1"</tt>).
+        #
+        #   RatatuiRuby::Event::Key.new(code: "a").char      # => "a"
+        #   RatatuiRuby::Event::Key.new(code: "enter").char  # => nil
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def char
+          text? ? @code : nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # DWIM predicates for common key patterns.
+      #
+      # These predicates anticipate what developers intuitively try. Space bars,
+      # character categories, Unix signals, and Vim-style navigation.
+      module Dwim
+        # Returns true if the key is a space character.
+        #
+        #   event.space? # => true for " "
+        def space?
+          @code == " " && @modifiers.empty?
+        end
+
+        alias spacebar? space?
+
+        # Returns true if the key is Enter. Alias for carriage return.
+        #
+        #   event.cr? # => true for enter
+        def cr?
+          @code == "enter" && @modifiers.empty?
+        end
+
+        alias carriagereturn? cr?
+        alias linefeed? cr?
+        alias newline? cr?
+        alias lf? cr?
+
+        # Returns true if the key is a single letter (a-z, A-Z).
+        #
+        #   Event::Key.new(code: "a").letter? # => true
+        def letter?
+          @code.length == 1 && @code.match?(/\A[A-Za-z]\z/)
+        end
+
+        # Returns true if the key is a digit (0-9).
+        #
+        #   Event::Key.new(code: "5").digit? # => true
+        def digit?
+          @code.length == 1 && @code.match?(/\A[0-9]\z/)
+        end
+
+        # Returns true if the key is alphanumeric.
+        #
+        #   Event::Key.new(code: "a").alphanumeric? # => true
+        def alphanumeric?
+          letter? || digit?
+        end
+
+        # Returns true if the key is punctuation.
+        #
+        #   Event::Key.new(code: "@", modifiers: ["shift"]).punctuation? # => true
+        def punctuation?
+          return false unless @code.length == 1
+          !letter? && !digit? && !whitespace?
+        end
+
+        # Returns true if the key is whitespace (space, enter, tab).
+        #
+        #   Event::Key.new(code: " ").whitespace? # => true
+        def whitespace?
+          @code == " " || @code == "enter" || @code == "tab"
+        end
+
+        # Returns true for interrupt (Ctrl+C).
+        #
+        #   event.interrupt? # => true for Ctrl+C
+        def interrupt?
+          @code == "c" && @modifiers == ["ctrl"]
+        end
+
+        # Returns true for end-of-file (Ctrl+D).
+        #
+        #   event.eof? # => true for Ctrl+D
+        def eof?
+          @code == "d" && @modifiers == ["ctrl"]
+        end
+
+        # Returns true for cancel (Esc or Ctrl+C).
+        #
+        #   event.cancel? # => true for Esc or Ctrl+C
+        def cancel?
+          (@code == "esc" && @modifiers.empty?) || interrupt?
+        end
+
+        # Returns true for SIGINT (Ctrl+C).
+        #
+        #   event.sigint? # => true for Ctrl+C
+        def sigint?
+          interrupt?
+        end
+
+        alias int? sigint?
+
+        # Returns true for SIGTSTP (Ctrl+Z) - suspend/stop.
+        #
+        #   event.suspend? # => true for Ctrl+Z
+        def suspend?
+          @code == "z" && @modifiers == ["ctrl"]
+        end
+
+        alias sigtstp? suspend?
+        alias tstp? suspend?
+
+        # Returns true for SIGQUIT (Ctrl+\).
+        #
+        #   event.quit? # => true for Ctrl+\
+        def quit?
+          @code == "\\" && @modifiers == ["ctrl"]
+        end
+
+        alias sigquit? quit?
+
+        NAVIGATION_KEYS = %w[up down left right home end page_up page_down].freeze # :nodoc:
+
+        # Returns true if key is a navigation key.
+        #
+        #   Event::Key.new(code: "up").navigation? # => true
+        def navigation?
+          NAVIGATION_KEYS.include?(@code) && @modifiers.empty?
+        end
+
+        ARROW_KEYS = %w[up down left right].freeze # :nodoc:
+
+        # Returns true if key is an arrow key.
+        #
+        #   Event::Key.new(code: "up").arrow? # => true
+        def arrow?
+          ARROW_KEYS.include?(@code) && @modifiers.empty?
+        end
+
+        VIM_MOVEMENT_KEYS = %w[h j k l w b g G].freeze # :nodoc:
+
+        # Returns true if key is a Vim movement key.
+        #
+        #   Event::Key.new(code: "j").vim? # => true
+        def vim?
+          return true if VIM_MOVEMENT_KEYS.include?(@code) && @modifiers.empty?
+          @code == "G" && @modifiers == ["shift"]
+        end
+
+        # Returns true for Vim left (h).
+        def vim_left?
+          @code == "h" && @modifiers.empty?
+        end
+
+        # Returns true for Vim down (j).
+        def vim_down?
+          @code == "j" && @modifiers.empty?
+        end
+
+        # Returns true for Vim up (k).
+        def vim_up?
+          @code == "k" && @modifiers.empty?
+        end
+
+        # Returns true for Vim right (l).
+        def vim_right?
+          @code == "l" && @modifiers.empty?
+        end
+
+        # Returns true for Vim word forward (w).
+        def vim_word_forward?
+          @code == "w" && @modifiers.empty?
+        end
+
+        # Returns true for Vim word backward (b).
+        def vim_word_backward?
+          @code == "b" && @modifiers.empty?
+        end
+
+        # Returns true for Vim go to top (gg pattern, here just g).
+        def vim_top?
+          @code == "g" && @modifiers.empty?
+        end
+
+        # Returns true for Vim go to bottom (G).
+        def vim_bottom?
+          @code == "G" && @modifiers == ["shift"]
+        end
+
+        # Punctuation name predicates - generated at load time for performance.
+        # Maps intuitive names to their symbol characters.
+        # :nodoc:
+        PUNCTUATION_NAMES = {
+          # Navigation shortcuts (the original use case!)
+          tilde: "~",
+          slash: "/",
+          forwardslash: "/",
+          backslash: "\\",
+
+          # Common punctuation
+          comma: ",",
+          period: ".",
+          dot: ".",
+          colon: ":",
+          semicolon: ";",
+
+          # Question and exclamation
+          question: "?",
+          questionmark: "?",
+          exclamation: "!",
+          exclamationmark: "!",
+          exclamationpoint: "!",
+          bang: "!",
+
+          # Programming symbols
+          at: "@",
+          atsign: "@",
+          hash: "#",
+          pound: "#",
+          numbersign: "#",
+          dollar: "$",
+          dollarsign: "$",
+          percent: "%",
+          caret: "^",
+          circumflex: "^",
+          ampersand: "&",
+          asterisk: "*",
+          star: "*",
+
+          # Arithmetic and comparison
+          underscore: "_",
+          hyphen: "-",
+          dash: "-",
+          minus: "-",
+          plus: "+",
+          equals: "=",
+          equalsign: "=",
+          pipe: "|",
+          bar: "|",
+          lessthan: "<",
+          lt: "<",
+          greaterthan: ">",
+          gt: ">",
+
+          # Brackets and parens
+          lparen: "(",
+          leftparen: "(",
+          openparen: "(",
+          leftparenthesis: "(",
+          openparenthesis: "(",
+          rparen: ")",
+          rightparen: ")",
+          closeparen: ")",
+          rightparenthesis: ")",
+          closeparenthesis: ")",
+          lbracket: "[",
+          leftbracket: "[",
+          openbracket: "[",
+          leftsquarebracket: "[",
+          opensquarebracket: "[",
+          rbracket: "]",
+          rightbracket: "]",
+          closebracket: "]",
+          rightsquarebracket: "]",
+          closesquarebracket: "]",
+          lbrace: "{",
+          leftbrace: "{",
+          openbrace: "{",
+          leftcurlybrace: "{",
+          opencurlybrace: "{",
+          rbrace: "}",
+          rightbrace: "}",
+          closebrace: "}",
+          rightcurlybrace: "}",
+          closecurlybrace: "}",
+
+          # Quotes
+          backtick: "`",
+          grave: "`",
+          singlequote: "'",
+          apostrophe: "'",
+          doublequote: "\"",
+        }.freeze
+
+        # Generate predicate methods at load time (faster than method_missing)
+        PUNCTUATION_NAMES.each do |name, char|
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{name}?
+              @code == #{char.inspect}
+            end
+          RUBY
+        end
+
+        # quote? matches both single and double quotes
+        def quote?
+          @code == "'" || @code == "\""
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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,107 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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 windows? 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
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   if event.modifier?
+        #     # Handle solo modifier key press
+        #   end
+        #--
+        # SPDX-SnippetEnd
+        #++
+        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,72 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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: back_tab?/backtab? matches back_tab code even with shift modifier
+          # (since back_tab semantically implies shift)
+          if (key_name == "back_tab" || key_name == "backtab") && @code == "back_tab" && (@modifiers.empty? || @modifiers == ["shift"])
+            return true
+          end
+
+          # 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 = {
+            # Arrow key aliases (disambiguate from Mouse#up? and Mouse#down?)
+            arrow_up: "up",
+            up_arrow: "up",
+            arrow_down: "down",
+            down_arrow: "down",
+            arrow_left: "left",
+            left_arrow: "left",
+            arrow_right: "right",
+            right_arrow: "right",
+            # Other 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