ratatui_ruby-tea 0.2.0 → 0.3.0

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.0"
   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/sig/ratatui_ruby/tea/command.rbs

@@ -0,0 +1,47 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Sentinel value for application termination.
+      class Exit < Data
+        def self.new: () -> instance
+      end
+
+      # Command to run a shell command via Open3.
+      class System < Data
+        attr_reader command: String
+        attr_reader tag: Symbol | Class
+        attr_reader stream: bool
+
+        # Returns true if streaming mode is enabled.
+        def stream?: () -> bool
+
+        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
+
+        def self.new: (inner_command: execution, mapper: ^(untyped) -> untyped) -> instance
+      end
+
+      # Union type for all valid commands
+      type execution = Execute | Mapped
+
+      # Creates a quit command.
+      def self.exit: () -> Quit
+
+      # 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
+    end
+  end
+end

data/sig/ratatui_ruby/tea/router.rbs

@@ -0,0 +1,99 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    # Interface for child bag modules (required by route).
+    interface _Bag[M]
+      def self.UPDATE: ^(top, M) -> [M, Command::execution?]
+      def self.INITIAL: M
+    end
+
+    # Declarative DSL for Fractal Architecture.
+    module Router
+      def self.included: (Class base) -> void
+
+      # Guard callable: receives model, returns truthy/falsy.
+      type guard[M] = ^(M model) -> boolish
+
+      # Handler callable: returns a command or nil.
+      type handler = ^() -> Command::execution?
+
+      # Click handler: receives x, y coordinates.
+      type click_handler = ^(Integer x, Integer y) -> Command::execution?
+
+      # Key handler config stored in handlers hash.
+      type key_config[M] = {
+        handler: handler?,
+        action: Symbol?,
+        route: Symbol?,
+        guard: guard[M]?
+      }
+
+      # Mouse handler config.
+      type mouse_config = {
+        handler: handler | click_handler,
+        action: Symbol?
+      }
+
+      # Class methods added when Router is included.
+      module ClassMethods
+        def route: [M] (Symbol | String prefix, to: _Bag[M]) -> void
+        def routes: () -> Hash[Symbol, Module]
+
+        def action: (Symbol | String name, handler) -> void
+        def actions: () -> Hash[Symbol, handler]
+
+        def keymap: () { () -> void } -> void
+        def key_handlers: [M] () -> Hash[String, key_config[M]]
+
+        def mousemap: () { () -> void } -> void
+        def mouse_handlers: () -> Hash[Symbol, mouse_config]
+
+        # Generates an UPDATE lambda from routes, keymap, and mousemap.
+        def from_router: [M, Msg] () -> ^(Msg message, M model) -> [M, Command::execution?]
+      end
+
+      # Builder for keymap DSL.
+      class KeymapBuilder
+        @handlers: Hash[String, key_config[top]]
+
+        attr_reader handlers: Hash[String, key_config[top]]
+
+        def initialize: () -> void
+
+        # Registers a key handler with optional guards.
+        def key: [M] (
+          String | Symbol key_name,
+          handler | Symbol handler_or_action,
+          ?route: Symbol?,
+          ?when: guard[M]?,
+          ?if: guard[M]?,
+          ?only: guard[M]?,
+          ?guard: guard[M]?,
+          ?unless: guard[M]?,
+          ?except: guard[M]?,
+          ?skip: guard[M]?
+        ) -> void
+      end
+
+      # Builder for mousemap DSL.
+      class MousemapBuilder
+        @handlers: Hash[Symbol, mouse_config]
+
+        attr_reader handlers: Hash[Symbol, mouse_config]
+
+        def initialize: () -> void
+
+        def click: (click_handler | Symbol handler_or_action) -> void
+        def scroll: (:up | :down direction, handler | Symbol handler_or_action) -> void
+
+        private
+
+        def register: (Symbol key, handler | click_handler | Symbol handler_or_action) -> void
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby-tea
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kerrick Long
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: 0.9.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: 0.9.1
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -101,20 +101,38 @@ files:
 - doc/images/verify_readme_usage.png
 - doc/images/widget_cmd_exec.png
 - 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/verify_readme_usage/README.md
 - examples/verify_readme_usage/app.rb
