vident-phlex 1.0.0.beta2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4466b6e94b193580be755d18af0d75b075b31bc1a5cfb96911aa04302ca7604
-  data.tar.gz: '038b7d3c7fd7633372cde14d268a671067edf2299a13805269e4a934d89a5202'
+  metadata.gz: 1a941674bbc07885fbd2a26849332fc6e6957a22feb5162b9cee454746d8205c
+  data.tar.gz: '0912a7ad696343c5437056344b51822e4e9af4b2dbca92ea78c805b2e3039567'
 SHA512:
-  metadata.gz: b92de4dca48fff939f1fe933d913ccc7f84f734593fa81072251d904e4171f70901ae1a4e13c41c7cd4635305715e9b879dbac31329390b422a0ea166fc16d12
-  data.tar.gz: ceea7b4cabf7aa0e2711ce9048b3f531ba71513ad2e0591c4135ee26e25037a9755a9712e66b43707125cab56b0f85ab78a16055a8802f1774862766165ae620
+  metadata.gz: 3331181090bf6dc0edf13b515f71881e570b453c7655c991414a3ae1c49965cbaacb40597e5484fe1316ab298e8af4aa6051efd4a4f63c38f6d880200ed8273b
+  data.tar.gz: 85c1212c4e9ee24e021cf9192bbe78134723243da8a5e45d2163eba243abc180f10169a41133dc2a51078f9f289223442d3b1d2c4c6fc89b6471e16fce0aefee

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/phlex/html.rb

@@ -3,7 +3,7 @@
 module Vident
   module Phlex
     class HTML < ::Phlex::HTML
-      include ::Vident::Component
+      include Vident::Component
 
       STANDARD_ELEMENTS = [:a, :abbr, :address, :article, :aside, :b, :bdi, :bdo, :blockquote, :body, :button, :caption, :cite, :code, :colgroup, :data, :datalist, :dd, :del, :details, :dfn, :dialog, :div, :dl, :dt, :em, :fieldset, :figcaption, :figure, :footer, :form, :g, :h1, :h2, :h3, :h4, :h5, :h6, :head, :header, :hgroup, :html, :i, :iframe, :ins, :kbd, :label, :legend, :li, :main, :map, :mark, :menuitem, :meter, :nav, :noscript, :object, :ol, :optgroup, :option, :output, :p, :path, :picture, :pre, :progress, :q, :rp, :rt, :ruby, :s, :samp, :script, :section, :select, :slot, :small, :span, :strong, :style, :sub, :summary, :sup, :svg, :table, :tbody, :td, :template_tag, :textarea, :tfoot, :th, :thead, :time, :title, :tr, :u, :ul, :video, :wbr].freeze
       VOID_ELEMENTS = [:area, :br, :embed, :hr, :img, :input, :link, :meta, :param, :source, :track, :col].freeze
@@ -29,15 +29,11 @@ module Vident
       def root_element(**overrides, &block)
         tag_type = root_element_tag_type
         check_valid_html_tag!(tag_type)
-        # Evaluate before generating the outer tag options to ensure DSL methods are executed
+        # Evaluate block first so DSL methods run before outer tag options are computed.
         if block_given?
           content = capture(self, &block).html_safe
           options = resolve_root_element_attributes_before_render(overrides)
-          if content
-            send(tag_type, **options) { content }
-          else
-            send(tag_type, **options)
-          end
+          send(tag_type, **options) { content }
         else
           send(tag_type, **resolve_root_element_attributes_before_render(overrides))
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vident-phlex
 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: phlex
   requirement: !ruby/object:Gem::Requirement
@@ -131,7 +131,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="