phlex-stimulus 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '01190c3e09b4d2381741d1191ba5b06f2222fed5c20246e69732f80672e742b0'
-  data.tar.gz: 79686f42a9561d53b17c94f7652c762ba9d43358ad710f8fd456129907ea0e76
+  metadata.gz: f7130b1b0657eb83abc485ee417ef0df2f26179c78a8eb4dbdd507e94f42350d
+  data.tar.gz: 4edb623ff5c547ed266a26c8bd3f612d0ecd86869f102c851dda10c26fca6f0d
 SHA512:
-  metadata.gz: 5e857f549c94fa68e8639f9e8bbcfda48626bbf2e3fb960d25d0e1490f97c453cce96174239c660532a1be4a2abd2be85a82221f3a8c2c380da24b5d9ed24fde
-  data.tar.gz: 7d459a8ff17f0626c0fc692b5b9fa929c2081815b8438e38a198518f10e94a16d0157a2c6e5ce94597c37914085d2a8216d121e8e67ffa51bb845af437d43334
+  metadata.gz: a94440b690254ad5a75deb5b6c4b9b6a7ba3bf069ce66e6448ca478b463e2b48739f70f479a7f224fc53d79104ec62f3802417de5e24498ca3484a108687dbb5
+  data.tar.gz: d3888457777dc1807b7c9d437a82c7086a0a5d9a098a5d397304754a4e07b64f75e3b47948a5410fd973e0d39a682953d4e94bcc55944deceaa4d5cb7e1c4edb

data/CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Add changes in new features here. Do not change the gem's version in pull/merge requests.
 
