ratatui_ruby-tea 0.3.1 → 0.4.0

data/sig/ratatui_ruby/tea.rbs

@@ -6,23 +6,43 @@
 module RatatuiRuby
   # The Elm Architecture for RatatuiRuby.
   module Tea
-    # Starts the MVU event loop.
+    # Starts the MVU event loop (positional fragment).
     def self.run: [Model] (
+      ?Module? root_fragment,
+      ?fps: Integer
+    ) -> Model
+
+    # Starts the MVU event loop (explicit parameters).
+    | [Model] (
+      ?Module? root_fragment,
+      ?fps: Integer,
       model: Model,
-      view: ^(Model, RatatuiRuby::TUI) -> (RatatuiRuby::_CustomWidget | RatatuiRuby::widget),
+      view: ^(Model, RatatuiRuby::TUI) -> Runtime::renderable,
       update: ^(RatatuiRuby::Event, Model) -> Runtime::update_result?,
-      ?init: (^() -> untyped)?
+      ?command: Command::execution?
+    ) -> Model
+
+    # Starts the MVU event loop (explicit parameters without fps).
+    | [Model] (
+      ?Module? root_fragment,
+      model: Model,
+      view: ^(Model, RatatuiRuby::TUI) -> Runtime::renderable,
+      update: ^(RatatuiRuby::Event, Model) -> Runtime::update_result?,
+      ?command: Command::execution?
     ) -> Model
 
     # Wraps a command with a routing prefix.
     def self.route: (Command::execution command, Symbol prefix) -> Command::Mapped
 
-    # Delegates a prefixed message to a child bag's UPDATE.
+    # Delegates a prefixed message to a child fragment's UPDATE.
     def self.delegate: (
       untyped message,
       Symbol prefix,
       ^(Array[untyped]?, untyped) -> [untyped, Command::execution?] child_update,
       untyped child_model
     ) -> ([untyped, Command::execution?] | nil)
+
+    # Normalizes Init callable return value to [model, command] tuple.
+    def self.normalize_init: [Model] (Runtime::init_result result) -> [Model?, Command::execution?]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby-tea
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Kerrick Long
@@ -37,6 +37,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby-edge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +122,16 @@ files:
 - Steepfile
 - doc/concepts/application_architecture.md
 - doc/concepts/application_testing.md
+- doc/concepts/async_work.md
+- doc/concepts/commands.md
+- doc/concepts/message_processing.md
+- doc/contributors/WIP/decomposition_strategies_analysis.md
+- doc/contributors/WIP/implementation_plan.md
+- doc/contributors/WIP/init_callable_proposal.md
+- doc/contributors/WIP/mvu_tea_implementations_research.md
+- doc/contributors/WIP/runtime_refactoring_status.md
+- doc/contributors/WIP/task.md
+- doc/contributors/WIP/v0.4.0_todo.md
 - doc/contributors/design/commands_and_outlets.md
 - doc/contributors/kit-no-outlet.md
 - doc/contributors/priorities.md
@@ -105,19 +143,19 @@ files:
 - doc/index.md
 - examples/app_fractal_dashboard/README.md
 - examples/app_fractal_dashboard/app.rb
-- examples/app_fractal_dashboard/bags/custom_shell_input.rb
-- examples/app_fractal_dashboard/bags/custom_shell_modal.rb
-- examples/app_fractal_dashboard/bags/custom_shell_output.rb
-- examples/app_fractal_dashboard/bags/disk_usage.rb
-- examples/app_fractal_dashboard/bags/network_panel.rb
-- examples/app_fractal_dashboard/bags/ping.rb
-- examples/app_fractal_dashboard/bags/stats_panel.rb
-- examples/app_fractal_dashboard/bags/system_info.rb
-- examples/app_fractal_dashboard/bags/uptime.rb
 - examples/app_fractal_dashboard/dashboard/base.rb
 - examples/app_fractal_dashboard/dashboard/update_helpers.rb
 - examples/app_fractal_dashboard/dashboard/update_manual.rb
 - examples/app_fractal_dashboard/dashboard/update_router.rb
