stimulus_tag_helper 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6abf8489a80e3128ea3a0d0a81b935e5b1b2303e0e911af50069ddaad5d84d8
-  data.tar.gz: 45e22a4a2b76553502ffdf0cca5b49b24f59c3e6f8139f57052b159a0e3a45b0
+  metadata.gz: a65ec6e3ca5fbdb0773a81dd380c4ca366e3de6dc30f5e00d45c8d7371c03a25
+  data.tar.gz: d0593dc01c202aa3de8364b7e48eb97d6cb27a8cd5b1435442756fa7e46683ce
 SHA512:
-  metadata.gz: 72427f49698c21330c73061f040fdd1c4eb7a630dd41b15555dc703234771dd614a00d9ade29258d88d4ffc74b33fa4f23c88d24230d62dc2daaa7770440f58e
-  data.tar.gz: 06c29df33bf224027b006d059ef0631693d7be19a92dddba137a004c774ebb8a91c2408d90a5f5061ba1130f2b700109b2997de8c2d9fe80077d2811332396c7
+  metadata.gz: 5e15a8b9cbc3f422577d967807f7b22fe1c4f9d9c6b947f26bc0ac678a422e0088b4c584e25bf2c2959ad97e7d549cf235b8c8e54c58a2baf5f445cfd0d7d88b
+  data.tar.gz: b2837afeee0dac24ad6abe6ff12cebae2c3ba1510bb126f447eaf30383317148d42ddeba86ab707dc6823e0fccf40417547d2cdf6cb054fb5a0083752d6721a4

data/README.md

@@ -1,19 +1,29 @@
 # stimulus_tag_helper
 
