ratatui_ruby-tea 0.2.0 → 0.3.0

data/lib/ratatui_ruby/tea/command.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    # Commands represent side effects.
+    #
+    # The MVU pattern separates logic from effects. Your update function returns a pure
+    # model transformation. Side effects go in commands. The runtime executes them.
+    #
+    # Commands produce **messages**, not callbacks. The +tag+ argument names the message
+    # so your update function can pattern-match on it. This keeps all logic in +update+
+    # and ensures messages are Ractor-shareable.
+    #
+    # === Examples
+    #
+    #   # Terminate the application
+    #   [model, Command.exit]
+    #
+    #   # Run a shell command; produces [:got_files, {stdout:, stderr:, status:}]
+    #   [model, Command.system("ls -la", :got_files)]
+    #
+    #   # No side effect
+    #   [model, nil]
+    module Command
+      # Sentinel value for application termination.
+      #
+      # The runtime detects this before dispatching. It breaks the loop immediately.
+      Exit = Data.define
+
+      # Creates a quit command.
+      #
+      # Returns a sentinel the runtime detects to terminate the application.
+      #
+      # === Example
+      #
+      #   def update(message, model)
+      #     case message
+      #     in { type: :key, code: "q" }
+      #       [model, Command.exit]
+      #     else
+      #       [model, nil]
+      #     end
+      #   end
+      def self.exit
+        Exit.new
+      end
+
+      # Command to run a shell command via Open3.
+      #
+      # The runtime executes the command and produces messages. In batch mode
+      # (default), a single message arrives: <tt>[tag, {stdout:, stderr:, status:}]</tt>.
+      #
+      # In streaming mode, messages arrive incrementally:
+      # - <tt>[tag, :stdout, line]</tt> for each stdout line
+      # - <tt>[tag, :stderr, line]</tt> for each stderr line
+      # - <tt>[tag, :complete, {status:}]</tt> when the command finishes
+      # - <tt>[tag, :error, {message:}]</tt> if the command cannot start
+      #
+      # The <tt>status</tt> is the integer exit code (0 = success).
+      System = Data.define(:command, :tag, :stream) do
+        # Returns true if streaming mode is enabled.
+        def stream?
+          stream
+        end
+      end
+
+      # Creates a shell execution command.
+      #
+      # [command] Shell command string to execute.
+      # [tag] Symbol or class to tag the result message.
+      # [stream] If <tt>true</tt>, the runtime sends incremental stdout/stderr
+      #   messages as they arrive. If <tt>false</tt> (default), waits for
+      #   completion and sends a single message with all output.
+      #
+      # === Example (Batch Mode)
+      #
+      #   # Return this from update:
+      #   [model.with(loading: true), Command.system("ls -la", :got_files)]
+      #
+      #   # Then handle it later:
+      #   def update(message, model)
+      #     case message
+      #     in [:got_files, {stdout:, status: 0}]
+      #       [model.with(files: stdout.lines), nil]
+      #     in [:got_files, {stderr:, status:}]
+      #       [model.with(error: stderr), nil]
+      #     end
+      #   end
+      #
+      # === Example (Streaming Mode)
+      #
+      #   # Return this from update:
+      #   [model.with(loading: true), Command.system("tail -f log.txt", :log, stream: true)]
+      #
+      #   # Then handle incremental messages:
+      #   def update(message, model)
+      #     case message
+      #     in [:log, :stdout, line]
+      #       [model.with(lines: [*model.lines, line]), nil]
+      #     in [:log, :stderr, line]
+      #       [model.with(errors: [*model.errors, line]), nil]
+      #     in [:log, :complete, {status:}]
+      #       [model.with(loading: false, exit_status: status), nil]
+      #     in [:log, :error, {message:}]
+      #       [model.with(loading: false, error: message), nil]
+      #     end
+      #   end
+      def self.system(command, tag, stream: false)
+        System.new(command:, tag:, stream:)
+      end
+
+      # Command that wraps another command's result with a transformation.
+      #
+      # Fractal Architecture requires composition. Child bags produce commands.
+      # Parent bags route child results back to themselves. +Mapped+ wraps a
+      # child bag's command and transforms its result message into a parent message.
+      Mapped = Data.define(:inner_command, :mapper)
+
+      # Creates a mapped command for Fractal Architecture composition.
+      #
+      # Wraps an inner command. When the inner command completes, the +mapper+ block
+      # transforms the result into a parent message. This prevents monolithic update
+      # functions (the "God Reducer" anti-pattern).
+      #
+      # [inner_command] The child command to wrap.
+      # [mapper] Block that transforms child message to parent message.
+      #
+      # === Example
+      #
+      #   # Child returns Command.execute that produces [:got_files, {...}]
+      #   child_command = Command.system("ls", :got_files)
+      #
+      #   # Parent wraps to route as [:sidebar, :got_files, {...}]
+      #   parent_command = Command.map(child_command) { |child_result| [:sidebar, *child_result] }
+      def self.map(inner_command, &mapper)
+        Mapped.new(inner_command:, mapper:)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/router.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    # Declarative DSL for Fractal Architecture.
+    #
+    # Large applications decompose into bags. Each bag has its own Model,
+    # UPDATE, and VIEW. Parent bags route messages to child bags and compose views.
+    # Writing this routing logic by hand is tedious and error-prone.
+    #
+    # Include this module to declare routes and keymaps. Call +from_router+ to
+    # generate an UPDATE lambda that handles routing automatically.
+    #
+    # A *bag* is a module containing <tt>Model</tt>, <tt>INITIAL</tt>,
+    # <tt>UPDATE</tt>, and <tt>VIEW</tt> constants. Bags compose: parent bags
+    # delegate to child bags.
+    #
+    # === Example
+    #
+    #   class Dashboard
+    #     include Tea::Router
+    #
+    #     route :stats, to: StatsPanel
+    #     route :network, to: NetworkPanel
+    #
+    #     keymap do
+    #       key "s", -> { SystemInfo.fetch_command }, route: :stats
+    #       key "q", -> { Command.exit }
+    #     end
+    #
+    #     Model = Data.define(:stats, :network)
+    #     INITIAL = Model.new(stats: StatsPanel::INITIAL, network: NetworkPanel::INITIAL)
+    #     VIEW = ->(model, tui) { ... }
+    #     UPDATE = from_router
+    #   end
+    module Router
+      # :nodoc:
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods added when Router is included.
+      module ClassMethods
+        # Declares a route to a child.
+        #
+        # [prefix] Symbol or String identifying the route (normalized via +.to_s.to_sym+).
+        # [to] The child module (must have UPDATE and INITIAL constants).
+        def route(prefix, to:)
+          routes[prefix.to_s.to_sym] = to
+        end
+
+        # Returns the registered routes hash.
+        def routes
+          @routes ||= {}
+        end
+
+        # Declares a named action.
+        #
+        # Actions are shared handlers that keymap and mousemap can reference.
+        # This avoids duplicating logic for keys and mouse events that do
+        # the same thing.
+        #
+        # [name] Symbol or String identifying the action (normalized via +.to_s.to_sym+).
+        # [handler] Callable that returns a command or message.
+        def action(name, handler)
+          actions[name.to_s.to_sym] = handler
+        end
+
+        # Returns the registered actions hash.
+        def actions
+          @actions ||= {}
+        end
+
+        # Declares key handlers in a block.
+        #
+        # === Example
+        #
+        #   keymap do
+        #     key "q", -> { Command.exit }
+        #     key :up, :scroll_up  # Delegate to action
+        #   end
+        def keymap(&)
+          builder = KeymapBuilder.new
+          builder.instance_eval(&)
+          @key_handlers = builder.handlers
+        end
+
+        # Returns the registered key handlers hash.
+        def key_handlers
+          @key_handlers ||= {}
+        end
+
+        # Declares mouse handlers in a block.
+        #
+        # === Example
+        #
+        #   mousemap do
+        #     click -> (x, y) { [:clicked, x, y] }
+        #     scroll :up, :scroll_up  # Delegate to action
+        #   end
+        def mousemap(&)
+          builder = MousemapBuilder.new
+          builder.instance_eval(&)
+          @mouse_handlers = builder.handlers
+        end
+
+        # Returns the registered mouse handlers hash.
+        def mouse_handlers
+          @mouse_handlers ||= {}
+        end
+
+        # Generates an UPDATE lambda from routes, keymap, and mousemap.
+        #
+        # The generated UPDATE:
+        # 1. Routes prefixed messages to child UPDATEs
+        # 2. Handles keyboard events via keymap
+        # 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
+            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)
+
+                # 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]
+              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]
+                end
+              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
+              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
+            end
+
+            # 4. Unhandled - return model unchanged
+            [model, nil]
+          end
+        end
+      end
+
+      # Builder for keymap DSL.
+      class KeymapBuilder
+        # Returns the registered handlers hash.
+        attr_reader :handlers
+
+        # :nodoc:
+        def initialize
+          @handlers = {}
+          @guard_stack = []
+        end
+
+        # Registers a key handler.
+        #
+        # [key_name] String or Symbol for the key (normalized via +.to_s+).
+        # [handler_or_action] Callable or Symbol (action name).
+        # [route] Optional route prefix for the command result.
+        # [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 = {}
+          if handler_or_action.is_a?(Symbol)
+            entry[:action] = handler_or_action
+          else
+            entry[:handler] = handler_or_action
+          end
+          entry[:route] = route if route
+
+          guards = @guard_stack.dup
+
+          # Positive guards (when, if, only, guard)
+          positive = binding.local_variable_get(:when) ||
+            binding.local_variable_get(:if) ||
+            only ||
+            guard
+          guards << positive if positive
+
+          # Negative guards (unless, except, skip) - wrap to invert
+          negative = binding.local_variable_get(:unless) || except || skip
+          if negative
+            guards << -> (model) { !negative.call(model) }
+          end
+
+          if guards.any?
+            entry[:guard] = -> (model) { guards.all? { |g| g.call(model) } }
+          end
+
+          @handlers[key_name.to_s] = entry
+        end
+
+        # Applies a guard to all keys in the block.
+        #
+        # [when/if/only/guard] Guard that runs if truthy.
+        def only(when: nil, if: nil, only: nil, guard: nil, &)
+          arg_count = 0
+          arg_count += 1 if binding.local_variable_get(:when)
+          arg_count += 1 if binding.local_variable_get(:if)
+          arg_count += 1 if only
+          arg_count += 1 if guard
+
+          if arg_count > 1
+            raise ArgumentError, "only accepts exactly one of: when, if, only, guard"
+          end
+
+          positive = binding.local_variable_get(:when) ||
+            binding.local_variable_get(:if) ||
+            only ||
+            guard
+          with_guard(positive, &)
+        end
+
+        # Skips all keys in the block when the guard is true.
+        #
+        # [when/if/skip/guard] Guard that skips if truthy.
+        def skip(when: nil, if: nil, skip: nil, guard: nil, &)
+          arg_count = 0
+          arg_count += 1 if binding.local_variable_get(:when)
+          arg_count += 1 if binding.local_variable_get(:if)
+          arg_count += 1 if skip
+          arg_count += 1 if guard
+
+          if arg_count > 1
+            raise ArgumentError, "skip accepts exactly one of: when, if, skip, guard"
+          end
+
+          skip_guard = binding.local_variable_get(:when) ||
+            binding.local_variable_get(:if) ||
+            skip ||
+            guard
+
+          # Invert the guard: skip when true means run when false
+          inverted = skip_guard ? -> (model) { !skip_guard.call(model) } : nil
+          with_guard(inverted, &)
+        end
+        private def with_guard(guard, &block)
+          if guard
+            @guard_stack << guard
+            begin
+              block.call
+            ensure
+              @guard_stack.pop
+            end
+          else
+            block.call
+          end
+        end
+      end
+
+      # Builder for mousemap DSL.
+      class MousemapBuilder
+        # Returns the registered handlers hash.
+        attr_reader :handlers
+
+        # :nodoc:
+        def initialize
+          @handlers = {}
+        end
+
+        # Registers a click handler.
+        #
+        # [handler_or_action] Callable or Symbol (action name).
+        def click(handler_or_action)
+          register(:click, handler_or_action)
+        end
+
+        # Registers a scroll handler.
+        #
+        # [direction] <tt>:up</tt> or <tt>:down</tt>.
+        # [handler_or_action] Callable 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
+          else
+            entry[:handler] = handler_or_action
+          end
+          @handlers[key] = entry
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/runtime.rb

