ratatui_ruby-tea 0.3.0 → 0.4.0

data/lib/ratatui_ruby/tea.rb

@@ -6,6 +6,7 @@
 #++
 
 require_relative "tea/version"
+require_relative "tea/message"
 require_relative "tea/command"
 require_relative "tea/runtime"
 require_relative "tea/router"
@@ -24,35 +25,68 @@ module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
     # Starts the MVU event loop.
     #
     # Convenience delegator to Runtime.run. See Runtime for full documentation.
-    def self.run(...)
-      Runtime.run(...)
+    def self.run(root_fragment = nil, **)
+      Runtime.run(root_fragment, **)
+    end
+
+    # Normalizes Init callable return value to <tt>[model, command]</tt> tuple.
+    #
+    # Init callables use DWIM syntax. They can return just a model, just a command,
+    # or a full <tt>[model, command]</tt> tuple.
+    #
+    # This method handles all formats. Use it when composing child fragment Inits
+    # in fractal architecture.
+    #
+    # [result] The Init return value.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Parent fragment composes children
+    #   Init = ->(theme:) do
+    #     stats_model, stats_cmd = Tea.normalize_init(StatsPanel::Init.(theme: theme))
+    #     network_model, network_cmd = Tea.normalize_init(NetworkPanel::Init.(theme: theme))
+    #
+    #     model = Model.new(stats: stats_model, network: network_model)
+    #     command = Command.batch(stats_cmd, network_cmd)
+    #     [model, command]
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def self.normalize_init(result)
+      Runtime.normalize_init(result)
     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.
+    # Parent fragments trigger child fragment commands. The results need routing back
+    # to the correct child fragment. Manually wrapping every command is tedious.
     #
     # This method prefixes command results automatically. Use it to route
-    # child bag command results in Fractal Architecture.
+    # child fragment command results in Fractal Architecture.
     #
-    # [command] The child bag command to wrap.
+    # [command] The child fragment command to wrap.
     # [prefix] Symbol prepended to results (e.g., <tt>:stats</tt>).
     #
     # === Example
     #
     #   # Verbose:
-    #   Command.map(child_bag.fetch_command) { |r| [:stats, *r] }
+    #   Command.map(child_fragment.fetch_command) { |r| [:stats, *r] }
     #
     #   # Concise:
-    #   Tea.route(child_bag.fetch_command, :stats)
+    #   Tea.route(child_fragment.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.
+    # Delegates a prefixed message to a child fragment's UPDATE.
     #
-    # Parent bag UPDATE functions route messages to child bags. Each route
+    # Parent fragment UPDATE functions route messages to child fragments. Each route
     # requires pattern matching, calling the child, and rewrapping any returned
     # command. The boilerplate adds up fast.
     #

data/rbs_collection.lock.yaml

