stimulus_helpers 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd7023b93ba3d485fbea28c5eee63938fab133d3a142d40494e0bf37b7216ab1
-  data.tar.gz: 61bd7b0845434ceffeece2f56560207c80f220646622abf207dde1fb79434cf8
+  metadata.gz: 14c71e9cd468dd53e36d2ff91e05d42a05f3adc2b77a206cb54a92d3ada5b2aa
+  data.tar.gz: 8c74bf98bef6ea4be290669a45a27f0dd4ffdc22fa35bd77fb010aa7b0cb1c86
 SHA512:
-  metadata.gz: 2d5a7e5abb4d4263004243f8967f9d1f04cc1b360acd68ca13359286a79928f6ce8407dc08962325d96e2bf146dece12193187bd7dcc9aa83f6bc42916723ab0
-  data.tar.gz: 22852bd7e2403fe4acc820cd7626a22caf3ca834f310a17a9751f9c003f7d91b497ad8065b988781cdcdc77f06c127b882904c021831dfb556f5762bc665cf23
+  metadata.gz: 9a8089db24fa96a1791ac596b2287d0a934091c6b153fcc5714ef93f04539b615bf7aa1c3f6b362577a8cc36f93e217ffd63d2d0c4df2ff03a141ab303f1d959
+  data.tar.gz: e54556d56355788621c6ed9144beaa00dd20bdaa42947b27627b9495c4e294dbb2f022e7590dcb28addab75f689effb8464d38599559607e95cde44b71010293

data/.ruby-version

@@ -1 +1 @@
-3.1.2
+3.3.5

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-01-06
+
+### Performance
+- Optimize string operations and concatenations for large attribute sets
+- Add caching for dasherized keys to avoid repeated string transformations
+- Implement batch JSON serialization to reduce overhead
+- Improve action building performance by replacing array operations with direct string building
+
+## [0.1.0] - 2024-XX-XX
+
+### Added
+- Initial release of stimulus_helpers gem
+- Helper methods for Stimulus controller attributes:
+  - `stimulus_controller(name)` - Controller binding
+  - `stimulus_action(controller, action, listener)` and `stimulus_actions(controller, actions)` - Action bindings
+  - `stimulus_class(controller, name, value)` and `stimulus_classes(controller, classes)` - CSS class bindings
+  - `stimulus_value(controller, name, value)` and `stimulus_values(controller, values)` - Value bindings
+  - `stimulus_target(controller, target)` - Target bindings
+  - `stimulus_param(controller, name, value)` and `stimulus_params(controller, params)` - Parameter bindings
+  - `stimulus_outlet(controller, name, value)` and `stimulus_outlets(controller, outlets)` - Outlet bindings
+- Automatic JSON serialization for complex values (Arrays and Hashes)
+- Automatic dasherization of attribute names following Stimulus conventions

data/CLAUDE.md

