vident 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28c989b42d9883afb6e1750f3d7946e83c263e2b33a0c820f57c8a31a91b5530
-  data.tar.gz: cec460e6550831ddcbae2ce9bb521b002d91a055677149c075f75a0cc1889ea1
+  metadata.gz: 5a79dcf9aadabd901dedc14da649f0aa2bee309caa0e17c7c10f0c3afea4c863
+  data.tar.gz: 34115cae656bdc0ef14f21f79aa0e98afa131b517cadd2aee5bf2f5fe6781074
 SHA512:
-  metadata.gz: c137452697e7e0b0e752c302d0d530aa495236f547a1ee33d2b474f8f8a1a09674e07a4e7cc6d9edd01c0edffa00ef2d455feb9d159b49114c82a67270b3c7de
-  data.tar.gz: 93e5fac5252a7586d03953812316042877e31e72e9ec2edb508cf427d91622c5cf6bc34eb8c6a89fe17952681110a09da99790ce8fd5ab66d327506c873425c0
+  metadata.gz: 9e3c2a2a1ea99972a07fe4e50b5652aed7a6971e389984d997f9f08509f78c3310f6b1e506e4aa7d18622055937a0cacdf58ef19e72599499fdf9af73a32fa7d
+  data.tar.gz: d40bb597e686af902916aebc6dc26b1b4bf803dfb3c4abcac1528140106fe601a229d19ac9f51b0c0d3d2a560548f29ade5356084328e6eaa99aa4946dfc75b9

data/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [1.0.2] - 2026-04-21
+
+### Changed
+
+- Stimulus DSL procs (`values foo: -> { ... }`, `actions -> { ... }`, etc.) now resolve at **render time** — Phlex's `before_template` for `Vident::Phlex::HTML`, ViewComponent's `before_render` for `Vident::ViewComponent::Base` — instead of in `after_initialize`. Procs can now reach `helpers` / `view_context`, so they can call Rails helpers (`number_with_precision`, `t`, `l`, url helpers, etc.). Non-proc DSL entries still land in the collections at init time, so `after_component_initialize` mutators and external readers see them in the same order as before.
+
+### Added
+
+- `phlex_helpers :name1, :name2, ...` class macro on `Vident::Phlex::HTML` — opts the component into Phlex's per-helper Rails adapters (`Phlex::Rails::Helpers::<CamelCase>`) so DSL procs can call helpers bare (`number_with_precision(@amount, precision: 2)`) instead of via the deprecated `helpers.<method>`. Unknown helper names raise `ArgumentError` at class definition.
+
+
 ## [1.0.0] - 2026-04-19
 
 ### Breaking