@@ -0,0 +1,108 @@
+# 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: 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: ratatui_ruby
+  version: 0.10.2
+  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/concurrent.rbs

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+# Minimal stubs for concurrent-ruby-edge types used by Tea.
+# This is not a complete type definition — just enough for Steep.
+
+module Concurrent
+  module Promises
+    # Factory for resolvable events.
+    def self.resolvable_event: () -> ResolvableEvent
+
+    # A future/event that can be resolved by user code.
+    class ResolvableEvent
+      def resolve: (?bool wait, ?bool raise_on_reassign) -> self
+      def resolved?: () -> bool
+      def wait: (?Numeric? timeout) -> self
+    end
+
+    # Thread-safe FIFO channel for message passing.
+    class Channel
+      def initialize: (?Integer capacity) -> void
+      def push: (untyped message, ?Numeric? timeout) -> self
+      def pop: (?Numeric? timeout, ?untyped timeout_value) -> untyped
+      def try_pop: (?untyped no_value) -> untyped
+    end
+
+    # Represents a value that may not yet be available.
+    class Future[T]
+      def pending?: () -> bool
+      def resolved?: () -> bool
+      def rejected?: () -> bool
+      def wait: (?Numeric? timeout) -> self
+      def value: () -> T?
+      def reason: () -> Exception?
+    end
+
+    # Factory method for creating futures.
+    def self.future: [T] () { () -> T } -> Future[T]
+
+    # Races multiple futures/events, returning when any resolves.
+    def self.any_event: (*Future[untyped] | ResolvableEvent) -> ResolvableEvent
+  end
+
+  # Single-element blocking container for synchronization.
+  class MVar
+    TIMEOUT: Symbol
+
+    def initialize: (?untyped initial_value) -> void
+    def put: (untyped value) -> void
+    def take: (?Numeric? timeout) -> untyped
+  end
+
+  # Cooperative cancellation abstraction.
+  class Cancellation
+    def self.new: (?Promises::ResolvableEvent origin) -> [Cancellation, Promises::ResolvableEvent]
+    def self.timeout: (Numeric seconds) -> Cancellation
+
+    def origin: () -> Promises::ResolvableEvent
+    def canceled?: () -> bool
+    def check!: (?Class error) -> self
+    def join: (*Cancellation cancellations) -> Cancellation
+  end
+
+  # Thread-safe hash implementation.
+  class Map[K, V]
+    def initialize: () -> void
+    def []: (K key) -> V?
+    def []=: (K key, V value) -> V
+    def delete: (K key) -> V?
+    def each: () { (K, V) -> void } -> self
+  end
+end

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_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

@@ -6,42 +6,262 @@
 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, Concurrent::Cancellation 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
 
-      # Command to run a shell command via Open3.
+      # 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, Concurrent::Cancellation 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: ^(untyped) -> untyped
+        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, Concurrent::Cancellation token) -> void
 
-        def self.new: (inner_command: execution, mapper: ^(untyped) -> untyped) -> instance
+        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 = Execute | Mapped
+      type execution = System | Mapped | _Command
 
       # Creates a quit command.
-      def self.exit: () -> Quit
+      def self.exit: () -> Exit
+
+      # Creates a fresh cancellation that never fires.
+      def self.uncancellable: () -> Concurrent::Cancellation
 
       # 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) { (untyped) -> untyped } -> Mapped
