vident 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2966a65af9fba6bbddf4ffe3c93868a99e6c281cc992db859408dbb4c46050be
-  data.tar.gz: e7224204b0d79fe83df5c3a98f0f779ab035645b7d6fabee01818341c6089480
+  metadata.gz: 1c85914dca2e7df8a1ff9711be7cf0f1528409ff7d44dbb72501474c2c1359c2
+  data.tar.gz: 43e7d176b19a36b2c7d8640cd230429ae59a46e0b77ad9e6c6d24c9c40e38973
 SHA512:
-  metadata.gz: 7b1a90bb87dc01712457acfa7b28d6dc3379cce5a66fa635dfbf6f357d1ecb2e635a563330e4f8facc88f3c213ec7309a40193d20a55e391f33f05ec418130cb
-  data.tar.gz: 5a9aecbe18952241b8b53788a41808e8ba43968c4adc4989aa1184deb683cd91b1b680ee5ff1e697746ceb8fa7cceb0f000ee051f7da7d34f6b1dae48b0952a4
+  metadata.gz: 4e07543b9851d9b4d7a9ef98eadec0a53ad8c8e409934fd0f92e942386235fa7f964d36fa04bb84bde91d036ce4cf7231d848e13274f3190f91573b00339a999
+  data.tar.gz: b89835399b32ff4e98efd24f1fb75328ed0633a73c935eb6a7c844f5f1dc7f909ade0805741445db81a0d704ffcc066aa416c17ee6a65100b9d8fb9738d86b41

data/CHANGELOG.md