@@ -0,0 +1,137 @@
+# Instructions for Claude Code
+
+## Project Overview
+
+This is the `stimulus_helpers` Ruby gem - a utility library that provides helper methods for building Stimulus controller attributes in Ruby views. The gem makes it easier to work with Stimulus.js by providing a clean Ruby API for generating the necessary HTML attributes.
+
+## Key Information
+
+- **Gem Name**: stimulus_helpers
+- **Current Version**: 0.1.0
+- **Ruby Version**: 3.1.2
+- **License**: MIT
+- **Author**: Tomáš Celizna
+
+## Project Structure
+
+```
+stimulus_helpers/
+├── lib/
+│   ├── stimulus_helpers.rb          # Main module with all helper methods
+│   └── stimulus_helpers/
+│       └── version.rb               # Version constant
+├── test/
+│   ├── stimulus_helpers_test.rb     # Test suite
+│   └── test_helper.rb               # Test configuration
+├── stimulus_helpers.gemspec         # Gem specification
+├── Gemfile                          # Dependencies
+├── Rakefile                         # Build tasks
+└── README.md                        # Documentation
+```
+
+## Development Workflow
+
+### Running Tests
+```bash
+bundle exec rake test
+# or simply
+bundle exec rake
+```
+
+### Running Linter
+```bash
+bundle exec rubocop
+```
+
+### Installing Dependencies
+```bash
+bundle install
+```
+
+### Building the Gem
+```bash
+bundle exec rake build
+```
+
+### Releasing a New Version
+1. Update the version number in `lib/stimulus_helpers/version.rb`
+2. Update CHANGELOG.md with the changes
+3. Commit the changes
+4. Run `bundle exec rake release`
+
+## Code Style Guidelines
+
+- Follow the RuboCop configuration in `.rubocop.yml`
+- Use Ruby 3.1+ syntax features (like value omission in hash literals)
+- Keep methods focused and well-documented
+- Maintain test coverage for all public methods
+
+## Helper Methods Overview
+
+The gem provides the following helper methods:
+
+1. **Controller**: `stimulus_controller(name)`
+2. **Actions**: `stimulus_action(controller, action, listener)` and `stimulus_actions(controller, actions)`
+3. **Classes**: `stimulus_class(controller, name, value)` and `stimulus_classes(controller, classes)`
+4. **Values**: `stimulus_value(controller, name, value)` and `stimulus_values(controller, values)`
+5. **Target**: `stimulus_target(controller, target)`
+6. **Params**: `stimulus_param(controller, name, value)` and `stimulus_params(controller, params)`
+7. **Outlets**: `stimulus_outlet(controller, name, value)` and `stimulus_outlets(controller, outlets)`
+
+## Implementation Notes
+
+- The main module uses `build_stimulus_action` and `build_stimulus_attribute` private methods to construct the attribute hashes
+- Complex values (Arrays and Hashes) are automatically converted to JSON
+- Attribute names are dasherized to follow Stimulus conventions
+- The gem depends on ActiveSupport for string inflections
+
+## Testing Approach
+
+- Tests are in `test/stimulus_helpers_test.rb`
+- Each helper method has corresponding test coverage
+- Tests verify the exact structure of returned hashes
+- Run tests with `bundle exec rake test`
+
+## Common Tasks
+
+### Adding a New Helper Method
+
+1. Add the public method to `lib/stimulus_helpers.rb`
+2. Use the existing private methods (`build_stimulus_action` or `build_stimulus_attribute`) if applicable
+3. Add corresponding tests to `test/stimulus_helpers_test.rb`
+4. Update the README.md with usage examples
+5. Run tests and linter to ensure everything passes
+
+### Debugging
+
+- Use `bin/console` to start an IRB session with the gem loaded
+- The test suite uses Minitest - add debugging with `puts` or use a debugger gem
+- Check the GitHub Actions workflow results for CI failures
+
+## Important Considerations
+
+1. **Backwards Compatibility**: This gem is used by other projects, so maintain backwards compatibility when making changes
+2. **Dependencies**: Keep dependencies minimal - currently only requires ActiveSupport
+3. **Documentation**: Update README.md when adding new features
+4. **Versioning**: Follow semantic versioning (MAJOR.MINOR.PATCH)
+
+## Git Workflow
+
+- The main branch is protected
+- Create feature branches for new work
+- Ensure all tests pass before merging
+- The GitHub Actions workflow runs on every push
+
+## Troubleshooting
+
+- If tests fail locally but pass in CI, check Ruby version (should be 3.1.2)
+- RuboCop violations can often be auto-fixed with `bundle exec rubocop -A`
+- Bundle install issues: try `bundle update` or delete `Gemfile.lock` and reinstall
+
+## Future Improvements
+
+Based on the current codebase, potential areas for enhancement:
+- Add more comprehensive documentation/examples
+- Consider adding type signatures (RBS file is currently minimal)
+- Add more edge case testing
+- Consider performance optimizations for large attribute sets

data/README.md