-- examples/widget_cmd_exec/README.md
-- examples/widget_cmd_exec/app.rb
+- examples/widget_command_system/README.md
+- examples/widget_command_system/app.rb
 - exe/.gitkeep
 - lib/ratatui_ruby/tea.rb
-- lib/ratatui_ruby/tea/cmd.rb
+- lib/ratatui_ruby/tea/command.rb
+- lib/ratatui_ruby/tea/router.rb
 - lib/ratatui_ruby/tea/runtime.rb
+- lib/ratatui_ruby/tea/shortcuts.rb
 - lib/ratatui_ruby/tea/version.rb
 - mise.toml
 - sig/examples/verify_readme_usage/app.rbs
-- sig/examples/widget_cmd_exec/app.rbs
+- sig/examples/widget_command_system/app.rbs
 - sig/ratatui_ruby/tea.rbs
-- sig/ratatui_ruby/tea/cmd.rbs
+- sig/ratatui_ruby/tea/command.rbs
+- sig/ratatui_ruby/tea/router.rbs
 - sig/ratatui_ruby/tea/runtime.rbs
 - tasks/example_viewer.html.erb
 - tasks/resources/build.yml.erb

data/lib/ratatui_ruby/tea/cmd.rb

@@ -1,88 +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
-    # 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, Cmd.quit]
-    #
-    #   # Run a shell command; produces [:got_files, {stdout:, stderr:, status:}]
-    #   [model, Cmd.exec("ls -la", :got_files)]
-    #
-    #   # No side effect
-    #   [model, nil]
-    module Cmd
-      # Sentinel value for application termination.
-      #
-      # The runtime detects this before dispatching. It breaks the loop immediately.
-      Quit = Data.define
-
-      # Creates a quit command.
-      #
-      # Returns a sentinel the runtime detects to terminate the application.
-      #
-      # === Example
-      #
-      #   def update(msg, model)
-      #     case msg
-      #     in { type: :key, code: "q" }
-      #       [model, Cmd.quit]
-      #     else
-      #       [model, nil]
-      #     end
-      #   end
-      def self.quit
-        Quit.new
-      end
-
-      # Command to run a shell command via Open3.
-      #
-      # The runtime executes the command and produces a message:
-      # <tt>[tag, {stdout:, stderr:, status:}]</tt>
-      #
-      # The +status+ is the integer exit code (0 = success).
-      Exec = Data.define(:command, :tag)
-
-      # Creates a shell execution command.
-      #
-      # [command] Shell command string to execute.
-      # [tag] Symbol or class to tag the result message.
-      #
-      # When the command completes, the runtime sends
-      # <tt>[tag, {stdout:, stderr:, status:}]</tt> to update.
-      #
-      # === Example
-      #
-      #   # Return this from update:
-      #   [model.with(loading: true), Cmd.exec("ls -la", :got_files)]
-      #
-      #   # Then handle it later:
-      #   def update(msg, model)
-      #     case msg
-      #     in [:got_files, {stdout:, status: 0}]
-      #       [model.with(files: stdout.lines), nil]
-      #     in [:got_files, {stderr:, status:}]
-      #       [model.with(error: stderr), nil]
-      #     end
-      #   end
-      def self.exec(command, tag)
-        Exec.new(command:, tag:)
-      end
-    end
-  end
-end

data/sig/ratatui_ruby/tea/cmd.rbs

@@ -1,32 +0,0 @@
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  module Tea
-    module Cmd
-      # Sentinel value for application termination.
-      class Quit < Data
-        def self.new: () -> instance
-      end
-
-      # Command to run a shell command via Open3.
-      class Exec < Data
-        attr_reader command: String
-        attr_reader tag: Symbol | Class
-
-        def self.new: (command: String, tag: (Symbol | Class)) -> instance
-      end
-
-      # Union type for all valid commands
-      type execution = Exec
-
-      # Creates a quit command.
-      def self.quit: () -> Quit
-
-      # Creates a shell execution command.
-      def self.exec: (String command, (Symbol | Class) tag) -> Exec
-    end
-  end
-end