ratatui_ruby 0.8.0 → 0.9.1

data/lib/ratatui_ruby/event/mouse.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -20,9 +20,17 @@ module RatatuiRuby
     #
     # === 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>).
       #
@@ -38,8 +46,16 @@ module RatatuiRuby
       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.
@@ -49,9 +65,17 @@ module RatatuiRuby
 
       # 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
@@ -98,19 +122,35 @@ module RatatuiRuby
 
       # 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
 
       # 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

data/lib/ratatui_ruby/event/none.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -23,10 +23,18 @@ module RatatuiRuby
     #
     # === 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

data/lib/ratatui_ruby/event/paste.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -20,15 +20,31 @@ module RatatuiRuby
     # === 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.
       #
@@ -37,9 +53,17 @@ module RatatuiRuby
 
       # 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
@@ -54,10 +78,18 @@ module RatatuiRuby
 
       # 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

data/lib/ratatui_ruby/event/resize.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -21,15 +21,31 @@ module RatatuiRuby
     # === 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.
       #
@@ -43,9 +59,17 @@ module RatatuiRuby
 
       # 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
@@ -63,10 +87,18 @@ module RatatuiRuby
 
       # 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

data/lib/ratatui_ruby/event/sync.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Event
+    # Synthetic event for synchronizing async operations in tests.
+    #
+    # Testing async behavior is tricky. You inject an event, but results arrive
+    # later. By the time you assert, the async work may not have completed.
+    #
+    # When a runtime (Tea, Kit) encounters this event, it should wait for all
+    # pending async operations to complete before processing the next event.
+    # This enables deterministic testing without changing production code paths.
+    #
+    # Inject this event between user actions and assertions to ensure async
+    # results have been processed:
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   inject_key("s")           # Triggers async command
+    #   inject_sync               # Wait for command to complete
+    #   inject_key(:q)            # Quit after seeing results
+    #   Tea.run(...)
+    #   assert_snapshots("after_s_with_results")
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # This is not "test mode"—it's a real event that runtimes handle.
+    # Production apps could use it too (e.g., "ensure saves complete before quit").
+    class Sync < Event
+      # Returns true for Sync events.
+      def sync?
+        true
+      end
+
+      # Deconstructs the event for pattern matching.
+      def deconstruct_keys(keys)
+        { type: :sync }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -26,6 +26,11 @@ module RatatuiRuby
   # Use <tt>case...in</tt> to dispatch on every possible event type. This ensures
   # you handle every case without needing an +else+ clause:
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   case RatatuiRuby.poll_event
   #   in { type: :key, code: "q" }
   #     break
@@ -47,10 +52,18 @@ module RatatuiRuby
   #     # Idle
   #   end
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   # == Predicates
   #
   # Check event types with predicates without pattern matching:
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   event = RatatuiRuby.poll_event
   #   if event.key?
   #     puts "Key pressed"
@@ -59,6 +72,9 @@ module RatatuiRuby
   #   elsif event.mouse?
   #     puts "Mouse event"
   #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
   class Event
     # Returns true if this is a None event.
     def none?
@@ -95,6 +111,11 @@ module RatatuiRuby
       false
     end
 
+    # Returns true if this is a Sync event.
+    def sync?
+      false
+    end
+
     # Responds to dynamic predicate methods for key checks.
     # All non-Key events return false for any key predicate.
     def method_missing(name, *args, &block)
@@ -114,10 +135,18 @@ module RatatuiRuby
     #
     # Keys argument is unused but required by the protocol.
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   case event
     #   in type: :key, code:
     #     puts "Key: #{code}"
     #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
     def deconstruct_keys(keys)
       {}
     end
@@ -131,3 +160,4 @@ require_relative "event/resize"
 require_relative "event/paste"
 require_relative "event/focus_gained"
 require_relative "event/focus_lost"
+require_relative "event/sync"

data/lib/ratatui_ruby/frame.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -30,13 +30,26 @@ module RatatuiRuby
   #
   # Basic usage with a single widget:
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   RatatuiRuby.draw do |frame|
   #     paragraph = RatatuiRuby::Widgets::Paragraph.new(text: "Hello, world!")
   #     frame.render_widget(paragraph, frame.area)
   #   end
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   # Using Layout.split for multi-region layouts:
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   RatatuiRuby.draw do |frame|
   #     sidebar, main = RatatuiRuby::Layout.split(
   #       frame.area,
@@ -53,6 +66,9 @@ module RatatuiRuby
   #     # Store rects for hit testing — no duplication!
   #     @regions = { sidebar: sidebar, main: main }
   #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
   class Frame
     ##
     # :method: area
@@ -65,10 +81,18 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.draw do |frame|
     #     puts "Terminal size: #{frame.area.width}x#{frame.area.height}"
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # (Native method implemented in Rust)
 
     ##
@@ -83,15 +107,31 @@ module RatatuiRuby
     # [widget]
     #   The widget to render (Paragraph, Layout, List, Table, etc.).
     # [area]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   A Rect specifying where to render the widget.
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.draw do |frame|
     #     para = RatatuiRuby::Widgets::Paragraph.new(text: "Content")
     #     frame.render_widget(para, frame.area)
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # (Native method implemented in Rust)
 
     ##
@@ -116,10 +156,23 @@ module RatatuiRuby
     # [area]
     #   The Rect area to render into.
     # [state]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   The mutable state object (Output) (e.g., RatatuiRuby::ListState).
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   # Initialize state once (outside the loop)
     #   @list_state = RatatuiRuby::ListState.new
     #
@@ -131,6 +184,9 @@ module RatatuiRuby
     #   # Read back the offset calculated by Ratatui
     #   puts @list_state.offset
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # (Native method implemented in Rust)
 
     ##
@@ -151,12 +207,25 @@ module RatatuiRuby
     # [x]
     #   Column position (<tt>0</tt> = leftmost column).
     # [y]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   Row position (<tt>0</tt> = topmost row).
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Example
     #
     # Position the cursor at the end of typed text in a login form:
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   PREFIX = "Username: [ "
     #   username = "alice"
     #
@@ -175,6 +244,9 @@ module RatatuiRuby
     #     frame.set_cursor_position(cursor_x, cursor_y)
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # See also:
     # - {Component-based implementation using Frame API}[link:/examples/app_color_picker/app_rb.html]
     # - {Declarative implementation using Tree API}[link:/examples/app_login_form/app_rb.html]