vident 1.0.1 → 2.0.0

data/skills/vident/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Vident
 description: This skill should be used when writing or editing Rails view components in a project that depends on `vident`, `vident-view_component`, or `vident-phlex` — i.e. any class inheriting from `Vident::ViewComponent::Base` or `Vident::Phlex::HTML`, any paired `*_component_controller.js` Stimulus file next to such a component, or the `stimulus_*` props / `stimulus do ... end` DSL / `child_element` / `root_element` / `class_list_for_stimulus_classes` / `Vident::StimulusNull` / `Vident::StableId` APIs. It also covers the `bin/rails generate vident:install` initializer and the per-request ID seeding it installs on `ApplicationController`.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Vident
@@ -10,6 +10,8 @@ Vident is a thin layer on top of ViewComponent / Phlex that gives a component th
 
 A Vident component is always a class with props, a single `root_element`, and (optionally) a `stimulus do ... end` block that declares the controllers, actions, targets, values, classes and outlets its paired JavaScript file needs.
 
+> **Going deeper.** This file is the everyday reference. For end-to-end walkthroughs (dashboard, forms, slot-based parent/child wiring, ERB helper comparisons), read [`examples.md`](examples.md). For the exhaustive public-API spec (every signature, raise-condition, and argument shape), read [`api-reference.md`](api-reference.md).
+
 ---
 
 ## 1. Stimulus → Vident mapping
@@ -52,13 +54,64 @@ class Foo::BarComponent < Vident::ViewComponent::Base
 end
 ```
 
+**Subclass re-enables the controller.** `no_stimulus_controller` is inherited by subclasses. A subclass that has its own paired JS controller calls `has_stimulus_controller` to flip the flag back on:
+
+```ruby
+class ApplicationComponent < Vident::Phlex::HTML
+  no_stimulus_controller                          # shell — no paired JS
+end
+
+class DropdownComponent < ApplicationComponent
+  has_stimulus_controller                         # emits data-controller="dropdown-component"
+  stimulus { actions :toggle }
+end
+```
+
 Cross-controller references elsewhere (actions/targets/values/classes/outlets) use the `"path/to/controller"` **string** form — Vident stimulizes it for you.
 
 ### 1.2 Actions
 
 Stimulus descriptor: `event->controller#method`, with optional modifiers (`:once`, `:prevent`, `keydown.ctrl+a`, `@window`, etc.). Stimulus encodes them as space-separated tokens in `data-action="..."`.
 
-Vident `actions` DSL entries (all of these work inside `stimulus do ... end`):
+**Primary form — the fluent `action(...)` builder.** Singular `action` returns a builder that reads left-to-right:
+
+```ruby
+stimulus do
+  action :click                                        # implied#click
+  action(:submit).on(:click)                           # click->implied#submit
+  action(:save).on(:click).modifier(:prevent, :stop)   # click:prevent:stop->implied#save
+  action(:escape).on(:keydown).keyboard("esc").window  # keydown.esc@window->implied#escape
+  action(:delete).when { admin? }                      # conditional — `.when` takes a predicate proc
+end
+```
+
+Chain methods: `.on(event)`, `.call_method(name)` (override), `.modifier(*opts)`, `.keyboard(str)`, `.window`, `.on_controller(alias_sym)`, `.when { predicate }`. Each returns `self`.
+
+**Kwargs shorthand.** Equivalent to the fluent chain — pick whichever reads better:
+
+```ruby
+action :save, on: :click, modifier: [:prevent, :stop]
+action :escape, on: :keydown, keyboard: "esc", window: true
+action :delete, when: -> { admin? }
+action :save, on: :click, call_method: :handle_save
+```
+
+Recognised keys: `on:`, `call_method:`, `modifier:` (Symbol or Array), `keyboard:`, `window:`, `on_controller:`, `when:`. Anything else raises `ArgumentError`.
+
+**Controller aliases.** Declare a short name for a cross-controller path with `controller "path", as: :alias`, then reference it from action entries:
+
+```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
+```
+
+The alias resolves at render time — unknown aliases raise `Vident::DeclarationError`. Also works for runtime inputs: `stimulus_actions: [{method: :save, controller: :admin}]` resolves against the same declared map.
+
+**Legacy plural form.** Still accepted for compat — `actions(*entries)` accepts:
 
 | Ruby                                        | Emits                                              |
 | ------------------------------------------- | -------------------------------------------------- |
@@ -67,10 +120,9 @@ Vident `actions` DSL entries (all of these work inside `stimulus do ... end`):
 | `[:click, "other/ctrl", :my_thing]`         | `click->other--ctrl#myThing`                       |
 | `"click->other--ctrl#myThing"`              | pass-through, parsed into its parts                |
 | `{event: :click, method: :submit, options: [:once, :prevent]}` | `click:once:prevent->implied#submit` |
