ratatui_ruby 1.2.1 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa64c94e2dded3a4de71ebdff888860a1528f42a4b9a1ed0200361d3a811e715
-  data.tar.gz: aa98fe686ef20f10e310b3a0bc87b60412279d85d1d60befa31c60c3eef5bf01
+  metadata.gz: 859d136b449ee3babaa09dd80f9bfa1507f08146a632564369c6ab2aa3b937c8
+  data.tar.gz: dd7e5cf58b04c81e2b5a0c2eb75e796dbfdcbcdc925d4ee6d6f5eda3fdb15df9
 SHA512:
-  metadata.gz: fab99ab43c386a115027ea204ec578c7d20c1b4bd7ddfeee43d384825f536ed49162ca8957e1c46b994809cbd20137d16857f39c792330148a5b1eb3d69957a3
-  data.tar.gz: c6b42590b5f920d19062e99fef14a92dfffe2a5482a9b3295fc5b73df095336a99c33b782e1ae14fd17027593253f545957919cf8603936842e121e166dd54b7
+  metadata.gz: 75ccfaca2381095492f89c37abfc04530391e6ff31691253cdcd7feb93f12c81bb71bf011dbe00ef34f7cf9a580cf601d5939e592e22949390ebde29721bf05f
+  data.tar.gz: d498466df9bb6af3f4e2c76ce6db58c379a684a8670fa01df1912c621306dc35bdb30c4d1481196b6b493751546d0a03f88bf3be9ac1a888cd80c4c478ae8adc

data/ext/ratatui_ruby/Cargo.lock

@@ -1059,12 +1059,13 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "1.2.1"
+version = "1.3.2"
 dependencies = [
  "bumpalo",
  "lazy_static",
  "magnus",
  "ratatui",
+ "rb-sys",
  "time",
  "unicode-width 0.1.14",
 ]

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "1.2.1"
+version = "1.3.2"
 edition = "2021"
 
 [lib]
@@ -11,6 +11,7 @@ crate-type = ["cdylib", "staticlib"]
 
 [dependencies]
 magnus = "0.8.2"
+rb-sys = "*"
 ratatui = { version = "0.30", features = ["widget-calendar", "layout-cache", "unstable-rendered-line-info", "palette"] }
 unicode-width = "0.1"
 

data/ext/ratatui_ruby/src/events.rs

@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use magnus::{Error, IntoValue, TryConvert, Value};
+use rb_sys::rb_thread_call_without_gvl;
 use std::cell::RefCell;
+use std::os::raw::c_void;
 
 /// Wrapper enum for test events - includes crossterm events and our Sync event.
 #[derive(Debug, Clone)]
@@ -314,6 +316,92 @@ pub fn clear_events() {
     EVENT_QUEUE.with(|q| q.borrow_mut().clear());
 }
 