+- examples/app_fractal_dashboard/fragments/custom_shell_input.rb
+- examples/app_fractal_dashboard/fragments/custom_shell_modal.rb
+- examples/app_fractal_dashboard/fragments/custom_shell_output.rb
+- examples/app_fractal_dashboard/fragments/disk_usage.rb
+- examples/app_fractal_dashboard/fragments/network_panel.rb
+- examples/app_fractal_dashboard/fragments/ping.rb
+- examples/app_fractal_dashboard/fragments/stats_panel.rb
+- examples/app_fractal_dashboard/fragments/system_info.rb
+- examples/app_fractal_dashboard/fragments/uptime.rb
 - examples/verify_readme_usage/README.md
 - examples/verify_readme_usage/app.rb
 - examples/widget_command_system/README.md
@@ -125,24 +163,38 @@ files:
 - exe/.gitkeep
 - lib/ratatui_ruby/tea.rb
 - lib/ratatui_ruby/tea/command.rb
-- lib/ratatui_ruby/tea/command/cancellation_token.rb
+- lib/ratatui_ruby/tea/command/all.rb
+- lib/ratatui_ruby/tea/command/batch.rb
 - lib/ratatui_ruby/tea/command/custom.rb
+- lib/ratatui_ruby/tea/command/http.rb
+- lib/ratatui_ruby/tea/command/lifecycle.rb
 - lib/ratatui_ruby/tea/command/outlet.rb
+- lib/ratatui_ruby/tea/command/wait.rb
+- lib/ratatui_ruby/tea/message.rb
+- lib/ratatui_ruby/tea/message/all.rb
+- lib/ratatui_ruby/tea/message/http_response.rb
+- lib/ratatui_ruby/tea/message/system/batch.rb
+- lib/ratatui_ruby/tea/message/system/stream.rb
+- lib/ratatui_ruby/tea/message/timer.rb
 - lib/ratatui_ruby/tea/router.rb
 - lib/ratatui_ruby/tea/runtime.rb
 - lib/ratatui_ruby/tea/shortcuts.rb
+- lib/ratatui_ruby/tea/test_helper.rb
 - lib/ratatui_ruby/tea/version.rb
 - mise.toml
 - rbs_collection.lock.yaml
 - rbs_collection.yaml
+- sig/concurrent.rbs
 - sig/examples/verify_readme_usage/app.rbs
 - sig/examples/widget_command_system/app.rbs
 - sig/open3.rbs
 - sig/ratatui_ruby/tea.rbs
 - sig/ratatui_ruby/tea/command.rbs
+- sig/ratatui_ruby/tea/message.rbs
 - sig/ratatui_ruby/tea/router.rbs
 - sig/ratatui_ruby/tea/runtime.rbs
 - sig/ratatui_ruby/tea/shortcuts.rbs
+- sig/ratatui_ruby/tea/test_helper.rbs
 - sig/ratatui_ruby/tea/version.rbs
 - tasks/example_viewer.html.erb
 - tasks/resources/build.yml.erb

data/examples/app_fractal_dashboard/bags/custom_shell_modal.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-require_relative "custom_shell_input"
-require_relative "custom_shell_output"
-
-# Parent coordinator bag for custom shell modal.
-#
-# Routes to active child (input or output). Checks child model state for transitions.
-module CustomShellModal
-  Command = RatatuiRuby::Tea::Command
-
-  Model = Data.define(:mode, :input, :output)
-  INITIAL = Ractor.make_shareable(Model.new(mode: :none, input: CustomShellInput::INITIAL, output: CustomShellOutput::INITIAL))
-
-  VIEW = lambda do |model, tui|
-    case model.mode
-    when :none then nil
-    when :input then CustomShellInput::VIEW.call(model.input, tui)
-    when :output then CustomShellOutput::VIEW.call(model.output, tui)
-    end
-  end
-
-  UPDATE = lambda do |message, model|
-    case model.mode
-    when :input
-      new_input, cmd = CustomShellInput::UPDATE.call(message, model.input)
-
-      if new_input.cancelled
-        [INITIAL, nil]
-      elsif new_input.submitted
-        shell_cmd = new_input.text
-        new_output = CustomShellOutput::INITIAL.with(command: shell_cmd, running: true)
-        [
-          model.with(mode: :output, input: CustomShellInput::INITIAL, output: new_output),
-          Command.system(shell_cmd, :shell_output, stream: true),
-]
-      else
-        [model.with(input: new_input), cmd]
-      end
-
-    when :output
-      # Route streaming messages (strip :shell_output prefix)
-      routed = case message
-               in [:shell_output, *rest] then rest
-               else message
-      end
-
-      new_output, cmd = CustomShellOutput::UPDATE.call(routed, model.output)
-
-      if new_output.dismissed
-        [INITIAL, nil]
-      else
-        [model.with(output: new_output), cmd]
-      end
-
-    else
-      [model, nil]
-    end
-  end
-
-  def self.open
-    INITIAL.with(mode: :input, input: CustomShellInput::INITIAL)
-  end
-
-  def self.active?(model)
-    model.mode != :none
-  end
-end