@@ -2,7 +2,7 @@
 
 [![StimulusHelpers](https://github.com/tomasc/stimulus_helpers/actions/workflows/ruby.yml/badge.svg)](https://github.com/tomasc/stimulus_helpers/actions/workflows/ruby.yml)
 
-Helpers to build stimulus controller attributes for use in views and components.
+Helpers to build stimulus controller attributes for use in views and controller-names.
 
 ## Installation
 
@@ -32,42 +32,68 @@ ActionView::Base.send :include, StimulusHelpers
 
 This will add the following helpers:
 
+Controller:
+
 ```ruby
-stimulus_controller("component")
-# => { "controller" => "component" }
+stimulus_controller("controller-name")
+# => { "controller" => "controller-name" }
+```
 
-stimulus_action("component", "click", "open")
-# => { "action" => "click->component#open" }
+Action:
 
-stimulus_actions("component", click: "open", blur: "close")
-# => { "action" => "click->component#open blur->component#close" }
+```ruby
+stimulus_action("controller-name", "click", "open")
+# => { "action" => "click->controller-name#open" }
+
+stimulus_actions("controller-name", click: "open", blur: "close")
+# => { "action" => "click->controller-name#open blur->controller-name#close" }
+```
 
-stimulus_class("component", "open", "component--open")
-# => { "component-open-class" => "component--open" }
+Class:
 
-stimulus_classes("component", open: "component--open", closed: "component--closed")
-# => { "component-open-class" => "component--open", "component-closed-class" => "component--closed" }
+```ruby
+stimulus_class("controller-name", "open", "controller-name--open")
+# => { "controller-name-open-class" => "controller-name--open" }
 
-stimulus_value("component", "open", true)
-# => { "component-open-value" => "true" }
+stimulus_classes("controller-name", open: "controller-name--open", closed: "controller-name--closed")
+# => { "controller-name-open-class" => "controller-name--open", "controller-name-closed-class" => "controller-name--closed" }
+```
 
-stimulus_values("component", user: { name: "Jens" }, names: ["foo", "bar"])
-# => { "component-user-value" => "{\"name\":\"Jens\"}", "component-names-value" => "[\"foo\",\"bar\"]" }
+Value:
 
-stimulus_target("component", :input)
-# => { "component-target" => "input" }
+```ruby
+stimulus_value("controller-name", "open", true)
+# => { "controller-name-open-value" => "true" }
 
-stimulus_param("component", "id", 123)
-# => { "component-id-param" => "123" }
+stimulus_values("controller-name", user: { name: "Jens" }, names: ["foo", "bar"])
+# => { "controller-name-user-value" => "{\"name\":\"Jens\"}", "controller-name-names-value" => "[\"foo\",\"bar\"]" }
+```
 
-stimulus_params("component", id: 123, name: "Jens")
-# => { "component-id-param" => "123", "component-name-param" => "Jens" }
+Target:
 
-stimulus_outlet("component", "result", ".result")
-# => { "component-result-outlet" => ".result" }
+```ruby
+stimulus_target("controller-name", :input)
+# => { "controller-name-target" => "input" }
+```
+
+Param:
+
+```ruby
+stimulus_param("controller-name", "id", 123)
+# => { "controller-name-id-param" => "123" }
+
+stimulus_params("controller-name", id: 123, name: "Jens")
+# => { "controller-name-id-param" => "123", "controller-name-name-param" => "Jens" }
+```
+
+Outlet:
+
+```ruby
+stimulus_outlet("controller-name", "result", ".result")
+# => { "controller-name-result-outlet" => ".result" }
 
-stimulus_outlets("component", result: ".result", output: ".output")
-# => { "component-result-outlet" => ".result", "component-output-outlet" => ".output" }
+stimulus_outlets("controller-name", result: ".result", output: ".output")
+# => { "controller-name-result-outlet" => ".result", "controller-name-output-outlet" => ".output" }
 ```
 
 ## Development
@@ -78,4 +104,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/stimulus_helpers.
+Bug reports and pull requests are welcome on GitHub at https://github.com/tomasc/stimulus_helpers.

data/lib/stimulus_helpers/version.rb

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

data/lib/stimulus_helpers.rb

@@ -5,6 +5,14 @@ require "active_support/core_ext/string/inflections"
 require "json"
 
 module StimulusHelpers
+  # Cache for dasherized keys to avoid repeated string operations
+  @dasherized_cache = {}
+  @cache_mutex = Mutex.new
+
+  class << self
+    attr_reader :dasherized_cache, :cache_mutex
+  end
+
   # @see https://blog.saeloun.com/2021/09/28/ruby-allow-value-omission-in-hash-literals
   def stimulus_controller(controller)
     { controller: }
@@ -91,19 +99,48 @@ module StimulusHelpers
 
   private
     def build_stimulus_action(controller:, actions: {})
-      action = actions.map do |action, listeners|
-        Array(listeners).map do |listener|
-          "#{action}->#{controller}##{listener}"
+      # Use string concatenation instead of array operations for better performance
+      action_parts = []
+      actions.each do |action_name, listeners|
+        Array(listeners).each do |listener|
+          action_parts << "#{action_name}->#{controller}##{listener}"
         end
-      end.join(" ")
-      { action: }
+      end
+      { action: action_parts.join(" ") }
     end
 
     def build_stimulus_attribute(controller:, type: nil, attributes: {})
-      attributes.transform_keys! { |key| "#{key}-#{type}" } if type
-      attributes.each_with_object({}) do |(key, value), res|
-        value = value.to_json if value.is_a?(Array) || value.is_a?(Hash)
-        res["#{controller}-#{key.to_s.dasherize}"] = value.to_s
+      # Pre-process keys and batch JSON serialization for better performance
+      result = {}
+      json_values = {}
+      
+      attributes.each do |key, value|
+        # Build the final key once
+        final_key = if type
+          "#{controller}-#{cached_dasherize("#{key}-#{type}")}"
+        else
+          "#{controller}-#{cached_dasherize(key.to_s)}"
+        end
+        
+        # Batch JSON serialization
+        if value.is_a?(Array) || value.is_a?(Hash)
+          json_values[final_key] = value
+        else
+          result[final_key] = value.to_s
+        end
+      end
+      
+      # Serialize all JSON values at once to reduce overhead
+      json_values.each do |key, value|
+        result[key] = value.to_json
+      end
+      
+      result
+    end
+
+    def cached_dasherize(string)
+      StimulusHelpers.cache_mutex.synchronize do
+        StimulusHelpers.dasherized_cache[string] ||= string.dasherize
       end
     end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_helpers
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tomas Celizna
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-11 00:00:00.000000000 Z
+date: 2025-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -106,6 +106,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE
 - README.md
@@ -136,7 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Helper methods for stimulus controllers.