---
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.2.0
---
# Vident
Vident is a thin layer on top of ViewComponent / Phlex that gives a component three things Stimulus alone does not: **typed props** (via Literal), a **declarative Ruby DSL** that compiles down to the `data-*` attributes Stimulus expects, and **first-class outlets** including a host/child self-registration pattern. Every component also comes with a **stable, deterministic element id** system so HTML output is etag-stable across requests.
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
For each Stimulus primitive: first the Stimulus contract, then the Ruby declaration that produces it, then the HTML it emits.
Identifier conventions used throughout this doc:
- A component class `Foo::BarComponent` has **stimulus identifier** `foo--bar-component` (namespace separators become `--`, CamelCase becomes kebab-case).
- The **implied controller** inside a component's DSL is that component's own identifier. Every DSL entry binds to it unless explicitly redirected.
- A Ruby symbol name is `.camelize(:lower)`-d before being emitted (so `:my_thing` → `myThing` in JS).
- A Ruby `"path/to/thing"` string is `stimulize_path`-d before being emitted (so `"admin/users"` → `admin--users`).
### 1.1 Controllers / identifiers
Stimulus: `data-controller="foo bar"` attaches one instance each of `foo` and `bar` to the element and its subtree.
Vident: every component attaches *itself* as a controller on its root element by default. Extra controllers come from the `stimulus_controllers:` prop or `root_element_attributes`.
```ruby
class Admin::UserCardComponent < Vident::Phlex::HTML
# No DSL needed for the implied controller — it's automatic.
end
```
```html
…
```
To attach extra controllers, or to opt out:
```ruby
class Foo::BarComponent < Vident::ViewComponent::Base
no_stimulus_controller # don't emit the implied `data-controller`
# or keep the implied one AND add more:
def root_element_attributes
{ stimulus_controllers: ["other/widget", :tooltip] }
end
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) take the controller in one of two forms: a `"path/to/controller"` **string** (Vident stimulizes it for you), or the **component class/instance** itself in that slot — `OtherComponent` in place of `"other_component"`. The component form is refactor-safe: rename the class and the reference follows, with no identifier string to drift.
### 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="..."`.
**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 |
| ------------------------------------------- | -------------------------------------------------- |
| `:my_thing` | `implied#myThing` (no explicit event) |
| `[:click, :my_thing]` | `click->implied#myThing` |
| `[:click, "other/ctrl", :my_thing]` | `click->other--ctrl#myThing` |
| `[:click, OtherCtrl, :my_thing]` | same, via the component class (refactor-safe) |
| `"click->other--ctrl#myThing"` | pass-through, parsed into its parts |
| `{event: :click, method: :submit, options: [:once, :prevent]}` | `click:once:prevent->implied#submit` |
| `-> { [:click, :my_thing] if @editable }` | proc, evaluated in component instance; `nil`/`false` returns drop the entry |
**Modifiers via the Hash form.** Accepted keys:
| Key | Type | Emits |
| ------------ | ----------------- | ---------------------------------------- |
| `event:` | Symbol / String | prepends `event->` |
| `method:` | Symbol / String | the `#method` part (required) |
| `controller:`| String path | routes to another controller |
| `options:` | `Array` from `:once`, `:prevent`, `:stop`, `:passive`, `:"!passive"`, `:capture`, `:self` | `:once:prevent…` suffix on event |
| `keyboard:` | String like `"ctrl+a"` | `.ctrl+a` suffix on event filter |
| `window:` | Boolean | `@window` suffix on event |
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]})
# => keydown.esc:prevent->implied#onEscape
actions({event: :click, method: :handle, controller: "dialog/open", window: true})
# => click@window->dialog--open#handle
```
```ruby
stimulus do
actions :toggle # implied#toggle
actions [:click, :submit], [:input, :on_input] # multiple entries
actions [:click, "dialog/open", :show] # cross-controller
end
```
Emits (combined on one element):
```html
data-action="implied#toggle click->implied#submit input->implied#onInput click->dialog--open#show"
```
The same shapes are accepted by the `stimulus_actions:` prop, `child_element(stimulus_action: …)`, and the `as_stimulus_action(s)` ERB helpers.
**Scoped events on window.** To listen for an event *dispatched by another component*, reference the dispatcher's class:
```ruby
actions -> { [OtherComponent.stimulus_scoped_event_on_window(:data_ready), :handle_ready] }
```
`OtherComponent.stimulus_scoped_event_on_window(:data_ready)` returns the symbol `:"other-component:dataReady@window"`. The action parser treats the whole symbol as the event name, so this yields `data-action="other-component:dataReady@window->implied#handleReady"`. On the dispatcher's JS side, `this.dispatch("dataReady", { target: window })` produces exactly that event type because Stimulus prefixes dispatches with the dispatcher's identifier. **Always call the class method on the dispatcher, never on the listener.**
There is also `stimulus_scoped_event(:name)` (no `@window`) when the event bubbles naturally and doesn't need a global listener.
### 1.3 Targets
Stimulus: `data--target="name"` on an element exposes `this.nameTarget` / `this.nameTargets` / `this.hasNameTarget` in the JS controller. CamelCase names in JS / kebab-case in HTML.
Vident `targets` DSL:
| Ruby | Emits |
| ------------------------------ | -------------------------------------------------- |
| `:button` | `data-implied-target="button"` on the root |
| `["other/ctrl", :row]` | `data-other--ctrl-target="row"` on the root |
| `[OtherCtrl, :row]` | same, via the component class (refactor-safe) |
| Same shapes on `child_element` | `data-implied-target="..."` on the child |
```ruby
stimulus do
targets :body, :footer
end
# and in the view:
card.child_element(:button, stimulus_target: :promote_button) { "Promote" }
# =>
```
A proc form `-> { cond ? :foo : nil }` is supported; returning `nil` drops the entry.
### 1.4 Values
Stimulus: `data---value="..."` with types `String | Number | Boolean | Object | Array`. In JS: `this.nameValue` / `this.nameValue=` / `this.hasNameValue`. Name is camelCase in JS, kebab-case in HTML.
Vident has three entry points, all composable:
**(a) `values(key: value, …)` in the DSL.** Static values, or procs evaluated in the component instance at render time:
```ruby
stimulus do
values initial_open: false,
status_label: -> { @status.to_s.capitalize }
end
```
**(b) `values_from_props :a, :b, …` in the DSL.** Mirrors a typed prop straight through — the emitted value is the prop's current `@ivar`.
```ruby
prop :release_id, Integer
stimulus do
values_from_props :release_id
end
# => data-implied-release-id-value="42"
```
**(c) `stimulus_values:` prop / `child_element(stimulus_value(s): …)`.** Array form required for cross-controller:
```ruby
stimulus_values: [
[:foo, "bar"], # implied-foo-value="bar"
["other/ctrl", :baz, 42], # other--ctrl-baz-value="42"
[OtherCtrl, :baz, 42], # same, via the component class
]
```
Serialization: Booleans/Numbers stringify directly; `Array` / `Hash` serialize as JSON. `String` stringifies.
**The nil rule.** A `nil` resolved value (from a proc or static) **omits the data attribute entirely**, letting Stimulus use its per-type default. Never rely on `nil` becoming `""`. If you need explicit JSON `null` on the JS side for an `Object`- or `Array`-typed value, return the `Vident::StimulusNull` sentinel, which serializes to the literal string `"null"` that Stimulus's Object parser feeds to `JSON.parse`:
```ruby
values release: -> { @selected ? @selected.to_h : Vident::StimulusNull }
```
Use `StimulusNull` *only* for Object/Array values — for `String`/`Number`/`Boolean` it reads as garbage ("null" / NaN / truthy).
### 1.5 Value-change callbacks
Stimulus: defining `fooValueChanged(newValue, previousValue)` on a controller fires once on connect and on every subsequent change to `this.fooValue`.
Vident: **pure JS, no Ruby-side hook.** Vident only emits the attribute — the callback is written in the paired `_controller.js`. See section 7.
### 1.6 Classes
Stimulus: `data---class="foo bar"` exposes `this.nameClass` (first token) / `this.nameClasses` (array) in the controller. Classes are applied manually via `classList` in JS.
Vident `classes` DSL:
```ruby
stimulus do
classes loading: "opacity-50 cursor-wait", # static
status: -> { # proc
case @status
when :deployed then "border-green-500 bg-green-50"
when :failed then "border-red-500 bg-red-50"
else "border-yellow-400 bg-yellow-50"
end
}
end
```
Emits:
```html
data-implied-loading-class="opacity-50 cursor-wait"
data-implied-status-class="border-green-500 bg-green-50"
```
These only tell the JS controller *which* classes to toggle; they do **not** apply them to the first render. For SSR initial state, inline the resolved value into `class=` via `class_list_for_stimulus_classes(:status, :loading)` (see section 4).
### 1.7 Outlets
Stimulus: `data---outlet=""` attaches matching controller instances as `this.nameOutlet` / `this.nameOutlets` / `this.nameOutletElement(s)` / `this.hasNameOutlet`. The `` is the kebab-case identifier of the *child* controller — Stimulus enforces this; it is not just a free label.
Argument vocabulary (same as Action/Target/Value/etc.): `Symbol` and bare `String` always denote a controller (path or identifier); a verbatim CSS selector must be wrapped with `Vident::Selector(...)`. A bare `".modal"` is rejected.
Vident has three forms.
**(a) DSL on the root:**
```ruby
stimulus do
outlets modal: nil # auto-selector: [data-controller~=modal]
outlets user_status: Vident::Selector(".online-user")
outlets({"admin--users" => nil}) # positional-hash, namespaced child id
outlets({"admin--users" => Vident::Selector(".admin-user")})
end
```
The kwarg/Hash key is the **child controller identifier**. Use the singular `outlet` form for cross-controller cases:
```ruby
outlet "some/parent-ctrl", :child # auto-selector
outlet "some/parent-ctrl", :child, Vident::Selector(".x") # verbatim
```
**(b) `stimulus_outlets:` prop / `root_element_attributes` / `child_element(stimulus_outlet(s): …)`:**
```ruby
stimulus_outlets: [
:user_status, # auto-selector
[:modal, Vident::Selector(".modal")], # explicit selector
["admin/users", :row, Vident::Selector(".user-row")], # cross-controller, explicit
other_component_instance, # # [data-controller~=]
]
```
**(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|
@releases.each do |r|
render ReleaseCardComponent.new(**r, stimulus_outlet_host: page)
end
end
```
The host's JS still declares the outlet name in `static outlets = ["release-card-component"]`.
Emits on host root (example):
```html
data-page-component-release-card-component-outlet="#page-123 [data-controller~=release-card-component]"
```
### 1.8 Lifecycle callbacks
Stimulus: `initialize()`, `connect()`, `disconnect()`, `TargetConnected(el)`, `TargetDisconnected(el)`, `OutletConnected(ctrl, el)`, `OutletDisconnected(ctrl, el)`.
Vident: **pure JS, no Ruby-side hook.** Write them in the paired `_controller.js`. Vident's `after_component_initialize` is a Ruby-side post-props-assigned hook on the component — unrelated to the Stimulus lifecycle.
### 1.9 Action params
Stimulus: `data---param="value"` lives on an element. Any action handler whose event fires on or bubbles through that element reads the values as `event.params.` (auto-typecast to Number/String/Object/Boolean).
Vident has three entry points, all mirroring `values`:
**(a) `params(key: value, …)` in the DSL.** Static values or procs evaluated in the component instance:
```ruby
stimulus do
actions [:click, :promote]
params release_id: -> { @release_id }, kind: "promote"
end
# => data-implied-release-id-param="42" data-implied-kind-param="promote"
```
**(b) `stimulus_params:` prop / `child_element(stimulus_params: …)`.** The common "one button, one action, params for that action" case lives here — co-located with the `stimulus_action:` it informs:
```ruby
card.child_element(:button,
stimulus_action: [:click, :promote],
stimulus_params: { release_id: @release_id, kind: "promote" })
```
**(c) Array form on the prop for cross-controller:**
```ruby
stimulus_params: [
[:release_id, 42], # implied-release-id-param="42"
["other/ctrl", :scope, "full"], # other--ctrl-scope-param="full"
]
```
**Element-scoped, not action-scoped.** In Stimulus, params live on the element, not on an individual action. Multiple actions on the same element share the same params. Vident's DSL matches this: `params` is a sibling of `actions`, not nested inside it.
Inline helper (ERB): `as_stimulus_param(:release_id, 42)` / `as_stimulus_params({release_id: 42})`.
---
## 2. Component scaffolding
The fastest path is the bundled generator, which writes the component, its Stimulus controller sidecar, and a unit test in one go:
```bash
bin/rails generate vident:component Dashboard::TaskCard
# or, when you want to be explicit:
bin/rails generate vident:phlex:component Dashboard::TaskCard
bin/rails generate vident:view_component:component Dashboard::TaskCard
```
The umbrella `vident:component` dispatcher picks the engine when only one is in the Gemfile; pass `--engine=phlex` or `--engine=view_component` if both are. Useful flags: `--skip-stimulus`, `--skip-controller`, `--skip-test`, `--typescript` / `-t`, `--parent=ClassName`. A trailing `Component` in the input is stripped.
Generated components inherit from `ApplicationPhlexComponent` or `ApplicationViewComponent` (created by `vident:install`). If you're writing a component by hand, pick the right base class directly:
- **ViewComponent:** `class Foo::BarComponent < Vident::ViewComponent::Base`
- **Phlex:** `class Foo::BarComponent < Vident::Phlex::HTML`
Both include `Vident::Component`, which brings in the Stimulus DSL, class-list builder, caching, and child-element helper.
### Props
Defined with the Literal DSL:
```ruby
prop :title, String # required
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 # 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`.
### Built-in props every component inherits
From `Vident::Component`:
- `element_tag` — `Symbol`, root tag type, default `:div`.
- `id` — `String?`. Auto-generated via `StableId` if omitted. The generated form is `-`.
- `classes` — `String | Array(String)`. Appended to the root element's `class=`.
- `html_options` — `Hash`. Merged onto the root element; highest precedence.
From `Vident::Component`:
- `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.
### `root_element` and `root_element_attributes`
Every component renders **exactly one** root element via `root_element`. Override `root_element_attributes` (returns a Hash) to set the tag, add HTML options, or push stimulus attributes declaratively:
```ruby
private
def root_element_attributes
{
element_tag: @url ? :a : :button, # default :div
html_options: { href: @url }.compact,
# stimulus_actions:, stimulus_targets:, stimulus_values:, stimulus_classes:,
# stimulus_controllers:, stimulus_outlets: — all accepted here.
}
end
```
`root_element_attributes` attributes have **higher precedence** than `stimulus do ... end` DSL entries, so a hardcoded `html_options[:class]` wins over `classes:` passed at render.
Phlex template:
```ruby
def view_template
root_element(class: "space-y-4") do |component|
h2 { @title }
component.child_element(:button, stimulus_action: [:click, :promote]) { "Promote" }
end
end
```
ViewComponent template (`.html.erb`):
```erb
<%= root_element(class: "space-y-4") do |component| %>