vident 1.0.0.alpha1 → 1.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d59f73664008e87455784726ec60622da719f758449339ac3904f99c7b04b1b6
-  data.tar.gz: d10178e8d4cfe43d441d8dde5b7540d847ecad01fea060024362d0e6c74735e6
+  metadata.gz: 1ae2c093011a8047255f21fff2b284520d9be75660af61afc511c85bfdcc9f76
+  data.tar.gz: 47bbde103e62632fca8a11bb1ddd6321dd8c6c8711d21790a51a3e657e3d6f66
 SHA512:
-  metadata.gz: 4a605e928c5749975f0f4127c49192f6676ee349e979b3d9531013a2cd988228516a7b6a592155ea175e60e30648417c7c76bb3ec4535a1b26008baa27eb3eaf
-  data.tar.gz: 1057b3d13ef990e098d0011f5b00ff0e020c605fae330c88baf0677f85fffa46ec1ff604e97276d6934e23ff1aaad03ddbd87856c1ca7bdcd555663d81b3cb06
+  metadata.gz: df35e4be8597d580ad4f50b63f99c1e0a8032fd52c9c06676b6d4db9ee15a781f80d00c5112c87047238361560b5a131e60f11800e07c03f904d1e781fed3312
+  data.tar.gz: 5794832b1bb4a4abbc532beabdbe9133c3a45b7ef42eca8d11660051466a7b64298af3bcb8c7c90c55381a25bfec0680afe389f319c2b8ffc1602f1fb3f47d16

data/CHANGELOG.md

@@ -5,7 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [1.0.0.alpha1] - 2025-07-04
+## [1.0.0.alpha3] - 2025-07-21
+
+### Breaking
+- `element_classes` is now `root_element_classes` to make more consistent with the other root element methods.
+
+### Added
+
+-`.prop_names` and `#prop_values` methods to `Vident::Component` to return the names and values of the component's properties.
+
+## [1.0.0.alpha2] - 2025-07-08
+
+### Breaking
+- `nil` values in Stimulus values are ok, but `nil` for an action/target/outlet makes no sense so is ignored.
+
+### Fixed
+
+- `stimulus_scoped_event` must return a Symbol to work with `stimulus_action` and `stimulus_target` methods etc.
+
+## [1.0.0.alpha1] - 2025-07-08
 
 This release is a major overhaul of the Vident library, and introduces a new API for defining components and Stimulus attributes. The new API is designed to be more consistent and easier to use.
 

data/README.md

@@ -76,27 +76,32 @@ class ButtonComponent < Vident::ViewComponent::Base
   
   # Configure Stimulus integration
   stimulus do
-    actions [:click, :handle_click]
-    # Static values
-    values loading_duration: 1000
+    # Setup actions, including with proc to evaluate on instance 
+    actions [:click, :handle_click], 
+            -> { [stimulus_scoped_event(:my_custom_event), :handle_this] if should_handle_this? }
     # Map the clicked_count prop as a Stimulus value
     values_from_props :clicked_count
     # Dynamic values using procs (evaluated in component context)
-    values item_count: -> { @items.count }
-    values api_url: -> { Rails.application.routes.url_helpers.api_items_path }
+    values item_count: -> { @items.count },
+           api_url: -> { Rails.application.routes.url_helpers.api_items_path },
+           loading_duration: 1000 # or set static values
     # Static and dynamic classes
-    classes loading: "opacity-50 cursor-wait"
-    classes size: -> { @items.count > 10 ? "large" : "small" }
+    classes loading: "opacity-50 cursor-wait",
+            size: -> { @items.count > 10 ? "large" : "small" }
   end
 
   def call
-    root_element do
-      @text
+    root_element do |component|
+      # Wire up targets etc
+      component.tag(:span, stimulus_target: :status) do
+        @text
+      end
     end
   end
 
   private
 
+  # Configure your components root HTML element
   def root_element_attributes
     {
       element_tag: @url ? :a : :button,
@@ -104,7 +109,8 @@ class ButtonComponent < Vident::ViewComponent::Base
     }
   end
 
-  def element_classes
+  # optionally add logic to determine initial classes
+  def root_element_classes
     base_classes = "btn"
     case @style
     when :primary
@@ -130,14 +136,19 @@ export default class extends Controller {
     loadingDuration: Number 
   }
   static classes = ["loading"]
