ratatui_ruby-tea 0.2.0 → 0.3.1

data/lib/ratatui_ruby/tea/shortcuts.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "command"
+
+module RatatuiRuby
+  module Tea
+    # Convenient short aliases for Tea APIs.
+    #
+    # The library uses intention-revealing names that match Ruby built-ins:
+    # +Command+, +System+, +Exit+. These are great for readability.
+    #
+    # This module provides the short aliases common in TEA-style code:
+    #
+    # === Example
+    #
+    #   require "ratatui_ruby/tea/shortcuts"
+    #   include RatatuiRuby::Tea::Shortcuts
+    #
+    #   # Now use short names freely:
+    #   Cmd.exit               # → Command.exit
+    #   Cmd.sh("ls", :files)   # → Command.system("ls", :files)
+    #   Cmd.map(child) { ... } # → Command.map(child) { ... }
+    module Shortcuts
+      # Short alias for +Command+.
+      module Cmd
+        # Creates an exit command.
+        # Alias for +Command.exit+.
+        def self.exit
+          Command.exit
+        end
+
+        # Creates a shell execution command.
+        # Short alias for +Command.system+.
+        def self.sh(command, tag)
+          Command.system(command, tag)
+        end
+
+        # Creates a mapped command.
+        # Short alias for +Command.map+.
+        def self.map(inner_command, &mapper)
+          Command.map(inner_command, &mapper)
+        end
+      end
+    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.2.0"
+    VERSION = "0.3.1"
   end
 end

data/lib/ratatui_ruby/tea.rb

@@ -6,8 +6,9 @@
 #++
 
 require_relative "tea/version"
-require_relative "tea/cmd"
+require_relative "tea/command"
 require_relative "tea/runtime"
+require_relative "tea/router"
 
 module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
   # The Elm Architecture for RatatuiRuby.
@@ -26,5 +27,62 @@ module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
     def self.run(...)
       Runtime.run(...)
     end
+
+    # Wraps a command with a routing prefix.
+    #
+    # Parent bags trigger child bag commands. The results need routing back
+    # to the correct child bag. Manually wrapping every command is tedious.
+    #
+    # This method prefixes command results automatically. Use it to route
+    # child bag command results in Fractal Architecture.
+    #
+    # [command] The child bag command to wrap.
+    # [prefix] Symbol prepended to results (e.g., <tt>:stats</tt>).
+    #
+    # === Example
+    #
+    #   # Verbose:
+    #   Command.map(child_bag.fetch_command) { |r| [:stats, *r] }
+    #
+    #   # Concise:
+    #   Tea.route(child_bag.fetch_command, :stats)
+    def self.route(command, prefix)
+      Command.map(command) { |result| [prefix, *result] }
+    end
+
+    # Delegates a prefixed message to a child bag's UPDATE.
+    #
+    # Parent bag UPDATE functions route messages to child bags. Each route
+    # requires pattern matching, calling the child, and rewrapping any returned
+    # command. The boilerplate adds up fast.
+    #
+    # This method handles the dispatch. It checks the prefix, calls the child,
+    # and wraps any command. Returns <tt>nil</tt> if the prefix does not match.
+    #
+    # [message] Incoming message (e.g., <tt>[:stats, :system_info, {...}]</tt>).
+    # [prefix] Expected prefix symbol (e.g., <tt>:stats</tt>).
+    # [child_update] The child's UPDATE callable.
+    # [child_model] The child's current model.
+    #
+    # === Example
+    #
+    #   # Verbose:
+    #   case message
+    #   in [:stats, *rest]
+    #     new_child, cmd = StatsPanel::UPDATE.call(rest, model.stats)
+    #     mapped = cmd ? Command.map(cmd) { |r| [:stats, *r] } : nil
+    #     [new_child, mapped]
+    #   end
+    #
+    #   # Concise:
+    #   Tea.delegate(message, :stats, StatsPanel::UPDATE, model.stats)
+    def self.delegate(message, prefix, child_update, child_model)
+      return nil unless message.is_a?(Array) && message.first == prefix
+
+      rest = message[1..]
+      new_child, command = child_update.call(rest, child_model)
+      wrapped = command ? route(command, prefix) : nil
+      [new_child, wrapped]
+    end
   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