+## [0.3.0] - 18.08.2026
+
+[Diff](https://github.com/espago/phlex-stimulus/compare/v0.2.0...v0.3.0)
+
+- Expand action parameter support
+- Add `Components::Controller#merge` method for easily merging hashes
+- Add a new action parameter definition DSL
+- Add `_target_anchor` helpers to make attaching controller targets to DOM elements easier
+- Add action `_on` helpers to attach controller actions to DOM event easier and more typesafe with action parameters
+
 ## [0.2.0] - 29.07.2026
 
 [Diff](https://github.com/espago/phlex-stimulus/compare/v0.1.3...v0.2.0)

data/README.md

@@ -58,6 +58,10 @@ module Components
     self.controller_name = 'summary'
 
     actions :redirect          # => defines SummaryController.redirect_action  #=> "summary#redirect"
+    action :loadItem do # defines an action with action parameters
+      param :id # required action parameter
+      param :async, optional: true # optional action parameter
+    end
     targets :body              # => defines SummaryController.body_target       #=> "body"
 
     #: (title: String) -> void
@@ -81,11 +85,31 @@ You can render a controller like any other Phlex component:
 
 ```ruby
 render SummaryController.new(title: 'Report') do
-  # define an action
+  # define an action with parameters
+  button(data: merge(SummaryController.load_item_on('click', id: '25'), other: 'data')) { 'Go' }
+
+  # define an action without param checking
   button(data: { action: event('click', SummaryController.redirect_action) }) { 'Go' }
 
   # define a target
-  div(data: { SummaryController.target_key => SummaryController.body_target }) do
+  div(data: merge(SummaryController.body_target_anchor, other: "data")) do
+    plan "Foo"
+  end
+end
+```
+
+This is the same as:
+
+```rb
+div(data: { controller: 'summary', title: 'Report' }) do
+  # define an action with parameters
+  button(data: { action: 'click->summary#loadItem', 'summary-id-param' => '25', other: 'data' }) { 'Go' }
+
+  # define an action
+  button(data: { action: 'click->summary#redirect', other: 'data' }) { 'Go' }
+
+  # define a target
+  div(data: { 'summary-target' => 'body', other: 'data' }) do
     plan "Foo"
   end
 end
@@ -93,6 +117,47 @@ end
 
 ### Controller component helpers
 
+#### `_on`
+
+Each action you define will result in a corresponding `_on` method being available in Ruby.
+Sorbet is fully aware of these methods thanks to a tapioca compiler.
+
+These methods return an anchor hash that can be used as a value in `data:` to attach the
+action with parameters to a DOM event on a particular DOM element.
+
+You can read more about actions [here](https://stimulus.hotwired.dev/reference/actions).
+
+```rb
+class SummaryController < Controller
+  self.controller_name = 'summary'
+
+  actions :exit
+
+  action :loadItem do
+    param :id
+    param :async, optional: true
+  end
+end
+
+SummaryController.exit_on('click') #=> { action: "click->summary#exit" }
+SummaryController.load_item_on('click', id: "25") #=> { action: "click->summary#loadItem", "summary-id-param" => "25" }
+SummaryController.load_item_on('click', id: "25", async: "true") #=> { action: "click->summary#loadItem", "summary-id-param" => "25", "summary-async-param" => "true" }
+```
+
+This can be used to attach an action to an HTML element with full type safety including action params.
+
+```rb
+div(data: SummaryController.exit_on('click'))
+div(data: merge(SummaryController.load_item_on('click', id: "69"), other: "data"))
+```
+
+This is the same as:
+
+```rb
+div(data: { action: 'click->summary#exit' })
+div(data: { action: 'click->summary#loadItem', 'summary-id-param' => '69', other: 'data' })
+```
+
 #### `_action`
 
 Each action you define will result in a corresponding `_action` method being available in Ruby.
@@ -126,14 +191,12 @@ This is the same as:
 div(data: { action: 'click->summary#foo' })
 ```
 
-#### `_target`
+#### `_target_anchor`
 
-Each target you define will result in a corresponding `_target` method being available in Ruby.
+Each target you define will result in a corresponding `_target_anchor` method being available in Ruby.
 Sorbet is fully aware of these methods thanks to a tapioca compiler.
 
-These methods just return the name of the target so they may seem pointless.
-They exist only so that sorbet can check if the actions your using when building HTML elements
-actually exist.
+These methods return a hash that can be used to attach the target.
 
 You can read more about targets [here](https://stimulus.hotwired.dev/reference/targets).
 
@@ -144,13 +207,13 @@ class SummaryController < Controller
   targets :foo
 end
 
-SummaryController.foo_target #=> "foo"
+SummaryController.foo_target_anchor #=> { "summary-target" => "foo" }
 ```
 
 You would use it like so to attach a target with full type safety:
 
 ```rb
-div(data: { SummaryController.target_key => SummaryController.foo_target })
+div(data: SummaryController.foo_target_anchor)
 ```
 
 This is the same as:
@@ -159,6 +222,19 @@ This is the same as:
 div(data: { 'summary-target' => 'foo' })
 ```
 
+You can use `merge` to add other keys alongside the anchor to `data`.
+
+```rb
+div(data: merge(SummaryController.foo_target_anchor, bar: 'elo'))
+```
+
+This is the same as:
+
+```rb
+div(data: { 'summary-target' => 'foo', bar: 'elo' })
+```
+
+
 #### `target_key`
 
 This method returns the key that can be used to attach targets to the controller.
@@ -185,6 +261,39 @@ This is the same as:
 div(data: { 'summary-target' => 'foo' })
 ```
 
+#### `_target`
+
+Each target you define will result in a corresponding `_target` method being available in Ruby.
+Sorbet is fully aware of these methods thanks to a tapioca compiler.
+
+These methods just return the name of the target so they may seem pointless.
+They exist only so that sorbet can check if the actions your using when building HTML elements
+actually exist.
+
+You can read more about targets [here](https://stimulus.hotwired.dev/reference/targets).
+
+```rb
+class SummaryController < Controller
+  self.controller_name = 'summary'
+
+  targets :foo
+end
+
+SummaryController.foo_target #=> "foo"
+```
+
+You would use it like so to attach a target with full type safety:
+
+```rb
+div(data: { SummaryController.target_key => SummaryController.foo_target })
+```
+
+This is the same as:
+
+```rb
+div(data: { 'summary-target' => 'foo' })
+```
+
 #### `dispatched`
 
 This method helps you get the names of custom events dispatched by a stimulus controller.
@@ -207,7 +316,7 @@ div(data: { action: event(SummaryController.dispatched('redirected'), OtherContr
 This is the same as:
 
 ```rb
-div(data: { 'summary:redirected' => 'other#do' })
+div(data: { action: 'summary:redirected->other#do' })
 ```
 
 #### `param`
@@ -233,7 +342,7 @@ div(
   data: {
     action: event('click', SummaryController.foo_action),
     # will be available as `event.id` in the action
-    SummaryController.param('id') => 35,
+    SummaryController.param('id') => '35',
   },
 )
 ```
@@ -241,7 +350,12 @@ div(
 This is the same as:
 
 ```rb
-div(data: { 'summary:redirected' => 'other#do' })
+div(
+  data: {
+    action: 'click->summary#foo',
+    'summary-id-param' => '35',
+  },
+)
 ```
 
 ### Component Helpers

data/lib/generators/phlex/stimulus/install/install_generator.rb

@@ -44,6 +44,7 @@ module Phlex::Stimulus::Generators
       remove_file File.join(destination_root, 'app/javascript/application.js')
       copy_template 'app/javascript/application.ts'
 
+      remove_file File.join(destination_root, 'app/javascript/controllers/hello_controller.js')
       remove_file File.join(destination_root, 'app/javascript/controllers/application.js')
       copy_template 'app/javascript/controllers/application.ts'
 

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/chain_controller.ts.erb

@@ -10,6 +10,7 @@ import { Controller } from "@hotwired/stimulus"
 **/
 class ChainController extends Controller<HTMLElement> {
   controllerChain!: string
+  disconnected: boolean | undefined
 
   async connect() {
     let dataset = this.element.dataset
@@ -17,6 +18,10 @@ class ChainController extends Controller<HTMLElement> {
 
     let i = 0
     for (let controllerName of this.controllerChain.split(' ')) {
+      if (this.disconnected) {
+        return
+      }
+
       let controllerTemplate = this.element.querySelector(`template.${controllerName}-template-${i}`) as HTMLTemplateElement
       let controllerElement = document.importNode(controllerTemplate.content, true)
       let readyPromise = addEventPromise(this.element, `${controllerName}:ready`)
@@ -27,6 +32,10 @@ class ChainController extends Controller<HTMLElement> {
       i++
     }
   }
+
+  disconnect(): void {
+    this.disconnected = true
+  }
 }
 
 application.register("chain", ChainController)

data/lib/generators/phlex/stimulus/install/templates/app/javascript/utils/misc.ts.erb

@@ -32,6 +32,15 @@ export function sleep(timeout: number | undefined): Promise<void> {
  */
 export function addEventPromise(target: EventTarget, type: string): Promise<Event> {
   return new Promise((resolve) => {
-    target.addEventListener(type, (event) => resolve(event))
+    const aborter = new AbortController()
+
+    target.addEventListener(
+      type,
+      (event) => {
+        aborter.abort()
+        resolve(event)
+      },
+      { signal: aborter.signal },
+    )
   })
 }

data/lib/phlex/stimulus/components/base.rb

@@ -7,6 +7,18 @@ module Phlex::Stimulus
     #
     # @abstract
     class Base < Phlex::HTML
+      class << self
+        # Constructs a Stimulus event hook string
+        # eg.
+        #
+        #     event('click', 'summary#redirect') #=> "click->summary#redirect"
+        #
+        #: (String, String) -> String
+        def event(event_name, full_action_name)
+          "#{event_name}->#{full_action_name}"
+        end
+      end
+
       def h = view_context
 
       #: -> String
@@ -70,6 +82,16 @@ module Phlex::Stimulus
       alias strlist class_list
       alias strlist! class_list!
 
+      # Merges the given list of hashes (with optional nils)
+      # into a single hash.
+      #
+      #: [K, V] (*Hash[K, V]?) -> Hash[K, V]
+      def merge(*hashes)
+        hashes.each_with_object({}) do |elem, acc|
+          acc.merge!(elem) if elem
+        end
+      end
+
       #: (String) -> bool
       def image_exists?(path)
         Boolean(h.resolve_asset_path(path))

data/lib/phlex/stimulus/components/controller.rb

@@ -13,11 +13,14 @@ module Phlex::Stimulus
         attr_reader :component
         #: String
         attr_reader :action_name
+        #: Array[ActionParamDefinition]
+        attr_reader :params
 
-        #: (component: singleton(Controller), action_name: String) -> void
-        def initialize(component:, action_name:)
+        #: (component: singleton(Controller), action_name: String, ?params: Array[ActionParamDefinition]) -> void
+        def initialize(component:, action_name:, params: [])
           @component = component
           @action_name = action_name
+          @params = params
         end
 
         #: -> String
@@ -34,6 +37,36 @@ module Phlex::Stimulus
         def ruby_action_method_name
           "#{ruby_name}_action"
         end
+
+        #: -> String
+        def ruby_on_method_name
+          "#{ruby_name}_on"
+        end
+
+        # Define a new parameter for the controller action.
+        #
+        #: (Symbol, ?optional: bool) -> ActionParamDefinition
+        def param(name, optional: false)
+          p = ActionParamDefinition.new(action: self, param_name: name.to_s, optional: optional)
+          params << p
+          p
+        end
+      end
+
+      class ActionParamDefinition
+        #: ActionDefinition
+        attr_reader :action
+        #: String
+        attr_reader :param_name
+        #: bool
+        attr_reader :optional
+
+        #: (action: ActionDefinition, param_name: String, ?optional: bool) -> void
+        def initialize(action:, param_name:, optional: false)
+          @action = action
+          @param_name = param_name
+          @optional = optional
+        end
       end
 
       class TargetDefinition
@@ -57,6 +90,11 @@ module Phlex::Stimulus
         def ruby_target_method_name
           "#{ruby_name}_target"
         end
+
+        #: -> String
+        def ruby_target_anchor_method_name
+          "#{ruby_name}_target_anchor"
+        end
       end
 
       class << self
@@ -120,9 +158,51 @@ module Phlex::Stimulus
           "data-#{target_key}"
         end
 
+        # Register an action with parameters that exists on the Stimulus controller.
+        #
+        #     action :foo do
+        #       param :id
+        #       param :title, optional: true
+        #     end
+        #
+        #: (Symbol) ?{ [self: ActionDefinition] -> void } -> void
+        def action(name, &block)
+          action_def = ActionDefinition.new(
+            component:   self,
+            action_name: name.to_s,
+          )
+          action_defs << action_def
+          action_def.instance_eval(&block) if block
+
+          eval_buff = String.new
+          eval_buff << <<~RUBY
+            def #{action_def.ruby_action_method_name}
+              "\#{controller_name}##{name}"
+            end
+          RUBY
+
+          eval_buff << "\ndef #{action_def.ruby_on_method_name}(event_name"
+          action_def.params.each do |param|
+            eval_buff << ", #{param.param_name}:"
+            eval_buff << ' nil' if param.optional
+          end
+          eval_buff << ")\n"
+
+          eval_buff << "{ action: event(event_name, #{action_def.ruby_action_method_name}), "
+          action_def.params.each do |param|
+            eval_buff << "param(#{param.param_name.inspect}) => #{param.param_name}, "
+          end
+          eval_buff << "}.compact\n"
+          eval_buff << "end\n"
+
+          instance_eval eval_buff, __FILE__, __LINE__
+        end
+
         # Register actions that exist on the Stimulus controller.
         # Will define typed getter methods for each action.
         #
+        #     actions :foo, :bar
+        #
         #: (*Symbol) -> void
         def actions(*actions)
           actions.each do |action|
@@ -136,6 +216,10 @@ module Phlex::Stimulus
               def #{action_def.ruby_action_method_name}
                 "\#{controller_name}##{action}"
               end
+
+              def #{action_def.ruby_on_method_name}(event_name)
+                { action: event(event_name, #{action_def.ruby_action_method_name}) }
+              end
             RUBY
           end
         end
@@ -157,6 +241,10 @@ module Phlex::Stimulus
               def #{target_def.ruby_target_method_name}
                 #{target_str.inspect}
               end
+
+              def #{target_def.ruby_target_anchor_method_name}
+                { target_key => #{target_str.inspect} }
+              end
             RUBY
           end
         end

data/lib/phlex/stimulus/version.rb

@@ -3,6 +3,6 @@
 
 module Phlex
   module Stimulus
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/tapioca/dsl/compilers/phlex_controller.rb

@@ -50,6 +50,42 @@ module Tapioca
               return_type: 'String',
               comments:    comments,
             )
+
+            comments = [
+              RBI::Comment.new(
+                <<~DOC,
+                  Returns na anchor hash that can be used to attach `#{action.action_name}`
+                  action on `#{action.component.controller_name.inspect}` Stimulus controller
+                  to a particular DOM event.
+                DOC
+              ),
+            ]
+            mod.create_method(
+              action.ruby_on_method_name,
+              comments:    comments,
+            ) do |method|
+              method.add_param('event_name')
+              action.params.each do |param|
+                if param.optional
+                  method.add_kw_opt_param(param.param_name, 'nil')
+                else
+                  method.add_kw_param(param.param_name)
+                end
+              end
+
+              method.add_sig do |sig|
+                sig.return_type = 'T::Hash[T.any(Symbol, String), String]'
+
+                sig.add_param('event_name', 'String')
+                action.params.each do |param|
+                  if param.optional
+                    sig.add_param(param.param_name, 'T.nilable(String)')
+                  else
+                    sig.add_param(param.param_name, 'String')
+                  end
+                end
+              end
+            end
           end
 
           targets = constant.target_defs.sort_by(&:target_name)
@@ -69,6 +105,23 @@ module Tapioca
               return_type: 'String',
               comments:    comments,
             )
+
+            comments = [
+              RBI::Comment.new(
+                <<~DOC,
+                  Returns an anchor hash for `#{target.target_name}`
+                  target on `#{target.component.controller_name.inspect}` Stimulus controller
+                  that can be used to attach this target to a particular DOM element.
+
+                  Result: `{ #{constant.target_key} => #{target.target_name.inspect} }`
+                DOC
+              ),
+            ]
+            mod.create_method(
+              target.ruby_target_anchor_method_name,
+              return_type: 'T::Hash[String, String]',
+              comments:    comments,
+            )
           end
 
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-stimulus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Espago