stimulizer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4c0fe32e16955ce1cd02692f9c128243e3c7dcab8e55a0eca02e2a158d11e4d
-  data.tar.gz: 85e92867bb922c53924d2205f8db804f5aee7b41dd67d656ee49ea0a4eb7bf50
+  metadata.gz: c4ffb6c46838fb14026e86fdd23fcdaf02e96c54cc083f61de0700a00a3887da
+  data.tar.gz: 5d55ddacece2a9458bd3f1b1b44bdaf686e31e1295572d55a0ee83a16af29a26
 SHA512:
-  metadata.gz: 0ad40b936ef85923d186925342c25631066657dec4a1ebc8c7cb5adbf704d403fcb82ced1e922e4369a4cb7e036769fd96728ab4480d6e48cf1c4916bf762ae4
-  data.tar.gz: 90c2bc2f3cdd12cb919ba4f5d2d301a9cf49d11c4441a18d59c6825cb0e35a15fce7c9027a54a18634c2137cc8640a392924394ce8e970c96680b0076b0a34a1
+  metadata.gz: db21b71f5bc84d6fc9244d3ef2d918d5512c70aa5fe51c0149e968c85377287681ee5ff1d40b9c84b52861eeb683254f7a3a4bf09e0d3a82457950a9c7c61dc0
+  data.tar.gz: c7532b43834fe459df96cbbf623493a553a5cbafe8611ae77f682af9e29851fcaa08f68c3d2c246f9a224ba92cd19c04954859b11a6a041222b57c44f5d1031f

data/README.md