data/sig/examples/verify_readme_usage/app.rbs

@@ -13,7 +13,7 @@ class VerifyReadmeUsage
 
   VIEW: ^(Model, RatatuiRuby::TUI) -> untyped
 
-  UPDATE: ^(RatatuiRuby::Event, Model) -> (Model | [Model, RatatuiRuby::Tea::Cmd::Quit])
+  UPDATE: ^(RatatuiRuby::Event, Model) -> (Model | [Model, RatatuiRuby::Tea::Command::Exit])
 
   def run: () -> void
 end

data/sig/examples/{widget_cmd_exec → widget_command_system}/app.rbs

@@ -20,7 +20,7 @@ class WidgetCmdExec
   # Msg can be Event or [:got_output, Hash]
   type msg = RatatuiRuby::Event | [Symbol, Hash[Symbol, untyped]]
 
-  UPDATE: ^(msg, Model) -> (Model | [Model, RatatuiRuby::Tea::Cmd::execution?])
+  UPDATE: ^(msg, Model) -> (Model | [Model, RatatuiRuby::Tea::Command::execution?])
 
   def run: () -> void
 end

data/sig/open3.rbs

@@ -0,0 +1,17 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# Local shim for Open3 methods not in stdlib RBS.
+# The stdlib open3/0/open3.rbs only defines capture2e.
+# TODO: Remove when upstream RBS adds these methods.
+
+module Open3
+  # Executes a command and returns stdout, stderr, and status.
+  def self.capture3: (*String, ?stdin_data: String, ?binmode: boolish) -> [String, String, Process::Status]
+
+  # Executes a command with pipes for stdin, stdout, stderr.
+  def self.popen3: (*String) { (IO stdin, IO stdout, IO stderr, Thread wait_thr) -> void } -> Process::Status
+                 | (*String) -> [IO, IO, IO, Thread]
+end

data/sig/ratatui_ruby/tea/command.rbs

