ratatui_ruby-tea 0.3.0 → 0.3.1

data/lib/ratatui_ruby/tea/router.rb

@@ -39,6 +39,27 @@ module RatatuiRuby
     #     UPDATE = from_router
     #   end
     module Router
+      # Configuration for key handlers.
+      KeyHandlerConfig = Data.define(:handler, :action, :route, :guard) do
+        def initialize(handler: nil, action: nil, route: nil, guard: nil)
+          super
+        end
+      end
+
+      # Configuration for scroll handlers (no coordinates).
+      ScrollHandlerConfig = Data.define(:handler, :action) do
+        def initialize(handler: nil, action: nil)
+          super
+        end
+      end
+
+      # Configuration for click handlers (x, y coordinates).
+      ClickHandlerConfig = Data.define(:handler, :action) do
+        def initialize(handler: nil, action: nil)
+          super
+        end
+      end
+
       # :nodoc:
       def self.included(base)
         base.extend(ClassMethods)
@@ -90,11 +111,6 @@ module RatatuiRuby
           @key_handlers = builder.handlers
         end
 
-        # Returns the registered key handlers hash.
-        def key_handlers
-          @key_handlers ||= {}
-        end
-
         # Declares mouse handlers in a block.
         #
         # === Example
@@ -106,12 +122,23 @@ module RatatuiRuby
         def mousemap(&)
           builder = MousemapBuilder.new
           builder.instance_eval(&)
-          @mouse_handlers = builder.handlers
+          @scroll_handlers = builder.scroll_handlers
+          @click_handler = builder.click_handler
         end
 
-        # Returns the registered mouse handlers hash.
-        def mouse_handlers
-          @mouse_handlers ||= {}
+        # Returns the registered key handlers hash.
+        private def key_handlers
+          @key_handlers ||= {}
+        end
+
+        # Returns the registered scroll handlers hash.
+        private def scroll_handlers
+          @scroll_handlers ||= {}
+        end
+
+        # Returns the registered click handler, if any.
+        private def click_handler
+          @click_handler
         end
 
         # Generates an UPDATE lambda from routes, keymap, and mousemap.
@@ -122,73 +149,106 @@ module RatatuiRuby
         # 3. Handles mouse events via mousemap
         # 4. Returns model unchanged for unhandled messages
         def from_router
-          my_routes = routes
-          my_actions = actions
-          my_key_handlers = key_handlers
-          my_mouse_handlers = mouse_handlers
-
-          lambda do |message, model|
-            # 1. Try routing prefixed messages to children
-            my_routes.each do |prefix, child|
-              result = Tea.delegate(message, prefix, child::UPDATE, model.public_send(prefix))
-              if result
-                new_child, command = result
-                return [model.with(prefix => new_child), command]
-              end
+          RouterUpdate.new(
+            routes:,
+            actions:,
+            key_handlers:,
+            scroll_handlers:,
+            click_handler:
+          )
+        end
+      end
+
+      # Internal UPDATE callable with proper typing.
+      class RouterUpdate # :nodoc:
+        def initialize(routes:, actions:, key_handlers:, scroll_handlers:, click_handler:)
+          @routes = routes
+          @actions = actions
+          @key_handlers = key_handlers
+          @scroll_handlers = scroll_handlers
+          @click_handler = click_handler
+        end
+
+        # Process message and return [model, command] tuple.
+        def call(message, model)
+          # 1. Try routing prefixed messages to child bags
+          @routes.each do |prefix, bag|
+            bag_update = bag.const_get(:UPDATE)
+            result = Tea.delegate(message, prefix, bag_update, model.public_send(prefix))
+            if result
+              new_bag_model, command = result
+              return [model.with(prefix => new_bag_model), command] #: [_DataModel, Command::execution?]
             end
+          end
 
-            # 2. Try keymap handlers (message is an Event)
-            if message.respond_to?(:key?) && message.key?
-              my_key_handlers.each do |key_name, config|
-                predicate = :"#{key_name}?"
-                next unless message.respond_to?(predicate) && message.public_send(predicate)
+          # 2. Try keymap handlers (message is an Event::Key)
+          if message.is_a?(RatatuiRuby::Event::Key)
+            @key_handlers.each do |key_name, config|
+              predicate = :"#{key_name}?"
+              next unless message.respond_to?(predicate) && message.public_send(predicate)
 
