vident-view_component 1.0.0.beta2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04f65c3476a4173c32cc063c60eaaef6d588d0c66a6e94d9ae1237e8130ccf12
-  data.tar.gz: 40731bc5242a66c80a5a71b731adb97ef4c5f558da0580aff635c80a707171d4
+  metadata.gz: cd06405de6503622f0cfe065630cc6c87d5d71f2a370e71b50fa8b73c28fb9ea
+  data.tar.gz: 44460ee8ea6773c46fd4ac0686f51dd2d731f9b749af7584c3064df1895aba0c
 SHA512:
-  metadata.gz: fca4cc83f6bb06224ef3e3925f246459067bd12c72797b3542517c49092262f649ba1f2547fa169b93638ff64a7fce14cec943b780db4dd8864cd4a5d8e3439b
-  data.tar.gz: dbeb376b521f65809985226254496164ca5454f5988f376d0345a438578e8fe5a1497e10f9dfff1fba9ab1adc5af3abe711613c03c98406242fdcc66c0bdba09
+  metadata.gz: 23e25a96110c8d5f1a880df3023598eb5bd726a31a9dad637aedd74f6952ab0405bbcf43fd04e10b70b5bc59c3a6b98d9f0d6889e6811729fb8e3cc8fae1e4a1
+  data.tar.gz: f0576171afd7ab9d88bc593b34c8bff25b1a3f77ec33a40c352c3fe6255dc4b9178a123fdd5ce7e308a32fe2640bc37107c2f1079d491241c7dfc138b5820049

data/CHANGELOG.md

