ratatui_ruby 1.2.1 → 1.3.0

data/lib/ratatui_ruby/event/focus_gained.rb

@@ -70,6 +70,56 @@ module RatatuiRuby
       def ==(other)
         other.is_a?(FocusGained)
       end
+
+      # =========================================================================
+      # DWIM Predicates
+      # =========================================================================
+
+      # Returns true. The terminal window is now in focus.
+      #
+      #   event.focus? # => true
+      def focus?
+        true
+      end
+      alias focused? focus?
+
+      # Returns true. The application gained focus.
+      #
+      #   event.gained? # => true
+      def gained?
+        true
+      end
+
+      # Returns false. This is not a focus lost event.
+      #
+      #   event.lost? # => false
+      def lost?
+        false
+      end
+
+      # Returns false. Blur is the opposite of focus gained.
+      #
+      #   event.blur? # => false
+      def blur?
+        false
+      end
+      alias blurred? blur?
+
+      # Returns true. The application is active.
+      #
+      #   event.active? # => true
+      def active?
+        true
+      end
+      alias foreground? active?
+
+      # Returns false. The application is not inactive.
+      #
+      #   event.inactive? # => false
+      def inactive?
+        false
+      end
+      alias background? inactive?
     end
   end
 end

data/lib/ratatui_ruby/event/focus_lost.rb

@@ -71,6 +71,57 @@ module RatatuiRuby
       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/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/modifier.rb

@@ -40,6 +40,8 @@ module RatatuiRuby
         # Alias for {#super?}.
         alias win? super?
         # Alias for {#super?}.
+        alias windows? super?
+        # Alias for {#super?}.
         alias command? super?
         # Alias for {#super?}.
         alias cmd? super?

data/lib/ratatui_ruby/event/key.rb

@@ -6,6 +6,7 @@
 #++
 
 require_relative "key/character"
+require_relative "key/dwim"
 require_relative "key/media"
 require_relative "key/modifier"
 require_relative "key/navigation"
@@ -88,6 +89,7 @@ module RatatuiRuby
     # These keys will not work in Terminal.app, iTerm2, or GNOME Terminal.
     class Key < Event
       include Character
+      include Dwim
       include Media
       include Modifier
       include Navigation
@@ -435,6 +437,13 @@ module RatatuiRuby
           normalized_code = @code.delete("_")
           return true if normalized_predicate == normalized_code && @modifiers.empty?
 
+          # DWIM: Underscore variants delegate to existing methods
+          # space_bar? → spacebar? → space?, sig_int? → sigint?
+          normalized_method = :"#{normalized_predicate}?"
+          if normalized_method != name && respond_to?(normalized_method)
+            return public_send(normalized_method)
+          end
+
           false
         else
           super

data/lib/ratatui_ruby/event/mouse.rb

@@ -253,6 +253,39 @@ module RatatuiRuby
         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/paste.rb

@@ -67,6 +67,9 @@ module RatatuiRuby
       def paste?
         true
       end
+      alias clipboard? paste?
+      alias pasteboard? paste?
+      alias pasted? paste?
 
       # Creates a new Paste event.
       #
@@ -100,6 +103,28 @@ module RatatuiRuby
         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

@@ -151,6 +151,71 @@ module RatatuiRuby
         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

data/lib/ratatui_ruby/version.rb

@@ -8,5 +8,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 end