stimulus_tag_helper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6abf8489a80e3128ea3a0d0a81b935e5b1b2303e0e911af50069ddaad5d84d8
+  data.tar.gz: 45e22a4a2b76553502ffdf0cca5b49b24f59c3e6f8139f57052b159a0e3a45b0
+SHA512:
+  metadata.gz: 72427f49698c21330c73061f040fdd1c4eb7a630dd41b15555dc703234771dd614a00d9ade29258d88d4ffc74b33fa4f23c88d24230d62dc2daaa7770440f58e
+  data.tar.gz: 06c29df33bf224027b006d059ef0631693d7be19a92dddba137a004c774ebb8a91c2408d90a5f5061ba1130f2b700109b2997de8c2d9fe80077d2811332396c7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Anton Topchii
+
+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,133 @@
+# stimulus_tag_helper
+
+[![Rubocop](https://github.com/crawler/stimulus_tag_helper/workflows/Rubocop/badge.svg)](https://github.com/crawler/stimulus_tag_helper/actions)
+
+[![Gem](https://img.shields.io/gem/v/stimulus_tag_helper.svg)](https://rubygems.org/gems/stimulus_tag_helper)
+
+## WARING!
+
+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.
+
+## 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.
+
+---
+
+- [Quick start](#quick-start)
+- [Examples](#examples)
+- [Support](#support)
+- [License](#license)
+- [Code of conduct](#code-of-conduct)
+- [Contribution guide](#contribution-guide)
+
+## Quick start
+
+```ruby
+gem 'stimulus_tag_helper', github: 'crawler/stimulus_tag_helper'
+```
+
+### In the rails Controller
+
+```ruby
+helper StimulusTagHelper
+```
+
+### In the ViewComponent
+
+```ruby
+include StimulusTagHelper
+```
+
+## Examples
+
+Some examples is taken from the real app so may be not very)
+
+### "Hello, Stimulus" controller from the stimulusjs homepage
+
+```slim
+= stimulus_controller("hello", tag: "div") do |sc|
+  = text_field_tag('', '', **sc.target("name"))
+  = button_tag('Greet', type: 'button', **sc.action("click->greet"))
+  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:
+
+```html
+<div data-controller="hello">
+  <input type="text" name="" id="" value="" data-hello-target="name" />
+  <button name="button" type="button" data-action="click->hello#greet">Greet</button>
+  <span data-hello-target="output"></span>
+</div>
+```
+
+
+## "Slideshow" define controller without tag rendering
+
+(buttons messed up for the demonstation purposes)
+
+```slim
+= stimulus_controller("slideshow") do |sc|
+  div[*sc.controller_attribute]
+    = button_tag ' ← ', type: 'button', **sc.action("previous")
+    button[*sc.action("next")]
+      '  →
+    div[*sc.target("slide")] 🐵
+    div[*sc.target("slide")] 🙈
+    div[*sc.target("slide")] 🙉
+    div[*sc.target("slide")] 🙊
+```
+
+Became:
+
+```html
+<div data-controller="slideshow">
+  <button name="button" type="button" data-action="slideshow#previous"> ← </button>
+  <button data-action="slideshow#next"> → </button>
+  <div data-slideshow-target="slide">🐵</div>
+  <div data-slideshow-target="slide">🙈</div>
+  <div data-slideshow-target="slide">🙉</div>
+  <div data-slideshow-target="slide">🙊</div>
+</div>
+```
+
+### Nested controllers
+
+```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"
+
+```
+
+
+## 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!
+
+## License
+
+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).
+
+## Contribution guide
+
+Pull requests are welcome!

data/lib/stimulus_tag_helper.rb

@@ -0,0 +1,134 @@
+# 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"
+
+  def self.base_properties
+    %i[controller values classes targets target actions]
+  end
+
+  def self.aliases_map
+    { values: :value, classes: :class, actions: :action }
+  end
+
+  def self.alias_properties
+    @alias_properties ||= aliases_map.values
+  end
+
+  def self.property_names
+    @property_names ||= base_properties + alias_properties
+  end
+
+  def self.prevent_duplicates(properties_set, name)
+    alias_name = StimulusTagHelper.aliases_map[name]
+    return unless alias_name && (properties_set[alias_name])
+
+    raise(ArgumentError, <<~STRING)
+      "#{name} and #{alias_name} can't be passed at same time"
+    STRING
+  end
+
+  def stimulus_controller(identifier, tag: nil, **args, &block)
+    raise(ArgumentError, "Missing block") unless block
+
+    builder = StimulusControllerBuilder.new(identifier: identifier, template: self)
+
+    return capture(builder, &block) unless tag
+
+    stimulus_controller_tag(identifier, tag: tag, **args) do
+      capture(builder, &block)
+    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])))
+    tag_builder.tag_string(tag, **args.merge(data: data), &block)
+  end
+
+  def stimulus_properties(identifier, props)
+    {}.tap do |data|
+      StimulusTagHelper.property_names.each do |name|
+        next unless props[name]
+
+        params = Array.wrap(props[name]).unshift(identifier)
+        kwparams = params.last.is_a?(Hash) ? params.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))
+      end
+    end
+  end
+
+  def stimulus_controllers_property(*identifiers)
+    { controller: Array.wrap(identifiers).join(" ") }
+  end
+
+  alias stimulus_controller_property stimulus_controllers_property
+
+  def stimulus_values_properties(identifier, **values)
+    {}.tap do |properties|
+      values.each_pair do |name, value|
+        properties["#{identifier}-#{name}-value"] = value
+      end
+    end
+  end
+
+  alias stimulus_value_property stimulus_values_properties
+
+  def stimulus_classes_properties(identifier, **classes)
+    {}.tap do |properties|
+      classes.each_pair do |name, value|
+        properties["#{identifier}-#{name}-class"] = value
+      end
+    end
+  end
+
+  alias 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
+  end
+
+  def stimulus_target_property(identifier, name)
+    { "#{identifier}-target" => name }
+  end
+
+  def stimulus_actions_properties(identifier, *actions_params)
+    {
+      "action" => actions_params.map { |action_params| stimulus_action_value(identifier, action_params) }.join(" ")
+    }
+  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
+
+    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_attribute(...)
+    { data: stimulus_properties(...) }
+  end
+end

data/lib/stimulus_tag_helper/stimulus_action.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module StimulusTagHelper
+  class StimulusAction
+    STANDARD_PARSER =
+      /^(?<void>(?<event>.+?)(?<void>@(?<target>window|document))?->)?(?<identifier>.+?)(?<void>#(?<method>[^:]+?))(?<void>:(?<options>.+))?$/.freeze
+    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)
+
+    # event is nil to let stimulusjs decide default event for the element
+    def initialize(identifier:, method:, event: nil, target: nil, options: nil)
+      parts.each do |part|
+        instance_variable_set(:"@#{part}", binding.local_variable_get(part))
+      end
+    end
+
+    def event_part
+      "#{event}#{"@#{target}" if target}"
+    end
+
+    def handler_part
+      "#{identifier}##{method}#{":#{options}" if options}"
+    end
+
+    def to_s
+      "#{event_part.presence&.+'->'}#{handler_part}".html_safe
+    end
+
+    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
+    end
+  end
+end

data/lib/stimulus_tag_helper/stimulus_controller_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusTagHelper
+  class StimulusControllerBuilder
+    def initialize(identifier:, template:)
+      @identifier = identifier
+      @template = template
+    end
+
+    StimulusTagHelper.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 #{name}_#{attribute}(...)         # def value_attribute(...)
+          { data: #{name}_#{property}(...) }  #   { data: value_property(...) }
+        end                                   # end
+
+        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
+      RUBY
+    end
+
+    def attributes(props)
+      { data: @template.stimulus_properties(@identifier, props) }
+    end
+  end
+end

data/lib/stimulus_tag_helper/version.rb

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

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: stimulus_tag_helper
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Anton Topchii
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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
+description:
+email:
+- player1@infinitevoid.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/stimulus_tag_helper.rb
+- lib/stimulus_tag_helper/stimulus_action.rb
+- lib/stimulus_tag_helper/stimulus_controller_builder.rb
+- lib/stimulus_tag_helper/version.rb
+homepage: https://github.com/crawler/stimulus_tag_helper
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/crawler/stimulus_tag_helper/issues
+  changelog_uri: https://github.com/crawler/stimulus_tag_helper/releases
+  source_code_uri: https://github.com/crawler/stimulus_tag_helper
+  homepage_uri: https://github.com/crawler/stimulus_tag_helper
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: A form_for like, compact and elegant way to define stimulus attributes in
+  your views.
+test_files: []