@@ -36,6 +47,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `Vident::StimulusController`'s `implied_controller_path` / `implied_controller_name` overrides now raise the same `ArgumentError` as the base when `implied_controller` is nil, instead of a confusing `NoMethodError`.
 - `stimulus_values:` and `stimulus_classes:` props now accept cross-controller entries. The type unions include `Array` (matching `stimulus_actions:`/`stimulus_targets:`), and the collection parsers pass through pre-built `StimulusValue`/`StimulusValueCollection` (and class equivalents) instead of re-wrapping them into the single-value constructor and raising `ArgumentError: Invalid number of arguments` (#23).
 - `Vident::ComponentClassLists#class_list_builder` no longer memoises the `ClassListBuilder` instance. The first caller's `root_element_html_class:` was previously latched into the cached builder, which silently dropped the `class:` argument passed to a later `root_element(class: …)` whenever `class_list_for_stimulus_classes(:name)` ran first. The underlying `TailwindMerge::Merger` is still thread-cached, so the re-construction cost is negligible.
+- `Vident::ComponentClassLists#class_list_for_stimulus_classes` no longer leaks root element classes (component name, `root_element_classes`, etc.) into its return value. It previously reused the shared `class_list_builder`, whose `ClassListBuilder` is initialised with all root-element class sources baked in; `build` always prepends those, so child elements received the full root class soup instead of just the named Stimulus class CSS. Fix: build from a fresh `ClassListBuilder` with no root-element sources.
 
 ## [1.0.0.beta2] - 2026-04-16
 

data/README.md

@@ -415,7 +415,10 @@ class DynamicComponent < Vident::ViewComponent::Base
 end
 ```
 
-Procs have access to instance variables, component methods, and Rails helpers.
+Procs have access to instance variables and component methods. They run at render time (Phlex `before_template` / ViewComponent `before_render`), so they can reach the view context:
+
+- **Phlex**: `helpers` is deprecated in phlex-rails. Opt in per Rails helper by including the matching adapter — e.g. `include Phlex::Rails::Helpers::NumberWithPrecision` — and call the helper bare (`number_with_precision(@amount, precision: 2)`) inside the proc. Vident ships a `phlex_helpers :number_with_precision, :t, :l` class macro on `Vident::Phlex::HTML` that does the right include for each name. See [phlex.fun/rails/helpers](https://www.phlex.fun/rails/helpers) for the full list of adapters.
+- **ViewComponent**: call `helpers.<method>` or `view_context.<method>` directly.
 
 **Important**: Each proc returns a single value for its corresponding stimulus attribute. If a proc returns an array, that entire array is treated as a single value, not multiple separate values. To provide multiple values for an attribute, use multiple procs or mix procs with static values:
 

data/lib/vident/component_attribute_resolver.rb

@@ -6,14 +6,16 @@ module Vident
 
     private
 
-    # Prepare attributes set at initialization, which will later be merged together before rendering.
+    # Prepare attributes set at initialization. The DSL's static entries are
+    # merged in here so user-land `after_component_initialize` mutators append
+    # after them (preserving DSL-first ordering). DSL procs are NOT resolved
+    # here — they run at render time via `resolve_stimulus_attributes_at_render_time`
+    # so they can reach `helpers` / `view_context`.
     def prepare_component_attributes
       prepare_stimulus_collections
 
-      # Add stimulus attributes from DSL first (lower precedence)
-      add_stimulus_attributes_from_dsl
+      add_stimulus_attributes_from_dsl(phase: :static)
 
-      # Process root_element_attributes (higher precedence)
       extra = root_element_attributes
       @html_options = (extra[:html_options] || {}).merge(@html_options) if extra.key?(:html_options)
       @root_element_attributes_classes = extra[:classes]
@@ -23,6 +25,19 @@ module Vident
       Stimulus::PRIMITIVES.each do |primitive|
         send(mutator_method(primitive), extra[primitive.key]) if extra.key?(primitive.key)
       end
+
+      @stimulus_proc_attributes_resolved = false
+    end
+
+    # Render-phase: resolve DSL proc entries against the component instance,
+    # now that `helpers` / `view_context` are wired. Triggered by Phlex's
+    # `before_template` and ViewComponent's `before_render`. Idempotent —
+    # `stimulus_data_attributes` also calls this as a safety net.
+    def resolve_stimulus_attributes_at_render_time
+      return if @stimulus_proc_attributes_resolved
+      @stimulus_proc_attributes_resolved = true
+
+      add_stimulus_attributes_from_dsl(phase: :procs)
     end
 
     def resolve_root_element_attributes_before_render(root_element_html_options = nil)
@@ -51,10 +66,13 @@ module Vident
       final_attributes.merge!(other_html_options.except(:data))
     end
 
-    # Run every DSL attribute through its `add_stimulus_*` mutator. `values_from_props`
-    # is a sidecar on values, resolved at instance render time.
-    def add_stimulus_attributes_from_dsl
-      dsl_attrs = self.class.stimulus_dsl_attributes(self)
+    # Run DSL attributes through their `add_stimulus_*` mutators. `phase:` is
+    # forwarded to the builder: `:static` skips procs (init-time), `:procs`
+    # skips non-procs (render-time), `:all` resolves everything.
+    # `values_from_props` is a sidecar on values, resolved at instance
+    # render time (only during the static phase since it has no procs).
+    def add_stimulus_attributes_from_dsl(phase: :all)
+      dsl_attrs = self.class.stimulus_dsl_attributes(self, phase:)
       return if dsl_attrs.empty?
 
       Stimulus::PRIMITIVES.each do |primitive|
@@ -80,6 +98,7 @@ module Vident
     end
 
     def stimulus_data_attributes
+      resolve_stimulus_attributes_at_render_time
       collections = Stimulus::PRIMITIVES.to_h { |primitive| [primitive.name, instance_variable_get(collection_ivar(primitive))] }
       StimulusDataAttributeBuilder.new(**collections).build
     end

data/lib/vident/component_class_lists.rb

@@ -8,7 +8,13 @@ module Vident
     # 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.
     def class_list_for_stimulus_classes(*names)
-      class_list_builder.build(@stimulus_classes_collection&.to_a, stimulus_class_names: names) || ""
+      # DSL proc entries are resolved lazily at render time; trigger them now
+      # so procs that use only instance state work from ERB/template.
+      resolve_stimulus_attributes_at_render_time if respond_to?(:resolve_stimulus_attributes_at_render_time, true)
+      ClassListBuilder.new(tailwind_merger:).build(
+        @stimulus_classes_collection&.to_a,
+        stimulus_class_names: names
+      ) || ""
     end
 
     private

data/lib/vident/stimulus_builder.rb

@@ -62,14 +62,23 @@ module Vident
       self
     end
 
-    def to_attributes(component_instance)
+    # `phase:` controls which entries are resolved.
+    # - `:static` — resolve non-proc entries only; procs are skipped entirely
+    #   (no placeholder). Used at init time, before helpers/view_context exist.
+    # - `:procs` — resolve proc entries only; non-procs are skipped. Used at
+    #   render time so procs can reach `helpers` / `view_context`.
+    # - `:all` — resolve everything (legacy path, retained for safety).
+    def to_attributes(component_instance, phase: :all)
       attrs = {}
       DSL_PRIMITIVES.each do |primitive|
         entries = @entries[primitive.name]
         next if entries.empty?
-        attrs[primitive.key] = resolve_entries(primitive, entries, component_instance)
+        resolved = resolve_entries(primitive, entries, component_instance, phase:)
+        attrs[primitive.key] = resolved unless resolved.nil? || resolved.empty?
+      end
+      if phase != :procs && !@values_from_props.empty?
+        attrs[:stimulus_values_from_props] = @values_from_props.dup
       end
-      attrs[:stimulus_values_from_props] = @values_from_props.dup unless @values_from_props.empty?
       attrs
     end
 
@@ -87,19 +96,24 @@ module Vident
     # Outlets don't support procs — static merge only. The other keyed kinds
     # and the positional (Array-shaped) kinds resolve procs in the component
     # instance and drop nil results.
-    def resolve_entries(primitive, entries, component_instance)
-      return entries.dup if primitive.name == :outlets
+    def resolve_entries(primitive, entries, component_instance, phase:)
+      if primitive.name == :outlets
+        return (phase == :procs) ? {} : entries.dup
+      end
 
       if primitive.keyed?
-        resolve_hash_filtering_nil(entries, component_instance)
+        resolve_hash_filtering_nil(entries, component_instance, phase:)
       else
-        resolve_array_filtering_nil(entries, component_instance)
+        resolve_array_filtering_nil(entries, component_instance, phase:)
       end
     end
 
-    def resolve_array_filtering_nil(array, component_instance)
+    def resolve_array_filtering_nil(array, component_instance, phase:)
       array.each_with_object([]) do |value, out|
-        resolved = callable?(value) ? component_instance.instance_exec(&value) : value
+        is_proc = callable?(value)
+        next if phase == :static && is_proc
+        next if phase == :procs && !is_proc
+        resolved = is_proc ? component_instance.instance_exec(&value) : value
         out << resolved unless resolved.nil?
       end
     end
@@ -107,9 +121,12 @@ module Vident
     # Dropping nil matters because Stimulus's Boolean value parser reads an
     # empty data attribute as `true` — so `-> { flag? || nil }` would silently
     # flip a Boolean value on. Omitting the entry keeps the attribute off.
-    def resolve_hash_filtering_nil(hash, component_instance)
+    def resolve_hash_filtering_nil(hash, component_instance, phase:)
       hash.each_with_object({}) do |(key, value), out|
-        resolved = callable?(value) ? component_instance.instance_exec(&value) : value
+        is_proc = callable?(value)
+        next if phase == :static && is_proc
+        next if phase == :procs && !is_proc
+        resolved = is_proc ? component_instance.instance_exec(&value) : value
         out[key] = resolved unless resolved.nil?
       end
     end

data/lib/vident/stimulus_helper.rb

@@ -19,16 +19,16 @@ module Vident
         @stimulus_builder.instance_eval(&block)
       end
 
-      def stimulus_dsl_attributes(component_instance)
+      def stimulus_dsl_attributes(component_instance, phase: :all)
         # If no stimulus blocks have been defined on this class, check parent
         if @stimulus_builder.nil? && superclass.respond_to?(:stimulus_dsl_attributes)
-          return superclass.stimulus_dsl_attributes(component_instance)
+          return superclass.stimulus_dsl_attributes(component_instance, phase:)
         end
 
         # Ensure inheritance is applied at access time
         ensure_inheritance_merged
 
-        @stimulus_builder&.to_attributes(component_instance) || {}
+        @stimulus_builder&.to_attributes(component_instance, phase:) || {}
       end
 
       private
@@ -51,7 +51,7 @@ module Vident
     end
 
     # Instance method to get DSL attributes for this component instance
-    def stimulus_dsl_attributes = self.class.stimulus_dsl_attributes(self)
+    def stimulus_dsl_attributes(phase: :all) = self.class.stimulus_dsl_attributes(self, phase:)
 
     # Instance method to resolve prop-mapped values at runtime
     def resolve_values_from_props(prop_names)

data/lib/vident/version.rb

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

data/lib/vident2/caching.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module Vident2
+  # Fragment-caching opt-in. Include into a component to get `cacheable?`,
+  # `cache_key`, and the `with_cache_key` / `depends_on` class helpers.
+  #
+  # `cache_component_modified_time` lives on the adapter base class
+  # (Phlex: `.rb` mtime; VC: sidecar template + `.rb` mtime).
+  module Caching
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def inherited(subclass)
+        subclass.instance_variable_set(:@named_cache_key_attributes, @named_cache_key_attributes&.clone)
+        super
+      end
+
+      def with_cache_key(*attrs, name: :_collection)
+        attrs << :component_modified_time
+        attrs << :to_h if respond_to?(:to_h)
+        named_cache_key_includes(name, *attrs.uniq)
+      end
+
+      attr_reader :named_cache_key_attributes
+
+      def depends_on(*klasses)
+        @component_dependencies ||= []
+        @component_dependencies += klasses
+      end
+
+      attr_reader :component_dependencies
+
+      def component_modified_time
+        return @component_modified_time if defined?(::Rails) && ::Rails.env.production? && @component_modified_time
+
+        raise StandardError, "Must implement cache_component_modified_time" unless respond_to?(:cache_component_modified_time)
+
+        deps = component_dependencies&.map(&:component_modified_time)&.join("-") || ""
+        @component_modified_time = deps + cache_component_modified_time
+      end
+
+      private
+
+      def named_cache_key_includes(name, *attrs)
+        define_cache_key_method unless @named_cache_key_attributes
+        @named_cache_key_attributes ||= {}
+        @named_cache_key_attributes[name] = attrs
+      end
+
+      def define_cache_key_method
+        define_method :cache_key do |n = :_collection|
+          @cache_key ||= {}
+          return @cache_key[n] if @cache_key.key?(n)
+          generate_cache_key(n)
+          @cache_key[n]
+        end
+      end
+    end
+
+    def component_modified_time = self.class.component_modified_time
+
+    def cacheable? = respond_to?(:cache_key)
+
+    def cache_key_modifier = ENV["RAILS_CACHE_ID"]
+
+    def cache_keys_for_sources(key_attributes)
+      sources = key_attributes.flat_map { |n| n.is_a?(Proc) ? instance_eval(&n) : send(n) }
+      sources.compact.filter_map { |item| generate_item_cache_key_from(item) unless item == self }
+    end
+
+    def generate_item_cache_key_from(item)
+      if item.respond_to? :cache_key_with_version
+        item.cache_key_with_version
+      elsif item.respond_to? :cache_key
+        item.cache_key
+      elsif item.is_a?(String)
+        Digest::SHA1.hexdigest(item)
+      else
+        Digest::SHA1.hexdigest(Marshal.dump(item))
+      end
+    end
+
+    def generate_cache_key(index)
+      key_attributes = self.class.named_cache_key_attributes[index]
+      return nil unless key_attributes
+      key = "#{self.class.name}/#{cache_keys_for_sources(key_attributes).join("/")}"
+      raise StandardError, "Cache key for key #{key} is blank!" if key.blank?
+      @cache_key[index] = cache_key_modifier.present? ? "#{key}/#{cache_key_modifier}" : key
+    end
+  end
+end