-| `Vident::StimulusAction::Descriptor.new(event: :click, method: :submit, options: [:once])` | same — typed data object, Hash is sugar |
 | `-> { [:click, :my_thing] if @editable }`   | proc, evaluated in component instance; `nil`/`false` returns drop the entry |
 
-**Modifiers via the Hash / Descriptor form.** Accepted keys on the hash (and the `Descriptor` data class):
+**Modifiers via the Hash form.** Accepted keys:
 
 | Key          | Type              | Emits                                    |
 | ------------ | ----------------- | ---------------------------------------- |
@@ -81,7 +133,7 @@ Vident `actions` DSL entries (all of these work inside `stimulus do ... end`):
 | `keyboard:`  | String like `"ctrl+a"` | `.ctrl+a` suffix on event filter    |
 | `window:`    | Boolean           | `@window` suffix on event                |
 
-Unknown option symbols raise `ArgumentError`. Use the Hash form for the common case; use `Vident::StimulusAction::Descriptor.new(...)` when you want a typed, passable value object (reusable across components, shared helpers).
+Unknown option symbols raise `ArgumentError`. The Hash descriptor is parsed directly into `Vident::Stimulus::Action` — there is no separate `Descriptor` class in V2.
 
 ```ruby
 actions({event: :keydown, method: :on_escape, keyboard: "esc", options: [:prevent]})
@@ -245,7 +297,7 @@ stimulus_outlets: [
 ]
 ```
 
-**(c) Child self-registers on a host via `stimulus_outlet_host:`.** Every Vident component inherits a `stimulus_outlet_host` prop. Passing a parent component at render time calls `host.add_stimulus_outlets(self)` in `prepare_stimulus_collections`, so the host's root gets the outlet attribute without enumerating children in its DSL:
+**(c) Child self-registers on a host via `stimulus_outlet_host:`.** Every Vident component inherits a `stimulus_outlet_host` prop. Passing a parent component at render time calls `host.add_stimulus_outlets(self)` in `after_initialize` (via `Vident::Capabilities::StimulusDraft`), so the host's root gets the outlet attribute without enumerating children in its DSL:
 
 ```ruby
 render PageComponent.new do |page|
@@ -327,7 +379,7 @@ prop :count, Integer, default: 0                      # with default
 prop :url, _Nilable(String)                           # optional / nilable
 prop :variant, _Union(:primary, :secondary), default: :primary
 prop :items, _Array(Hash), default: -> { [] }         # callable defaults must be lambdas
-prop :open, _Boolean, default: false                  # generates an `open?` predicate
+prop :open, _Boolean, default: false                  # pass `predicate: :public` to also get an `open?` method
 ```
 
 Props become `@ivar`s at init time. To also expose a reader method, declare the prop with `reader: :public`.
@@ -341,9 +393,9 @@ From `Vident::Component`:
 - `classes` — `String | Array(String)`. Appended to the root element's `class=`.
 - `html_options` — `Hash`. Merged onto the root element; highest precedence.
 
-From `Vident::StimulusComponent`:
+From `Vident::Component`:
 
-- `stimulus_controllers` — `Array(String | Symbol | StimulusController | Collection)`. Defaults to `[default_controller_path]` unless `no_stimulus_controller` is declared.
+- `stimulus_controllers` — `Array(String | Symbol | Vident::Stimulus::Controller)`. Defaults to `[default_controller_path]` unless `no_stimulus_controller` is declared.
 - `stimulus_actions`, `stimulus_targets`, `stimulus_values`, `stimulus_classes`, `stimulus_outlets` — Array / Hash props matching the shapes described in section 1.
 - `stimulus_outlet_host` — optional `Vident::Component`; activates child→host outlet self-registration.
 