-                # Check guard if present
-                if (config[:guard]) && !config[:guard].call(model)
-                  next
-                end
+              # Check guard if present
+              if (config.guard) && !config.guard.call(model)
+                next
+              end
 
-                handler = config[:handler] || my_actions[config[:action]]
-                command = handler.call
-                if config[:route]
-                  command = Tea.route(command, config[:route])
-                end
-                return [model, command]
+              # Get handler - either inline or from actions registry
+              handler = config.handler
+              if handler.nil? && config.action
+                handler = @actions[config.action]
+              end
+              next unless handler
+
+              command = handler.call
+              if command && config.route
+                command = Tea.route(command, config.route)
               end
+              return [model, command] #: [_DataModel, Command::execution?]
             end
+          end
 
-            # 3. Try mousemap handlers
-            if message.respond_to?(:mouse?) && message.mouse?
-              # Scroll events
-              if message.respond_to?(:scroll_up?) && message.scroll_up?
-                config = my_mouse_handlers[:scroll_up]
-                if config
-                  handler = config[:handler] || my_actions[config[:action]]
-                  return [model, handler.call]
+          # 3. Try mousemap handlers (message is an Event::Mouse)
+          if message.is_a?(RatatuiRuby::Event::Mouse)
+            # Scroll events (handler takes no arguments)
+            if message.scroll_up?
+              config = @scroll_handlers[:scroll_up]
+              if config
+                scroll_handler = config.handler
+                if scroll_handler.nil? && config.action
+                  scroll_handler = @actions[config.action]
                 end
+                return [model, scroll_handler&.call] #: [_DataModel, Command::execution?]
               end
-              if message.respond_to?(:scroll_down?) && message.scroll_down?
-                config = my_mouse_handlers[:scroll_down]
-                if config
-                  handler = config[:handler] || my_actions[config[:action]]
-                  return [model, handler.call]
+            end
+            if message.scroll_down?
+              config = @scroll_handlers[:scroll_down]
+              if config
+                scroll_handler = config.handler
+                if scroll_handler.nil? && config.action
+                  scroll_handler = @actions[config.action]
                 end
+                return [model, scroll_handler&.call] #: [_DataModel, Command::execution?]
               end
-              # Click events
-              if message.respond_to?(:click?) && message.click?
-                config = my_mouse_handlers[:click]
-                if config
-                  handler = config[:handler] || my_actions[config[:action]]
-                  return [model, handler.call(message.x, message.y)]
-                end
+            end
+            # Click events (handler takes x, y coordinates)
+            click_config = @click_handler
+            if message.down? && click_config
+              click_handler_proc = click_config.handler
+              if click_handler_proc.nil? && click_config.action
+                # Actions don't take coordinates, so just call without args
+                action_handler = @actions[click_config.action]
+                return [model, action_handler&.call] #: [_DataModel, Command::execution?]
+              elsif click_handler_proc
+                return [model, click_handler_proc.call(message.x, message.y)] #: [_DataModel, Command::execution?]
               end
             end
-
-            # 4. Unhandled - return model unchanged
-            [model, nil]
           end
+
+          # 4. Unhandled - return model unchanged
+          [model, nil] #: [_DataModel, Command::execution?]
         end
       end
+      private_constant :RouterUpdate
 
       # Builder for keymap DSL.
       class KeymapBuilder
@@ -209,13 +269,13 @@ module RatatuiRuby
         # [when/if/only/guard] Guard that runs if truthy (aliases).
         # [unless/except/skip] Guard that runs if falsy (negative aliases).
         def key(key_name, handler_or_action, route: nil, when: nil, if: nil, only: nil, guard: nil, unless: nil, except: nil, skip: nil)
-          entry = {}
+          handler = nil
+          action = nil
           if handler_or_action.is_a?(Symbol)
-            entry[:action] = handler_or_action
+            action = handler_or_action
           else
-            entry[:handler] = handler_or_action
+            handler = handler_or_action
           end
-          entry[:route] = route if route
 
           guards = @guard_stack.dup
 
@@ -232,11 +292,16 @@ module RatatuiRuby
             guards << -> (model) { !negative.call(model) }
           end
 
-          if guards.any?
-            entry[:guard] = -> (model) { guards.all? { |g| g.call(model) } }
+          combined_guard = if guards.any?
+            -> (model) { guards.all? { |g| g.call(model) } }
           end
 
-          @handlers[key_name.to_s] = entry
+          @handlers[key_name.to_s] = KeyHandlerConfig.new(
+            handler:,
+            action:,
+            route:,
+            guard: combined_guard
+          )
         end
 
         # Applies a guard to all keys in the block.
@@ -299,37 +364,40 @@ module RatatuiRuby
 
       # Builder for mousemap DSL.
       class MousemapBuilder
-        # Returns the registered handlers hash.
-        attr_reader :handlers
+        # Returns the registered scroll handlers (scroll_up, scroll_down).
+        attr_reader :scroll_handlers
+
+        # Returns the registered click handler.
+        attr_reader :click_handler
 
         # :nodoc:
         def initialize
-          @handlers = {}
+          @scroll_handlers = {}
+          @click_handler = nil
         end
 
         # Registers a click handler.
         #
-        # [handler_or_action] Callable or Symbol (action name).
+        # [handler_or_action] Callable `^(Integer, Integer) -> Command` or Symbol (action name).
         def click(handler_or_action)
-          register(:click, handler_or_action)
+          if handler_or_action.is_a?(Symbol)
+            @click_handler = ClickHandlerConfig.new(action: handler_or_action)
+          else
+            @click_handler = ClickHandlerConfig.new(handler: handler_or_action)
+          end
         end
 
         # Registers a scroll handler.
         #
         # [direction] <tt>:up</tt> or <tt>:down</tt>.
-        # [handler_or_action] Callable or Symbol (action name).
+        # [handler_or_action] Callable `^() -> Command` or Symbol (action name).
         def scroll(direction, handler_or_action)
-          register(:"scroll_#{direction}", handler_or_action)
-        end
-
-        private def register(key, handler_or_action)
-          entry = {}
-          if handler_or_action.is_a?(Symbol)
-            entry[:action] = handler_or_action
+          config = if handler_or_action.is_a?(Symbol)
+            ScrollHandlerConfig.new(action: handler_or_action)
           else
-            entry[:handler] = handler_or_action
+            ScrollHandlerConfig.new(handler: handler_or_action)
           end
-          @handlers[key] = entry
+          @scroll_handlers[:"scroll_#{direction}"] = config
         end
       end
     end

data/lib/ratatui_ruby/tea/runtime.rb

@@ -54,7 +54,8 @@ module RatatuiRuby
         end
 
         queue = Queue.new
-        pending_threads = []
+        pending_threads = [] #: Array[Thread]
+        active_commands = {} #: Hash[Command::_Command, active_entry]
 
         catch(:quit) do
           RatatuiRuby.run do |tui|
@@ -75,7 +76,7 @@ module RatatuiRuby
                 validate_ractor_shareable!(model, "model")
                 throw :quit if command.is_a?(Command::Exit)
 
-                thread = dispatch(command, queue) if command
+                thread = dispatch(command, queue, active_commands) if command
                 pending_threads << thread if thread
               end
 
@@ -89,6 +90,9 @@ module RatatuiRuby
                   pending_threads.each(&:join)
                   pending_threads.clear
 
+                  # Yield to ensure any final queue writes are visible
+                  Thread.pass
+
                   # Process all pending queue items
                   until queue.empty?
                     begin
@@ -98,7 +102,7 @@ module RatatuiRuby
                       validate_ractor_shareable!(model, "model")
                       throw :quit if command.is_a?(Command::Exit)
 
-                      thread = dispatch(command, queue) if command
+                      thread = dispatch(command, queue, active_commands) if command
                       pending_threads << thread if thread
                     rescue ThreadError
                       break
@@ -116,7 +120,7 @@ module RatatuiRuby
                   validate_ractor_shareable!(model, "model")
                   throw :quit if command.is_a?(Command::Exit)
 
-                  thread = dispatch(command, queue) if command
+                  thread = dispatch(command, queue, active_commands) if command
                   pending_threads << thread if thread
                 rescue ThreadError
                   break
@@ -126,6 +130,30 @@ module RatatuiRuby
           end
         end
 
+        # Shutdown: signal all, wait grace periods, then kill
+        active_commands.each do |handle, entry|
+          entry[:token].cancel!
+          grace = handle.tea_cancellation_grace_period
+          if grace.finite?
+            deadline = Time.now + grace
+            sleep 0.02 while entry[:thread].alive? && Time.now < deadline
+            entry[:thread].kill if entry[:thread].alive?
+          else
+            entry[:thread].join
+          end
+        end
+
+        # Process any final messages from completed commands
+        until queue.empty?
+          begin
+            background_message = queue.pop(true)
+            result = update.call(background_message, model)
+            model, = normalize_update_result(result, model)
+          rescue ThreadError
+            break
+          end
+        end
+
         model
       end
 
@@ -140,26 +168,52 @@ module RatatuiRuby
           "View returned nil. Return a widget, or use TUI#clear for an empty screen."
       end
 
-      # Detects whether +result+ is a +[model, command]+ tuple, a plain model, or a Command alone.
+      # Extracts [model, command] from update result.
       #
-      # Returns +[model, command]+ in all cases.
+      # Uses is_a? checks for type narrowing. The result parameter is untyped
+      # because the method performs runtime type detection.
+      #
+      # @param result [Array, Command::execution, Object] The update result
+      # @param previous_model [Model] Fallback model if result is a command
+      # @return [Array(Object, Command::execution?)] The [model, command] tuple
       private_class_method def self.normalize_update_result(result, previous_model)
-        return result if result.is_a?(Array) && result.size == 2 && valid_command?(result[1])
-        return [previous_model, result] if valid_command?(result)
+        # Case 0: Nil result - preserve previous model
+        return [previous_model, nil] if result.nil?
 
-        [result, nil]
-      end
+        # Case 1: Already a [model, command] tuple
+        if result.is_a?(Array) && (result.size == 2)
+          model = result[0]
+          command = result[1]
+          # Verify the second element is a valid command (nil, built-in, or custom)
+          if command.nil? ||
+              command.class.name&.start_with?("RatatuiRuby::Tea::Command::") ||
+              (command.respond_to?(:tea_command?) && command.tea_command?)
 
-      # Returns +true+ if +value+ is a valid command (+nil+ or a +Command+ type).
-      private_class_method def self.valid_command?(value)
-        value.nil? || value.class.name&.start_with?("RatatuiRuby::Tea::Command::")
+            return [model, command]
+          end
+        end
+
+        # Case 2: Result is a Command - use previous model
+        if result.class.name&.start_with?("RatatuiRuby::Tea::Command::")
+          return [previous_model, result]
+        end
+        if result.respond_to?(:tea_command?) && result.tea_command?
+          return [previous_model, result]
+        end
+
+        # Case 3: Result is the new model
+        [result, nil]
       end
 
       # Validates an object is Ractor-shareable (deeply frozen).
       #
       # Models and messages must be shareable for future Ractor support.
       # Mutable objects cause race conditions. Freeze your data.
+      #
+      # Only enforced in debug mode (and tests). Production skips this check
+      # for performance; mutable objects will still cause bugs, but silently.
       private_class_method def self.validate_ractor_shareable!(object, name)
+        return unless RatatuiRuby::Debug.enabled?
         return if Ractor.shareable?(object)
 
         raise RatatuiRuby::Error::Invariant,
@@ -170,47 +224,37 @@ module RatatuiRuby
       #
       # Spawns a background thread and pushes results to the message queue.
       # See Command.system for message formats.
-      private_class_method def self.dispatch(command, queue)
+      private_class_method def self.dispatch(command, queue, active_commands = {})
         case command
-        when Command::System
-          Thread.new do
-            require "open3"
-            if command.stream?
-              begin
-                Open3.popen3(command.command) do |stdin, stdout, stderr, wait_thr|
-                  stdin.close
-                  stdout_thread = Thread.new do
-                    stdout.each_line do |line|
-                      queue << Ractor.make_shareable([command.tag, :stdout, line])
-                    end
-                  end
-                  stderr_thread = Thread.new do
-                    stderr.each_line do |line|
-                      queue << Ractor.make_shareable([command.tag, :stderr, line])
-                    end
-                  end
-                  stdout_thread.join
-                  stderr_thread.join
-                  status = wait_thr.value.exitstatus
-                  queue << Ractor.make_shareable([command.tag, :complete, { status: }])
-                end
-              rescue Errno::ENOENT, Errno::EACCES => e
-                queue << Ractor.make_shareable([command.tag, :error, { message: e.message }])
-              end
+        when Command::Cancel
+          entry = active_commands[command.handle]
+          if entry && entry[:thread].alive?
+            entry[:token].cancel!
+            grace = command.handle.tea_cancellation_grace_period
+            if grace.finite?
+              deadline = Time.now + grace
+              sleep 0.02 while entry[:thread].alive? && Time.now < deadline
+              entry[:thread].kill if entry[:thread].alive?
             else
-              stdout, stderr, status = Open3.capture3(command.command)
-              message = [command.tag, { stdout:, stderr:, status: status.exitstatus }]
-              queue << Ractor.make_shareable(message)
+              entry[:thread].join
             end
           end
-        when Command::Mapped
-          inner_queue = Queue.new
-          inner_thread = dispatch(command.inner_command, inner_queue)
-          Thread.new do
-            inner_thread&.join
-            inner_message = inner_queue.pop
-            transformed = command.mapper.call(inner_message)
-            queue << Ractor.make_shareable(transformed)
+          active_commands.delete(command.handle)
+          nil
+        else
+          # Custom command (responds to tea_command?)
+          if command.respond_to?(:tea_command?) && command.tea_command?
+            token = Command::CancellationToken.new
+            outlet = Command::Outlet.new(queue)
+
+            thread = Thread.new do
+              command.call(outlet, token)
+            rescue => e
+              queue << Command::Error.new(command:, exception: e)
+            end
+
+            active_commands[command] = { thread:, token: }
+            thread
           end
         end
       end

data/lib/ratatui_ruby/tea/version.rb

@@ -9,6 +9,6 @@ module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
   module Tea
     # The version of this gem.
     # See https://semver.org/spec/v2.0.0.html
-    VERSION = "0.3.0"
+    VERSION = "0.3.1"
   end
 end

data/rbs_collection.lock.yaml

@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+path: ".gem_rbs_collection"
+gems:
+- name: base64
+  version: 0.3.0
+  source:
+    type: rubygems
+- name: bigdecimal
+  version: '0'
+  source:
+    type: stdlib
+- name: csv
+  version: '0'
+  source:
+    type: stdlib
+- name: dbm
+  version: '0'
+  source:
+    type: stdlib
+- name: erb
+  version: '0'
+  source:
+    type: stdlib
+- name: ffi
+  version: 1.17.3
+  source:
+    type: rubygems
+- name: fileutils
+  version: '0'
+  source:
+    type: stdlib
+- name: forwardable
+  version: '0'
+  source:
+    type: stdlib
+- name: io-console
+  version: '0'
+  source:
+    type: stdlib
+- name: json
+  version: '0'
+  source:
+    type: stdlib
+- name: logger
+  version: '0'
+  source:
+    type: stdlib
+- name: minitest
+  version: '0'
+  source:
+    type: stdlib
+- name: monitor
+  version: '0'
+  source:
+    type: stdlib
+- name: mutex_m
+  version: 0.3.0
+  source:
+    type: rubygems
+- name: optparse
+  version: '0'
+  source:
+    type: stdlib
+- name: pp
+  version: '0'
+  source:
+    type: stdlib
+- name: prettyprint
+  version: '0'
+  source:
+    type: stdlib
+- name: prism
+  version: 1.7.0
+  source:
+    type: rubygems
+- name: pstore
+  version: '0'
+  source:
+    type: stdlib
+- name: psych
+  version: '0'
+  source:
+    type: stdlib
+- name: ratatui_ruby
+  version: 0.10.1
+  source:
+    type: rubygems
+- name: ratatui_ruby-devtools
+  version: 0.1.0
+  source:
+    type: rubygems
+- name: rbs
+  version: 3.10.2
+  source:
+    type: rubygems
+- name: rdoc
+  version: '0'
+  source:
+    type: stdlib
+- name: securerandom
+  version: '0'
+  source:
+    type: stdlib
+- name: stringio
+  version: '0'
+  source:
+    type: stdlib
+- name: strscan
+  version: '0'
+  source:
+    type: stdlib
+- name: tsort
+  version: '0'
+  source:
+    type: stdlib
+- name: uri
+  version: '0'
+  source:
+    type: stdlib
+gemfile_lock_path: Gemfile.lock

data/rbs_collection.yaml

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# RBS collection configuration
+# See: https://github.com/ruby/rbs/blob/master/docs/collection.md
+
+sources:
+  - type: stdlib
+  - type: rubygems
+
+path: .gem_rbs_collection
+
+gems:
+  - name: ratatui_ruby