@@ -27,8 +27,8 @@ module RatatuiRuby
     #++
     #   RatatuiRuby::Tea.run(
     #     model: { count: 0 }.freeze,
-    #     view: ->(m, tui) { tui.paragraph(text: m[:count].to_s) },
-    #     update: ->(msg, m) { msg.q? ? [m, Cmd.quit] : [m, nil] }
+    #     view: ->(model, tui) { tui.paragraph(text: model[:count].to_s) },
+    #     update: ->(message, model) { message.q? ? [model, Command.exit] : [model, nil] }
     #   )
     #--
     # SPDX-SnippetEnd
@@ -36,24 +36,25 @@ module RatatuiRuby
     class Runtime
       # Starts the MVU event loop.
       #
-      # Runs until the update function returns a <tt>Cmd.quit</tt> command.
+      # Runs until the update function returns a <tt>Command.exit</tt> command.
       #
       # [model] Initial application state (immutable).
       # [view] Callable receiving <tt>(model, tui)</tt>, returns a widget.
-      # [update] Callable receiving <tt>(msg, model)</tt>, returns <tt>[new_model, cmd]</tt> or just <tt>new_model</tt>.
+      # [update] Callable receiving <tt>(message, model)</tt>, returns <tt>[new_model, command]</tt> or just <tt>new_model</tt>.
       # [init] Optional callable to run at startup. Returns a message for update.
       def self.run(model:, view:, update:, init: nil)
         validate_ractor_shareable!(model, "model")
 
         # Execute init command synchronously if provided
         if init