@@ -0,0 +1,163 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Interface for user-defined custom commands.
+      # Any callable satisfying this interface can be dispatched.
+      interface _Command
+        # Brand predicate for update return disambiguation.
+        def tea_command?: () -> true
+
+        # Execute the command's side effect.
+        # Push result messages via the outlet.
+        def call: (Outlet out, CancellationToken token) -> void
+
+        # Grace period for cooperative cancellation (seconds).
+        # Runtime waits this long before force-killing the thread.
+        def tea_cancellation_grace_period: () -> Float
+      end
+
+      # Sentinel value for application termination.
+      class Exit < Data
+        def self.new: () -> instance
+      end
+
+      # Runs a shell command and routes its output back as messages.
+      class System < Data
+        attr_reader command: String
+        attr_reader tag: Symbol | Class
+        attr_reader stream: bool
+
+        # Command identification for runtime dispatch.
+        def tea_command?: () -> true
+
+        # Grace period for cleanup after cancellation.
+        def tea_cancellation_grace_period: () -> Float
+
+        # Returns true if streaming mode is enabled.
+        def stream?: () -> bool
+
+        # Executes the shell command and sends results via outlet.
+        def call: (Outlet out, CancellationToken token) -> void
+
+        def self.new: (command: String, tag: (Symbol | Class), stream: bool) -> instance
+      end
+
+      # Command that wraps another command's result with a transformation.
+      class Mapped < Data
+        attr_reader inner_command: execution
+        attr_reader mapper: ^(Array[untyped]) -> Array[untyped]
+
+        # Command identification for runtime dispatch.
+        def tea_command?: () -> true
+
+        # Grace period delegates to inner command.
+        def tea_cancellation_grace_period: () -> Float
+
+        # Executes the inner command and transforms the result.
+        def call: (Outlet out, CancellationToken token) -> void
+
+        def self.new: (inner_command: execution, mapper: ^(Array[untyped]) -> Array[untyped]) -> instance
+      end
+
+      # Sentinel value for command cancellation.
+      class Cancel < Data
+        attr_reader handle: _Command
+
+        def self.new: (handle: _Command) -> instance
+      end
+
+      # Sentinel value for command errors.
+      class Error < Data
+        attr_reader command: _Command
+        attr_reader exception: Exception
+
+        def self.new: (command: _Command, exception: Exception) -> instance
+      end
+
+      # Union type for all valid commands
+      type execution = System | Mapped | _Command
+
+      # Creates a quit command.
+      def self.exit: () -> Exit
+
+      # Creates a shell execution command.
+      def self.system: (String command, (Symbol | Class) tag, ?stream: bool) -> System
+
+      # Creates a mapped command for Fractal Architecture composition.
+      def self.map: (execution inner_command) { (Array[untyped]) -> Array[untyped] } -> Mapped
+
+      # Request cancellation of a running command.
+      def self.cancel: (_Command handle) -> Cancel
+
+      # Creates an error sentinel.
+      def self.error: (_Command command, Exception exception) -> Error
+
+      # Wraps a callable for unique identity per dispatch.
+      def self.custom: (^(Outlet, CancellationToken) -> void callable, ?grace_period: Float?) -> _Command
+                     | (?grace_period: Float?) { (Outlet, CancellationToken) -> void } -> _Command
+
+      # Private wrapper for Command.custom.
+      class Wrapped < Data
+        include Custom
+
+        attr_reader callable: ^(Outlet, CancellationToken) -> void
+        attr_reader grace_period: Float?
+
+        def self.new: (callable: ^(Outlet, CancellationToken) -> void, grace_period: Float?) -> instance
+        def call: (Outlet out, CancellationToken token) -> void
+      end
+
+      # Cooperative cancellation mechanism for long-running commands.
+      class CancellationToken
+        # Number of times cancel! has been called.
+        attr_reader cancel_count: Integer
+
+        def self.new: () -> instance
+
+        # Signals cancellation. Thread-safe.
+        def cancel!: () -> void
+
+        # Checks if cancellation was requested. Thread-safe.
+        def cancelled?: () -> bool
+
+        # Null object for commands that ignore cancellation.
+        class NoneToken < Data
+          attr_reader cancelled?: bool
+
+          def self.new: (cancelled?: bool) -> instance
+
+          # Does nothing. Ignores cancellation requests.
+          def cancel!: () -> nil
+        end
+
+        # Singleton null token.
+        NONE: NoneToken
+      end
+
+      # Mixin for user-defined custom commands.
+      module Custom
+        # Brand predicate for command identification.
+        def tea_command?: () -> true
+
+        # Cleanup time after cancellation is requested. In seconds.
+        # Default: 0.1 seconds (100 milliseconds).
+        def tea_cancellation_grace_period: () -> Float
+      end
+
+      # Messaging gateway for custom commands.
+      class Outlet
+        @queue: Thread::Queue[Array[untyped]]
+
+        def initialize: (Thread::Queue[Array[untyped]] queue) -> void
+
+        # Sends a tagged message to the runtime.
+        def put: (Symbol tag, *untyped payload) -> void
+      end
+    end
+  end
+end

data/sig/ratatui_ruby/tea/router.rbs