@@ -6,6 +6,60 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [2.0.0] - 2026-04-24
+
+Vident 2.0 is a ground-up rearchitecture of the DSL, attribute resolution, and composition model. The public shape of `stimulus do ... end`, `root_element`, `child_element`, outlets, props, and the `stimulus_*:` prop/kwarg API is preserved for common cases, but several internals and a handful of edge-case behaviours changed. See `doc/reviews/v1-gotchas.md` for the full list of fixed gotchas; the highlights are below.
+
+### Breaking
+
+- **Namespace consolidation.** The `Vident2::*` namespace used during side-by-side development has been removed. Everything now lives under `Vident::*` directly: `Vident::Component`, `Vident::Capabilities::*`, `Vident::Phlex::HTML`, `Vident::ViewComponent::Base`, `Vident::Stimulus::*` (value classes), `Vident::Internals::*` (DSL/Resolver/Plan). Upgrade path is a `s/Vident2::/Vident::/g` on project code.
+- **Legacy collection classes removed.** `Vident::StimulusAction`, `StimulusTarget`, `StimulusController`, `StimulusValue`, `StimulusParam`, `StimulusOutlet`, `StimulusClass`, and each of their `*Collection` companions (plus `StimulusBuilder`, `StimulusDataAttributeBuilder`, `StimulusAttributeBase`, `StimulusAttributes`, `StimulusAction::Descriptor`) are gone. The 2.0 equivalents live under `Vident::Stimulus::*` (`Action`, `Target`, `Controller`, `Value`, `Param`, `Outlet`, `ClassMap`, `Collection`). `#to_h` now uses **Symbol keys** uniformly; V1 returned String keys for some primitives.
+- **`child_element` strictness.** Passing both `stimulus_<singular>:` and `stimulus_<plural>:` kwargs now raises `ArgumentError` (`"mutually exclusive — pass one or the other."`). V1 silently dropped the singular when the plural was an empty array (latent since 1.0.0, see "Fixed" below). Workaround at call sites that relied on the V1 shape: `stimulus_targets: [:input, *control_targets]`.
+- **`stimulus_controllers:` prop appends instead of replacing.** V1 replaced the implied controller when you passed `stimulus_controllers:` at render time; V2 appends, so the root element carries `data-controller="implied extra"`. Migration: if you wanted to *replace*, add `no_stimulus_controller` at the class level.
+- **Outlet DSL procs now resolve.** V1 silently passed a proc through as the outlet selector string, emitting literal `#<Proc:0x...>`. V2 evaluates the proc in the instance binding and emits the returned string. This turns previously broken code into working code, but if you relied on the proc-as-identity string for some reason, you'll now see a different data attribute.
+- **`nil` vs `false` drop rule.** V1 dropped both `nil` and `false` proc returns silently via a `blank?` filter. V2 drops only `nil`; `false` reaches the parser and raises `Vident::ParseError`. Fix: return `nil` (not `false`) to mean "don't emit this entry."
+- **`no_stimulus_controller` + DSL body now raises loudly.** V1 raised a bare `StandardError` at instance init. V2 raises `Vident::DeclarationError` at `stimulus do ... end` time with the offending class name and caller location in the message.
+- **StableId strategy.** Unchanged from 1.0, but reiterated here because it's the biggest gotcha during upgrade. `Vident::StableId` requires an explicit `strategy` and per-request seed — `bin/rails generate vident:install` sets both up correctly.
+
+### Added
+
+- **Fluent action DSL.** Inside `stimulus do ... end`, the singular `action(...)` call returns a chainable builder: `action(:escape).on(:keydown).keyboard("esc").window`, `action(:save).modifier(:prevent, :stop)`, `action(:delete).when { admin? }`. Chain methods: `.on`, `.call_method`, `.modifier`, `.keyboard`, `.window`, `.on_controller`, `.when`.
+- **Kwargs shorthand for actions.** `action :save, on: :click, modifier: [:prevent, :stop], keyboard: "ctrl+s", window: true, on_controller: :admin, call_method: :handle_save, when: -> { ... }` — equivalent to the fluent chain, pick whichever reads better. Unknown kwargs raise `ArgumentError`.
+- **Controller aliases.** `controller "admin/users", as: :admin` inside `stimulus do` declares a short alias; `action(...).on_controller(:admin)` or `action(..., on_controller: :admin)` then routes through it. Unknown alias refs raise `Vident::DeclarationError`. Runtime inputs (`stimulus_actions: [{method: :save, controller: :admin}]`) resolve the same map.
+- **Capability mixin composition.** `Vident::Component` is a composition root that includes twelve focused capability mixins (`Tailwind`, `Declarable`, `Identifiable`, `StimulusDeclaring`, `StimulusParsing`, `StimulusMutation`, `StimulusDraft`, `StimulusDataEmitting`, `ClassListBuilding`, `RootElementRendering`, `ChildElementRendering`, `Inspectable`), plus an opt-in `Caching` mixin (thirteen in total, including Caching). Mixin order mirrors capability dependencies.
+- **Singular DSL primitives.** `value(:name, *, **)`, `param(:name, *, **)`, `outlet(:name, *, **)`, `class_map(:name, *, **)`, `controller(path, as: nil)`, `controllers(*paths)`, `target(:name).when { ... }` — full set of singular entry points alongside the plural forms.
+- **Draft → Plan seal pattern.** Internal: `after_component_initialize` mutators (e.g. `add_stimulus_actions`) still work against a mutable Draft; the Draft seals into an immutable Plan once rendering begins. Prevents the V1 "mutator silently ignored post-render" class of bug.
+- **Phase-split proc resolution.** DSL procs are evaluated in two phases: static (after_initialize, no `view_context`) and procs (`before_template` / `before_render`, `view_context`/`helpers` wired). Procs can now call Rails helpers (`number_with_precision`, url helpers, `t`, `l`, etc.) safely — already backported to 1.0.2.
+- `has_stimulus_controller` class method re-enables the implied controller in a subclass after a parent declared `no_stimulus_controller` (#27).
+- `root_element_class_list(extra = nil)` and `root_element_data_attributes` for components rendering through third-party tag helpers instead of `root_element(...)` (#25; V1 names `render_classes` / `stimulus_data_attributes` — see UPGRADING.md §8).
+- Class-level Stimulus builders — `MyComponent.stimulus_target(:x)` etc. — return value objects without a component instance (#18).
+- `Vident::Types::*` — seven named Literal unions for the built-in `stimulus_*:` prop types, reusable from user components (#16).
+- `cache_component(*keys, **options, &block)` on both adapter base classes — fragment-caches the block using the Vident-computed `cache_key` (#13).
+- Shared `Vident::Stimulus::Base` + `Combinable` for the value classes: `with(**overrides)` combinator, canonical `deconstruct_keys` (restores pattern matching — previously shadowed by the `to_h` data-attribute override), and `Action.parse([event, existing_action])` merge form (#28).
+
+### Fixed
+
+- `child_element` no longer silently drops a `stimulus_<singular>:` kwarg when `stimulus_<plural>:` is also passed with an empty array. The V1 helper returned early on an empty-but-truthy plural, losing the singular and emitting no data attribute — latent since 1.0.0, surfaced by call sites like `child_element(:input, stimulus_target: :input, stimulus_targets: control_targets)` where `control_targets` defaulted to `[]`. V2 raises `ArgumentError` on both-set (see Breaking); workaround on 1.x is `stimulus_targets: [:input, *control_targets]` (also works on 2.x).
+- Outlet DSL procs now resolve instead of being treated as identity strings (see Breaking).
+- `add_stimulus_actions([:click, :handle])` now treats the Array as *one* action descriptor (event + method pair) rather than splatting it into two separate `:click` and `:handle` actions. Matches the DSL's `actions [:click, :handle]` semantics — the V1 asymmetry is gone.
+
+### Removed
+
+- `Vident::StimulusAction::Descriptor` typed data class. The V2 equivalent is `Vident::Stimulus::Action` itself — the Hash shape accepted by the DSL (`{event:, method:, controller:, options:, keyboard:, window:}`) parses directly into the value class now. Callers that instantiated `Descriptor` explicitly should swap to `Vident::Stimulus::Action.parse(hash, implied: ...)` or just pass the Hash.
+- Legacy top-level requires like `require "vident/stimulus_action"`. The main `require "vident"` loads the whole surface; deep requires for individual value classes still work (`require "vident/stimulus/action"`) but are no longer the documented path.
+
+
+## [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

data/README.md

@@ -79,9 +79,13 @@ class ButtonComponent < Vident::ViewComponent::Base
   
   # Configure Stimulus integration
   stimulus do
-    # 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? }
+    # Fluent action DSL: reads left-to-right as "the handle_click method fires on the click event".
+    action(:handle_click).on(:click)
+    # Kwargs shorthand — same result, pick whichever reads better:
+    action :handle_submit, on: :submit, modifier: [:prevent, :stop]
+    # Proc for conditional / cross-component wiring, evaluated in the instance at render time.
+    action(-> { [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)
@@ -178,7 +182,7 @@ Use the component in your views:
 <%= render ButtonComponent.new(text: "Cancel", url: "/home", style: :secondary) %>
 
 <!-- Override things -->
-<%= render ButtonComponent.new(text: "Cancel", url: "/home" classes: "bg-red-900", html_options: {role: "button"}) %>
+<%= render ButtonComponent.new(text: "Cancel", url: "/home", classes: "bg-red-900", html_options: {role: "button"}) %>
 ```
 
 The rendered HTML includes all Stimulus data attributes:
@@ -227,7 +231,7 @@ class CardComponent < Vident::ViewComponent::Base
   # Property with validation
   prop :size, _Union(:small, :medium, :large), default: :medium
   
-  # Boolean property (creates predicate method)
+  # Boolean property (pass `predicate: :public` to also generate a `?` method)
   prop :featured, _Boolean, default: false
 end
 ```
@@ -271,7 +275,7 @@ The `root_element` helper method renders your component's root element with all
 ```ruby
 # In your component class
 def root_element_classes
-  ["card", featured? ? "card-featured" : nil]
+  ["card", @featured ? "card-featured" : nil]
 end
 
 private
@@ -362,17 +366,41 @@ class ToggleComponent < Vident::ViewComponent::Base
 end
 ```
 
-**Action modifiers** — the Array form `[:click, :method]` handles the common case. For Stimulus's modifier syntax (`:once`/`:prevent`/`:stop`/`:passive`/`:"!passive"`/`:capture`/`:self`, keyboard filters, `@window`), pass a Hash or a `Vident::StimulusAction::Descriptor`:
+**Action modifiers — fluent DSL.** Singular `action(...)` returns a builder you chain with event, modifier, keyboard, and window setters. Kwargs shorthand is equivalent:
 
 ```ruby
-actions({event: :click,   method: :submit, options: [:once, :prevent]})
-actions({event: :keydown, method: :on_key, keyboard: "ctrl+a"})
-actions({event: :resize,  method: :on_resize, window: true})
-# or, if you want a typed, passable object:
-actions Vident::StimulusAction::Descriptor.new(event: :click, method: :save, options: [:prevent])
+stimulus do
+  action(:submit).on(:click).modifier(:once, :prevent)          # click:once:prevent->implied#submit
+  action(:on_key).on(:keydown).keyboard("ctrl+a")               # keydown.ctrl+a->implied#onKey
+  action(:on_resize).on(:resize).window                         # resize@window->implied#onResize
+
+  # kwargs shorthand — same result:
+  action :submit,     on: :click,   modifier: [:once, :prevent]
+  action :on_key,     on: :keydown, keyboard: "ctrl+a"
+  action :on_resize,  on: :resize,  window: true
+  action :save,       on: :click,   call_method: :handle_save
+
+  # conditional inclusion via `.when` / `when:`:
+  action(:delete).when { admin? }
+end
 ```
 
-Unknown option symbols raise `ArgumentError` at attribute construction, not at render.
+Chain methods: `.on`, `.call_method`, `.modifier`, `.keyboard`, `.window`, `.on_controller`, `.when`. Recognised kwargs: `on:`, `call_method:`, `modifier:` (Symbol or Array), `keyboard:`, `window:`, `on_controller:`, `when:`. Unknown kwargs or modifier symbols raise `ArgumentError`.
+
+**Controller aliases.** Declare a short alias with `controller "path", as: :sym`, then reference it from action entries via the fluent `.on_controller(:sym)` or the `on_controller: :sym` kwarg:
+
+```ruby
+stimulus do
+  controller "admin/users", as: :admin
+
+  action(:save).on(:click).on_controller(:admin)     # click->admin--users#save
+  action :save, on: :click, on_controller: :admin    # same, kwargs form
+end
+```
+
+Unknown aliases raise `Vident::DeclarationError` at render time.
+
+**Legacy Hash form.** Still accepted for compat — `actions({event: :click, method: :submit, options: [:once, :prevent]})` parses the same way. The Hash descriptor is folded directly into `Vident::Stimulus::Action` — pass a Hash and it is parsed in place. Accepted keys: `method:`, `event:`, `controller:`, `options:`, `keyboard:`, `window:`.
 
 ### Dynamic Values and Classes with Procs
 
@@ -415,7 +443,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:
 
@@ -486,14 +517,14 @@ class MyComponent < Vident::ViewComponent::Base
     # This would generate: "my-component:dataLoaded"
     puts stimulus_scoped_event(:data_loaded)
     
-    # For window events, this generates: "my-component:dataLoaded@window" 
+    # For window events, this generates: :"my-component:dataLoaded@window" 
     puts stimulus_scoped_event_on_window(:data_loaded)
   end
 end
 
 # Available as both class and instance methods:
-MyComponent.stimulus_scoped_event(:data_loaded)      # => "my-component:dataLoaded"
-MyComponent.new.stimulus_scoped_event(:data_loaded)  # => "my-component:dataLoaded"
+MyComponent.stimulus_scoped_event(:data_loaded)      # => :"my-component:dataLoaded"
+MyComponent.new.stimulus_scoped_event(:data_loaded)  # => :"my-component:dataLoaded"
 ```
 
 This is useful for:
@@ -529,7 +560,7 @@ class CustomComponent < Vident::ViewComponent::Base
 end
 ```
 
-All stimulus props accept Symbol paths as well as Strings (e.g. `stimulus_controllers: [:custom, :"admin/users"]`). `stimulus_values:` and `stimulus_classes:` additionally accept Array entries (for cross-controller: `[["admin/users", :name, "value"]]`) and pre-built `StimulusValue`/`StimulusValueCollection` / `StimulusClass`/`StimulusClassCollection` instances, so you can compose attribute sets outside the component and pass them in.
+All stimulus props accept Symbol paths as well as Strings (e.g. `stimulus_controllers: [:custom, :"admin/users"]`). `stimulus_values:` and `stimulus_classes:` additionally accept Array entries (for cross-controller: `[["admin/users", :name, "value"]]`) and pre-built `Vident::Stimulus::Value` / `Vident::Stimulus::ClassMap` instances, so you can compose attribute sets outside the component and pass them in.
 
 or you can use tag helpers to generate HTML with Stimulus attributes:
 

data/lib/vident/caching.rb

@@ -1,114 +1,8 @@
 # frozen_string_literal: true
 
-module Vident
-  # Rails fragment caching works by either expecting the cached key object to respond to `cache_key` or for that object
-  # to be an array or hash.
-  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)
-        # Add view file to cache key
-        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
-
-      # Components can be used with fragment caching, but you need to be careful! Read on...
-      #
-      #     <% cache component do %>
-      #      <%= render component %>
-      #    <% end %>
-      #
-      # The most important point is that Rails cannot track dependencies on the component itself, so you need to
-      # be careful to be explicit on the attributes, and manually specify any sub Viewcomponent dependencies that the
-      # component has. The assumption is that the subcomponent takes any attributes from the parent, so the cache key
-      # depends on the parent component attributes. Otherwise changes to the parent or sub component views/Ruby class
-      # will result in different cache keys too. Of course if you invalidate all cache keys with a modifier on deploy
-      # then no need to worry about changing the cache key on component changes, only on attribute/data changes.
-      #
-      # A big caveat is that the cache key cannot depend on anything related to the view_context of the component (such
-      # as `helpers` as the key is created before the rending pipline is invoked (which is when the view_context is set).
-      def depends_on(*klasses)
-        @component_dependencies ||= []
-        @component_dependencies += klasses
-      end
-
-      attr_reader :component_dependencies
-
-      def component_modified_time
-        return @component_modified_time if Rails.env.production? && @component_modified_time
-
-        raise StandardError, "Must implement cache_component_modified_time" unless respond_to?(:cache_component_modified_time)
-
-        # FIXME: This could stack overflow if there are circular dependencies
-        deps = component_dependencies&.map(&:component_modified_time)&.join("-") || ""
-        @component_modified_time = deps + cache_component_modified_time
-      end
+require_relative "capabilities/caching"
 
-      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
-        # If the presenter defines cache key setup then define the method. Otherwise Rails assumes this
-        # will return a valid key if the class will respond to this
-        define_method :cache_key do |n = :_collection|
-          if defined?(@cache_key)
-            return @cache_key[n] if @cache_key.key?(n)
-          else
-            @cache_key ||= {}
-          end
-          generate_cache_key(n)
-          @cache_key[n]
-        end
-      end
-    end
-
-    # Component modified time which is combined with other cache key attributes to generate cache key for an instance
-    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.map do |item|
-        next if item == self
-        generate_item_cache_key_from(item)
-      end
-    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
+module Vident
+  # Top-level alias for the mixin at `Vident::Capabilities::Caching`.
+  Caching = Capabilities::Caching
 end

data/lib/vident/capabilities/caching.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module Vident
+  module Capabilities
+    # 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` must be implemented by the adapter base class.
+    module Caching
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def inherited(subclass)
+          subclass.instance_variable_set(:@named_cache_key_attributes, @named_cache_key_attributes&.dup)
+          subclass.instance_variable_set(:@component_dependencies, @component_dependencies&.dup)
+          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 ::Vident::ConfigurationError, "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
+        sources = cache_keys_for_sources(key_attributes)
+        if sources.empty?
+          raise ::Vident::ConfigurationError,
+            "no cache key sources resolved for #{self.class.name} — ensure `with_cache_key` attributes return non-nil values"
+        end
+        key = "#{self.class.name}/#{sources.join("/")}"
+        @cache_key[index] = cache_key_modifier.present? ? "#{key}/#{cache_key_modifier}" : key
+      end
+    end
+  end
+end

data/lib/vident/capabilities/child_element_rendering.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "../internals/registry"
+require_relative "../stimulus/collection"
+
+module Vident
+  module Capabilities
+    module ChildElementRendering
+      def child_element(
+        tag_name,
+        stimulus_controllers: nil,
+        stimulus_targets: nil,
+        stimulus_actions: nil,
+        stimulus_outlets: nil,
+        stimulus_values: nil,
+        stimulus_params: nil,
+        stimulus_classes: nil,
+        stimulus_controller: nil,
+        stimulus_target: nil,
+        stimulus_action: nil,
+        stimulus_outlet: nil,
+        stimulus_value: nil,
+        stimulus_param: nil,
+        stimulus_class: nil,
+        **options,
+        &block
+      )
+        inputs = {
+          controllers: [stimulus_controllers, stimulus_controller],
+          actions: [stimulus_actions, stimulus_action],
+          targets: [stimulus_targets, stimulus_target],
+          outlets: [stimulus_outlets, stimulus_outlet],
+          values: [stimulus_values, stimulus_value],
+          params: [stimulus_params, stimulus_param],
+          class_maps: [stimulus_classes, stimulus_class]
+        }
+
+        data_attrs = {}
+        ::Vident::Internals::Registry.each do |kind|
+          plural, singular = inputs.fetch(kind.name)
+          child_element_check_plural!(plural, singular, kind)
+          coll = child_element_build_collection(kind, plural, singular)
+          data_attrs.merge!(coll.to_h) unless coll.empty?
+        end
+
+        generate_child_element(tag_name, data_attrs, options, &block)
+      end
+
+      def generate_child_element(tag_name, stimulus_data_attributes, options, &block)
+        raise NoMethodError, "adapter must implement generate_child_element"
+      end
+
+      private
+
+      def child_element_check_plural!(plural, singular, kind)
+        if plural && singular
+          raise ArgumentError,
+            "'stimulus_#{kind.plural_name}:' and 'stimulus_#{kind.singular_name}:' " \
+            "are mutually exclusive — pass one or the other."
+        end
+        return if plural.nil?
+        return if plural.is_a?(Enumerable) && !plural.is_a?(Hash)
+        return if plural.is_a?(Hash) && kind.keyed?
+        raise ArgumentError,
+          "'stimulus_#{kind.plural_name}:' must be an enumerable. " \
+          "Did you mean 'stimulus_#{kind.singular_name}:'?"
+      end
+
+      # Exactly one of `plural` / `singular` is non-nil; guard above
+      # rejects both-set.
+      def child_element_build_collection(kind, plural, singular)
+        plural_method = :"stimulus_#{kind.plural_name}"
+        singular_method = :"stimulus_#{kind.singular_name}"
+
+        if plural
+          if kind.keyed? && plural.is_a?(Hash)
+            send(plural_method, plural)
+          elsif plural.is_a?(Array)
+            send(plural_method, *plural)
+          else
+            send(plural_method, *Array.wrap(plural))
+          end
+        elsif singular
+          coll_items = [send(singular_method, *Array.wrap(singular))]
+          ::Vident::Stimulus::Collection.new(kind: kind, items: coll_items)
+        else
+          ::Vident::Stimulus::Collection.new(kind: kind, items: [])
+        end
+      end
+    end
+  end
+end

data/lib/vident/capabilities/class_list_building.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../internals/class_list_builder"
+
+module Vident
+  module Capabilities
+    module ClassListBuilding
+      def class_list_for_stimulus_classes(*names)
+        resolve_stimulus_attributes_at_render_time
+        plan = seal_draft
+        maps = plan.class_maps
+        return "" if maps.empty? || names.empty?
+
+        result = ::Vident::Internals::ClassListBuilder.call(
+          stimulus_classes: maps,
+          stimulus_class_names: names,
+          tailwind_merger: tailwind_merger
+        )
+        result || ""
+      end
+    end
+  end
+end

data/lib/vident/capabilities/declarable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module Vident
+  module Capabilities
+    module Declarable
+      extend ActiveSupport::Concern
+
+      included do
+        extend Literal::Properties
+
+        prop :element_tag, Symbol, default: :div
+        prop :id, _Nilable(String)
+        prop :classes, _Union(String, _Array(String)), default: -> { [] }
+        prop :html_options, Hash, default: -> { {} }
+
+        # `stimulus_controllers:` APPENDS to the implied controller (which
+        # seeds first unless `no_stimulus_controller`).
+        prop :stimulus_controllers, ::Vident::Types::StimulusControllers, default: -> { [] }
+        prop :stimulus_actions, ::Vident::Types::StimulusActions, default: -> { [] }
+        prop :stimulus_targets, ::Vident::Types::StimulusTargets, default: -> { [] }
+        prop :stimulus_outlets, ::Vident::Types::StimulusOutlets, default: -> { [] }
+        prop :stimulus_outlet_host, _Nilable(::Vident::Component)
+        prop :stimulus_values, ::Vident::Types::StimulusValues, default: -> { {} }
+        prop :stimulus_params, ::Vident::Types::StimulusParams, default: -> { {} }
+        prop :stimulus_classes, ::Vident::Types::StimulusClasses, default: -> { {} }
+      end
+
+      class_methods do
+        def prop_names
+          literal_properties.properties_index.keys.map(&:to_sym)
+        end
+      end
+
+      def prop_names = self.class.prop_names
+    end
+  end
+end

data/lib/vident/capabilities/identifiable.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../stimulus/controller"
+require_relative "../stable_id"
+
+module Vident
+  module Capabilities
+    module Identifiable
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def stimulus_identifier_path
+          name&.underscore || "anonymous_component"
+        end
+
+        def stimulus_identifier
+          stimulus_identifier_path.split("/").map(&:dasherize).join("--")
+        end
+
+        def component_name
+          @component_name ||= stimulus_identifier
+        end
+      end
+
+      def component_name = self.class.component_name
+
+      def stimulus_identifier = self.class.stimulus_identifier
+
+      private def default_controller_path = self.class.stimulus_identifier_path
+
+      # `.presence` is intentional — blank string falls through to auto-generation.
+      def id
+        @id.presence || random_id
+      end
+
+      def random_id
+        @__vident_auto_id ||= "#{component_name}-#{::Vident::StableId.next_id_in_sequence}"
+      end
+
+      def outlet_id
+        @outlet_id ||= [stimulus_identifier, "##{id}"]
+      end
+
+      private
+
+      def implied_controller
+        @__vident_implied_controller ||= ::Vident::Stimulus::Controller.new(
+          path: self.class.stimulus_identifier_path,
+          name: self.class.stimulus_identifier
+        )
+      end
+    end
+  end
+end

data/lib/vident/capabilities/inspectable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Vident
+  module Capabilities
+    module Inspectable
+      # Matches the Data.define#with convention introduced in Ruby 3.2.
+      def with(overrides = {})
+        self.class.new(**to_h.merge(overrides))
+      end
+
+      def inspect(klass_name = "Component")
+        attr_text = to_h.map { |k, v| "#{k}=#{v.inspect}" }.join(", ")
+        "#<#{self.class.name}<Vident::#{klass_name}> #{attr_text}>"
+      end
+    end
+  end
+end