data/lib/ratatui_ruby/tea/command/cancellation_token.rb

@@ -1,135 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  module Tea
-    module Command
-      # Cooperative cancellation mechanism for long-running commands.
-      #
-      # Long-running commands block the event loop. Commands that poll, stream, or wait
-      # indefinitely prevent clean shutdown. Killing threads mid-operation corrupts state.
-      #
-      # This class signals cancellation requests. Commands check +cancelled?+ periodically
-      # and stop gracefully. The runtime calls +cancel!+ when shutdown begins.
-      #
-      # Use it to implement WebSocket handlers, database pollers, or any command that loops.
-      #
-      # === Example
-      #
-      #--
-      # SPDX-SnippetBegin
-      # SPDX-FileCopyrightText: 2026 Kerrick Long
-      # SPDX-License-Identifier: MIT-0
-      #++
-      #   class PollerCommand
-      #     include Tea::Command::Custom
-      #
-      #     def call(out, token)
-      #       until token.cancelled?
-      #         data = fetch_batch
-      #         out.put(:batch, data)
-      #         sleep 5
-      #       end
-      #       out.put(:poller_stopped)
-      #     end
-      #   end
-      #--
-      # SPDX-SnippetEnd
-      #++
-      class CancellationToken
-        # Number of times +cancel!+ has been called. :nodoc:
-        #
-        # Exposed for testing thread-safety. Not part of the public API.
-        attr_reader :cancel_count
-
-        # Creates a new cancellation token in the non-cancelled state.
-        def initialize
-          @cancel_count = 0
-          @mutex = Mutex.new
-        end
-
-        # Signals cancellation. Thread-safe.
-        #
-        # Call this to request the command stop. The command checks +cancelled?+
-        # and stops at the next safe point.
-        #
-        # === Example
-        #
-        #--
-        # SPDX-SnippetBegin
-        # SPDX-FileCopyrightText: 2026 Kerrick Long
-        # SPDX-License-Identifier: MIT-0
-        #++
-        #   token = CancellationToken.new
-        #   token.cancel!
-        #   token.cancelled?  # => true
-        #--
-        # SPDX-SnippetEnd
-        #++
-        def cancel!
-          @mutex.synchronize do
-            current = @cancel_count
-            sleep 0 # Force context switch (enables thread-safety testing)
-            @cancel_count = current + 1
-          end
-        end
-
-        # Checks if cancellation was requested. Thread-safe.
-        #
-        # Commands call this periodically in their main loop. When it returns
-        # <tt>true</tt>, the command should clean up and exit.
-        #
-        # === Example
-        #
-        #--
-        # SPDX-SnippetBegin
-        # SPDX-FileCopyrightText: 2026 Kerrick Long
-        # SPDX-License-Identifier: MIT-0
-        #++
-        #   until token.cancelled?
-        #     do_work
-        #     sleep 1
-        #   end
-        #--
-        # SPDX-SnippetEnd
-        #++
-        def cancelled?
-          @cancel_count > 0
-        end
-
-        # Null object for commands that ignore cancellation.
-        #
-        # Some commands complete quickly and do not check for cancellation.
-        # Pass this when the command signature requires a token but the
-        # command does not use it.
-        #
-        # Ractor-shareable. Calling <tt>cancel!</tt> does nothing.
-        class NoneToken < Data.define(:cancelled?)
-          # Does nothing. Ignores cancellation requests.
-          #
-          # === Example
-          #
-          #--
-          # SPDX-SnippetBegin
-          # SPDX-FileCopyrightText: 2026 Kerrick Long
-          # SPDX-License-Identifier: MIT-0
-          #++
-          #   CancellationToken::NONE.cancel!  # => nil (no effect)
-          #--
-          # SPDX-SnippetEnd
-          #++
-          def cancel!
-            nil
-          end
-        end
-
-        # Singleton null token. Always returns <tt>cancelled? == false</tt>.
-        NONE = NoneToken.new(cancelled?: false)
-      end
-    end
-  end
-end