rooibos 0.6.2 → 0.7.0

data/sig/rooibos/router.rbs

@@ -4,171 +4,226 @@
 #++
 
 module Rooibos
-  # Declarative DSL for Fractal Architecture.
-  module Router
-  def self.included: (Class base) -> void
-
-  # Duck type for Data-like models that support `with`.
+  # Duck type for Data-like models that support `with` and `public_send`.
   interface _DataModel
     def public_send: (Symbol, *Object) -> Object
     def with: (**Object) -> self
   end
 
-  # Interface for fractal child modules (fragments).
-  # 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?]
-    @routed_actions: Hash[Symbol, Module]
-    @key_handlers: Hash[Symbol, KeyHandlerConfig]
-    @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
-    @click_handler: ClickHandlerConfig?
-
-    def route: (Symbol | String fragment_model_instance_attr, to: Module) -> void
-    def routes: () -> Hash[Symbol, Module]
-
-    # Action: multiple syntax forms supported
-    def action: (
-      ?(Symbol | String | ^() -> Command::execution?) name,
-      ?(^() -> Command::execution? | Module) value,
-      ?keymap: (Symbol | Array[Symbol])?,
-      ?key: (Symbol | Array[Symbol])?,
-      ?keys: (Symbol | Array[Symbol])?,
-      ?mousemap: (Symbol | Array[Symbol])?,
-      **(^() -> Command::execution? | Module) kwargs
-    ) -> void
-    def actions: () -> Hash[Symbol, ^() -> Command::execution?]
-    def routed_actions: () -> Hash[Symbol, Module]
-
-    private def register_action: (Symbol name, (^() -> Command::execution? | Module) value) -> void
-
-    def keymap: () { (KeymapBuilder) [self: KeymapBuilder] -> void } -> void
-    def key_handlers: () -> Hash[Symbol, 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?]
-    @routed_actions: Hash[Symbol, Module]
-    @key_handlers: Hash[Symbol, KeyHandlerConfig]
-    @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
-    @click_handler: ClickHandlerConfig?
-
-    def initialize: (
-      routes: Hash[Symbol, Module],
-      actions: Hash[Symbol, ^() -> Command::execution?],
-      routed_actions: Hash[Symbol, Module],
-      key_handlers: Hash[Symbol, 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
-
-    # Variadic key binding: accepts multiple keys, optional action kwarg, hash bindings
-    def key: (
-      *(String | Symbol | ^() -> Command::execution? | Hash[Symbol, (^() -> Command::execution?) | Symbol]) args,
-      ?action: Symbol?,
-      ?route: Symbol?,
-      ?when: (^(_DataModel) -> bool)?,
-      ?if: (^(_DataModel) -> bool)?,
-      ?only: (^(_DataModel) -> bool)?,
-      ?guard: (^(_DataModel) -> bool)?,
-      ?unless: (^(_DataModel) -> bool)?,
-      ?except: (^(_DataModel) -> bool)?,
-      ?skip: (^(_DataModel) -> bool)?,
-      **(^() -> Command::execution? | Symbol) bindings
-    ) -> void
-
-    # Alias for key (reads better with multiple keys)
-    alias keys key
-
-    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
-    def register_key_handler: ((Symbol | String) key_name, (^() -> Command::execution? | Symbol)? handler, (Symbol | String | ^() -> Command::execution?)? action_name, Symbol? route, (^(_DataModel) -> bool)? guard) -> 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
+  # Fractal routing DSL for composing hierarchical updates.
+  module Router
+    # Sentinel type for broadcasting to all routes.
+    type all_routes_sentinel = Object
+
+    # Handler callable - zero or two argument form.
+    type handler = ^(message, _DataModel) -> Runtime::update_result
+                 | ^() -> Runtime::update_result
+
+    # Handler or action name symbol.
+    type handler_or_action = handler | Symbol
+
+    # Guard predicate callable.
+    type guard = ^(message, _DataModel) -> boolish
+
+    # Route target: model attribute symbol, fragment module, or Route.
+    type route_target = Symbol | Module | Route
+
+    # Sentinel for "all routes" broadcast.
+    ALL_ROUTES: all_routes_sentinel
+
+    # Module inclusion hook.
+    def self.included: (Class base) -> void
+
+    # Class methods added when Router is included.
+    module ClassMethods : Module
+      @routes: Routes
+      @actions: Actions
+      @forwards: Forwards
+      @receives: Receives
+      @observes: Observes
+      @otherwises: Otherwises
+      @_scoped_target: route_target?
+
+      # Assembles all declarations into a frozen RouterUpdate callable.
+      def from_router: () -> ^(message, _DataModel) -> [_DataModel, Command::execution?]
+
+      # Declares a child route binding a nested fragment to a model slice.
+      def route: (
+        ?Symbol? prefix,
+        to: Module,
+        ?read: (^(_DataModel) -> _DataModel)?,
+        ?write: (^(_DataModel, _DataModel) -> _DataModel)?
+      ) -> Route
+
+      # Forwards all instances of a class to routes.
+      def forward_instances_of: (
+        Class klass,
+        ?to: route_target?,
+        ?as: Symbol?,
+        ?broadcast: bool,
+        ?broadcast_to: Array[route_target]?
+      ) -> void
+
+      # Defines a named action referenceable by symbol.
+      def action: (?Symbol? name, ?handler? handler_arg) -> void
+
+      # Handles matching key events. Stops further processing.
+      def receive_events: (
+        Symbol | Array[Symbol] keys,
+        handler_or_action handler,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      # Handles matching routed messages. Stops further processing.
+      def receive_routed: (
+        Symbol envelope,
+        handler_or_action handler,
+        ?guard: guard?
+      ) -> void
+
+      # Handles matching class instances. Stops further processing.
+      def receive_instances_of: (
+        Class klass,
+        handler_or_action handler,
+        ?guard: guard?
+      ) -> void
+
+      # Handles any message. Stops further processing.
+      def receive_all: (
+        handler_or_action handler,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      # Handles messages matching a custom predicate. Stops further processing.
+      def receive: (
+        guard predicate,
+        handler_or_action handler,
+        ?guard: guard?
+      ) -> void
+
+      # Alias for receive_events.
+      alias intercept_events receive_events
+      # Alias for receive_routed.
+      alias intercept_routed receive_routed
+      # Alias for receive_instances_of.
+      alias intercept_instances_of receive_instances_of
+      # Alias for receive_all.
+      alias intercept_all receive_all
+      # Alias for receive.
+      alias intercept receive
+
+      # Routes matching key events to a declared route.
+      def forward_events: (
+        Symbol | Array[Symbol] keys,
+        ?to: route_target?,
+        ?as: Symbol?,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      # Routes matching routed messages to a declared route.
+      def forward_routed: (
+        Symbol | Array[Symbol] envelopes,
+        ?to: route_target?,
+        ?as: Symbol?
+      ) -> void
+
+      # Routes messages matching a custom predicate.
+      def forward: (
+        guard predicate,
+        ?to: route_target?,
+        ?as: Symbol?
+      ) -> void
+
+      # Observes matching key events. Does not stop further processing.
+      def observe_events: (
+        Symbol | Array[Symbol] keys,
+        handler_or_action handler,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      # Observes matching routed messages. Does not stop further processing.
+      def observe_routed: (
+        Symbol envelope,
+        handler_or_action handler,
+        ?guard: guard?
+      ) -> void
+
+      # Observes matching class instances. Does not stop further processing.
+      def observe_instances_of: (
+        Class klass,
+        handler_or_action handler,
+        ?guard: guard?
+      ) -> void
+
+      # Observes any message. Does not stop further processing.
+      def observe_all: (
+        handler_or_action handler,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      # Observes messages matching a custom predicate. Does not stop further processing.
+      def observe: (
+        guard predicate,
+        handler_or_action handler,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      # Catches unhandled messages as a router-level fallback.
+      def otherwise: (
+        ?route_to: route_target,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      private
+
+      # Route registry for this router.
+      def routes: () -> Routes
+
+      # Action registry for this router.
+      def actions: () -> Actions
+
+      # Forward rule registry for this router.
+      def forwards: () -> Forwards
+
+      # Receive rule registry for this router.
+      def receives: () -> Receives
+
+      # Observe rule registry for this router.
+      def observes: () -> Observes
+
+      # Otherwise rule registry for this router.
+      def otherwises: () -> Otherwises
+
+      # Routes any message to a declared route.
+      def forward_all: (
+        ?to: route_target?,
+        ?guard: guard?,
+        ?when: guard?,
+        ?unless: guard?
+      ) -> void
+
+      # Scopes a positive guard over declarations.
+      def only: (?when: guard?, ?if: guard?) ?{ () -> void } -> void
+
+      # Scopes a negative guard over declarations.
+      def skip: (?when: guard?, ?if: guard?) ?{ () -> void } -> void
+
+      # Scopes forward target for a block.
+      def route_to: (route_target target) ?{ () -> void } -> void
+    end
   end
 end
-end

data/sig/rooibos/runtime.rbs

@@ -59,7 +59,6 @@ module Rooibos
   private
 
   def self.validate_view_return!: (renderable? widget) -> void
-  def self.normalize_update_return: [Model] (update_result? result, Model? previous_model) -> [Model?, Command::execution?]
   def self.validate_ractor_shareable!: [T] (T object, String name) -> void
   def self.fragment_from_kwargs: (Module? root_fragment, ?model: untyped, ?view: untyped, ?update: untyped, ?command: untyped) -> Module
   def self.fragment_invariant!: (String param) -> void

data/sig/rooibos/test_helper.rbs

@@ -10,5 +10,11 @@ module Rooibos
     # Fails if any Command::Error is present in the messages array.
     # Relies on Minitest's flunk method being available in the including class.
     def assert_no_errors: (Array[untyped] messages, ?String? msg) -> void
+
+    # Shared fixtures for Ractor-shareable testing patterns
+    ClearView: ^(untyped, untyped) -> void
+    ExitOnQUpdate: ^(untyped, untyped) -> [untyped, Command::Exit?]
+    ExitOnAnyKeyUpdate: ^(untyped, untyped) -> [untyped, Command::Exit]
   end
 end
+

data/sig/rooibos/transition.rbs

@@ -0,0 +1,33 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # Transition represents a normalized [model, command] tuple from Update.
+  class Transition < Data
+    attr_reader model: _DataModel
+    attr_reader command: Command::execution?
+
+    # Normalizes a DWIM return value into a Transition.
+    def self.from: (update_result result, _DataModel previous_model) -> Transition
+
+    # Creates an initial Transition with no command.
+    def self.initial: (_DataModel model) -> Transition
+
+    # Returns new Transition with updated model, or self if nil.
+    def with_model: (_DataModel? new_model) -> Transition
+
+    # Returns new Transition with updated command, or self if nil.
+    def with_command: (Command::execution? new_command) -> Transition
+
+    # Returns new Transition with command added (batched if existing).
+    def with_added_command: (Command::execution? new_command) -> Transition
+
+    # Returns new Transition with command added via Separate (for observe).
+    def with_separate_command: (Command::execution? new_command) -> Transition
+
+    # Converts to [model, command] tuple.
+    def to_a: () -> [_DataModel, Command::execution?]
+  end
+end

data/sig/rooibos.rbs

@@ -30,16 +30,6 @@ module Rooibos
     ?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 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?]