@@ -1,8 +1,36 @@
 # Stimulizer
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/stimulizer`. To experiment with that code, run `bin/console` for an interactive prompt.
+Easily work with StimulusJS `data-*` attributes in ViewComponents, Phlex templates, etc.
 
-TODO: Delete this and the text above, and describe your gem
+This gem is particularly handy in ViewComponents and Phlex when you have a 1-1 relationship between a component and a Stimulus controller, especially when using 'sidecar' controllers.
+
+For example:
+
+### ViewComponent
+```ruby
+  class Mynamespace::Deeper::ButtonsGridComponent < ApplicationComponent
+  # ...
+```
+#### Before
+```html
+<div 
+  data-controller="mynamespace--deeper--buttons-grid-component"
+  data-mynamespace--deeper--buttons-grid-component-url-value="http://example.com"
+  data-mynamespace--deeper--buttons-grid-component-url-color="#ff0000"
+  data-action="click->data-mynamespace--deeper--buttons-grid-component#doSomething"
+>
+```
+
+#### After
+```html
+<div 
+  <%= stimulus(
+    :controller, 
+    values: {url: "http://example.com", color: "#ff0000"}, 
+    action: "click->doSomething"
+  )%>
+>
+```
 
 ## Installation
 
@@ -21,8 +49,121 @@ Or install it yourself as:
     $ gem install stimulizer
 
 ## Usage
+Include this in your model:
+
+```ruby
+class MyComponent < ApplicationComponent
+  include Stimulizer
+  # ...
+```
+
+Render the stimulusjs data strings into your template...
+
+```html
+  <!-- use the derived controller name -->
+  <%= stimulus(:controller) %>   
+
+  <!-- specify the controller explicity, and/or add more controllers space-separated -->
+  <%= stimulus(controller: "another foo")
+  
+  <!-- Note: 'action' is singular because it works like 'data-action' -->
+  <%= stimulus(action: "click->doThing")
+
+  <!-- but you can have multiple actions separated by spaces -->
+  <%= stimulus(action: "click->doThing mouseup->otherThing")
+
+  <!-- you can also skip the event, just like usual -->
+  <%= stimulus(action: "doThing")
+
+  <!-- 
+    target for this element (if you need to also target it for other controllers, you'll have to do that manually with the old 'data-blah-target=' approach)
+  -->
+  <%= stimulus(target: "button")
+
+  <!-- supports the 'classes' feature -->
+  <%= stimulus(classes: {foo: "text-red-500", busy: "opacity-50 animate-spin"})
+  
+  <!-- supports the 'values' feature -->
+  <%= stimulus(values: {url: "https://example.com"})
+
+  <!-- supports the 'params' feature -->
+  <%= stimulus(params: {foo: "bar", this_thing: "whatever"})
+```
+... or combine them:
+```
+  <%= stimulus(:controller, target: "button", action: "click->doThing")
+```
+
+## Options
+
+### `stimulize`
+Use the `stimulize` method after including the module to set some config options...
+
+#### `ignore_prefix`
+Use the `ignore_prefix` option to chop off some of the namespacing if you want to shorten up those crazy-long controller filenames.
+```ruby
+stimulize ignore_prefix: "Components::"
+```
+
+#### `output`
+Use the `output` option to change from an html-style string of data attributes (default) to a Hash of data attributes, useful in other circumstances, like tag builders and Phlex views.
+```ruby
+stimulize output: :hash
+```
+
+## Overriding the derived controller name
+My main use case for Stimulizer is with so-called 'sidecar' javascript. That is, if I have a component in the filepath `components/foo/bar/other/button_component.rb`, I will also have a stimulus controller at `components/foo/bar/other/button_component_controller.js`. 
+
+**In this case, Stimulizer will auto-derive the controller name properly.**
+
+If you're not doing things this way, you may need to manually set your controller name in each component/template...
 
-TODO: Write usage instructions here
+```ruby
+def stimulus_controller
+  "whatever--name--you-want-here"
+end
+```
+
+**or...**
+
+You can also pass the controller name directly to the `stimulus()` method. This starts to become less automagical, but still handy in reducing the repetition of those controller names.
+
+```ruby
+<div
+  <%= stimulus(
+    controller_name: "my--fancy--buttons", 
+    action: "click->show", 
+    values: {url: "example.com"}
+  ) %>
+>
+
+# => <div data-controller='my--fancy--buttons' data-action='click->my--fancy--buttons#show' data-my--fancy--buttons-url-value="example.com">
+```
+
+## Using with Phlex (or if you want a hash for some other reason)
+By default, Stimulizer returns a html-style string of `data-*` attributes from the `stimulus()` method. But if you're using something like Phlex templates, or if you want to use this with a tag-building method, you might want the original Hash instead. You have two options:
+
+### 1. Class-level configuration
+```ruby
+module Views
+  class ApplicationView < Phlex::View
+    include Stimulizer
+    stimulize output: :hash
+```
+
+### 2. Specifically ask for a hash with `stimulus_hash` instead
+```ruby
+stimulus_hash(:controller, action: "click->doThis")
+```
+
+## Phlex: Destructuring for the win!
+Thanks to [@joeldrapper](https://github.com/joeldrapper) for suggesting this and for inspiring the idea of this gem. You can use destructuring to great effect in Phlex views:
+
+```ruby
+div(**stimulus(:controller, action: "click->show"), class: "text-red-500") do
+  # ...
+```
+*Note that this example is assuming you've turned on `:hash` mode as above. You could also use `**stimulus_hash()` in the same way.*
 
 ## Development
 

data/lib/stimulizer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stimulizer
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/stimulizer.rb

@@ -31,8 +31,12 @@ module Stimulizer
     build_stimulus_controller
   end
 
+  def stimulus_hash(*args)
+    build_stimulus_hash(*args)
+  end
+
   def stimulus(*args)
-    output = build_stimulus_hash(*args)
+    output = stimulus_hash(*args)
     return output if _stimulizer_opts[:output] == :hash
 
     raw(
@@ -71,7 +75,8 @@ module Stimulizer
   # ... or combine them:
   #
   #   <%= stimulus(:controller, target: "button", action: "click->doThing")
-  def build_stimulus_hash(default_controller = false, controller: nil, target: nil, action: nil, params: nil, values: nil, classes: nil)
+  def build_stimulus_hash(default_controller = false, controller_name: nil, controller: nil, target: nil, action: nil, params: nil, values: nil, classes: nil)
+    raise ArgumentError(":controller_name specified, but blank") if controller_name&.blank?
     raise ArgumentError(":controller specified, but blank") if controller&.blank?
     raise ArgumentError(":target specified, but blank") if target&.blank?
     raise ArgumentError(":action specified, but blank") if action&.blank?
@@ -82,8 +87,13 @@ module Stimulizer
     {}.tap do |hash|
       hash[:"data-controller"] = ""
 
+      local_controller_name = stimulus_controller
+
       if default_controller.to_s.downcase.to_sym == :controller
         hash[:"data-controller"] += " #{stimulus_controller}"
+      elsif controller_name.present?
+        hash[:"data-controller"] += " #{controller_name}"
+        local_controller_name = controller_name
       end
 
       hash[:"data-controller"] += " #{controller}" if controller
@@ -100,7 +110,7 @@ module Stimulizer
           if function.include?("#")
             "#{event}#{function}"
           else
-            "#{event}#{stimulus_controller}##{function}"
+            "#{event}#{local_controller_name}##{function}"
           end
         end.compact
 
@@ -108,18 +118,18 @@ module Stimulizer
       end
 
       params&.each do |key, value|
-        hash[:"data-#{stimulus_controller}-#{LuckyCase.dash_case(key.to_s)}-param"] = value
+        hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-param"] = value
       end
 
       values&.each do |key, value|
-        hash[:"data-#{stimulus_controller}-#{LuckyCase.dash_case(key.to_s)}-value"] = value
+        hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-value"] = value
       end
 
       classes&.each do |key, value|
-        hash[:"data-#{stimulus_controller}-#{LuckyCase.dash_case(key.to_s)}-class"] = value
+        hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-class"] = value
       end
 
-      hash[:"data-#{stimulus_controller}-target"] = target if target
+      hash[:"data-#{local_controller_name}-target"] = target if target
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulizer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Matt E Patterson