stimulus-rails-helpers 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a132c55044ffd41c15f8d0702ab3a4f72bbfbf28e8b29c6ceb7e5748e080c76
-  data.tar.gz: 2961baf10845ef355fee37a5b005f43ddb73bfbf5838a55500b21800317acfdf
+  metadata.gz: 5d94e7182dccf2637dc640562e39d84921aa1de182dc622486a64f6a582e82a0
+  data.tar.gz: e9181e3deed0534406dec25caf8920cdf8fb312d39e59a67a252832e7e680686
 SHA512:
-  metadata.gz: fb213579bbba148914e97d4ff6f2544c56931c0e35814f9414ea1cdbfe6c576e60b9855f6cfc3cd77f790b2f327e8a800606c5909ac6a65a3060307549e835ed
-  data.tar.gz: 45135e8bf239106e05990b8192b7b938281c14dfce379fedae2e082091257e1fe9985d60cb7a32d5521254805fa34ff22af1b22f78b30f38ba1fff11e70b593b
+  metadata.gz: 4b23329bf97c705a7fa254d85b91b6c26565884a23df9b1ee9441f4ffba1b638d32b8e09a2ce5b70e45d84c092e1933885594418b2191739d5e3ae5f841370fd
+  data.tar.gz: c6d195bdf2f4964b6a04ddda64f22343550499e14d17f3dadb083285cc7a224019f8fe8933a89fa3fefc6647d20fd8bed568749b7c58b32af3eaa12a4c085b13

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Rails Stimulus Helpers Changelog
+
+## 26 June 2026 - 0.1.2
+
+Fix files missed out when packaging.
+
+## 23 June 2026 - 0.1.1
+
+Fix bad declaration of runtime dependencies.
+
+## 22 June 2026 - 0.1.0
+
+Initial release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jon Gilbraith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,257 @@
+# Rails Helpers for Stimulus
+
+Some helpers to help tame the task of wrangling Stimulus' `data` attributes.
+
+At its core it revolves around a simple short hand notation for describing the various attributes you have to generate when wiring Stimulus controllers into the DOM.
+
+Design philosophy:
+
+* Just use camel case
+* Just use symbols (well almost, for all the Stimulus parts at least)
+* Leverage hashes to describe Stimulus attributes in an intuitive, terser format
+
+No validation or sanity checking, it's purely a shorthand. It won't warn you if you've got a typo in an attribute or anything like that. But hopefully this makes it easier to avoid these kinds of issues.
+
+## How it works
+
+Two core methods for Stimulus attributes, with one more for namespaces, then two more that are identical counterparts for the first two, just for when using namespaces.
+
+## The two methods - create an element or generate data attributes, for adding to another element
+
+Create an element with the helper `stimulus_element` (or `stim_el` for short). Pass a block if you have content to go inside the element. Much like `content_tag` (that's what's used underneath).
+
+Generate attributes with the helper `stimulus_data` (or `stim_data` for short).
+
+Both of these use pretty much the same arguments, other than the fact that `stimulus_element` has an optional first argument of what type of element it is (it defaults to `:div`) and it can take a block.
+
+When using the namespace functionality (documented at the end of this README) you yield an object on which you call two methods that are the direct equivalent of these two methods.
+
+## Example
+
+Simple example of a Stimulus controller declared on a wrapper div, that watches a field via the `refreshCount` action and updates a message in a div with target of `field`
+
+```
+<%= stimulus_element controller: :word_count, class: "form-group" do %>
+  <%=
+    text_field_tag :user_name,
+      params[:user_name],
+      data: stimulus_data(actions: { word_count: :refresh_count }),
+      class: "input text-field"
+  %>
+  <%= stimulus_element targets: { word_count: :field }, class: "word-count-message" %>
+<% end %>
+```
+
+This will produce something along the lines of:
+
+```
+<div data-controller"word-count" class="form-group">
+  <input type="text" name="user_name" value="jon" data-action="word-count#refreshCount" class="input text-field">
+  <div data-word-count-target="field" class="word-count-message"></div>
+</div>
+```
+
+That's all there is to it. You just need to know what other arguments you can pass to `stimulus_element` and `stimulus_data` to handle other types of Stimulus attributes.
+
+## The arguents in depth
+
+### `controllers`
+
+Pass in an array of controller names and you'll get the `data-controller` attribute with the arguments provided.
+
+So for example `controllers: [:word_count, :image_upload]` gets you:
+
+```
+data-controller="word-count image-upload"
+```
+
+### `targets`
+
+Pass in a correctly structured hash and you get the expected data attributes for the targets.
+
+The format is `controller_name: :target_name` for a single target, or `controller_name: [:target_name, :another_target_name]`
+
+So for example:
+
+```
+targets: {
+  calculate_tax: :tax_amount,
+  calculate_total: [:sub_total, :grand_total]
+}
+```
+
+Gets you:
+
+```
+data-calculate-tax-target="taxAmount"
+data-calculate-total-target="subTotal"
+data-calculate-total-target="grandTotal"
+```
+
+### `actions`
+
+Pass in a correctly structured hash (for multiple actions for multiple controllers) and you get the expected data attribute for the actions.
+
+The format is `controller_name: :action_name` for the default event, or `controller_name: { event: :action_name }` for other events.
+
+So for example:
+
+```
+actions: {
+  calculate_tax: :refresh_total,
+  calculate_total: { blur: :warn_if_exceeds_balance }
+}
+```
+
+Gets you:
+
+```
+data-action="calculate-tax#refreshTotal blur->calculate-total#warnIfExceedsBalance"
+```
+
+### `values`
+
+Pass in a correctly structured hash and you get the expected data attributes for the values.
+
+The format is `controller_name: { value_name: :value_value }`
+
+So for example: `values: { calculate_tax: { tax_rate: 20 } }`
+
+Gets you:
+
+```
+data-calculate-tax-tax-rate-value="20"
+```
+
+### `outlets`
+
+Pass in a correctly structured hash and you get the expected data attributes for the outlets.
+
+The format is `source_controller_name: { target_controller_name: :target_controller_selector }`
+
+So for example:
+
+```
+outlets: {
+  calculate_tax: {
+    calculate_total: "#calculate-total"
+  }
+}
+```
+
+Gets you:
+
+```
+data-calculate-tax-calculate-total-outlet="#calculate-total"
+```
+
+# Additional attributes
+
+In both methods, any additional arguments passed in will be passed on as other attributes (`stimulus_element`) or other data attributes (`stimulus_data`).
+
+E.g.
+
+```
+stimulus_element(:span, targets: { calculate_tax: :tax_amount }, class: "highlight")
+```
+
+Gets you:
+
+```
+<span data-calculate-tax-target="taxAmount" class="highlight"></span>
+```
+
+Or
+
+```
+<%=
+  text_field_tag :user_name,
+    params[:user_name],
+    data: stimulus_data(
+      actions: { word_count: :refresh_count },
+      user_tracking_id: 1234
+    ),
+    class: "input text-field"
+%>
+```
+
+```
+<input type="text" name="user_name" value="jon" data-action="word-count#refreshCount" data-user-tracking-id="1234" class="input text-field">
+```
+
+# Namespaces
+
+The quick and dirty way if applying a namespace is to just pass a `namespace` param when calling `stimulus_element` or `stimulus_data`. However in most scenarios that will likely get repetetive.
+
+To declare your namespace once and have it apply automatically you can use a namespace scope.
+
+## Namespace scopes
+
+You can call the `stimulus_namespace` helper (or `stim_ns` for short) with a any number of arguments and it will yield an object for each of them, each representing a separate namespace.
+
+On the yielded object(s) you call `element` (or `el` for short) or `data` (short enough, no alias) on them and they work exactly the same way as the helpers described before, except all outputs will have the prefix attached.
+
+Like so:
+
+```
+<%= stimulus_namespace :admin do |stimulus| %>
+  <%= stimulus.element controller: :word_count do %>
+    text_field_tag :user_name,
+      params[:user_name],
+      data: stimulus.data(actions: { word_count: :refresh_count }),
+      class: "input text-field"
+  %>
+  <%= stimulus_element targets: { word_count: :field }, class: "word-count-message" %>
+<% end %>
+```
+
+This will produce something along the lines of:
+
+```
+<div data-controller"admin--word-count" class="form-group">
+  <input type="text" name="user_name" value="jon" data-action="admin--word-count#refreshCount class="input text-field">
+  <div data-admin--word-count-target="field" class="word-count-message"></div>
+</div>
+```
+
+With multiple namespaces:
+
+```
+<%= stimulus_namespace :one_namespace, :another_namespace do |one, another| %>
+  .
+  .
+  .
+<% end %>
+```
+
+And you can describe deeper nested namespaces too:
+
+```
+<%= stimulus_namespace parent: :child do |stimulus| %>
+  .
+  .
+  .
+<% end %>
+```
+
+Which will apply a prefix of `parent--child--`.
+
+Finally, arrays work too:
+
+```
+<%= stimulus_namespace [:first, :second, :third] do |stimulus| %>
+  .
+  .
+  .
+<% end %>
+```
+
+Which produces `first--second--third--`.
+
+# Problems
+
+It's occurred to me that if you have overlapping namespaces you'll likely want to populate attributes for both of them on the same element, and my current approach doesn't take that into account.
+
+You'd have to call `stimulus_data` and merge the output of that into other calls of `stimulus_element` and `stimulus_data`, which on second thoughts might not be so janky after all.
+
+But I'll be thinking about a good solution for that.

data/stimulus-rails-helpers.gemspec

@@ -1,9 +1,9 @@
 Gem::Specification.new do |s|
   s.name          = "stimulus-rails-helpers"
-  s.version       = "0.1.1"
+  s.version       = "0.1.2"
   s.summary       = "Some helpers to help tame the task of wrangling Stimulus' data attributes."
   s.authors       = ["Jon Gilbraith"]
-  s.files         = ["stimulus-rails-helpers.gemspec"] + Dir["lib/**/*.rb"]
+  s.files         = ["stimulus-rails-helpers.gemspec", "README.md", "CHANGELOG.md", "LICENSE"] + Dir["lib/**/*.rb"]
   s.metadata      = { "source_code_uri" => "https://github.com/jongilbraith/stimulus-rails-helpers" }
   s.license       = "MIT"
   s.homepage      = "https://github.com/jongilbraith/stimulus-rails-helpers"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stimulus-rails-helpers
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Jon Gilbraith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -44,6 +44,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - lib/stimulus-rails-helpers.rb
 - lib/stimulus_rails_helpers/rails_helpers.rb
 - lib/stimulus_rails_helpers/railtie.rb