@@ -411,15 +463,50 @@ When handwriting HTML inside ERB instead of using `child_element`, emit just the
 <div <%= component.as_stimulus_values(%i[count label]) %>></div>
 ```
 
-Plural (`as_stimulus_targets`, `as_stimulus_actions`, `as_stimulus_values`, `as_stimulus_classes`, `as_stimulus_outlets`, `as_stimulus_controllers`) and singular variants exist for every attribute kind. These helpers are defined on `Vident::ViewComponent::Base`; for Phlex, use `child_element` or compose directly.
+Plural (`as_stimulus_targets`, `as_stimulus_actions`, `as_stimulus_values`, `as_stimulus_params`, `as_stimulus_classes`, `as_stimulus_outlets`, `as_stimulus_controllers`) and singular variants (`as_stimulus_target`, `as_stimulus_action`, `as_stimulus_value`, `as_stimulus_param`, `as_stimulus_class`, `as_stimulus_outlet`, `as_stimulus_controller`) exist for every attribute kind. These helpers are defined on `Vident::ViewComponent::Base`; for Phlex, use `child_element` or compose directly.
+
+### Class-level Stimulus builders (no instance needed)
+
+When you need a Stimulus value without a component instance (Turbo-Stream partials, JSON endpoints, test selectors), call the builders on the class:
+
+```ruby
+ButtonComponent.stimulus_target(:submit)            # Vident::Stimulus::Target
+ButtonComponent.stimulus_action(:click, :handle)    # click->implied#handle
+ButtonComponent.stimulus_value(:count, 0)
+ButtonComponent.stimulus_param(:item_id, 42)
+ButtonComponent.stimulus_class(:loading, "opacity-50")
+ButtonComponent.stimulus_outlet(:modal, ".js-modal") # selector required
+ButtonComponent.stimulus_controller                  # the implied controller
+```
+
+Returns a `Vident::Stimulus::*` value object with the same `#to_h` / `#to_data_pair` as the instance equivalents — splat `.to_h` into a tag's HTML options. Two restrictions at class level: **outlets require an explicit selector** (no `component_id` to auto-scope), and **cross-controller forms are rejected** (call `Vident::Stimulus::Target.parse(...)` directly for those).
+
+### Rendering outside `root_element(...)`
+
+For components that build their root tag via a third-party helper (e.g. `inline_svg_tag`), two instance methods return what `root_element(...)` would emit:
+
+- `root_element_class_list(extra_classes = nil)` → `String` with the full class cascade (`component_name`, `root_element_classes`, `@classes` prop, `html_options[:class]`, extras) plus Tailwind-merging.
+- `root_element_data_attributes` → `Hash` (Symbol keys) with the full `data-*` set (controller, action, target, value, param, class, outlet) from the sealed Plan.
+
+```ruby
+def view_template
+  svg("data-src" => helpers.image_path(file_name),
+      id: @id,
+      class: root_element_class_list,
+      data: root_element_data_attributes) {}
+end
+```
 
 ---
 
 ## 3. `stimulus do ... end` block
 
-Opens a `Vident::StimulusBuilder` instance scoped to the class. It supports `actions`, `targets`, `values`, `values_from_props`, `classes`, `outlets`. Multiple `stimulus do` blocks on the same class are merged; a subclass's block is merged with its superclass's (subclass entries appended, values/classes/outlets merged by key, subclass wins on conflicts).
+Opens a `Vident::Internals::DSL` instance scoped to the class. It supports `actions`, `targets`, `values`, `values_from_props`, `classes`, `outlets`. Multiple `stimulus do` blocks on the same class are merged; a subclass's block is merged with its superclass's (subclass entries appended, values/classes/outlets merged by key, subclass wins on conflicts).
+
+Procs passed anywhere in the DSL are evaluated via `instance_exec` on the **component instance** at render time (Phlex `before_template` / ViewComponent `before_render`), so they see `@ivars`, public/private instance methods, and the view context.
 