-          init_msg = init.call
-          result = update.call(init_msg, model)
-          model, _cmd = normalize_update_result(result, model)
+          init_message = init.call
+          result = update.call(init_message, model)
+          model, _command = normalize_update_result(result, model)
           validate_ractor_shareable!(model, "model")
         end
 
         queue = Queue.new
+        pending_threads = []
 
         catch(:quit) do
           RatatuiRuby.run do |tui|
@@ -65,28 +66,58 @@ module RatatuiRuby
               end
 
               # 1. Handle user input (blocks up to 16ms)
-              msg = tui.poll_event
+              message = tui.poll_event
 
               # If provided, handle the event
-              unless msg.is_a?(RatatuiRuby::Event::None)
-                result = update.call(msg, model)
-                model, cmd = normalize_update_result(result, model)
+              unless message.is_a?(RatatuiRuby::Event::None)
+                result = update.call(message, model)
+                model, command = normalize_update_result(result, model)
                 validate_ractor_shareable!(model, "model")
-                throw :quit if cmd.is_a?(Cmd::Quit)
+                throw :quit if command.is_a?(Command::Exit)
 
-                dispatch(cmd, queue) if cmd
+                thread = dispatch(command, queue) if command
+                pending_threads << thread if thread
               end
 
-              # 2. Check for background outcomes
+              # 2. Check for synthetic events (Sync)
+              # This comes AFTER poll_event so Sync waits for commands dispatched
+              # by the preceding event (e.g., inject_key("a"); inject_sync)
+              if RatatuiRuby::SyntheticEvents.pending?
+                synthetic = RatatuiRuby::SyntheticEvents.pop
+                if synthetic&.sync?
+                  # Wait for all pending threads to complete
+                  pending_threads.each(&:join)
+                  pending_threads.clear
+
+                  # Process all pending queue items
+                  until queue.empty?
+                    begin
+                      background_message = queue.pop(true)
+                      result = update.call(background_message, model)
+                      model, command = normalize_update_result(result, model)
+                      validate_ractor_shareable!(model, "model")
+                      throw :quit if command.is_a?(Command::Exit)
+
+                      thread = dispatch(command, queue) if command
+                      pending_threads << thread if thread
+                    rescue ThreadError
+                      break
+                    end
+                  end
+                end
+              end
+
+              # 3. Check for background outcomes (non-blocking)
               until queue.empty?
                 begin