+      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, Concurrent::Cancellation) -> void callable, ?grace_period: Float?) -> _Command
+                     | (?grace_period: Float?) { (Outlet, Concurrent::Cancellation) -> void } -> _Command
+
+      # Creates a one-shot timer command.
+      def self.wait: (Float seconds, Symbol tag) -> Wait
+
+      # Alias for wait, semantically used for recurring timers.
+      def self.tick: (Float seconds, Symbol tag) -> Wait
+
+      # One-shot timer command that waits, then sends a message.
+      class Wait < Data
+        include Custom
+
+        attr_reader seconds: Float
+        attr_reader tag: Symbol
+
+        def self.new: (seconds: Float, tag: Symbol) -> instance
+
+        # Execute the timer with cooperative cancellation.
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
+      end
+
+      # Private wrapper for Command.custom.
+      class Wrapped < Data
+        include Custom
+
+        attr_reader callable: ^(Outlet, Concurrent::Cancellation) -> void
+        attr_reader grace_period: Float?
+
+        def self.new: (callable: ^(Outlet, Concurrent::Cancellation) -> void, grace_period: Float?) -> instance
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
+      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
+
+      # Minimal interface for callables accepted by Lifecycle.run_sync.
+      interface _Callable
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
+        def respond_to?: (Symbol, ?bool) -> bool
+        def tea_cancellation_grace_period: () -> Float
+      end
+
+      # Manages command execution with lifecycle support.
+      class Lifecycle
+        # Internal representation of a tracked async command.
+        class Entry < Data
+          attr_reader future: Concurrent::Promises::Future[void]
+          attr_reader origin: Concurrent::Promises::ResolvableEvent
+
+          def self.new: (future: Concurrent::Promises::Future[void], origin: Concurrent::Promises::ResolvableEvent) -> instance
+        end
+
+        @active: Concurrent::Map[_Callable, Entry]
+
+        def initialize: () -> void
+
+        # Runs a command synchronously, returning its result.
+        def run_sync: (_Callable command, Concurrent::Cancellation token, timeout: Float) -> Object?
+
+        # Runs a command asynchronously, tracking it for later cancellation.
+        def run_async: (_Callable command, Concurrent::Promises::Channel channel) -> Entry
+
+        # Cancels a running command, waiting for its grace period.
+        def cancel: (_Callable command) -> void
+
+        # Cancels all active commands and waits for them to complete.
+        def shutdown: () -> void
+      end
+
+      # Messaging gateway for custom commands.
+      class Outlet
+        @channel: Concurrent::Promises::Channel
+        @live: Lifecycle
+
+        def initialize: (Concurrent::Promises::Channel channel, lifecycle: Lifecycle) -> void
+
+        # Internal infrastructure for nested command lifecycle sharing.
+        attr_reader live: Lifecycle
+
+        # Sends a message to the runtime.
+        def put: (*Object args) -> void
+
+        # Runs a child command synchronously, returning its result.
+        def source: (_Callable command, Concurrent::Cancellation token, ?timeout: Float) -> Object?
+      end
+
+      # A fire-and-forget parallel command.
+      class Batch
+        include Custom
+
+        attr_reader commands: Array[Custom]
+
+        def self.new: (*Custom | Array[Custom]) -> instance
+
+        def call: (Outlet outlet, Concurrent::Cancellation token) -> void
+      end
+
+      # Creates a parallel batch command.
+      def self.batch: (*Custom | Array[Custom]) -> Batch
+
+      # An aggregating parallel command.
+      class All
+        include Custom
+
+        attr_reader tag: Symbol
+        attr_reader commands: Array[Custom]
+        attr_reader nested: bool
+
+        def self.new: (Symbol tag, *Custom | Array[Custom]) -> instance
+
+        def call: (Outlet outlet, Concurrent::Cancellation token) -> void
+      end
+
+      # Creates an aggregating parallel command.
+      def self.all: (Symbol tag, *Custom | Array[Custom]) -> All
+
+      # HTTP response shapes for pattern matching
+      type http_success_shape = { type: :http, envelope: Symbol, status: Integer, body: String, headers: Hash[String, String] }
+      type http_error_shape = { type: :http, envelope: Symbol, error: String }
+
+      # HTTP response with deconstruct_keys for pattern matching.
+      class HttpResponse < Data
+        attr_reader envelope: Symbol
+        attr_reader status: Integer?
+        attr_reader body: String?
+        attr_reader headers: Hash[String, String]?
+        attr_reader error: String?
+
+        def self.new: (envelope: Symbol, status: Integer?, body: String?, headers: Hash[String, String]?, error: String?) -> instance
+
+        def deconstruct_keys: (Array[Symbol]?) -> (http_success_shape | http_error_shape)
+      end
+
+      # An HTTP request command.
+      class Http < Data
+        include Custom
+
+        attr_reader method: Symbol
+        attr_reader url: String
+        attr_reader envelope: Symbol
+        attr_reader headers: Hash[String, String]?
+        attr_reader body: String?
+        attr_reader timeout: (Integer | Float)?
+
+        def self.new: (method: Symbol, url: String, envelope: Symbol, headers: Hash[String, String]?, body: String?, timeout: (Integer | Float)?) -> instance
+
+        def call: (Outlet outlet, Concurrent::Cancellation token) -> void
+      end
+
+      # Creates an HTTP request command.
+      # DWIM: accepts positional args, method keywords (get:, post:, etc.), or explicit keywords.
+      # See Http class and documentation for all supported patterns.
+      def self.http: (*(Symbol | String | nil), **(Symbol | String | Integer | Float | Hash[String, String] | ^(String, Hash[String, String]?, Integer?) -> Object | nil)) -> Http
     end
   end
 end