@@ -0,0 +1,155 @@
+#--
+# 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.
+    module Router
+      def self.included: (Class base) -> void
+
+      # Duck type for Data-like models that support `with`.
+      interface _DataModel
+        def public_send: (Symbol, *Object) -> Object
+        def with: (**Object) -> self
+      end
+
+      # Interface for fractal child modules (bags).
+      # Routed modules must have an UPDATE constant that handles child messages.
+      # NOTE: We use Module here because RBS interfaces can't declare class methods.
+
+      # Configuration for key handlers.
+      class KeyHandlerConfig < Data
+        attr_reader handler: (^() -> Command::execution?)?
+        attr_reader action: Symbol?
+        attr_reader route: Symbol?
+        attr_reader guard: (^(_DataModel) -> bool)?
+
+        def initialize: (?handler: (^() -> Command::execution?)?, ?action: Symbol?, ?route: Symbol?, ?guard: (^(_DataModel) -> bool)?) -> void
+      end
+
+      # Configuration for scroll handlers (no coordinates).
+      class ScrollHandlerConfig < Data
+        attr_reader handler: (^() -> Command::execution?)?
+        attr_reader action: Symbol?
+
+        def initialize: (?handler: (^() -> Command::execution?)?, ?action: Symbol?) -> void
+      end
+
+      # Configuration for click handlers (x, y coordinates).
+      class ClickHandlerConfig < Data
+        attr_reader handler: (^(Integer, Integer) -> Command::execution?)?
+        attr_reader action: Symbol?
+
+        def initialize: (?handler: (^(Integer, Integer) -> Command::execution?)?, ?action: Symbol?) -> void
+      end
+
+      # Class methods added when Router is included.
+      module ClassMethods : Module
+        @routes: Hash[Symbol, Module]
+        @actions: Hash[Symbol, ^() -> Command::execution?]
+        @key_handlers: Hash[String, KeyHandlerConfig]
+        @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        @click_handler: ClickHandlerConfig?
+
+        def route: (Symbol | String prefix, to: Module) -> void
+        def routes: () -> Hash[Symbol, Module]
+
+        def action: (Symbol | String name, ^() -> Command::execution? handler) -> void
+        def actions: () -> Hash[Symbol, ^() -> Command::execution?]
+
+        def keymap: () { (KeymapBuilder) [self: KeymapBuilder] -> void } -> void
+        def key_handlers: () -> Hash[String, KeyHandlerConfig]
+
+        def mousemap: () { (MousemapBuilder) [self: MousemapBuilder] -> void } -> void
+        def scroll_handlers: () -> Hash[Symbol, ScrollHandlerConfig]
+        def click_handler: () -> ClickHandlerConfig?
+
+        # Returns UPDATE callable that handles routing.
+        # Uses is_a? checks for Event::Key and Event::Mouse type narrowing.
+        # Model must be Data-like with `with` and field accessors.
+        def from_router: () -> RouterUpdate
+      end
+
+      # UPDATE callable returned by from_router with proper typing.
+      # Implements #call to satisfy Proc-like interfaces.
+      class RouterUpdate
+        @routes: Hash[Symbol, Module]
+        @actions: Hash[Symbol, ^() -> Command::execution?]
+        @key_handlers: Hash[String, KeyHandlerConfig]
+        @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        @click_handler: ClickHandlerConfig?
+
+        def initialize: (
+          routes: Hash[Symbol, Module],
+          actions: Hash[Symbol, ^() -> Command::execution?],
+          key_handlers: Hash[String, KeyHandlerConfig],
+          scroll_handlers: Hash[Symbol, ScrollHandlerConfig],
+          click_handler: ClickHandlerConfig?
+        ) -> void
+
+        # Process message and return [model, command] tuple.
+        def call: (
+          (RatatuiRuby::Event::Key | RatatuiRuby::Event::Mouse | Array[Object]) message,
+          _DataModel model
+        ) -> [_DataModel, Command::execution?]
+      end
+
+      # Builder for keymap DSL.
+      class KeymapBuilder
+        @handlers: Hash[String, KeyHandlerConfig]
+        @guard_stack: Array[^(_DataModel) -> bool]
+
+        attr_reader handlers: Hash[String, KeyHandlerConfig]
+
+        def initialize: () -> void
+
+        def key: (
+          String | Symbol key_name,
+          (^() -> Command::execution?) | Symbol handler_or_action,
+          ?route: Symbol?,
+          ?when: (^(_DataModel) -> bool)?,
+          ?if: (^(_DataModel) -> bool)?,
+          ?only: (^(_DataModel) -> bool)?,
+          ?guard: (^(_DataModel) -> bool)?,
+          ?unless: (^(_DataModel) -> bool)?,
+          ?except: (^(_DataModel) -> bool)?,
+          ?skip: (^(_DataModel) -> bool)?
+        ) -> void
+
+        def only: (
+          ?when: (^(_DataModel) -> bool)?,
+          ?if: (^(_DataModel) -> bool)?,
+          ?only: (^(_DataModel) -> bool)?,
+          ?guard: (^(_DataModel) -> bool)?
+        ) { () -> void } -> void
+
+        def skip: (
+          ?when: (^(_DataModel) -> bool)?,
+          ?if: (^(_DataModel) -> bool)?,
+          ?skip: (^(_DataModel) -> bool)?,
+          ?guard: (^(_DataModel) -> bool)?
+        ) { () -> void } -> void
+
+        private
+
+        def with_guard: ((^(_DataModel) -> bool)?) { () -> void } -> void
+      end
+
+      # Builder for mousemap DSL.
+      class MousemapBuilder
+        @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        @click_handler: ClickHandlerConfig?
+
+        attr_reader scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        attr_reader click_handler: ClickHandlerConfig?
+
+        def initialize: () -> void
+
+        def click: ((^(Integer, Integer) -> Command::execution?) | Symbol handler_or_action) -> void
+        def scroll: (:up | :down direction, (^() -> Command::execution?) | Symbol handler_or_action) -> void
+      end
+    end
+  end
+end