-Procs passed anywhere in the DSL are evaluated via `instance_exec` on the **component instance** at render time, so they see `@ivars` and public/private instance methods.
+- **Phlex**: `helpers` is deprecated in phlex-rails. Opt in per Rails helper via `include Phlex::Rails::Helpers::NumberWithPrecision` (etc.), or use the `phlex_helpers :number_with_precision, :t, :l` class macro on `Vident::Phlex::HTML` which expands to the matching includes. Then call the helper bare inside the proc — `number_with_precision(@amount, precision: 2)`. See [phlex.fun/rails/helpers](https://www.phlex.fun/rails/helpers) for the full adapter list.
+- **ViewComponent**: `helpers.<method>` and `view_context.<method>` both work.
 
 ---
 
@@ -490,8 +577,30 @@ Vident::StableId.with_sequence_generator(seed: "some-unique-key") { render ... }
 
 - **`after_component_initialize`** — override in your component; runs after props are assigned and Vident has prepared its stimulus collections. Don't override `after_initialize` unless you `super` — Literal calls it to wire everything up.
 - **`component_name` / `stimulus_identifier`** — class method and instance method; the kebab-case/`--`-separated identifier. Used for outlet auto-selectors, scoped event names, and the default class on the root.
-- **Caching** (`include Vident::Caching` + `with_cache_key :attr1, :attr2`) — declares attributes that feed `cache_key`. Combined with a template mtime so edits bust the cache. `depends_on(OtherComponent, …)` chains subcomponent mtimes into the key.
-- **`clone(overrides = {})`** — returns a new instance with merged props.
+- **Caching** (`include Vident::Caching` + `with_cache_key :attr1, :attr2`) — declares attributes that feed `cache_key`. Combined with a template mtime so edits bust the cache. `depends_on(OtherComponent, …)` chains subcomponent mtimes into the key. Two separable concerns:
+  - **Computing the key** — `component.cache_key` is always available once `with_cache_key` is declared. Use it for etags, conditional rendering, explicit `Rails.cache.fetch(key) { ... }` at the call site, or any other place you need a content-addressed identifier.
+  - **Fragment-caching the render** — `cache_component(*extra_keys, &block)` wraps the block with Rails.cache using the Vident-computed key. Works on both adapters. For Phlex, call it inside `view_template` (delegates to Phlex's `cache(...)`); for ViewComponent, call inside `call` (uses `Rails.cache.fetch` + `capture`). Sidecar ERB templates can just write `<% cache cache_key do %> ... <% end %>` directly.
+
+    ```ruby
+    # Phlex
+    def view_template
+      cache_component do
+        root_element { ... }
+      end
+    end
+
+    # ViewComponent (def call form)
+    def call
+      cache_component { root_element { ... } }
+    end
+
+    # ViewComponent (sidecar ERB) — use the Rails helper with component.cache_key
+    # <% cache cache_key do %>
+    #   <%= root_element do %>...<% end %>
+    # <% end %>
+    ```
+    Calling `cache_component` on a non-cacheable component (no `with_cache_key`) raises `Vident::ConfigurationError`.
+- **`with(overrides = {})`** — returns a new instance with merged props. (`clone` is a backward-compat alias.)
 - **Phlex tag safety** — `Vident::Phlex::HTML` validates every `child_element` tag name against a whitelist; passing an unknown tag raises.
 
 ---
@@ -553,6 +662,8 @@ Inside `<name>OutletConnected`, **do not iterate `this.<name>Outlets`**. Stimulu
 
 ## 8. Recipes
 
+One-liners per task. For worked end-to-end versions (dashboard with outlets, slot trigger, ERB variants) see [`examples.md`](examples.md).
+
 **Click handler on the root** — `stimulus do; actions [:click, :select]; end` + `select(event) {…}` in JS.
 
 **Click handler on a child button** — `card.child_element(:button, stimulus_action: [:click, :promote]) { "Promote" }`.
@@ -616,13 +727,14 @@ end
 
 ## 9. Key source files
 
-- `lib/vident/stimulus_builder.rb` — DSL evaluator.
-- `lib/vident/stimulus_attributes.rb` — parser for every `stimulus_*` input shape + `as_stimulus_*` helpers' backing.
-- `lib/vident/stimulus_{action,target,value,outlet,class,controller}.rb` — value objects; read `parse_arguments` to learn the argument shapes.
-- `lib/vident/child_element_helper.rb` — `child_element` kwargs and validation.
-- `lib/vident/component_attribute_resolver.rb` — how DSL, props, and `root_element_attributes` compose at render time.
-- `lib/vident/component_class_lists.rb` — `class_list_for_stimulus_classes` / `render_classes`.
+For the exhaustive public-API listing (every method signature, argument shape, and raise-condition, verified against current code), see [`api-reference.md`](api-reference.md). The files below are useful when you need to read the implementation itself.
+
+- `lib/vident/component.rb` — composition root; includes all capabilities in dependency order.
 - `lib/vident/stable_id.rb` — the StableId strategy system.
 - `lib/vident/stimulus_null.rb` — the StimulusNull sentinel.
-- `lib/vident/view_component/base.rb` / `lib/vident/phlex/html.rb` — framework-specific `root_element` / `child_element` backings and (ViewComponent only) `as_stimulus_*` helpers.
+- `lib/vident/stimulus/` — value classes: `Action`, `Target`, `Controller`, `Outlet`, `Value`, `Param`, `ClassMap`, `Collection`, `Null`, `Naming`.
+- `lib/vident/capabilities/` — focused capability mixins: `Tailwind`, `Caching`, `Declarable`, `Identifiable`, `StimulusDeclaring`, `StimulusParsing`, `StimulusMutation`, `StimulusDraft`, `StimulusDataEmitting`, `ClassListBuilding`, `RootElementRendering`, `ChildElementRendering`, `Inspectable`.
+- `lib/vident/internals/` — internal DSL/resolver plumbing: `Registry`, `Declaration`, `Declarations`, `DSL`, `Draft`, `Plan`, `Resolver`, `AttributeWriter`, `ClassListBuilder`, `ActionBuilder`, `TargetBuilder`.
+- `lib/vident/phlex/html.rb` — Phlex adapter (`root_element`, `child_element`, tag whitelist).
+- `lib/vident/view_component/base.rb` — ViewComponent adapter (`root_element`, `child_element`, `as_stimulus_*` helpers).
 - `test/dummy/app/components/dashboard/` — canonical multi-component example (outlets, scoped events, `StimulusNull`, dynamic classes, `values_from_props`, `class_list_for_stimulus_classes`, full JS side).