+  static targets = ["status"]
   
   handleClick(event) {
     // Increment counter
     this.clickedCountValue++
     
+    // Store original text
+    const originalText = this.statusTarget.textContent
+    
     // Add loading state
     this.element.classList.add(this.loadingClass)
     this.element.disabled = true
+    this.statusTarget.textContent = "Loading..."
     
     // Use the loading duration from the component
     setTimeout(() => {
@@ -145,7 +156,7 @@ export default class extends Controller {
       this.element.disabled = false
       
       // Update text to show count
-      this.element.textContent = `${this.element.textContent} (${this.clickedCountValue})`
+      this.statusTarget.textContent = `${originalText} (${this.clickedCountValue})`
     }, this.loadingDurationValue)
   }
 }
@@ -178,7 +189,7 @@ The rendered HTML includes all Stimulus data attributes:
         data-button-component-loading-duration-value="1000"
         data-button-component-loading-class="opacity-50 cursor-wait"
         id="button-component-123">
-  Save
+  <span data-button-component-target="status">Save</span>
 </button>
 
 <!-- Second button with pre-set count -->
@@ -189,7 +200,7 @@ The rendered HTML includes all Stimulus data attributes:
         data-button-component-loading-duration-value="1000"
         data-button-component-loading-class="opacity-50 cursor-wait"
         id="button-component-456">
-  Submit
+  <span data-button-component-target="status">Submit</span>
 </button>
 ```
 
@@ -218,6 +229,29 @@ class CardComponent < Vident::ViewComponent::Base
 end
 ```
 
+### Post-Initialization Hooks
+
+Vident provides a hook for performing actions after component initialization:
+
+```ruby
+class MyComponent < Vident::ViewComponent::Base
+  prop :data, Hash, default: -> { {} }
+  
+  def after_component_initialize
+    @processed_data = process_data(@data)
+  end
+  
+  private
+  
+  def process_data(data)
+    # Your initialization logic here
+    data.transform_values(&:upcase)
+  end
+end
+```
+
+**Important**: If you decide to override Literal's `after_initialize`, you **must** call `super` first to ensure Vident's initialization completes properly. Alternatively, use `after_component_initialize` which doesn't require calling `super`.
+
 ### Built-in Properties
 
 Every Vident component includes these properties:
@@ -233,7 +267,7 @@ The `root_element` helper method renders your component's root element with all
 
 ```ruby
 # In your component class
-def element_classes
+def root_element_classes
   ["card", featured? ? "card-featured" : nil]
 end
 
@@ -389,7 +423,7 @@ Vident provides helper methods to generate scoped event names for dispatching cu
 class MyComponent < Vident::ViewComponent::Base
   stimulus do
     # Define an action that responds to a scoped event
-    actions [stimulus_scoped_event_on_window(:data_loaded), :handle_data_loaded]
+    actions -> { [stimulus_scoped_event_on_window(:data_loaded), :handle_data_loaded] }
   end
   
   def handle_click
@@ -589,7 +623,7 @@ class StyledComponent < Vident::ViewComponent::Base
   private
   
   # Classes on the root element
-  def element_classes
+  def root_element_classes
     ["base-class", variant_class]
   end
   
@@ -623,7 +657,7 @@ class TailwindComponent < Vident::ViewComponent::Base
   
   private
   
-  def element_classes
+  def root_element_classes
     # Conflicts with size_class will be resolved automatically
     "p-2 text-sm #{size_class}"
   end

data/lib/vident/class_list_builder.rb

@@ -6,12 +6,23 @@ module Vident
   class ClassListBuilder
     CLASSNAME_SEPARATOR = " "
 
-    def initialize(tailwind_merger: nil, component_name: nil, element_classes: nil, html_class: nil, additional_classes: nil)
+    # If the HTML "class" option is provided, it is taken in order of precedence of source.
+    # The order of precedence is:
+    # lowest  | root_element_classes => whatever is returned
+    # ....... | root_element_attributes => the `html_options[:class]` value
+    # ....... | root_element(class: ...) => the `class` value of the arguments passed to the root element
+    # highest | render MyComponent.new(html_options: { class: ... }) => the `html_options[:class]` value
+    # The "classes" prop on the component on the other hand is used to add additional classes to the component.
+    # eg: render MyComponent.new(classes: "my-additional-class another-class")
+    def initialize(tailwind_merger: nil, component_name: nil, root_element_attributes_classes: nil, root_element_classes: nil, root_element_html_class: nil, html_class: nil, additional_classes: nil)
       @class_list = component_name ? [component_name] : []
-      @class_list.concat(Array.wrap(element_classes)) if element_classes
+      @class_list.concat(Array.wrap(root_element_classes)) if root_element_classes && !root_element_attributes_classes && !root_element_html_class && !html_class
+      @class_list.concat(Array.wrap(root_element_attributes_classes)) if root_element_attributes_classes && !root_element_html_class && !html_class
+      @class_list.concat(Array.wrap(root_element_html_class)) if root_element_html_class && !html_class
       @class_list.concat(Array.wrap(html_class)) if html_class
       @class_list.concat(Array.wrap(additional_classes)) if additional_classes
       @class_list.compact!
+
       @tailwind_merger = tailwind_merger
 
       if @tailwind_merger && !defined?(::TailwindMerge::Merger)

data/lib/vident/component.rb

@@ -16,20 +16,27 @@ module Vident
       prop :html_options, Hash, default: -> { {} }
     end
 
+    class_methods do
+      # Returns the names of the properties defined in the component class.
+      def prop_names
+        literal_properties.properties_index.keys.map(&:to_sym)
+      end
+    end
+
     include StimulusComponent
     include ComponentClassLists
     include ComponentAttributeResolver
 
     include TagHelper
     include Tailwind
-    include StimulusDSL
+    include StimulusHelper
 
     # Override this method to perform any initialisation after attributes are set
     def after_component_initialize
     end
 
     # This can be overridden to return an array of extra class names, or a string of class names.
-    def element_classes
+    def root_element_classes
     end
 
     # Properties/attributes passed to the "root" element of the component. You normally override this method to
@@ -50,6 +57,12 @@ module Vident
     # attributes which require elements to reference by ID. Note this overrides the `id` accessor
     def id = @id.presence || random_id
 
+
+    # Return the names of the properties defined in the component class.
+    def prop_names
+      self.class.prop_names
+    end
+
     private
 
     # Called by Literal::Properties after the component is initialized.
@@ -66,14 +79,6 @@ module Vident
       root_element(...)
     end
 
-    def root_element_tag_options
-      options = @html_options&.dup || {}
-      data_attrs = stimulus_data_attributes
-      options[:data] = options[:data].present? ? data_attrs.merge(options[:data]) : data_attrs
-      return options unless @id
-      options.merge(id: @id)
-    end
-
     def root_element_tag_type
       @element_tag.presence&.to_sym || :div
     end

data/lib/vident/component_attribute_resolver.rb

@@ -4,18 +4,18 @@ module Vident
   module ComponentAttributeResolver
     private
 
-    # FIXME: in a view_component the parsing of html_options might have to be in `before_render`
+    # Prepare attributes set at initialization, which will later be merged together before rendering.
     def prepare_component_attributes
       prepare_stimulus_collections
 
       # Add stimulus attributes from DSL first (lower precedence)
       add_stimulus_attributes_from_dsl
 
-      # Process root_element_attributes (higher precedence) 
+      # Process root_element_attributes (higher precedence)
       extra = root_element_attributes
       @html_options = (extra[:html_options] || {}).merge(@html_options) if extra.key?(:html_options)
-      @html_options[:class] = render_classes(extra[:classes])
-      @html_options[:id] = (extra[:id] || id) unless @html_options.key?(:id)
+      @root_element_attributes_classes = extra[:classes]
+      @root_element_attributes_id = (extra[:id] || id)
       @element_tag = extra[:element_tag] if extra.key?(:element_tag)
 
       add_stimulus_controllers(extra[:stimulus_controllers]) if extra.key?(:stimulus_controllers)
@@ -26,6 +26,32 @@ module Vident
       add_stimulus_classes(extra[:stimulus_classes]) if extra.key?(:stimulus_classes)
     end
 
+    def resolve_root_element_attributes_before_render(root_element_html_options = nil)
+      extra = root_element_html_options || {}
+
+      # Options set on component at render time take precedence over attributes set by methods on the component
+      # or attributes passed to root_element in the template
+      final_attributes = {
+        data: stimulus_data_attributes  # Lowest precedence
+      }
+      if root_element_html_options.present? # Mid precedence
+        root_element_tag_html_options_merge(final_attributes, root_element_html_options)
+      end
+      if @html_options.present? # Highest precedence
+        root_element_tag_html_options_merge(final_attributes, @html_options)
+      end
+      final_attributes[:class] = render_classes(extra[:class])
+      final_attributes[:id] = (extra[:id] || @root_element_attributes_id) unless final_attributes.key?(:id)
+      final_attributes
+    end
+
+    def root_element_tag_html_options_merge(final_attributes, other_html_options)
+      if other_html_options[:data].present?
+        final_attributes[:data].merge!(other_html_options[:data])
+      end
+      final_attributes.merge!(other_html_options.except(:data))
+    end
+
     # Add stimulus attributes from DSL declarations using existing add_* methods
     def add_stimulus_attributes_from_dsl
       dsl_attrs = self.class.stimulus_dsl_attributes(self)
@@ -36,20 +62,19 @@ module Vident
       add_stimulus_actions(dsl_attrs[:stimulus_actions]) if dsl_attrs[:stimulus_actions]
       add_stimulus_targets(dsl_attrs[:stimulus_targets]) if dsl_attrs[:stimulus_targets]
       add_stimulus_outlets(dsl_attrs[:stimulus_outlets]) if dsl_attrs[:stimulus_outlets]
-      
+
       # Add static values (now includes resolved proc values)
       add_stimulus_values(dsl_attrs[:stimulus_values]) if dsl_attrs[:stimulus_values]
-      
+
       # Resolve and add values from props
       if dsl_attrs[:stimulus_values_from_props]
         resolved_values = resolve_values_from_props(dsl_attrs[:stimulus_values_from_props])
         add_stimulus_values(resolved_values) unless resolved_values.empty?
       end
-      
+
       add_stimulus_classes(dsl_attrs[:stimulus_classes]) if dsl_attrs[:stimulus_classes]
     end
 
-
     # Prepare stimulus collections and implied controller path from the given attributes, called after initialization
     def prepare_stimulus_collections # Convert raw attributes to stimulus attribute collections
       @stimulus_controllers_collection = stimulus_controllers(*Array.wrap(@stimulus_controllers))

data/lib/vident/component_class_lists.rb

@@ -3,7 +3,7 @@
 module Vident
   module ComponentClassLists
     # Generates the full list of HTML classes for the component
-    def render_classes(extra_classes = nil) = class_list_builder.build(extra_classes)
+    def render_classes(root_element_html_class = nil) = class_list_builder(root_element_html_class).build
 
     # Getter for a stimulus classes list so can be used in view to set initial state on SSR
     # Returns a String of classes that can be used in a `class` attribute.
@@ -15,11 +15,13 @@ module Vident
 
     # Get or create a class list builder instance
     # Automatically detects if Tailwind module is included and TailwindMerge gem is available
-    def class_list_builder
+    def class_list_builder(root_element_html_class = nil)
       @class_list_builder ||= ClassListBuilder.new(
         tailwind_merger:,
         component_name:,
-        element_classes:,
+        root_element_attributes_classes: @root_element_attributes_classes,
+        root_element_classes:,
+        root_element_html_class:,
         additional_classes: @classes,
         html_class: @html_options&.fetch(:class, nil)
       )

data/lib/vident/stimulus_attributes.rb

@@ -5,13 +5,14 @@ module Vident
     extend ActiveSupport::Concern
 
     class_methods do
-      # Class methods for generating scoped event names
+      # Class methods for generating scoped event names. Returns a symbol
+      # so that the action parser will see it as a Stimulus event.
       def stimulus_scoped_event(event)
-        "#{component_name}:#{stimulus_js_name(event)}"
+        :"#{component_name}:#{stimulus_js_name(event)}"
       end
 
       def stimulus_scoped_event_on_window(event)
-        "#{component_name}:#{stimulus_js_name(event)}@window"
+        :"#{component_name}:#{stimulus_js_name(event)}@window"
       end
 
       private

data/lib/vident/stimulus_builder.rb

@@ -35,7 +35,7 @@ module Vident
       @values.merge!(value_hash) unless value_hash.empty?
       self
     end
-    
+
     def values_from_props(*prop_names)
       @values_from_props.concat(prop_names)
       self
@@ -53,11 +53,11 @@ module Vident
 
     def to_attributes(component_instance)
       attrs = {}
-      attrs[:stimulus_actions] = resolve_values(@actions, component_instance) unless @actions.empty?
-      attrs[:stimulus_targets] = resolve_values(@targets, component_instance) unless @targets.empty?
-      attrs[:stimulus_values] = resolve_hash_values(@values, component_instance) unless @values.empty?
+      attrs[:stimulus_actions] = resolve_attributes_filtering_nil(@actions, component_instance) unless @actions.empty?
+      attrs[:stimulus_targets] = resolve_attributes_filtering_nil(@targets, component_instance) unless @targets.empty?
+      attrs[:stimulus_values] = resolve_hash_values_allowing_nil(@values, component_instance) unless @values.empty?
       attrs[:stimulus_values_from_props] = @values_from_props.dup unless @values_from_props.empty?
-      attrs[:stimulus_classes] = resolve_hash_values(@classes, component_instance) unless @classes.empty?
+      attrs[:stimulus_classes] = resolve_hash_classes_filtering_nil(@classes, component_instance) unless @classes.empty?
       attrs[:stimulus_outlets] = @outlets.dup unless @outlets.empty?
       attrs
     end
@@ -95,22 +95,45 @@ module Vident
 
     private
 
-    def resolve_values(array, component_instance)
-      array.map do |value|
+    # For actions, targets - filter out nil values from procs AND static
+    def resolve_attributes_filtering_nil(array, component_instance)
+      result = []
+      array.each do |value|
         if callable?(value)
-          component_instance.instance_exec(&value)
+          resolved_value = component_instance.instance_exec(&value)
+          # Exclude nil from procs (nil is not valid for actions/targets)
+          result << resolved_value unless resolved_value.nil?
         else
-          value
+          # Exclude static nil values (nil is not valid for actions/targets)
+          result << value unless value.nil?
         end
       end
+      result
     end
 
-    def resolve_hash_values(hash, component_instance)
+    # For values - allow nil values from procs and static (will become "null" in JavaScript)
+    def resolve_hash_values_allowing_nil(hash, component_instance)
       hash.transform_values { |value| callable?(value) ? component_instance.instance_exec(&value) : value }
     end
 
+    # For classes - filter out nil values from procs AND static
+    def resolve_hash_classes_filtering_nil(hash, component_instance)
+      result = {}
+      hash.each do |key, value|
+        if callable?(value)
+          resolved_value = component_instance.instance_exec(&value)
+          # Exclude nil from procs (nil is not valid for classes)
+          result[key] = resolved_value unless resolved_value.nil?
+        else
+          # Exclude static nil values (nil is not valid for classes)
+          result[key] = value unless value.nil?
+        end
+      end
+      result
+    end
+
     def callable?(value)
       value.respond_to?(:call)
     end
   end
-end
+end

data/lib/vident/{stimulus_dsl.rb → stimulus_helper.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Vident
-  module StimulusDSL
+  module StimulusHelper
     extend ActiveSupport::Concern
 
     class_methods do
@@ -11,10 +11,10 @@ module Vident
           @stimulus_builder = StimulusBuilder.new
           @inheritance_merged = false
         end
-        
+
         # Ensure inheritance is applied
         ensure_inheritance_merged
-        
+
         # Execute the new block to add/merge new attributes
         @stimulus_builder.instance_eval(&block)
       end
@@ -24,10 +24,10 @@ module Vident
         if @stimulus_builder.nil? && superclass.respond_to?(:stimulus_dsl_attributes)
           return superclass.stimulus_dsl_attributes(component_instance)
         end
-        
+
         # Ensure inheritance is applied at access time
         ensure_inheritance_merged
-        
+
         @stimulus_builder&.to_attributes(component_instance) || {}
       end
 
@@ -35,7 +35,7 @@ module Vident
 
       def ensure_inheritance_merged
         return if @inheritance_merged || @stimulus_builder.nil?
-        
+
         if superclass.respond_to?(:stimulus_dsl_builder, true)
           parent_builder = superclass.send(:stimulus_dsl_builder)
           if parent_builder
@@ -71,4 +71,4 @@ module Vident
       resolved
     end
   end
-end
+end

data/lib/vident/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Vident
-  VERSION = "1.0.0.alpha1"
+  VERSION = "1.0.0.alpha3"
 
   # Shared version for all vident gems
   def self.version

data/lib/vident.rb

@@ -46,7 +46,7 @@ require "vident/stimulus_component"
 require "vident/component_class_lists"
 require "vident/component_attribute_resolver"
 require "vident/stimulus_builder"
-require "vident/stimulus_dsl"
+require "vident/stimulus_helper"
 
 require "vident/component"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: vident
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha1
+  version: 1.0.0.alpha3
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 bindir: bin
 cert_chain: []
-date: 2025-07-08 00:00:00.000000000 Z
+date: 2025-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -102,7 +102,7 @@ files:
 - lib/vident/stimulus_controller.rb
 - lib/vident/stimulus_controller_collection.rb
 - lib/vident/stimulus_data_attribute_builder.rb
-- lib/vident/stimulus_dsl.rb
+- lib/vident/stimulus_helper.rb
 - lib/vident/stimulus_outlet.rb
 - lib/vident/stimulus_outlet_collection.rb
 - lib/vident/stimulus_target.rb