-                  bg_msg = queue.pop(true)
-                  result = update.call(bg_msg, model)
-                  model, cmd = normalize_update_result(result, model)
+                  background_message = queue.pop(true)
+                  result = update.call(background_message, model)
+                  model, command = normalize_update_result(result, model)
                   validate_ractor_shareable!(model, "model")
-                  throw :quit if cmd.is_a?(Cmd::Quit)
+                  throw :quit if command.is_a?(Command::Exit)
 
-                  dispatch(cmd, queue) if cmd
+                  thread = dispatch(command, queue) if command
+                  pending_threads << thread if thread
                 rescue ThreadError
                   break
                 end
@@ -109,19 +140,19 @@ module RatatuiRuby
           "View returned nil. Return a widget, or use TUI#clear for an empty screen."
       end
 
-      # Detects whether +result+ is a +[model, cmd]+ tuple, a plain model, or a Cmd alone.
+      # Detects whether +result+ is a +[model, command]+ tuple, a plain model, or a Command alone.
       #
-      # Returns +[model, cmd]+ in all cases.
+      # Returns +[model, command]+ in all cases.
       private_class_method def self.normalize_update_result(result, previous_model)
-        return result if result.is_a?(Array) && result.size == 2 && valid_cmd?(result[1])
-        return [previous_model, result] if valid_cmd?(result)
+        return result if result.is_a?(Array) && result.size == 2 && valid_command?(result[1])
+        return [previous_model, result] if valid_command?(result)
 
         [result, nil]
       end
 
-      # Returns +true+ if +value+ is a valid command (+nil+ or a +Cmd+ type).
-      private_class_method def self.valid_cmd?(value)
-        value.nil? || value.class.name&.start_with?("RatatuiRuby::Tea::Cmd::")
+      # 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::")
       end
 
       # Validates an object is Ractor-shareable (deeply frozen).
@@ -135,23 +166,52 @@ module RatatuiRuby
           "#{name.capitalize} is not Ractor-shareable. Use Ractor.make_shareable or Object#freeze."
       end
 
-      # Dispatches a command to the worker pool.
+      # Dispatches a command asynchronously. :nodoc:
       #
-      # Spawns a thread for async commands. Pushes result to +queue+.
-      # Handles nested commands (Batch, Sequence) recursively.
-      private_class_method def self.dispatch(cmd, queue)
-        case cmd
-        when Cmd::Exec
+      # 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)
+        case command
+        when Command::System
           Thread.new do
             require "open3"
-            stdout, stderr, status = Open3.capture3(cmd.command)
-            msg = [cmd.tag, { stdout:, stderr:, status: status.exitstatus }]
-            queue << Ractor.make_shareable(msg)
-          rescue => e
-            # Should we send an error message? For now, crash in debug, ignore in prod?
-            # Better to rely on Open3 not raising for standard execution.
+            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
+            else
+              stdout, stderr, status = Open3.capture3(command.command)
+              message = [command.tag, { stdout:, stderr:, status: status.exitstatus }]
+              queue << Ractor.make_shareable(message)
+            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)
           end
-          # TODO: Add Batch, Sequence, NetHttp
         end
       end
     end