@@ -6,11 +6,42 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [1.0.0] - 2026-04-19
+
+### Breaking
+
+- `nil` stimulus values (static or returned from a proc) are now filtered out of the rendered data attributes instead of being serialized to an empty string. The previous behaviour silently turned Boolean-typed Stimulus values on, because Stimulus parses empty strings as `true`. To explicitly emit the JS `null` literal (for Object/Array values), return the new `Vident::StimulusNull` sentinel (#24).
+- `Vident::StableId` now requires an explicit strategy and an explicit per-request seed (#14). Run `bin/rails generate vident:install` to create an initializer that picks `STRICT` outside tests and wires a `before_action` in `ApplicationController` seeding the generator from `request.fullpath`. `set_current_sequence_generator` now requires `seed:` (nil raises `ArgumentError`); calling `next_id_in_sequence` with no strategy configured raises `Vident::StableId::StrategyNotConfiguredError`; in `STRICT` mode, missing the per-request seeding raises `Vident::StableId::GeneratorNotSetError`. The previous hard-coded seed of `42` (which produced identical IDs across unrelated requests and caused DOM collisions when Ajax fragments were grafted into server-rendered pages) is gone, and the `new_current_sequence_generator` alias has been removed.
+
+### Added
+
+- `Vident::StimulusNull` sentinel. Assign or return it from a value proc to emit `data-...-value="null"`, which Stimulus's Object/Array parser reads as JSON `null`.
+- `Vident::StableId.with_sequence_generator(seed:) { ... }` block helper for scoping a generator to a render outside the normal request flow (mailers, jobs, previews) (#14).
+- `bin/rails generate vident:install` installer that writes `config/initializers/vident.rb` and patches `ApplicationController` with the per-request seed hook (#14).
+- Claude Code skill at `skills/vident/SKILL.md` shipped with the gem. The install generator drops it into `.claude/skills/vident/SKILL.md` in the host app so Claude Code picks up the gem's conventions automatically.
+- Action descriptor support. The `stimulus_actions:` prop, `stimulus do ... actions(...)` DSL, and `child_element(stimulus_action(s): ...)` now accept a `Hash` (`{event:, method:, controller:, options:, keyboard:, window:}`) or a typed `Vident::StimulusAction::Descriptor` instance, allowing the `:once`/`:prevent`/`:stop`/`:passive`/`:"!passive"`/`:capture`/`:self` event-option modifiers, `.ctrl+a`-style keyboard filters, and `@window` in a structured Ruby form rather than a hand-typed descriptor string.
+- Stimulus action parameters. New `Vident::StimulusParam` / `StimulusParamCollection`, a `stimulus_params:` prop, a `params` DSL entry (mirrors `values`), a `stimulus_params:`/`stimulus_param:` kwarg on `child_element`, and inline `as_stimulus_param(s)` helpers. Emits `data-<controller>-<name>-param` attributes readable via `event.params.<name>` in the JS controller; element-scoped to match Stimulus's own semantics.
+
+### Changed
+
+- Internal refactor: introduced a `Vident::Stimulus::PRIMITIVES` registry (`lib/vident/stimulus.rb`) as the single source of truth for the seven Stimulus primitive kinds (controllers, actions, targets, outlets, values, params, classes). `StimulusDataAttributeBuilder`, the seven `stimulus_<kind>s(...)` plural parsers, and the seven `add_stimulus_<kind>s(...)` mutators are now generated from that registry, so adding a future primitive is a one-line registry addition plus a Value/Collection class pair — no per-kind edits in the resolver, builder, child-element helper, or data-attribute builder. No user-visible API change.
+- `serialize_value` lives on `StimulusAttributeBase` and is shared across `StimulusValue` / `StimulusParam` (was duplicated).
+- `StimulusAttributeBase.stimulize_path` is the canonical path → identifier helper (`stimulus_identifier_from_path` on `StimulusComponent` now delegates); both accept Symbol input consistently.
+- `StimulusBuilder`'s two nil-filter methods collapsed into one `resolve_hash_filtering_nil`.
+- Uniform shape matrix across all seven plural parsers: every kind now consistently accepts pre-built `<Kind>` instances, pre-built `<Kind>Collection`s, Arrays, and (where meaningful) Hashes in its variadic input.
+
+### Fixed
+
+- `stimulus_controllers:` prop and the `stimulus_controllers(...)` helper now accept Symbol paths (e.g. `:my_controller`, `:"admin/users"`) instead of raising `NoMethodError: undefined method 'split' for an instance of Symbol` (#15).
+- `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.
+
 ## [1.0.0.beta2] - 2026-04-16
 
 ### Breaking
 
-- Renamed the `tag(...)` helper to `child_element(...)` (and the internal `Vident::TagHelper` module to `Vident::ChildElementHelper`). The old name shadowed Rails' own `tag(name, options)` positional API, which breaks Rails helpers like `hidden_field_tag` and `image_tag` when called inside vident components. Rename any `component.tag(...)` calls to `component.child_element(...)`.
+- Renamed the `tag(...)` helper to `child_element(...)` (and the internal `Vident::TagHelper` module to `Vident::ChildElementHelper`). The old name shadowed Rails' own `tag(name, options)` positional API, which breaks Rails helpers like `hidden_field_tag` and `image_tag` when called inside vident components (#22). Rename any `component.tag(...)` calls to `component.child_element(...)`.
 
 ### Fixed
 

data/README.md

@@ -59,8 +59,11 @@ Then run:
 
 ```bash
 bundle install
+bin/rails generate vident:install
 ```
 
+The `vident:install` generator writes `config/initializers/vident.rb`, wires per-request ID seeding into `ApplicationController`, and (if you use Claude Code) drops a Vident skill into `.claude/skills/vident/SKILL.md` so the model has first-party guidance on the gem's conventions. See [Element IDs and request-scoped seeding](#element-ids-and-request-scoped-seeding) for the initializer rationale, and [Claude Code skill](#claude-code-skill) for the skill.
+
 ## Quick Start
 
 Here's a simple example of a Vident component using ViewComponent:
@@ -352,10 +355,25 @@ class ToggleComponent < Vident::ViewComponent::Base
     classes expanded: "block",
             collapsed: "hidden",
             transitioning: "opacity-50"
+
+    # Action parameters (element-scoped; readable as event.params.* in JS)
+    params item_id: -> { @item.id }, kind: "inline"
   end
 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`:
+
+```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])
+```
+
+Unknown option symbols raise `ArgumentError` at attribute construction, not at render.
+
 ### Dynamic Values and Classes with Procs
 
 The Stimulus DSL supports dynamic values and classes using procs or lambdas that are evaluated in the component instance context:
@@ -415,6 +433,43 @@ stimulus do
 end
 ```
 
+**Nil values.** Returning `nil` from a value proc (or setting a static `nil`) omits the data attribute entirely, so Stimulus uses its per-type default. Don't rely on `nil` becoming empty-string — that silently reads as `true` for Boolean values. If you genuinely need to emit a JS `null` (only meaningful for Object/Array-typed Stimulus values), return the `Vident::StimulusNull` sentinel, which serializes to the literal string `"null"` for JSON.parse.
+
+```ruby
+values current_user_id: -> { @user&.id },          # nil → attribute omitted
+       config: -> { @user ? @config : Vident::StimulusNull }  # nil object → JSON null
+```
+
+### Action Parameters
+
+Stimulus action parameters — `data-<controller>-<name>-param="value"` — are read inside an action handler as `event.params.<name>` (auto-typecast to Number / String / Object / Boolean). Params are **element-scoped**: every action attached to the same element sees the same params.
+
+Vident mirrors the `values` entry points:
+
+```ruby
+# In the DSL (component root element)
+stimulus do
+  actions [:click, :promote]
+  params release_id: -> { @release_id }, kind: "promote"
+end
+
+# As a prop at render time
+render MyComponent.new(stimulus_params: { release_id: 42 })
+
+# Cross-controller (Array form) — both as a prop and in the DSL
+stimulus_params: [
+  [:release_id, 42],                # implied-release-id-param="42"
+  ["other/ctrl", :scope, "full"],   # other--ctrl-scope-param="full"
+]
+
+# On a child element (co-located with the action it informs)
+card.child_element(:button,
+  stimulus_action: [:click, :promote],
+  stimulus_params: { release_id: @release_id })
+```
+
+Inline helpers: `as_stimulus_param(:name, value)` / `as_stimulus_params({name: value, ...})`.
+
 ### Scoped Custom Events
 
 Vident provides helper methods to generate scoped event names for dispatching custom events that are unique to your component:
@@ -474,6 +529,8 @@ 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.
+
 or you can use tag helpers to generate HTML with Stimulus attributes:
 
 ```erb
@@ -521,36 +578,71 @@ or directly in the ViewComponent template (eg with ERB) using the `as_stimulus_*
 
 ### Stimulus Helpers in Templates
 
-Vident provides helper methods for generating Stimulus attributes:
+Inline helpers emit pre-built `data-*` fragments you can drop into any tag. Both singular and plural forms exist; pass one or many arguments accordingly.
 
 ```erb
 <%= render root do |component| %>
-  <!-- Create a target -->
-  <div <%= component.as_target(:content) %>>
+  <div <%= component.as_stimulus_target(:content) %>>
     Content here
   </div>
-  
-  <!-- Create an action -->
-  <button <%= component.as_action(:click, :toggle) %>>
-    Toggle
-  </button>
-  
-  <!-- Use the tag helper -->
-  <%= component.tag :div, stimulus_target: :output, class: "mt-4" do %>
+
+  <button <%= component.as_stimulus_action(:click, :toggle) %>>Toggle</button>
+
+  <input <%= component.as_stimulus_targets(:input, :field) %>
+         <%= component.as_stimulus_actions([:input, :validate], [:change, :save]) %>>
+
+  <%# Or build a whole element with the child_element helper: %>
+  <%= component.child_element(:div, stimulus_target: :output, class: "mt-4") do %>
     Output here
   <% end %>
-  
-  <!-- Multiple targets/actions -->
-  <input <%= component.as_targets(:input, :field) %> 
-         <%= component.as_actions([:input, :validate], [:change, :save]) %>>
 <% end %>
 ```
 
+Parallel helpers exist for every attribute kind: `as_stimulus_controller(s)`, `as_stimulus_value(s)`, `as_stimulus_class(es)`, `as_stimulus_outlet(s)`.
+
 ### Stimulus Outlets
 
-Connect components via Stimulus outlets:
+[Stimulus outlets](https://stimulus.hotwired.dev/reference/outlets) let one controller hold references to other controllers matched by a CSS selector. Vident has a few forms for declaring them.
 
+**On the component's root element** — via the DSL:
 
+```ruby
+class DashboardComponent < Vident::ViewComponent::Base
+  stimulus do
+    # kwarg form: outlet name is the implied controller's identifier
+    outlets modal: ".modal", user_status: ".online-user"
+
+    # positional-hash form: required when the outlet identifier contains "--"
+    # (e.g. cross-namespace controllers) because Ruby kwarg keys can't have dashes
+    outlets({"admin--users" => ".admin-users"})
+  end
+end
+```
+
+Or via the `stimulus_outlets:` prop / `root_element_attributes`:
+
+```ruby
+stimulus_outlets: [
+  [:modal, ".modal"],                     # [name, selector] on implied controller
+  ["admin/users", :row, ".user-row"],     # [controller_path, name, selector] for cross-controller
+  :user_status,                           # single symbol → auto-selector (see below)
+  other_component                         # component instance → reuses its stimulus_identifier + id
+]
+```
+
+**Auto-generated selectors.** Pass just a name (symbol or string) and the selector becomes `[data-controller~=<name>]`. Pass a component instance and the selector additionally scopes to the component's id (`#<id> [data-controller~=...]`), which is what lets you target a specific instance rather than every matching controller on the page.
+
+**Self-registration via `stimulus_outlet_host`.** A built-in prop on every Vident component. When set to another component, the child registers itself as an outlet on that host at initialization — the host doesn't need to know about the child in its DSL:
+
+```ruby
+render DashboardComponent.new do |dashboard|
+  render ModalComponent.new(stimulus_outlet_host: dashboard)
+end
+```
+
+The modal now appears on the dashboard's root element as `data-dashboard-component-modal-component-outlet="#<modal-id>"` without the dashboard declaring it upfront.
+
+**On child elements** — `child_element` accepts `stimulus_outlet:` (singular) and `stimulus_outlets:` (plural / Enumerable) exactly like the target/action kwargs, so a nested `<div>` can carry its own outlet declarations.
 
 
 ### Stimulus Controller Naming
@@ -586,7 +678,7 @@ end
 <% end %>
 ```
 
-This creates a nested component that once clicked triggers the parent components `handleTrigger` action.
+This creates a nested component that once clicked triggers the parent components `handleTrigger` action. The same pattern works for cross-controller `stimulus_values:`, `stimulus_classes:`, and `stimulus_outlets:` — build the entries with the parent's helpers (`parent.stimulus_value(...)`, etc.) and pass them down.
 
 ## Other Features
 
@@ -692,6 +784,68 @@ end
 <% end %>
 ```
 
+### Element IDs and request-scoped seeding
+
+Every Vident component generates an element `id` at construction time (e.g. `button-component-abc123-0`). The IDs are produced by a deterministic sequence so the same render produces the same markup — which is what lets HTTP `ETag` caching return `304 Not Modified` for unchanged pages.
+
+Because the IDs are deterministic, **the sequence has to be keyed on something that identifies the logical content of the request**. If two unrelated renders share the same seed, the same sequence indices produce the same IDs, and Ajax-inserted fragments can collide with IDs already on the page.
+
+The `vident:install` generator wires this up for you. It writes `config/initializers/vident.rb`:
+
+```ruby
+# config/initializers/vident.rb
+Vident::StableId.strategy = if Rails.env.test?
+  Vident::StableId::RANDOM_FALLBACK
+else
+  Vident::StableId::STRICT
+end
+```
+
+and patches `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action do
+    Vident::StableId.set_current_sequence_generator(seed: request.fullpath)
+  end
+  after_action do
+    Vident::StableId.clear_current_sequence_generator
+  end
+end
+```
+
+**Why `request.fullpath`?** It includes the query string, so `/items/1?page=2` and `/items/1?page=3` get different seeds and different IDs — which is what you want, because they are different pages from a caching perspective. Requests to the same fullpath get identical IDs, so `ETag` matches work unchanged.
+
+#### Strategies
+
+- `Vident::StableId::STRICT` (production/development default). Raises `Vident::StableId::GeneratorNotSetError` if a component renders on a thread that has no generator set. Use this in any environment where missing the `before_action` is a bug — the loud failure tells you immediately.
+- `Vident::StableId::RANDOM_FALLBACK` (test default). Emits a random hex id when no generator is set. Tests, ViewComponent previews, and ad-hoc renders work without any extra wiring. You can still call `set_current_sequence_generator(seed:)` when you want to assert on deterministic IDs.
+
+You can point `strategy` at any callable of your own, e.g. to log every generation or route through a different generator entirely.
+
+#### Rendering outside a request
+
+Mailers, jobs, previews, and scripts run outside the controller callback cycle, so there's no `before_action` to seed the generator. Under `STRICT` they will raise. Two options:
+
+1. **Wrap the render in a scoped generator:**
+   ```ruby
+   Vident::StableId.with_sequence_generator(seed: "daily-digest-#{Date.today}") do
+     render_component(DigestComponent.new(...))
+   end
+   ```
+   The block sets the generator, yields, and restores whatever was on the thread before (including `nil`) in an `ensure`.
+2. **Run in a context where `RANDOM_FALLBACK` is fine.** If you don't care about id stability for that particular render (no caching, no snapshot comparison), either swap the strategy for that block or just accept random IDs.
+
+#### The collision bug in earlier versions
+
+Before 1.0.0 `set_current_sequence_generator` hard-coded the seed to `42`, so every request that called it got the same deterministic sequence. When two independent renders shipped in one browser session — e.g. a server-rendered page and an Ajax fragment loaded into it — both started from index 0 and produced colliding `id` attributes. This surfaced as duplicate IDs in the DOM, broken `label[for=...]` associations, and Stimulus controllers attaching to the wrong element. Upgrading and running `bin/rails generate vident:install` seeds from `request.fullpath` instead, so each render gets its own sequence space.
+
+### Claude Code skill
+
+Vident ships a [Claude Code](https://docs.claude.com/claude-code) skill at `skills/vident/SKILL.md` that teaches the model the gem's conventions: the `stimulus do` DSL, `child_element`, outlets (including `stimulus_outlet_host` self-registration), the `nil` / `Vident::StimulusNull` value rules, the per-request StableId setup, and the Ruby↔JS dispatch handshake. It covers the foot-guns ahead of time so the model doesn't repeat them.
+
+`bin/rails generate vident:install` copies the file into `.claude/skills/vident/SKILL.md` of the host app (skipped if already present). Claude Code picks it up automatically via skill discovery; no further wiring needed. If you want to update the skill later, delete the file and re-run the generator.
+
 
 ## Testing
 

data/lib/vident/view_component/base.rb

@@ -1,7 +1,7 @@
 module Vident
   module ViewComponent
     class Base < ::ViewComponent::Base
-      include ::Vident::Component
+      include Vident::Component
 
       class << self
         def cache_component_modified_time
@@ -92,6 +92,14 @@ module Vident
         to_data_attribute_string(**stimulus_value(...))
       end
 
+      def as_stimulus_params(...)
+        to_data_attribute_string(**stimulus_params(...))
+      end
+
+      def as_stimulus_param(...)
+        to_data_attribute_string(**stimulus_param(...))
+      end
+
       def as_stimulus_classes(...)
         to_data_attribute_string(**stimulus_classes(...))
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vident-view_component
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta2
+  version: 1.0.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
@@ -55,14 +55,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0.beta2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0.beta2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement