has_stimulus_attrs 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a3a965811c25f20f220e33a4d7e579081309e45501235c168238b8ed83db4b3
-  data.tar.gz: '0804e6cd1db9b7399bb70ec14e3df96b78a67bd84a92d6d799d39709924923cb'
+  metadata.gz: 0d92df61326364a67fd89516850b87e5dfe9e85cbbc1982f6f5815978f033c18
+  data.tar.gz: d7cfcb016ff83d8aa53c43527cb6753b587958e075f071f0261cf16044365ac1
 SHA512:
-  metadata.gz: 850a00e3ee81c9783f59711efdd2045b4405225dc424759c6f8a5071526187aa588f1e1136cd572ddaef16dc9b1134142eeaef4c17a69e5726eaa3e35a0d8a69
-  data.tar.gz: 9e81d373052c1861e0304beb023ce2b0ed0e345bcd844a7afcba10fe7dec2c9cdb7173fba46893339d83102b247f0bd2da56ea4c61484a820561f60675951ef8
+  metadata.gz: eb72b769b5aa0ed1eadb3bb7dfaac561c987ff2d11acc9273fa80ec71284fcd790ec42bf7a78c82b607561062981b97b1fad3c611e6e57dd3662b439b584cb8d
+  data.tar.gz: 58afec2f65b664ce1a424931e7b987e0bf210343f6d782407f04514df651995107a22e8f09d9a5e9b21950caf27390f3eb88a23a8702274009a6041567ef960d

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.3.0](https://github.com/tomasc/has_stimulus_attrs/compare/v0.2.2...v0.3.0) (2025-01-02)
+
+### Performance
+
+* **Major performance optimizations**: Implemented intelligent memoization for `dom_data` method to prevent expensive Proc re-evaluation on repeated calls
+* **Early conditional exit**: Optimized conditional attribute evaluation to skip expensive operations when `:if`/`:unless` conditions fail
+* **Controller name caching**: Added instance-level caching for `controller_name` to avoid repeated class method calls
+* **Smart cache management**: Added `reset_dom_data_cache!` method for manual cache invalidation when needed
+
+### Features
+
+* **Performance testing**: Added comprehensive performance test suite to validate optimizations and prevent regressions
+
 ## [0.2.2](https://github.com/tomasc/has_stimulus_attrs/compare/v0.2.1...v0.2.2) (2025-01-31)
 
 ### Features

data/CLAUDE.md

@@ -0,0 +1,612 @@
+# HasStimulusAttrs
+
+## Overview
+
+HasStimulusAttrs is a Ruby gem that provides a clean, declarative DSL for managing [Stimulus.js](https://stimulus.hotwired.dev/) data attributes in Ruby classes. It's particularly useful for component-based architectures in Rails applications where you need to generate Stimulus-compatible HTML attributes programmatically.
+
+## Core Concepts
+
+### What Problem Does This Solve?
+
+When building Rails applications with Stimulus.js, you often need to generate HTML elements with specific data attributes that Stimulus uses:
+- `data-controller`
+- `data-action`
+- `data-[controller]-target`
+- `data-[controller]-value`
+- etc.
+
+Managing these attributes manually can become cumbersome, especially when dealing with:
+- Multiple controllers on a single element
+- Dynamic values that change based on component state
+- Conditional attributes
+- Consistent naming conventions
+
+HasStimulusAttrs solves these problems by providing a Ruby DSL that handles the complexity of generating proper Stimulus attributes.
+
+### How It Works
+
+The gem works by:
+1. Including the `HasStimulusAttrs` module in your Ruby class
+2. Defining a `controller_name` method that returns your Stimulus controller's identifier
+3. Using the provided DSL methods to declare what Stimulus attributes your component needs
+4. The gem automatically generates the correct `dom_data` hash with properly formatted Stimulus attributes
+
+## Architecture
+
+### Module Structure
+
+```
+HasStimulusAttrs
+├── Includes HasDomAttrs (for DOM attribute management)
+├── Includes StimulusHelpers (for Stimulus-specific formatting)
+└── Provides ClassMethods when included
+```
+
+### Key Dependencies
+
+1. **has_dom_attrs** - Provides the underlying DOM attribute management functionality
+2. **stimulus_helpers** - Provides helper methods for formatting Stimulus-specific attributes
+3. **activesupport** - Used for core Ruby extensions (like `blank?`)
+
+## API Reference
+
+### Including the Module
+
+```ruby
+class MyComponent
+  include HasStimulusAttrs
+  
+  def self.controller_name
+    "my-component"
+  end
+end
+```
+
+### Available Methods
+
+#### `has_stimulus_controller(name = controller_name, **options)`
+
+Adds a Stimulus controller to the element.
+
+```ruby
+# Use default controller name
+has_stimulus_controller
+
+# Add additional controller
+has_stimulus_controller "click-outside"
+
+# Conditional controller
+has_stimulus_controller "modal", if: :open?
+
+# Dynamic controller name
+has_stimulus_controller -> { "theme-#{current_theme}" }
+```
+
+#### `has_stimulus_action(event, action, controller: nil, **options)`
+
+Defines a Stimulus action.
+
+```ruby
+# Basic action
+has_stimulus_action "click", "handleClick"
+
+# Action for different controller
+has_stimulus_action "submit", "save", controller: "form-controller"
+
+# Conditional action
+has_stimulus_action "keydown", "handleEscape", if: :keyboard_enabled?
+
+# Dynamic action name (v0.2.2+)
+has_stimulus_action "click", -> { admin? ? "adminAction" : "userAction" }
+```
+
+#### `has_stimulus_class(name, value, controller: nil, **options)`
+
+Defines CSS classes managed by Stimulus.
+
+```ruby
+# Static class
+has_stimulus_class "active", "component--active"
+
+# Dynamic class
+has_stimulus_class "size", -> { "component--#{size}" }
+
+# Using method
+has_stimulus_class "theme", :theme_class_name
+```
+
+#### `has_stimulus_outlet(name, value, controller: nil, **options)`
+
+Defines Stimulus outlets.
+
+```ruby
+# CSS selector outlet
+has_stimulus_outlet "modal", "#main-modal"
+
+# Dynamic outlet
+has_stimulus_outlet "target", -> { "##{dom_id}" }
+```
+
+#### `has_stimulus_param(name, value, controller: nil, **options)`
+
+Defines Stimulus parameters.
+
+```ruby
+# Static param
+has_stimulus_param :url, "/api/endpoint"
+
+# Dynamic param
+has_stimulus_param :id, -> { model.id }
+
+# Using method
+has_stimulus_param :config, :configuration_json
+```
+
+#### `has_stimulus_target(name, controller: nil, **options)`
+
+Marks element as a Stimulus target.
+
+```ruby
+# Basic target
+has_stimulus_target "button"
+
+# Target for different controller
+has_stimulus_target "input", controller: "form-controller"
+```
+
+#### `has_stimulus_value(name, value = nil, controller: nil, **options)`
+
+Defines Stimulus values.
+
+```ruby
+# Static value
+has_stimulus_value "endpoint", "/api/data"
+
+# Dynamic value
+has_stimulus_value "userId", -> { current_user.id }
+
+# Using method name as value
+has_stimulus_value :timeout  # calls timeout method
+```
+
+#### `reset_dom_data_cache!`
+
+Manually clears the cached `dom_data` result, forcing recomputation on the next call.
+
+```ruby
+class DynamicComponent
+  include HasStimulusAttrs
+  
+  attr_accessor :state
+  
+  has_stimulus_value "state", -> { state }
+  
+  def update_state(new_state)
+    @state = new_state
+    reset_dom_data_cache! # Force recomputation
+  end
+end
+```
+
+### Options
+
+All methods support these options:
+- `:if` - Include attribute only if condition is truthy
+- `:unless` - Include attribute unless condition is truthy
+- `:controller` - Specify a different controller (can be string or Proc)
+
+## Usage Patterns
+
+### Basic Component
+
+```ruby
+class DropdownComponent
+  include HasStimulusAttrs
+  
+  attr_reader :open
+  
+  def self.controller_name
+    "dropdown"
+  end
+  
+  has_stimulus_controller
+  has_stimulus_action "click", "toggle"
+  has_stimulus_class "open", "dropdown--open"
+  has_stimulus_value "open", -> { open }
+  has_stimulus_target "menu"
+end
+```
+
+### Component with Multiple Controllers
+
+```ruby
+class ModalComponent
+  include HasStimulusAttrs
+  
+  def self.controller_name
+    "modal"
+  end
+  
+  has_stimulus_controller
+  has_stimulus_controller "trap-focus"
+  has_stimulus_controller "click-outside", if: :dismissible?
+  
+  has_stimulus_action "click", "close", controller: "click-outside"
+  has_stimulus_action "keydown.esc", "close"
+end
+```
+
+### Dynamic Component
+
+```ruby
+class ThemeComponent
+  include HasStimulusAttrs
+  
+  attr_reader :theme, :user_preferences
+  
+  def self.controller_name
+    "theme"
+  end
+  
+  has_stimulus_controller
+  has_stimulus_value "theme", -> { user_preferences[:theme] || "light" }
+  has_stimulus_class "mode", -> { "theme--#{theme}" }
+  has_stimulus_param :config, -> { theme_configuration.to_json }
+end
+```
+
+### Inheritance Pattern
+
+```ruby
+class ApplicationComponent
+  include HasStimulusAttrs
+  
+  def self.controller_name
+    name.underscore.dasherize
+  end
+end
+
+class AlertComponent < ApplicationComponent
+  # Inherits controller_name as "alert-component"
+  has_stimulus_controller
+  has_stimulus_action "click", "dismiss"
+  has_stimulus_class "type", -> { "alert--#{type}" }
+end
+```
+
+## Integration with Rails
+
+### ViewComponent Example
+
+```ruby
+class ButtonComponent < ViewComponent::Base
+  include HasStimulusAttrs
+  
+  def self.controller_name
+    "button"
+  end
+  
+  has_stimulus_controller
+  has_stimulus_action "click", "handleClick"
+  has_stimulus_value "loading", -> { loading? }
+  
+  def call
+    tag.button(**dom_attrs) do
+      content
+    end
+  end
+end
+```
+
+### Phlex Example
+
+```ruby
+class Card < Phlex::HTML
+  include HasStimulusAttrs
+  
+  def self.controller_name
+    "card"
+  end
+  
+  has_stimulus_controller
+  has_stimulus_action "mouseenter", "highlight"
+  has_stimulus_action "mouseleave", "unhighlight"
+  
+  def template
+    div(**dom_attrs) do
+      yield
+    end
+  end
+end
+```
+
+## Advanced Usage
+
+### Conditional Controllers
+
+```ruby
+class ToggleComponent
+  include HasStimulusAttrs
+  
+  has_stimulus_controller "toggle"
+  has_stimulus_controller "animation", if: :animated?
+  has_stimulus_controller "a11y", unless: :accessibility_disabled?
+  
+  def animated?
+    @options[:animate] != false
+  end
+  
+  def accessibility_disabled?
+    @options[:disable_a11y] == true
+  end
+end
+```
+
+### Dynamic Controller Names
+
+```ruby
+class PolymorphicComponent
+  include HasStimulusAttrs
+  
+  has_stimulus_controller -> { "#{record.class.name.underscore}-controller" }
+  has_stimulus_value "id", -> { record.id }
+  has_stimulus_value "type", -> { record.class.name }
+end
+```
+
+### Complex Actions
+
+```ruby
+class FormComponent
+  include HasStimulusAttrs
+  
+  # Multiple actions on same event
+  has_stimulus_action "submit", "validate"
+  has_stimulus_action "submit", "save"
+  
+  # Actions with modifiers
+  has_stimulus_action "keydown.enter", "submit"
+  has_stimulus_action "input->debounced:300", "search"
+  
+  # Dynamic action based on state
+  has_stimulus_action "click", -> { draft? ? "saveDraft" : "publish" }
+end
+```
+
+## Testing
+
+### Testing Components with Stimulus Attrs
+
+```ruby
+class MyComponentTest < Minitest::Test
+  def test_stimulus_controller_included
+    component = MyComponent.new
+    assert_includes component.dom_data[:controller], "my-component"
+  end
+  
+  def test_conditional_controller
+    component = MyComponent.new(active: true)
+    assert_includes component.dom_data[:controller], "active-state"
+    
+    component = MyComponent.new(active: false)
+    refute_includes component.dom_data[:controller], "active-state"
+  end
+  
+  def test_stimulus_values
+    component = MyComponent.new(user_id: 123)
+    assert_equal "123", component.dom_data["my-component-user-id-value"]
+  end
+end
+```
+
+## Best Practices
+
+### 1. Use Consistent Naming
+
+```ruby
+# Good: Consistent with Stimulus conventions
+def self.controller_name
+  "user-profile"  # kebab-case
+end
+
+# Avoid: Inconsistent naming
+def self.controller_name
+  "UserProfile"  # Wrong case
+end
+```
+
+### 2. Keep Controllers Focused
+
+```ruby
+# Good: Single responsibility
+class SearchComponent
+  has_stimulus_controller "search"
+  has_stimulus_action "input", "performSearch"
+  has_stimulus_value "endpoint", "/search"
+end
+
+# Avoid: Too many responsibilities
+class KitchenSinkComponent
+  has_stimulus_controller "search"
+  has_stimulus_controller "modal"
+  has_stimulus_controller "dropdown"
+  # ... many more
+end
+```
+
+### 3. Use Procs for Dynamic Values
+
+```ruby
+# Good: Dynamic value using Proc
+has_stimulus_value "timestamp", -> { Time.current.to_i }
+
+# Avoid: Static value that should be dynamic
+has_stimulus_value "timestamp", Time.current.to_i  # Set once at class load
+```
+
+### 4. Leverage Conditionals
+
+```ruby
+# Good: Conditional attributes for performance
+has_stimulus_controller "animation", if: :animations_enabled?
+has_stimulus_controller "analytics", unless: :private_mode?
+
+# Avoid: Always including optional controllers
+has_stimulus_controller "animation"  # Even when not needed
+```
+
+## Common Pitfalls
+
+### 1. Forgetting controller_name
+
+```ruby
+# Wrong: No controller_name defined
+class MyComponent
+  include HasStimulusAttrs
+  has_stimulus_controller  # Will raise NotImplementedError
+end
+
+# Correct: Define controller_name
+class MyComponent
+  include HasStimulusAttrs
+  
+  def self.controller_name
+    "my-component"
+  end
+  
+  has_stimulus_controller
+end
+```
+
+### 2. Incorrect Proc Usage
+
+```ruby
+# Wrong: Proc called at class definition
+has_stimulus_value "random", -> { rand(100) }.call
+
+# Correct: Proc called at runtime
+has_stimulus_value "random", -> { rand(100) }
+```
+
+### 3. Naming Conflicts
+
+```ruby
+# Be careful with multiple controllers
+has_stimulus_target "button"  # For default controller
+has_stimulus_target "button", controller: "modal"  # Different target!
+```
+
+## Performance Considerations
+
+HasStimulusAttrs includes several built-in performance optimizations:
+
+### Built-in Optimizations
+
+1. **Automatic Memoization**: `dom_data` is automatically cached after first computation
+2. **Early Conditional Exit**: Expensive Procs are skipped when `:if`/`:unless` conditions fail
+3. **Controller Name Caching**: Instance-level caching avoids repeated class method calls
+4. **Lazy Evaluation**: Procs are only evaluated when `dom_data` is called
+
+### Performance Methods
+
+#### `reset_dom_data_cache!`
+
+Manually clear the cached `dom_data` when component state changes:
+
+```ruby
+class DynamicComponent
+  include HasStimulusAttrs
+  
+  attr_accessor :theme
+  
+  def self.controller_name
+    "dynamic"
+  end
+  
+  has_stimulus_value "theme", -> { theme }
+  
+  def theme=(new_theme)
+    @theme = new_theme
+    reset_dom_data_cache! # Clear cache when state changes
+  end
+end
+```
+
+### Optimization Best Practices
+
+1. **Use Conditional Attributes**: Leverage `:if`/`:unless` for expensive operations
+2. **Cache External Data**: Pre-fetch expensive data rather than computing in Procs
+3. **Reset Cache Appropriately**: Call `reset_dom_data_cache!` only when component state changes
+
+```ruby
+class OptimizedComponent
+  include HasStimulusAttrs
+  
+  # These are automatically optimized:
+  has_stimulus_controller "rich-text-editor", if: :rich_text_enabled?
+  has_stimulus_controller "syntax-highlighter", if: :code_blocks_present?
+  has_stimulus_value "config", -> { expensive_config_computation }
+  
+  private
+  
+  def expensive_config_computation
+    # This will only run once per component instance
+    # unless reset_dom_data_cache! is called
+    complex_calculation
+  end
+end
+```
+
+### Performance Impact
+
+- **Memoized calls**: No Proc re-evaluation on subsequent `dom_data` calls
+- **Conditional skipping**: Expensive operations avoided when conditions aren't met
+- **Cached controller names**: Single class method call per instance
+- **Memory efficient**: Cache cleared automatically when component is garbage collected
+
+## Debugging Tips
+
+### 1. Inspect Generated Attributes
+
+```ruby
+component = MyComponent.new
+puts component.dom_data.inspect
+# => {:controller=>"my-component", :action=>"click->my-component#handleClick", ...}
+```
+
+### 2. Check Formatted Output
+
+```ruby
+# In Rails console or tests
+component = MyComponent.new
+component.dom_data.each do |key, value|
+  puts "data-#{key}=\"#{value}\""
+end
+```
+
+### 3. Verify in Browser
+
+Use browser developer tools to inspect the generated HTML and ensure Stimulus attributes are correct.
+
+## Version History
+
+- **0.3.0** (Unreleased): Major performance optimizations
+  - Automatic `dom_data` memoization to prevent expensive Proc re-evaluation
+  - Early conditional exit optimization for `:if`/`:unless` attributes
+  - Controller name instance-level caching
+  - Added `reset_dom_data_cache!` method for manual cache management
+- **0.2.2** (2025-01-31): Added support for Proc in `has_stimulus_action`
+- **0.2.0** (2023-03-22): Added Proc support for controller option
+- **0.1.0**: Initial release
+
+## Contributing
+
+The gem is open source and welcomes contributions. Key areas for contribution:
+1. Additional stimulus attribute types
+2. Performance improvements
+3. Documentation and examples
+4. Integration guides for different frameworks
+
+## Conclusion
+
+HasStimulusAttrs provides a powerful, Ruby-idiomatic way to manage Stimulus.js attributes in your components. By leveraging its DSL, you can write cleaner, more maintainable component code while ensuring proper Stimulus integration.

data/README.md

@@ -2,19 +2,15 @@
 
 [![HasStimulusAttrs](https://github.com/tomasc/has_stimulus_attrs/actions/workflows/ruby.yml/badge.svg)](https://github.com/tomasc/has_stimulus_attrs/actions/workflows/ruby.yml)
 
-Helper methods for dealing with [stimulus](https://stimulus.hotwired.dev/) data attributes.
+A Ruby DSL for managing [Stimulus.js](https://stimulus.hotwired.dev/) data attributes in component-based architectures.
 
-Relies on [`has_dom_attrs`](https://github.com/tomasc/has_dom_attrs) and [`stimulus_helpers`](https://github.com/tomasc/stimulus_helpers).
+Built on [`has_dom_attrs`](https://github.com/tomasc/has_dom_attrs) and [`stimulus_helpers`](https://github.com/tomasc/stimulus_helpers).
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add has_stimulus_attrs
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-    $ gem install has_stimulus_attrs
+```bash
+bundle add has_stimulus_attrs
+```
 
 ## Usage
 
@@ -48,8 +44,7 @@ DetailsComponent.controller_name
 # => "details-component"
 ```
 
-You can then use the included class methods to easily set stimulus attributes on
-your class:
+Use the DSL methods to define Stimulus attributes:
 
 ```ruby
 class ModalComponent < ApplicationComponent
@@ -87,9 +82,10 @@ end
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+bin/setup    # Install dependencies
+bin/console  # Interactive prompt
+```
 
 ## Contributing
 

data/lib/has_stimulus_attrs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HasStimulusAttrs
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/has_stimulus_attrs.rb

@@ -10,6 +10,10 @@ module HasStimulusAttrs
   include HasDomAttrs
   include StimulusHelpers
 
+  def controller_name
+    @_stimulus_controller_name ||= self.class.controller_name
+  end
+
   class << self
     def included(base)
       base.extend ClassMethods
@@ -136,23 +140,32 @@ module HasStimulusAttrs
 
     private
       def prepend___has_stimulus___method(key, value, **options)
+        # First, add the stimulus attribute module
         prepend(
           Module.new do
             define_method :dom_data do
-              cond = options[:if] || options[:unless]
-              cond_value = case cond
+              # Early exit for conditional attributes - avoid expensive key/value evaluation
+              if options.key?(:if)
+                cond = options[:if]
+                cond_value = case cond
                            when Proc then instance_exec(&cond)
                            when Symbol, String then send(cond)
-              end
-
-              if cond && options.key?(:if)
+                           else cond
+                           end
                 return super() unless cond_value
               end
 
-              if cond && options.key?(:unless)
+              if options.key?(:unless)
+                cond = options[:unless]
+                cond_value = case cond
+                           when Proc then instance_exec(&cond)
+                           when Symbol, String then send(cond)
+                           else cond
+                           end
                 return super() if cond_value
               end
 
+              # Only evaluate key and value if conditions pass
               k = case key
                   when Proc then instance_exec(&key)
                   else key
@@ -169,6 +182,32 @@ module HasStimulusAttrs
             end
           end
         )
+        
+        # Then, ensure memoization is always at the top
+        ensure_memoization_at_top
+      end
+      
+      def ensure_memoization_at_top
+        # Remove any existing memoization module
+        if const_defined?(:StimulusMemoization, false)
+          remove_const(:StimulusMemoization)
+        end
+        
+        # Create a new memoization module at the top
+        memoization_module = Module.new do
+          def dom_data
+            return @_stimulus_dom_data if defined?(@_stimulus_dom_data)
+            @_stimulus_dom_data = super
+          end
+          
+          def reset_dom_data_cache!
+            remove_instance_variable(:@_stimulus_dom_data) if defined?(@_stimulus_dom_data)
+            super if defined?(super)
+          end
+        end
+        
+        const_set(:StimulusMemoization, memoization_module)
+        prepend(memoization_module)
       end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_stimulus_attrs
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Tomas Celizna
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-31 00:00:00.000000000 Z
+date: 2025-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: stimulus_helpers
@@ -134,6 +134,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE
 - README.md