+/// Result of polling crossterm from outside the GVL.
+///
+/// The blocking I/O (poll + read) happens without the Ruby GVL held,
+/// so other Ruby threads can run concurrently. This enum carries the
+/// result back across the GVL boundary for Ruby object construction.
+#[derive(Debug)]
+enum PollResult {
+    /// A crossterm event was read successfully.
+    Event(ratatui::crossterm::event::Event),
+    /// The timeout expired with no event available.
+    NoEvent,
+    /// An I/O error occurred during poll or read.
+    Error(String),
+}
+
+/// Data passed to the GVL-free polling callback.
+///
+/// The `timeout` field controls the poll behavior:
+/// - `Some(duration)`: poll with a timeout, return `NoEvent` if it expires.
+/// - `None`: block indefinitely until an event arrives.
+struct PollData {
+    timeout: Option<std::time::Duration>,
+    result: PollResult,
+}
+
+/// Polls crossterm for events without the Ruby GVL held.
+///
+/// This is the work function passed to `rb_thread_call_without_gvl`.
+/// It performs blocking I/O that would otherwise starve Ruby threads.
+extern "C" fn poll_without_gvl(data: *mut c_void) -> *mut c_void {
+    // SAFETY: `data` is a valid pointer to `PollData`, passed by
+    // `poll_crossterm_without_gvl` via `rb_thread_call_without_gvl`. The
+    // pointer remains valid for the duration of this callback because the
+    // caller owns the `PollData` on the stack and waits for us to return.
+    let data = unsafe { &mut *data.cast::<PollData>() };
+
+    data.result = match data.timeout {
+        Some(duration) => match ratatui::crossterm::event::poll(duration) {
+            Ok(true) => match ratatui::crossterm::event::read() {
+                Ok(event) => PollResult::Event(event),
+                Err(e) => PollResult::Error(e.to_string()),
+            },
+            Ok(false) => PollResult::NoEvent,
+            Err(e) => PollResult::Error(e.to_string()),
+        },
+        None => match ratatui::crossterm::event::read() {
+            Ok(event) => PollResult::Event(event),
+            Err(e) => PollResult::Error(e.to_string()),
+        },
+    };
+
+    std::ptr::null_mut()
+}
+
+/// Polls crossterm with the GVL released, then converts the result
+/// to a Ruby value after reacquiring the GVL.
+fn poll_crossterm_without_gvl(
+    ruby: &magnus::Ruby,
+    timeout: Option<std::time::Duration>,
+) -> Result<Value, Error> {
+    let mut data = PollData {
+        timeout,
+        result: PollResult::NoEvent,
+    };
+
+    // SAFETY: `data` is a valid stack-local `PollData` whose lifetime
+    // spans this entire call. `poll_without_gvl` only reads/writes
+    // through the pointer while `rb_thread_call_without_gvl` blocks,
+    // and we don't access `data` again until that function returns.
+    unsafe {
+        rb_thread_call_without_gvl(
+            Some(poll_without_gvl),
+            (&raw mut data).cast::<c_void>(),
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+
+    // GVL is now re-held — safe to create Ruby objects.
+    match data.result {
+        PollResult::Event(event) => handle_crossterm_event(event),
+        PollResult::NoEvent => Ok(ruby.qnil().into_value_with(ruby)),
+        PollResult::Error(msg) => Err(Error::new(ruby.exception_runtime_error(), msg)),
+    }
+}
+
 pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value, Error> {
     let event = EVENT_QUEUE.with(|q| {
         let mut queue = q.borrow_mut();
@@ -334,24 +422,8 @@ pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value
         return Ok(ruby.qnil().into_value_with(ruby));
     }
 
-    if let Some(secs) = timeout_val {
-        // Timed poll: wait up to the specified duration
-        let duration = std::time::Duration::from_secs_f64(secs);
-        if ratatui::crossterm::event::poll(duration)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?
-        {
-            let event = ratatui::crossterm::event::read()
-                .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-            handle_crossterm_event(event)
-        } else {
-            Ok(ruby.qnil().into_value_with(ruby))
-        }
-    } else {
-        // Blocking: wait indefinitely for an event
-        let event = ratatui::crossterm::event::read()
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-        handle_crossterm_event(event)
-    }
+    let timeout = timeout_val.map(std::time::Duration::from_secs_f64);
+    poll_crossterm_without_gvl(ruby, timeout)
 }
 
 fn handle_test_event(event: TestEvent) -> Result<Value, Error> {
@@ -559,3 +631,70 @@ fn handle_focus_event(event_type: &str) -> Result<Value, Error> {
     hash.aset(ruby.to_symbol("type"), ruby.to_symbol(event_type))?;
     Ok(hash.into_value_with(&ruby))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn poll_data_defaults_to_no_event() {
+        let data = PollData {
+            timeout: Some(std::time::Duration::from_millis(0)),
+            result: PollResult::NoEvent,
+        };
+        assert!(matches!(data.result, PollResult::NoEvent));
+    }
+
+    #[test]
+    fn poll_data_accepts_none_timeout_for_indefinite_blocking() {
+        let data = PollData {
+            timeout: None,
+            result: PollResult::NoEvent,
+        };
+        assert!(data.timeout.is_none());
+    }
+
+    #[test]
+    fn poll_result_error_preserves_message() {
+        let result = PollResult::Error("connection reset".to_string());
+        match result {
+            PollResult::Error(msg) => assert_eq!(msg, "connection reset"),
+            _ => panic!("Expected PollResult::Error"),
+        }
+    }
+
+    #[test]
+    fn poll_result_event_wraps_crossterm_event() {
+        let key_event =
+            ratatui::crossterm::event::Event::Key(ratatui::crossterm::event::KeyEvent::new(
+                ratatui::crossterm::event::KeyCode::Char('q'),
+                ratatui::crossterm::event::KeyModifiers::empty(),
+            ));
+        let result = PollResult::Event(key_event.clone());
+        match result {
+            PollResult::Event(e) => assert_eq!(format!("{e:?}"), format!("{key_event:?}")),
+            _ => panic!("Expected PollResult::Event"),
+        }
+    }
+
+    #[test]
+    fn poll_without_gvl_returns_no_event_on_zero_timeout() {
+        // With a zero-duration timeout, poll returns immediately with no event.
+        // In headless environments (CI), crossterm may return an Error because
+        // there is no terminal to read from — that's also a valid outcome.
+        let mut data = PollData {
+            timeout: Some(std::time::Duration::from_millis(0)),
+            result: PollResult::Error("sentinel — should be overwritten".to_string()),
+        };
+
+        poll_without_gvl(&mut data as *mut PollData as *mut c_void);
+
+        // The callback must have overwritten the sentinel value.
+        match &data.result {
+            PollResult::Error(msg) if msg == "sentinel — should be overwritten" => {
+                panic!("poll_without_gvl did not write to data.result")
+            }
+            _ => {} // NoEvent, Event, or a *different* Error are all fine.
+        }
+    }
+}

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.2"
 end

data/sig/ratatui_ruby/event.rbs

@@ -67,11 +67,46 @@ module RatatuiRuby
         private def match_system_dwim?: (String key_name, Symbol key_sym) -> bool
       end
 
+      # DWIM predicates for common key patterns
+      module Dwim
+        NAVIGATION_KEYS: Array[String]
+        ARROW_KEYS: Array[String]
+        VIM_MOVEMENT_KEYS: Array[String]
+        PUNCTUATION_NAMES: Hash[Symbol, String]
+
+        def space?: () -> bool
+        def cr?: () -> bool
+        def letter?: () -> bool
+        def digit?: () -> bool
+        def alphanumeric?: () -> bool
+        def punctuation?: () -> bool
+        def whitespace?: () -> bool
+        def interrupt?: () -> bool
+        def eof?: () -> bool
+        def cancel?: () -> bool
+        def sigint?: () -> bool
+        def suspend?: () -> bool
+        def quit?: () -> bool
+        def navigation?: () -> bool
+        def arrow?: () -> bool
+        def vim?: () -> bool
+        def vim_left?: () -> bool
+        def vim_down?: () -> bool
+        def vim_up?: () -> bool
+        def vim_right?: () -> bool
+        def vim_word_forward?: () -> bool
+        def vim_word_backward?: () -> bool
+        def vim_top?: () -> bool
+        def vim_bottom?: () -> bool
+        def quote?: () -> bool
+      end
+
       include Character
       include Modifier
       include Media
       include Navigation
       include System
+      include Dwim
 
       attr_reader code: String
       attr_reader modifiers: Array[String]
@@ -114,6 +149,23 @@ module RatatuiRuby
       def left?: () -> bool
       def right?: () -> bool
       def middle?: () -> bool
+      def scroll?: () -> bool
+      def moved?: () -> bool
+      def hover?: () -> bool
+      def hovering?: () -> bool
+      def move?: () -> bool
+      def primary?: () -> bool
+      def secondary?: () -> bool
+      def context_menu?: () -> bool
+      def aux?: () -> bool
+      def auxiliary?: () -> bool
+      def wheel_up?: () -> bool
+      def wheel_down?: () -> bool
+      def release?: () -> bool
+      def released?: () -> bool
+      def press?: () -> bool
+      def pressed?: () -> bool
+      def dragging?: () -> bool
       def to_sym: () -> Symbol
       def ==: (top other) -> bool
       def deconstruct_keys: (Array[Symbol]?) -> { type: :mouse, kind: String, x: Integer, y: Integer, button: String, modifiers: Array[String] }
@@ -127,6 +179,20 @@ module RatatuiRuby
       def to_sym: () -> Symbol
       def ==: (top other) -> bool
       def deconstruct_keys: (Array[Symbol]?) -> { type: :resize, width: Integer, height: Integer }
+
+      # DWIM predicates
+      VT100_WIDTH: Integer
+      VT100_HEIGHT: Integer
+      def sigwinch?: () -> bool
+      def winch?: () -> bool
+      def sig_winch?: () -> bool
+      def landscape?: () -> bool
+      def portrait?: () -> bool
+      def vt100?: () -> bool
+      def at_least_vt100?: () -> bool
+      def over_vt100?: () -> bool
+      def cramped?: () -> bool
+      def constrained?: () -> bool
     end
 
     class Paste < Event
@@ -134,14 +200,45 @@ module RatatuiRuby
 
       def initialize: (content: String) -> void
       def deconstruct_keys: (Array[Symbol]?) -> { type: :paste, content: String }
+
+      # DWIM predicates
+      def clipboard?: () -> bool
+      def pasteboard?: () -> bool
+      def pasted?: () -> bool
+      def empty?: () -> bool
+      def blank?: () -> bool
+      def multiline?: () -> bool
+      def multi_line?: () -> bool
+      def single_line?: () -> bool
+      def singleline?: () -> bool
     end
 
     class FocusGained < Event
       def deconstruct_keys: (Array[Symbol]?) -> { type: :focus_gained }
+
+      # DWIM predicates
+      def focus?: () -> bool
+      def gained?: () -> bool
+      def lost?: () -> bool
+      def blur?: () -> bool
+      def active?: () -> bool
+      def inactive?: () -> bool
+      def foreground?: () -> bool
+      def background?: () -> bool
     end
 
     class FocusLost < Event
       def deconstruct_keys: (Array[Symbol]?) -> { type: :focus_lost }
+
+      # DWIM predicates
+      def focus?: () -> bool
+      def gained?: () -> bool
+      def lost?: () -> bool
+      def blur?: () -> bool
+      def active?: () -> bool
+      def inactive?: () -> bool
+      def foreground?: () -> bool
+      def background?: () -> bool
     end
 
     class None < Event

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.2
 platform: ruby
 authors:
 - Kerrick Long
@@ -474,6 +474,7 @@ files:
 - lib/ratatui_ruby/event/focus_lost.rb
 - lib/ratatui_ruby/event/key.rb
 - lib/ratatui_ruby/event/key/character.rb
+- lib/ratatui_ruby/event/key/dwim.rb
 - lib/ratatui_ruby/event/key/media.rb
 - lib/ratatui_ruby/event/key/modifier.rb
 - lib/ratatui_ruby/event/key/navigation.rb