-[![Rubocop](https://github.com/crawler/stimulus_tag_helper/workflows/Rubocop/badge.svg)](https://github.com/crawler/stimulus_tag_helper/actions)
-
+[![Rubocop](https://github.com/crawler/stimulus_tag_helper/actions/workflows/rubocop.yml/badge.svg)](https://github.com/crawler/stimulus_tag_helper/actions/workflows/rubocop.yml)
+[![Tests](https://github.com/crawler/stimulus_tag_helper/actions/workflows/test.yml/badge.svg)](https://github.com/crawler/stimulus_tag_helper/actions/workflows/test.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 [![Gem](https://img.shields.io/gem/v/stimulus_tag_helper.svg)](https://rubygems.org/gems/stimulus_tag_helper)
 
-## WARING!
+## ~~WARING!~~
+
+~~This gem is in the proof of concept stage. I made it for myself, and it is not yet covered with tests and documentation.~~
 
-This gem is in the proof of concept stage. I made it for myself, and it is not yet covered with tests and the documentation.
+🎉 After around a year from initial publication, the helper is pretty useful and simple enough to be stable and compatible with different Ruby/Rails versions. So I decided to cover it with tests and add fancy badges.
+
+If Russia has not dropped a nuclear bomb on Kyiv then the repo is still maintained by me.
 
 ## Description
 
-The stimulusjs is a great js framework for the HTML that you already have, but once u start using it the HTML becomes pretty big as you need to extend it with the attributes that your required to tight it with controllers. So I made this modest (even more modest than the stimulus itself) helper. Currently, I use it with the Slim(http://slim-lang.com/). So for now examples will be in it.
+The stimulusjs is a great js framework for the HTML that you already have, but once you start using it the HTML became wordier, as you need to extend it with more attributes that you already have. So I made this even more modest than the stimulus helper.
+
+Sometimes it makes the template cleaner, sometimes it is not. It's up to you when to use it.
+
+Helper matches Stimulus 2.0+ requirements. You can mix attributes of multiple controllers in a single element or the tag helper. In the end, the stimulus helpers return is a simple Hash.
 
 ---
 
+- [Compatibility](#compatibility)
 - [Quick start](#quick-start)
 - [Examples](#examples)
 - [Support](#support)
@@ -21,13 +31,17 @@ The stimulusjs is a great js framework for the HTML that you already have, but o
 - [Code of conduct](#code-of-conduct)
 - [Contribution guide](#contribution-guide)
 
+## Compatibility
+
+**Ruby:** 3.1, 3.0, 2.7; **Rails:** edge, 7.0, 6.1, 6.0
+
 ## Quick start
 
 ```ruby
-gem 'stimulus_tag_helper', github: 'crawler/stimulus_tag_helper'
+gem `stimulus_tag_helper`
 ```
 
-### In the rails Controller
+### In the Rails Controller
 
 ```ruby
 helper StimulusTagHelper
@@ -41,10 +55,9 @@ include StimulusTagHelper
 
 ## Examples
 
-Some examples is taken from the real app so may be not very)
-
-### "Hello, Stimulus" controller from the stimulusjs homepage
+### The controller from the stimulusjs homepage
 
+**Slim Lang:**
 ```slim
 = stimulus_controller("hello", tag: "div") do |sc|
   = text_field_tag('', '', **sc.target("name"))
@@ -52,9 +65,7 @@ Some examples is taken from the real app so may be not very)
   span[*sc.target("output")]
 ```
 
-Please note that to support nesting, and the stimulus 2.0 attributes notation, the actions and the targets will be prefixed with controller name
-
-So example above will became:
+**Output:**
 
 ```html
 <div data-controller="hello">
@@ -64,29 +75,30 @@ So example above will became:
 </div>
 ```
 
+*To support nesting, and the stimulus 2.0 attributes notation, the actions, and the targets are prefixed with the controller name*
+
 
-## "Slideshow" define controller without tag rendering
+### Initialize the builder and use the controller attribute later
 
-(buttons messed up for the demonstation purposes)
+**Slim Lang**
 
 ```slim
 = stimulus_controller("slideshow") do |sc|
   div[*sc.controller_attribute]
     = button_tag ' ← ', type: 'button', **sc.action("previous")
-    button[*sc.action("next")]
-      '  →
+    = button_tag ' → ', type: 'button', **sc.action("next")
     div[*sc.target("slide")] 🐵
     div[*sc.target("slide")] 🙈
     div[*sc.target("slide")] 🙉
     div[*sc.target("slide")] 🙊
 ```
 
-Became:
+**Output:**
 
 ```html
 <div data-controller="slideshow">
   <button name="button" type="button" data-action="slideshow#previous"> ← </button>
-  <button data-action="slideshow#next"> → </button>
+  <button name="button" type="button" data-action="slideshow#next"> → </button>
   <div data-slideshow-target="slide">🐵</div>
   <div data-slideshow-target="slide">🙈</div>
   <div data-slideshow-target="slide">🙉</div>
@@ -94,39 +106,45 @@ Became:
 </div>
 ```
 
-### Nested controllers
+### Nested controllers example
 
-```slim
-= stimulus_controller( \
-    "flash", tag: "div", class: "flash flash_global", values: { "page-cached" => page_will_be_cached?, src: flash_path },
-    actions: %w[flash-message:connect->registerMessage flash-message:disconnect->removeMessage] \
-  ) do |fc|
-  - unless page_will_be_cached?
-    - flash.keys.each do |type|
-      .flash__message
-        = stimulus_controller( \
-            "flash-message",
-            tag: "div", class: "flash-message flash-message_type_#{type}",
-            actions: %w[animationend->next click->hide] \
-          ) do |fmc|
-          .flash-message__text = flash[type]
-          button.flash-message__dismiss-button[aria-label="Close flash message" *fmc.action("dismiss")]
-            = svg_sprite "icons/common.svg#common-times", class: "icon"
+**Plain Ruby:**
 
+```ruby
+stimulus_controller(:effects) do |ec|
+  stimulus_controller(
+    :clipboard, tag: :div, **ec.controller_property.merge(ec.action_property("clipboard:copy->flash"))
+  ) do |cc|
+    safe_join([
+      "PIN: ",
+      tag.input(**cc.attributes(target: "source"), type: "text", value: "1234", readonly: true),
+      tag.button(**cc.action("copy")) { "Copy to Clipboard" }
+    ])
+  end
+end
 ```
 
+**Output:**
+
+```html
+<div data-controller="clipboard effects" data-action="clipboard:copy->effects#flash">
+  PIN: <input data-clipboard-target="source" type="text" value="1234" readonly="readonly">
+  <button data-action="clipboard#copy">Copy to Clipboard</button>
+</div>
+```
 
 ## Support
 
-If you want to report a bug, or have ideas, feedback or questions about the gem, [let me know via GitHub issues](https://github.com/crawler/stimulus_tag_helper/issues/new) and I will do my best to provide a helpful answer. Happy hacking!
+If you want to report a bug or have ideas, feedback, or questions about the gem, [let me know via GitHub issues](https://github.com/crawler/stimulus_tag_helper/issues/new) and I will do my best to provide a helpful answer. Happy hacking!
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+The gem is available as open-source under the terms of the [MIT License](LICENSE.txt).
 
 ## Code of conduct
 
-Everyone interacting in this project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+Everyone interacting in this project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow
+the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## Contribution guide
 

data/lib/stimulus_tag_helper/stimulus_action.rb

@@ -3,19 +3,30 @@
 module StimulusTagHelper
   class StimulusAction
     STANDARD_PARSER =
-      /^(?<void>(?<event>.+?)(?<void>@(?<target>window|document))?->)?(?<identifier>.+?)(?<void>#(?<method>[^:]+?))(?<void>:(?<options>.+))?$/.freeze
+      /^(?<void>(?<event>.+?)(?<void>@(?<target>window|document))?->)?(?<identifier>.+?)(?<void>#(?<method>[^:]+?))(?<void>:(?<options>.+))?$/
     NO_CONTROLLER_PARSER =
-      /^(?<void>(?<event>.+?)?(?<void>@(?<target>window|document))?->)?(?<method>[^#:]+?)(?<void>:(?<options>.+))?$/.freeze
-    class_attribute :parts, default: %i[identifier method event target options]
-    attr_reader(*parts)
+      /^(?<void>(?<event>.+?)?(?<void>@(?<target>window|document))?->)?(?<method>[^#:]+?)(?<void>:(?<options>.+))?$/
+    PARTS = %i[identifier method event target options]
 
-    # event is nil to let stimulusjs decide default event for the element
+    # event is nil to let stimulus.js decide default event for the element
     def initialize(identifier:, method:, event: nil, target: nil, options: nil)
-      parts.each do |part|
+      PARTS.each do |part|
         instance_variable_set(:"@#{part}", binding.local_variable_get(part))
       end
     end
 
+    def to_s
+      "#{event_part.presence&.+("->")}#{handler_part}"
+    end
+
+    def ==(other)
+      other.is_a?(StimulusAction) && other.to_s == to_s
+    end
+
+    private
+
+    attr_reader(*PARTS) # define attr readers for each part
+
     def event_part
       "#{event}#{"@#{target}" if target}"
     end
@@ -24,16 +35,15 @@ module StimulusTagHelper
       "#{identifier}##{method}#{":#{options}" if options}"
     end
 
-    def to_s
-      "#{event_part.presence&.+'->'}#{handler_part}".html_safe
-    end
+    class << self
+      def parse(string, **defaults)
+        to_parse = string.to_s
+        parsed =
+          to_parse.include?("#") ? STANDARD_PARSER.match(to_parse) : NO_CONTROLLER_PARSER.match(to_parse)
+        raise(ArgumentError, "Can't parse stimulus action #{string.inspect}") unless parsed
 
-    def self.parse(str)
-      parsed =
-        str.include?("#") ? STANDARD_PARSER.match(str) : NO_CONTROLLER_PARSER.match(str)
-      raise(ArgumentError, "can't parse action string #{str}") unless parsed
-
-      parsed.named_captures.except("void").symbolize_keys
+        new(**defaults.merge(parsed.named_captures.except("void").transform_keys(&:to_sym)))
+      end
     end
   end
 end

data/lib/stimulus_tag_helper/stimulus_controller_builder.rb

@@ -18,14 +18,14 @@ module StimulusTagHelper
 
         alias #{name} #{name}_#{attribute} # alias value value_attribute
 
-        def #{name}_#{property}(*args, **kws)                                        # def value_property(*args, **kws)
-          @template.stimulus_#{name}_#{property}(*args.unshift(@identifier), **kws)  #   stimulus_value_property(@identifier, *args, **kws)
-        end                                                                          # end
+        def #{name}_#{property}(*args, **kwargs)                                        # def value_property(*args, **kwargs)
+          @template.stimulus_#{name}_#{property}(*args.unshift(@identifier), **kwargs)  #   stimulus_value_property(@identifier, *args, **kwargs)
+        end                                                                             # end
       RUBY
     end
 
-    def attributes(props)
-      { data: @template.stimulus_properties(@identifier, props) }
+    def attributes(**attributes)
+      @template.stimulus_attributes(@identifier, **attributes)
     end
   end
 end

data/lib/stimulus_tag_helper/version.rb

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

data/lib/stimulus_tag_helper.rb

@@ -1,20 +1,25 @@
 # frozen_string_literal: true
 
-module StimulusTagHelper
-  autoload :VERSION, "stimulus_tag_helper/version"
-  autoload :StimulusAction, "stimulus_tag_helper/stimulus_action"
-  autoload :StimulusControllerBuilder, "stimulus_tag_helper/stimulus_controller_builder"
+require "active_support/all"
+require "zeitwerk"
+Zeitwerk::Loader.for_gem.setup
 
+module StimulusTagHelper
   def self.base_properties
-    %i[controller values classes targets target actions]
+    %i[controller values classes targets target actions].freeze
+  end
+
+  def self.aliases
+    {controller: :controllers, value: :values, class: :classes, target: :targets, action: :actions}.freeze
   end
 
-  def self.aliases_map
-    { values: :value, classes: :class, actions: :action }
+  def self.methods_map
+    {controllers: :stimulus_controllers_property, values: :stimulus_values_properties,
+     classes: :stimulus_classes_properties, targets: :stimulus_targets_properties, actions: :stimulus_actions_property}.freeze
   end
 
   def self.alias_properties
-    @alias_properties ||= aliases_map.values
+    @alias_properties ||= aliases.keys
   end
 
   def self.property_names
@@ -22,11 +27,11 @@ module StimulusTagHelper
   end
 
   def self.prevent_duplicates(properties_set, name)
-    alias_name = StimulusTagHelper.aliases_map[name]
+    alias_name = StimulusTagHelper.aliases[name]
     return unless alias_name && (properties_set[alias_name])
 
     raise(ArgumentError, <<~STRING)
-      "#{name} and #{alias_name} can't be passed at same time"
+      "#{name} and #{alias_name} should not be passed at the same time"
     STRING
   end
 
@@ -42,33 +47,60 @@ module StimulusTagHelper
     end
   end
 
-  def stimulus_controller_tag(identifier, tag:, data: {}, **args, &block)
-    data.merge!(stimulus_controllers_property(identifier))
-    # class option goes to the tag
-    data.merge!(stimulus_properties(identifier, args.extract!(*StimulusTagHelper.property_names - %i[class])))
+  # controller arg is used to add additional stimulus controllers to the element
+  def stimulus_controller_tag(identifier, tag:, data: {}, controller: nil, **args, &block)
+    # class class interpreted as class attribute, not a stimulus class
+    # what about value and action action? maybe here should be warning
+
+    # maybe data should be merged in args?
+    data.merge!(stimulus_properties(
+      identifier,
+      controller: data[:controller] || controller, # nil is allowed, because the args will be prepended by the identifier
+      **args.extract!(*StimulusTagHelper.property_names - %i[class])
+    ))
     tag_builder.tag_string(tag, **args.merge(data: data), &block)
   end
 
-  def stimulus_properties(identifier, props)
+  # Does not includes the controller attribute
+  def stimulus_attributes(...)
+    {data: stimulus_properties(...)}
+  end
+
+  alias_method :stimulus_attribute, :stimulus_attributes
+
+  # Does not includes the controller property
+  def stimulus_properties(identifier, **props)
     {}.tap do |data|
       StimulusTagHelper.property_names.each do |name|
-        next unless props[name]
+        next unless props.key?(name)
 
-        params = Array.wrap(props[name]).unshift(identifier)
-        kwparams = params.last.is_a?(Hash) ? params.pop : {}
+        args = Array.wrap(props[name]).unshift(identifier)
+        kwargs = args.last.is_a?(Hash) ? args.pop : {}
         StimulusTagHelper.prevent_duplicates(props, name)
-        name = name.to_s
-        property = name.pluralize == name ? "properties" : "property"
-        data.merge!(public_send("stimulus_#{name}_#{property}", *params, **kwparams))
+        data.merge!(
+          public_send(StimulusTagHelper.methods_map[StimulusTagHelper.aliases[name] || name], *args, **kwargs)
+        )
       end
     end
   end
 
+  def stimulus_controllers_attribute(...)
+    {data: stimulus_controllers_properties(...)}
+  end
+
+  alias_method :stimulus_controller_attribute, :stimulus_controllers_attribute
+
   def stimulus_controllers_property(*identifiers)
-    { controller: Array.wrap(identifiers).join(" ") }
+    {controller: Array.wrap(identifiers).compact.join(" ")}
   end
 
-  alias stimulus_controller_property stimulus_controllers_property
+  alias_method :stimulus_controller_property, :stimulus_controllers_property
+
+  def stimulus_values_attributes(...)
+    {data: stimulus_values_properties(...)}
+  end
+
+  alias_method :stimulus_value_attribute, :stimulus_values_attributes
 
   def stimulus_values_properties(identifier, **values)
     {}.tap do |properties|
@@ -78,7 +110,13 @@ module StimulusTagHelper
     end
   end
 
-  alias stimulus_value_property stimulus_values_properties
+  alias_method :stimulus_value_property, :stimulus_values_properties
+
+  def stimulus_classes_attributes(...)
+    {data: stimulus_classes_properties(...)}
+  end
+
+  alias_method :stimulus_class_attribute, :stimulus_classes_attributes
 
   def stimulus_classes_properties(identifier, **classes)
     {}.tap do |properties|
@@ -88,47 +126,33 @@ module StimulusTagHelper
     end
   end
 
-  alias stimulus_class_property stimulus_classes_properties
+  alias_method :stimulus_class_property, :stimulus_classes_properties
 
-  def stimulus_targets_properties(identifier, *targets)
-    {}.tap do |properties|
-      targets.each do |target|
-        properties.merge!(stimulus_target_property(identifier, target))
-      end
-    end
+  def stimulus_targets_attributes(...)
+    {data: stimulus_targets_properties(...)}
   end
 
-  def stimulus_target_property(identifier, name)
-    { "#{identifier}-target" => name }
+  alias_method :stimulus_target_attribute, :stimulus_targets_attributes
+
+  def stimulus_targets_properties(identifier, *targets)
+    {"#{identifier}-target" => targets.join(" ")}
   end
 
-  def stimulus_actions_properties(identifier, *actions_params)
+  alias_method :stimulus_target_property, :stimulus_targets_properties
+
+  def stimulus_actions_property(identifier, *actions_params)
     {
-      "action" => actions_params.map { |action_params| stimulus_action_value(identifier, action_params) }.join(" ")
+      action: actions_params.map { |action_params| stimulus_action_value(identifier, action_params) }.join(" ").html_safe
     }
   end
 
-  alias stimulus_action_property stimulus_actions_properties
-
-  def stimulus_action_value(identifier, action_params_or_action_str)
-    if action_params_or_action_str.is_a?(String)
-      action_params_or_action_str = StimulusAction.parse(action_params_or_action_str)
-    end
+  alias_method :stimulus_action_property, :stimulus_actions_property
 
-    StimulusAction.new(identifier: identifier, **action_params_or_action_str).to_s
-  end
-
-  property_names.each do |name|
-    name = name.to_s
-    attribute, property = name.pluralize == name ? %w[attributes properties] : %w[attribute property]
-    class_eval <<-RUBY, __FILE__, __LINE__ + 1
-      def stimulus_#{name}_#{attribute}(...)        # def stimulus_value_attribute(...)
-        { data: stimulus_#{name}_#{property}(...) } #   { data: stimulus_value_property(...) }
-      end                                           # end
-    RUBY
-  end
+  def stimulus_action_value(identifier, args_or_string) # :nodoc:
+    return StimulusAction.parse(args_or_string, identifier: identifier) if args_or_string.is_a?(String)
 
-  def stimulus_attribute(...)
-    { data: stimulus_properties(...) }
+    # WARNING: this is unsafe for public use by unexpired developers.
+    # TODO: find a elegant way to escape -> splitter escaping &gt; back and forth.
+    StimulusAction.new(identifier: identifier, **args_or_string).to_s.html_safe
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_tag_helper
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Anton Topchii
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-06-23 00:00:00.000000000 Z
+date: 2022-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
 description:
 email:
 - player1@infinitevoid.net
@@ -60,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: A form_for like, compact and elegant way to define stimulus attributes in