data/sig/ratatui_ruby/tea/runtime.rbs

@@ -5,22 +5,40 @@
 
 module RatatuiRuby
   module Tea
+    # MVU runtime event loop.
     class Runtime
+      # Active command tracking entry.
+      type active_entry = { thread: Thread, token: Command::CancellationToken }
+
+      # Widget type accepted by view functions.
+      type renderable = RatatuiRuby::_CustomWidget | RatatuiRuby::widget
+
+      # Duck type for update result that can be normalized.
+      # Steep needs a union type (not interface) for is_a? narrowing.
+      type update_result = [Object, Command::execution?] | Command::execution | Object
+
+      # Duck type for values that can be queried for command-ness.
+      interface _MaybeCommand
+        def nil?: () -> bool
+        def class: () -> Class
+        def respond_to?: (Symbol, ?bool) -> bool
+        def tea_command?: () -> bool
+      end
+
       # Starts the MVU event loop.
-      def self.run: [M, Msg] (
-        model: M,
-        view: ^(M model, RatatuiRuby::TUI tui) -> untyped,
-        update: ^(Msg msg, M model) -> (M | [M, Cmd::execution?] | [M, Cmd::Quit] | [M, nil]),
-        ?init: ^() -> Msg
-      ) -> M
+      def self.run: [Model] (
+        model: Model,
+        view: ^(Model, RatatuiRuby::TUI) -> renderable,
+        update: ^(RatatuiRuby::Event, Model) -> update_result?,
+        ?init: (^() -> RatatuiRuby::Event)?
+      ) -> Model
 
       private
 
-      def self.validate_view_result!: (untyped widget) -> void
-      def self.normalize_update_result: [M] (untyped result, M previous_model) -> [M, untyped]
-      def self.valid_cmd?: (untyped value) -> bool
-      def self.validate_ractor_shareable!: (untyped object, String name) -> void
-      def self.dispatch: (untyped cmd, Queue queue) -> void
+      def self.validate_view_result!: (renderable? widget) -> void
+      def self.normalize_update_result: [Model] (update_result? result, Model previous_model) -> [Model, Command::execution?]
+      def self.validate_ractor_shareable!: [T] (T object, String name) -> void
+      def self.dispatch: (Command::execution command, Queue[Array[Symbol | Hash[Symbol, String | Integer]]], ?Hash[Command::_Command, active_entry] active_commands) -> Thread?
     end
   end
 end