vident 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 174865fed5f1a8edc71ef641af56b0656c97ab66dfe3dcc1c7b4eea996a7e31d
-  data.tar.gz: b581f504c154b4a732702f8cddbe21d020dff12450a11b3880f0f11b13236c4e
+  metadata.gz: ad2b06ce20d99e816db5362f70a9ef4e068c9f6452d629253eb2283efc7e4b7e
+  data.tar.gz: 5d91a89eef5349d1ba7922875cef900c696684d2a627a5c958a7f5ed5d237ba9
 SHA512:
-  metadata.gz: d3602b080034a184bcbb663602ff6d8fff95ef1cdbe855393b2d2d875f0d3485415237008818f4fa336da33c4587a7f57e52bcef6542d09a2f153f468bb1a7c9
-  data.tar.gz: f133d2034fbcbdf31429696469f7127a8d38f765e174f75857abd9c18f3f1e8da6156534514b84bdddbe436c590d2c927509bd29a2023fe6a53c6d034c81db96
+  metadata.gz: 19e30e85766415738689f4a746ade4c21fe4d649b83212f2f8cfeb829e93a4b7109d625ad46fb3391446afb9e7b6865a9542a78bac1be4f2cfca3644769b7902
+  data.tar.gz: f4f93452b54d1971ea135a39eb079f4a3e559b5057400154dbaf5998a2e22c072c70f6dd7cf786c14648de891ebeca2b959a5a9be670b7c8ea70a5249e91e207

data/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [3.0.0] - 2026-05-04
+
+A bare `String` now means the same thing across every Stimulus primitive — a controller path. The 2.x ambiguity where a `String` could variously mean controller path, outlet name, CSS selector, or fully-qualified action descriptor (depending on primitive and position) is gone, closing a class of silent-failure footguns. See `UPGRADING.md` "Upgrading to Vident 3.0" for symptom → fix on each breaking change.
+
+### Breaking
+
+- **Outlet: bare String is no longer a CSS selector** (#32). Wrap verbatim selectors in `Vident::Selector(...)`, or pass `nil` for auto-selector. Class-level `stimulus_outlet(name, selector)` and the `[Symbol, String]` / `[String, String]` array forms follow the same rule.
+- **Action: bare String is no longer a qualified descriptor.** Use structured args `:event, "ctrl", :method`, the Hash descriptor, or `Vident::Stimulus::Action.parse_descriptor(s)` for genuine wire strings.
+- **Target: bare String is no longer a target name.** Names must be Symbols. The cross-controller `[String, Symbol]` form is unchanged.
+
+### Added
+
+- `Vident::Stimulus::Selector` value class + `Vident::Selector(css)` (and `Vident::Stimulus.Selector(css)`) constructors for tagging verbatim CSS selectors at outlet sites (#32).
+- `Vident::Stimulus::Action.parse_descriptor(string)` — public escape hatch for parsing wire-format Stimulus action descriptors verbatim (formerly the private `parse_qualified_string`).
+- Component scaffold generators: `bin/rails g vident:phlex:component …` and `bin/rails g vident:view_component:component …` scaffold a component, sidecar Stimulus controller, and unit test, with `--skip-stimulus` / `--skip-controller` / `--skip-test` / `--typescript` / `--parent` flags.
+- `vident:component` umbrella generator dispatches to the right engine; requires `--engine=phlex` or `--engine=view_component` when both adapters are loaded.
+- `vident:install` now scaffolds `ApplicationPhlexComponent` / `ApplicationViewComponent` based on the installed adapter gem, mirroring `ApplicationRecord` / `ApplicationController`.
+
+### Changed
+
+- `bin/rails generate vident:install --force` overwrites an existing `.claude/skills/vident/SKILL.md` so upgrades can refresh it; without `--force` the existing file is preserved.
+
+
 ## [2.0.1] - 2026-04-24
 
 ### Fixed

data/README.md

@@ -1,10 +1,28 @@
-# Vident
+<p align="center">
+  <a href="https://vident-gem.diaconou.com">
+    <img src="https://vident-gem.diaconou.com/assets/img/vident-logo.png" alt="Vident" width="180">
+  </a>
+</p>
+
+<h1 align="center">Vident</h1>
+
+<p align="center">
+  <strong>Type-safe Rails components with first-class Stimulus, on Phlex or ViewComponent.</strong>
+  <br>
+  <a href="https://vident-gem.diaconou.com">Documentation</a>
+  &nbsp;·&nbsp;
+  <a href="https://vident-gem.diaconou.com/introduction/getting-started/">Getting started</a>
+  &nbsp;·&nbsp;
+  <a href="https://rubygems.org/gems/vident">RubyGems</a>
+</p>
 
 A powerful Ruby gem for building interactive, type-safe components in Rails applications with seamless [Stimulus.js](https://stimulus.hotwired.dev/) integration. 
 
 Vident supports both [ViewComponent](https://viewcomponent.org/) and [Phlex](https://www.phlex.fun/) rendering engines while providing a consistent API for creating 
 reusable UI components powered by [Stimulus.js](https://stimulus.hotwired.dev/).
 
+> **Full documentation lives at [vident-gem.diaconou.com](https://vident-gem.diaconou.com)** — including a live, clickable component demo on the home page.
+
 ## Table of Contents
 
 - [Introduction](#introduction)
@@ -62,7 +80,31 @@ 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.
+The `vident:install` generator writes `config/initializers/vident.rb`, wires per-request ID seeding into `ApplicationController`, generates `app/components/application_phlex_component.rb` and/or `application_view_component.rb` (one per engine gem in your Gemfile, mirroring `ApplicationRecord`), 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.
+
+### Scaffolding components
+
+Once `vident:install` has run, scaffold a component, its Stimulus controller sidecar, and a unit test in one go:
+
+```bash
+bin/rails generate vident:phlex:component Dashboard::TaskCard
+bin/rails generate vident:view_component:component Dashboard::TaskCard
+```
+
+There's also an umbrella `vident:component` dispatcher that picks the right engine when only one is in the Gemfile (pass `--engine=phlex` or `--engine=view_component` if both are):
+
+```bash
+bin/rails generate vident:component Dashboard::TaskCard
+```
+
+Useful flags:
+- `--skip-stimulus` — omit the `stimulus do` block and the JS controller sidecar.
+- `--skip-controller` — omit the JS sidecar but keep the `stimulus do` block (e.g. when sharing a controller).
+- `--skip-test` — skip the unit test.
+- `--typescript` / `-t` — emit a `.ts` controller instead of `.js`.
+- `--parent=ClassName` — override the default base class.
+
+A trailing `Component` in the input is stripped, so `g vident:component TaskCardComponent` and `g vident:component TaskCard` produce the same files.
 
 ## Quick Start
 
@@ -640,12 +682,16 @@ Parallel helpers exist for every attribute kind: `as_stimulus_controller(s)`, `a
 ```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"})
+    # kwarg form: key is the *child controller identifier*. nil = auto-selector
+    # (`#<host-id> [data-controller~=modal]`); wrap a verbatim CSS selector in
+    # Vident::Selector(...). Bare String values are rejected.
+    outlets modal: nil
+    outlets user_status: Vident::Selector(".online-user")
+
+    # positional-hash form: required when the child controller identifier contains "--"
+    # (e.g. cross-namespace) because Ruby kwarg keys can't carry dashes
+    outlets({"admin--users" => nil})
+    outlets({"admin--users" => Vident::Selector(".admin-users")})
   end
 end
 ```
@@ -654,14 +700,15 @@ 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
+  :user_status,                                       # symbol → auto-selector
+  [:modal, Vident::Selector(".modal")],               # [name, Selector] verbatim
+  ["admin/users", :row],                              # cross-controller, auto-selector
+  ["admin/users", :row, Vident::Selector(".x")],      # cross-controller, verbatim
+  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.
+**Auto-generated selectors.** Pass just a name (Symbol or String) and the selector becomes `#<host-id> [data-controller~=<name>]` — scoped to this component's element id so you target a specific instance rather than every matching controller on the page. Wrap a verbatim CSS selector in `Vident::Selector(...)` to opt out of auto-scoping. A bare String inside an outlet position is treated as a controller identifier, never as a CSS selector — that ambiguity used to silently produce broken outlets in v2 and is now rejected.
 
 **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:
 
@@ -671,7 +718,7 @@ render DashboardComponent.new do |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.
+The modal now appears on the dashboard's root element as `data-dashboard-component-modal-component-outlet="#<dashboard-id> [data-controller~=modal-component]"` 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.
 

data/lib/generators/vident/component/component_generator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Vident
+  module Generators
+    class ComponentGenerator < ::Rails::Generators::NamedBase
+      desc "Scaffold a Vident component. Dispatches to vident:phlex:component or vident:view_component:component based on which engine gem is loaded. Pass --engine to disambiguate when both are present."
+
+      class_option :engine, type: :string, default: nil,
+        desc: "Which engine to scaffold for: phlex or view_component"
+      class_option :skip_stimulus, type: :boolean, default: false
+      class_option :skip_controller, type: :boolean, default: false
+      class_option :skip_test, type: :boolean, default: false
+      class_option :typescript, type: :boolean, default: false, aliases: "-t"
+      class_option :parent, type: :string, default: nil
+
+      def dispatch
+        target = resolve_target_generator
+        invoke target, [name], forwarded_options
+      end
+
+      private
+
+      def resolve_target_generator
+        engine = options[:engine]
+        if engine.nil?
+          available = available_engines
+          if available.empty?
+            raise ::Thor::Error,
+              "No Vident engine gem detected. Add `vident-phlex` or `vident-view_component` to your Gemfile."
+          elsif available.size == 1
+            generator_for(available.first)
+          else
+            raise ::Thor::Error,
+              "Both vident-phlex and vident-view_component are loaded. Pass --engine=phlex or --engine=view_component."
+          end
+        else
+          unless %w[phlex view_component].include?(engine)
+            raise ::Thor::Error, "Unknown engine '#{engine}'. Use --engine=phlex or --engine=view_component."
+          end
+          generator_for(engine.to_sym)
+        end
+      end
+
+      def available_engines
+        engines = []
+        engines << :phlex if defined?(::Vident::Phlex::HTML)
+        engines << :view_component if defined?(::Vident::ViewComponent::Base)
+        engines
+      end
+
+      def generator_for(engine)
+        case engine
+        when :phlex then "vident:phlex:component"
+        when :view_component then "vident:view_component:component"
+        end
+      end
+
+      def forwarded_options
+        options.to_h.except("engine").transform_keys(&:to_s).reject { |_, v| v.nil? }
+      end
+    end
+  end
+end

data/lib/generators/vident/install/install_generator.rb

@@ -9,21 +9,29 @@ module Vident
 
       desc "Install Vident: writes a StableId strategy initializer, wires a per-request seed into ApplicationController, and copies the Vident Claude Code skill to .claude/skills/vident/."
 
-      # Path to the gem's ./skills directory, resolved relative to this file.
       SKILL_SOURCE = File.expand_path("../../../../skills/vident/SKILL.md", __dir__)
 
       def create_initializer
         template "vident.rb", "config/initializers/vident.rb"
       end
 
+      def create_application_components
+        write_application_component("application_phlex_component.rb") if defined?(::Vident::Phlex::HTML)
+        write_application_component("application_view_component.rb") if defined?(::Vident::ViewComponent::Base)
+      end
+
       def install_claude_skill
+        return unless File.exist?(SKILL_SOURCE)
         destination = ".claude/skills/vident/SKILL.md"
         absolute = File.expand_path(destination, destination_root)
-        if File.exist?(absolute)
+        # Preserve an existing skill file (user may have edited it);
+        # `--force` pulls the current SKILL from the installed gem over
+        # the top so upgrades can refresh it.
+        if File.exist?(absolute) && !options[:force]
           say_status :exist, destination, :blue
-        elsif File.exist?(SKILL_SOURCE)
+        else
           empty_directory(File.dirname(destination))
-          copy_file(SKILL_SOURCE, destination)
+          copy_file(SKILL_SOURCE, destination, force: true)
         end
       end
 
@@ -48,6 +56,21 @@ module Vident
 
         inject_into_class controller_path, "ApplicationController", "\n#{hook}"
       end
+
+      private
+
+      # Mirror the skill file's preserve-on-existing semantics: re-running
+      # the install generator should not clobber a base class the user has
+      # extended. `--force` opts back into overwriting.
+      def write_application_component(filename)
+        destination = "app/components/#{filename}"
+        absolute = File.expand_path(destination, destination_root)
+        if File.exist?(absolute) && !options[:force]
+          say_status :exist, destination, :blue
+        else
+          template "#{filename}.tt", destination
+        end
+      end
     end
   end
 end

data/lib/generators/vident/install/templates/application_phlex_component.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationPhlexComponent < Vident::Phlex::HTML
+  include Phlex::Rails::Helpers::Routes
+end

data/lib/generators/vident/install/templates/application_view_component.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationViewComponent < Vident::ViewComponent::Base
+end

data/lib/tasks/website.rake

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+WEBSITE_DIR = File.expand_path("../../website", __dir__)
+
+namespace :website do
+  desc "Render demo components and write HTML/source fragments into the docs site"
+  task :demos do
+    require File.expand_path("../../test/dummy/config/environment", __dir__)
+    require "fileutils"
+
+    out = File.join(WEBSITE_DIR, "_includes", "demos")
+    FileUtils.mkdir_p(out)
+
+    # The homepage demo is the same Phlex component the dummy app renders at
+    # /components/tasks. We pre-render it here so the static site can ship
+    # byte-identical HTML, paired with the same Stimulus controller registered
+    # in `website/assets/js/demo.js`.
+    demos = [
+      {
+        slug: "task_card",
+        component: ::Tasks::TaskCardComponent,
+        source_path: "test/dummy/app/components/tasks/task_card_component.rb",
+        args: [
+          {task_id: 1, title: "Write the launch announcement", due: "Today", list: :today, status: :todo},
+          {task_id: 2, title: "Migrate the legacy importer", due: "Wed", list: :this_week, status: :done},
+          {task_id: 3, title: "Add Stripe webhooks", due: "—", list: :backlog, status: :wont_do}
+        ]
+      }
+    ]
+
+    demos.each do |demo|
+      html = Vident::StableId.with_sequence_generator(seed: "vident-docs-#{demo[:slug]}") do
+        demo[:args].map { |a| demo[:component].new(**a).call }.join
+      end
+      html = clean(html)
+
+      File.write(File.join(out, "#{demo[:slug]}_rendered.html"), html + "\n")
+      File.write(File.join(out, "#{demo[:slug]}_html.html"), pretty_html(html))
+      File.write(
+        File.join(out, "#{demo[:slug]}_source.rb"),
+        File.read(File.expand_path("../../#{demo[:source_path]}", __dir__))
+      )
+
+      puts "  rendered #{demo[:slug]} → #{html.bytesize} bytes"
+    end
+
+    puts "Wrote demos to #{out}"
+  end
+
+  desc "Build the documentation website"
+  task build: :demos do
+    Dir.chdir(WEBSITE_DIR) do
+      sh "bundle install"
+      sh "bundle exec jekyll build"
+    end
+  end
+
+  desc "Serve the documentation website locally with live reload"
+  task serve: :demos do
+    Dir.chdir(WEBSITE_DIR) do
+      sh "bundle install"
+      sh "bundle exec jekyll serve --livereload"
+    end
+  end
+
+  desc "Clean the documentation website build"
+  task :clean do
+    Dir.chdir(WEBSITE_DIR) do
+      sh "bundle exec jekyll clean"
+    end
+  end
+
+  # Strip the development-only "Before ..." HTML comment that the dummy
+  # ApplicationComponent injects so the embedded fragment stays clean.
+  def clean(html)
+    html.gsub(/<!--\s*Before [^>]*?-->/, "").strip
+  end
+
+  # Pretty-prints the rendered fragment for the "Rendered HTML" tab. Nokogiri
+  # escapes `>` inside attribute values to `&gt;` (correct HTML5, but ugly to
+  # read), so we unescape that back — the result is still valid HTML and
+  # matches what a developer would expect to see in their source.
+  def pretty_html(html)
+    require "nokogiri"
+    Nokogiri::HTML5.fragment(html).to_xhtml(indent: 2).gsub("&gt;", ">")
+  end
+end

data/lib/vident/capabilities/stimulus_attribute_strings.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../internals/registry"
+
+module Vident
+  module Capabilities
+    # `as_stimulus_*` returns a ready-to-splat HTML data-attribute string for
+    # the given stimulus declaration — usable from any rendering context
+    # (ERB partials, Phlex templates, helpers, controller renderers).
+    #
+    # Unlike `child_element`, these helpers don't write to a buffer, so they
+    # work even when called on a Phlex Vident component from outside its own
+    # `view_template` lifecycle.
+    module StimulusAttributeStrings
+      ::Vident::Internals::Registry.each do |kind|
+        define_method(:"as_stimulus_#{kind.singular_name}") do |*args|
+          to_data_attribute_string(**send(:"stimulus_#{kind.singular_name}", *args).to_h)
+        end
+
+        define_method(:"as_stimulus_#{kind.plural_name}") do |*args|
+          to_data_attribute_string(**send(:"stimulus_#{kind.plural_name}", *args).to_h)
+        end
+
+        alias_method :"as_#{kind.singular_name}", :"as_stimulus_#{kind.singular_name}"
+      end
+
+      private
+
+      def to_data_attribute_string(**attributes)
+        attributes.map { |key, value| "data-#{escape_attribute_name_for_html(key)}=\"#{escape_attribute_value_for_html(value)}\"" }
+          .join(" ")
+          .html_safe
+      end
+
+      def escape_attribute_name_for_html(name)
+        name.to_s.gsub(/[^a-zA-Z0-9\-_]/, "").tr("_", "-")
+      end
+
+      def escape_attribute_value_for_html(value)
+        value.to_s.gsub('"', """).gsub("'", "'")
+      end
+    end
+  end
+end

data/lib/vident/capabilities/stimulus_parsing.rb

@@ -118,13 +118,13 @@ module Vident
 
         def stimulus_outlet(*args)
           case args
-          in [Symbol => _name, String => _selector] | [String => _name, String => _selector]
+          in [Symbol => _name, ::Vident::Stimulus::Selector] | [String => _name, ::Vident::Stimulus::Selector]
             ::Vident::Stimulus::Outlet.parse(*args, implied: implied_controller_for_class)
           else
             raise ::Vident::ParseError,
-              "#{name}.stimulus_outlet requires (name, selector) — no component_id at class level. " \
+              "#{name}.stimulus_outlet requires (name, Vident::Selector(...)) — no component_id at class level. " \
               "Use instance-level `component.stimulus_outlet(:name)` for auto-selector, " \
-              "or `#{name}.stimulus_outlet(:name, '.selector')` with an explicit selector."
+              "or `#{name}.stimulus_outlet(:name, Vident::Selector('.css'))` for a verbatim selector."
           end
         end
 

data/lib/vident/component.rb

@@ -14,6 +14,7 @@ module Vident
     include ::Vident::Capabilities::StimulusMutation
     include ::Vident::Capabilities::StimulusDraft
     include ::Vident::Capabilities::StimulusDataEmitting
+    include ::Vident::Capabilities::StimulusAttributeStrings
     include ::Vident::Capabilities::ClassListBuilding
     include ::Vident::Capabilities::RootElementRendering
     include ::Vident::Capabilities::ChildElementRendering

data/lib/vident/internals/dsl.rb

@@ -80,11 +80,11 @@ module Vident
       # Positional Hash arg supports keys like `"admin--users"` that can't be Ruby kwargs.
       def outlets(positional = nil, **hash)
         if positional.is_a?(Hash)
-          positional.each { |k, v| record_keyed(@outlets, k, v) }
+          positional.each { |k, v| record_outlet(k, v) }
         elsif !positional.nil?
           raise ArgumentError, "outlets: positional arg must be a Hash, got #{positional.class}"
         end
-        hash.each { |k, v| record_keyed(@outlets, k, v) }
+        hash.each { |k, v| record_outlet(k, v) }
         self
       end
 
@@ -158,6 +158,25 @@ module Vident
         replace_or_append(bucket, entry)
       end
 
+      def record_outlet(key, value)
+        validate_outlet_value!(key, value)
+        entry = [key, value.nil? ? Declaration.of : Declaration.of(value)]
+        replace_or_append(@outlets, entry)
+      end
+
+      def validate_outlet_value!(key, value)
+        return if value.nil?
+        return if value.is_a?(Proc)
+        return if value.is_a?(::Vident::Stimulus::Selector)
+        return if value.is_a?(::Vident::Stimulus::Outlet)
+        return if value.respond_to?(:stimulus_identifier)
+        raise ::Vident::ParseError,
+          "outlets: value for #{key.inspect} must be nil (auto-selector), " \
+          "a `Vident::Selector(…)`, a Proc returning one, an Outlet, or a child component. " \
+          "Got #{value.class}: #{value.inspect}. " \
+          "If you meant a verbatim CSS selector, wrap it: `Vident::Selector(#{value.inspect})`."
+      end
+
       def replace_or_append(bucket, entry)
         key = entry.first
         idx = bucket.index { |(k, _)| k == key }

data/lib/vident/stimulus/action.rb

@@ -34,8 +34,6 @@ module Vident
             method_name: Naming.js_name(method_sym),
             event: nil
           )
-        in [String => s]
-          parse_qualified_string(s)
         in [Symbol => event, Symbol => method_sym]
           new(
             controller: implied,
@@ -54,6 +52,12 @@ module Vident
             method_name: Naming.js_name(method_sym),
             event: event.to_s
           )
+        in [String => s]
+          raise ::Vident::ParseError,
+            "Action.parse: a bare String is a controller path, not a fully-qualified action descriptor. " \
+            "For event/controller/method use structured args like `:click, \"path/ctrl\", :method` " \
+            "or the Hash descriptor form. To parse an existing wire-format string like " \
+            "\"click->ctrl#m\", call `Vident::Stimulus::Action.parse_descriptor(#{s.inspect})`."
         else
           raise ::Vident::ParseError, "Action.parse: invalid arguments #{args.inspect}"
         end
@@ -103,8 +107,9 @@ module Vident
         )
       end
 
-      # Pass-through: the controller segment is NOT re-stimulized.
-      def self.parse_qualified_string(s)
+      # Parses a wire-format Stimulus action descriptor (`"event->ctrl#method"` or
+      # `"ctrl#method"`). The controller segment is taken verbatim — not re-stimulized.
+      def self.parse_descriptor(s)
         if s.include?("->")
           event_part, ctrl_method = s.split("->", 2)
           ctrl, method = ctrl_method.split("#", 2)

data/lib/vident/stimulus/outlet.rb

@@ -4,63 +4,61 @@ require "literal"
 require_relative "naming"
 require_relative "base"
 require_relative "controller"
+require_relative "selector"
 
 module Vident
   module Stimulus
-    # `data-<ctrl>-<name>-outlet` fragment. `selector` is the CSS selector
-    # the Stimulus runtime uses to resolve the outlet on the page.
+    # `data-<parent-ctrl>-<child-ctrl>-outlet` fragment.
     class Outlet < Base
       prop :controller, Controller
       prop :name, String
       prop :selector, String
 
+      # Characters that only make sense in a CSS selector, never in a
+      # Stimulus controller path/identifier.
+      SELECTOR_CHARS = /[.#\[>,*+:]/
+
       def self.parse(*args, implied:, component_id: nil)
         case args
+        in [Outlet => o]
+          o
         in [Symbol => sym]
           name = sym.to_s.dasherize
-          new(
-            controller: implied,
-            name: name,
-            selector: auto_selector(name, component_id: component_id)
-          )
+          new(controller: implied, name: name, selector: auto_selector(name, component_id: component_id))
+        in [String => str] if SELECTOR_CHARS.match?(str)
+          raise ::Vident::ParseError, raw_string_selector_message(str)
         in [String => str]
-          name = str.dasherize
-          new(
-            controller: implied,
-            name: name,
-            selector: auto_selector(name, component_id: component_id)
-          )
-        in [[identifier, selector]]
-          new(
-            controller: implied,
-            name: identifier.to_s.dasherize,
-            selector: selector
-          )
-        in [Symbol => sym, String => sel]
+          name = Naming.stimulize_path(str)
+          new(controller: implied, name: name, selector: auto_selector(name, component_id: component_id))
+        in [Symbol => sym, Selector => sel]
+          new(controller: implied, name: sym.to_s.dasherize, selector: sel.css)
+        in [String => str, Selector => sel]
+          new(controller: implied, name: Naming.stimulize_path(str), selector: sel.css)
+        in [String => parent_path, Symbol => child_sym]
+          child_name = child_sym.to_s.dasherize
           new(
-            controller: implied,
-            name: sym.to_s.dasherize,
-            selector: sel
+            controller: Controller.parse(parent_path, implied: implied),
+            name: child_name,
+            selector: auto_selector(child_name, component_id: component_id)
           )
-        in [String => id_or_name, String => sel]
+        in [String => parent_path, Symbol => child_sym, Selector => sel]
           new(
-            controller: implied,
-            name: id_or_name.dasherize,
-            selector: sel
-          )
-        in [String => ctrl_path, Symbol => sym, String => sel]
-          new(
-            controller: Controller.parse(ctrl_path, implied: implied),
-            name: sym.to_s.dasherize,
-            selector: sel
+            controller: Controller.parse(parent_path, implied: implied),
+            name: child_sym.to_s.dasherize,
+            selector: sel.css
           )
         in [obj] if obj.respond_to?(:stimulus_identifier)
           ident = obj.stimulus_identifier
-          new(
-            controller: implied,
-            name: ident,
-            selector: auto_selector(ident, component_id: component_id)
-          )
+          new(controller: implied, name: ident, selector: auto_selector(ident, component_id: component_id))
+        in [Selector => sel]
+          raise ::Vident::ParseError,
+            "Outlet.parse: a Selector must be paired with a child controller name. " \
+            "Use `(:name, Vident::Selector(#{sel.css.inspect}))` or " \
+            "`(\"some/parent\", :name, Vident::Selector(...))` for the cross-controller form."
+        in [_, String => sel]
+          raise ::Vident::ParseError, raw_string_selector_message(sel)
+        in [_, _, String => sel]
+          raise ::Vident::ParseError, raw_string_selector_message(sel)
         else
           raise ::Vident::ParseError, "Outlet.parse: invalid arguments #{args.inspect}"
         end
@@ -80,6 +78,13 @@ module Vident
         id.to_s.gsub(/[^A-Za-z0-9_-]/) { |c| "\\#{c.ord.to_s(16)} " }
       end
 
+      def self.raw_string_selector_message(value)
+        "Outlet.parse: a bare String is a controller path, never a CSS selector. " \
+          "Wrap verbatim selectors in `Vident::Selector(...)` (got #{value.inspect}). " \
+          "For auto-selectors based on a child controller identifier, pass a Symbol or " \
+          "an unwrapped String — Vident builds `[data-controller~=…]` for you."
+      end
+
       def to_s = selector
 
       def data_attribute_key = :"#{controller.name}-#{name}-outlet"

data/lib/vident/stimulus/selector.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Vident
+  module Stimulus
+    Selector = Data.define(:css) do
+      def to_s = css
+    end
+
+    def self.Selector(css) = Selector.new(css: css)
+  end
+
+  def self.Selector(css) = Stimulus::Selector.new(css: css)
+end

data/lib/vident/stimulus/target.rb

@@ -16,13 +16,16 @@ module Vident
         case args
         in [Symbol => sym]
           new(controller: implied, name: Naming.js_name(sym))
-        in [String => str]
-          new(controller: implied, name: str)
         in [String => ctrl_path, Symbol => sym]
           new(
             controller: Controller.parse(ctrl_path, implied: implied),
             name: Naming.js_name(sym)
           )
+        in [String => s]
+          raise ::Vident::ParseError,
+            "Target.parse: a bare String is a controller path; target names must be Symbols " \
+            "(got #{s.inspect}). Use `target :name` for a local target, or " \
+            "`target \"path/to/ctrl\", :name` for cross-controller."
         else
           raise ::Vident::ParseError, "Target.parse: invalid arguments #{args.inspect}"
         end

data/lib/vident/types.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "literal"
+require_relative "stimulus/selector"
 require_relative "stimulus/controller"
 require_relative "stimulus/action"
 require_relative "stimulus/target"

data/lib/vident/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vident
-  VERSION = "2.0.1"
+  VERSION = "3.0.0"
 end

data/lib/vident.rb

@@ -16,6 +16,7 @@ require "vident/stimulus_null"
 
 require "vident/stimulus/naming"
 require "vident/stimulus/null"
+require "vident/stimulus/selector"
 require "vident/stimulus/controller"
 require "vident/stimulus/action"
 require "vident/stimulus/target"
@@ -44,6 +45,7 @@ require "vident/capabilities/stimulus_parsing"
 require "vident/capabilities/stimulus_mutation"
 require "vident/capabilities/stimulus_draft"
 require "vident/capabilities/stimulus_data_emitting"
+require "vident/capabilities/stimulus_attribute_strings"
 require "vident/capabilities/class_list_building"
 require "vident/capabilities/root_element_rendering"
 require "vident/capabilities/child_element_rendering"

data/skills/vident/SKILL.md

@@ -273,7 +273,9 @@ These only tell the JS controller *which* classes to toggle; they do **not** app
 
 ### 1.7 Outlets
 
-Stimulus: `data-<identifier>-<outlet-name>-outlet="<css-selector>"` attaches matching controller instances as `this.nameOutlet` / `this.nameOutlets` / `this.nameOutletElement(s)` / `this.hasNameOutlet`. Outlet names are the kebab-case *identifier* of the outlet controller.
+Stimulus: `data-<identifier>-<outlet-name>-outlet="<css-selector>"` attaches matching controller instances as `this.nameOutlet` / `this.nameOutlets` / `this.nameOutletElement(s)` / `this.hasNameOutlet`. The `<outlet-name>` 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.
 
@@ -281,19 +283,28 @@ Vident has three forms.
 
 ```ruby
 stimulus do
-  outlets modal: ".modal", user_status: ".online-user"
-  outlets({"admin--users" => ".admin-user"})   # positional-hash for names containing `--`
+  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: [
-  [:modal, ".modal"],                       # implied controller
-  ["admin/users", :row, ".user-row"],       # cross-controller
-  :user_status,                             # auto-selector: [data-controller~=user-status]
-  other_component_instance,                 # #<id> [data-controller~=<other identifier>]
+  :user_status,                                              # auto-selector
+  [:modal, Vident::Selector(".modal")],                      # explicit selector
+  ["admin/users", :row, Vident::Selector(".user-row")],      # cross-controller, explicit
+  other_component_instance,                                   # #<id> [data-controller~=<other identifier>]
 ]
 ```
 
@@ -362,7 +373,18 @@ Inline helper (ERB): `as_stimulus_param(:release_id, 42)` / `as_stimulus_params(
 
 ## 2. Component scaffolding
 
-Pick the right base class:
+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`

data/skills/vident/api-reference.md

@@ -22,13 +22,6 @@ Adds:
   class precedence rules from SKILL.md §4). Self-closing tags (`:area`, `:br`, `:col`,
   `:embed`, `:hr`, `:img`, `:input`, `:link`, `:meta`, `:param`, `:source`, `:track`,
   `:wbr`) are emitted without children.
-- 14 `as_stimulus_*` helpers — return an HTML-safe `String` of raw `data-*` attributes
-  suitable for embedding inside an HTML tag in ERB. Signatures match the corresponding
-  `stimulus_*` method (see section 4):
-  - Plural: `as_stimulus_controllers`, `as_stimulus_actions`, `as_stimulus_targets`,
-    `as_stimulus_outlets`, `as_stimulus_values`, `as_stimulus_params`, `as_stimulus_classes`.
-  - Singular: `as_stimulus_controller`, `as_stimulus_action`, `as_stimulus_target`,
-    `as_stimulus_outlet`, `as_stimulus_value`, `as_stimulus_param`, `as_stimulus_class`.
 - Class-level cache support: `template_path`, `component_path`, `components_base_path`,
   `cache_component_modified_time`, `cache_sidecar_view_modified_time`,
   `cache_rb_component_modified_time` — used by `Vident::Caching` to chain
@@ -49,8 +42,13 @@ Adds:
   `child_element` raises `ArgumentError`.
 - Source-file tracking — the class-level `inherited` hook records each subclass's source
   file in `component_source_file_path` so `Vident::Caching` can pick up an mtime.
-- No `as_stimulus_*` helpers — Phlex has its own tag DSL; use `child_element` or spread
-  `data: { **component.stimulus_target(:name) }` inline.
+- `child_element` lifecycle constraint — `child_element` writes to Phlex's render
+  buffer, so it is **only valid during the component's own `view_template`**. From
+  outside the render lifecycle (an external ERB partial holding a Phlex component
+  reference, a helper, `ApplicationController.renderer.render(...)`, etc.) it raises
+  `undefined method 'buffer' for nil`. Use the `as_stimulus_*` helpers (see
+  `Vident::Component`) or spread `data: { **component.stimulus_target(:name) }` inline
+  instead — those don't touch the buffer.
 
 ### `Vident::Component` (module)
 
@@ -77,6 +75,17 @@ Public instance methods:
 - `id` — `String`, auto-generated from `StableId` if `@id` was nil. The generated form
   is `"#{component_name}-#{StableId.next_id_in_sequence}"`.
 - `prop_names` — instance-method alias for the class method.
+- 14 `as_stimulus_*` helpers + 7 short aliases — return an HTML-safe `String` of raw
+  `data-*` attributes, suitable for embedding inside an HTML tag (ERB or Phlex `raw(...)`).
+  Signatures match the corresponding `stimulus_*` method (see section 4). Pure transforms
+  over `stimulus_*` outputs — they don't write to a render buffer, so they're safe to call
+  on a Phlex Vident component from outside its `view_template` (unlike `child_element`).
+  - Plural: `as_stimulus_controllers`, `as_stimulus_actions`, `as_stimulus_targets`,
+    `as_stimulus_outlets`, `as_stimulus_values`, `as_stimulus_params`, `as_stimulus_classes`.
+  - Singular: `as_stimulus_controller`, `as_stimulus_action`, `as_stimulus_target`,
+    `as_stimulus_outlet`, `as_stimulus_value`, `as_stimulus_param`, `as_stimulus_class`.
+  - Aliases (singular only): `as_controller`, `as_action`, `as_target`, `as_outlet`,
+    `as_value`, `as_param`, `as_class`.
 
 Not public (override at your own risk, used internally):
 
@@ -468,7 +477,12 @@ def child_element(tag_name,
 - `**options` passes through as HTML options.
 - For ViewComponent's renderer, self-closing tags are emitted without the block.
 - For Phlex's renderer, the tag name is validated against
-  `Vident::Phlex::HTML::VALID_TAGS`; unknown tags raise `ArgumentError`.
+  `Vident::Phlex::HTML::VALID_TAGS`; unknown tags raise `ArgumentError`. Phlex's
+  `child_element` writes to the component's render buffer, so it is **only valid
+  during the component's own `view_template`**. Calling it from outside the render
+  lifecycle (an external ERB partial, a helper, `ApplicationController.renderer.render`)
+  raises `undefined method 'buffer' for nil`. Use `as_stimulus_*` helpers there
+  instead — those have no buffer dependency.
 
 ---
 

data/skills/vident/examples.md

@@ -398,8 +398,12 @@ a hand-authored HTML tag. All three are equivalent; pick one per file for consis
 <% end %>
 ```
 
-Phlex users have two choices — `child_element` (identical) and the native Phlex tag
-methods with `data: { **component.stimulus_target(:name) }`.
+Phlex users have three choices — `child_element` (identical to ERB, but only valid
+inside `view_template`), the native Phlex tag methods with
+`data: { **component.stimulus_target(:name) }`, and the `as_stimulus_*` helpers
+embedded via `raw(...)`. From an external ERB partial holding a Phlex component
+reference, `child_element` won't work (no render buffer) — use `as_stimulus_*` or
+the `data: { **stimulus_target(...) }` spread instead.
 
 ---
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vident
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
@@ -82,8 +82,12 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/generators/vident/component/component_generator.rb
 - lib/generators/vident/install/install_generator.rb
+- lib/generators/vident/install/templates/application_phlex_component.rb.tt
+- lib/generators/vident/install/templates/application_view_component.rb.tt
 - lib/generators/vident/install/templates/vident.rb
+- lib/tasks/website.rake
 - lib/vident.rb
 - lib/vident/caching.rb
 - lib/vident/capabilities/caching.rb
@@ -93,6 +97,7 @@ files:
 - lib/vident/capabilities/identifiable.rb
 - lib/vident/capabilities/inspectable.rb
 - lib/vident/capabilities/root_element_rendering.rb
+- lib/vident/capabilities/stimulus_attribute_strings.rb
 - lib/vident/capabilities/stimulus_data_emitting.rb
 - lib/vident/capabilities/stimulus_declaring.rb
 - lib/vident/capabilities/stimulus_draft.rb
@@ -124,6 +129,7 @@ files:
 - lib/vident/stimulus/null.rb
 - lib/vident/stimulus/outlet.rb
 - lib/vident/stimulus/param.rb
+- lib/vident/stimulus/selector.rb
 - lib/vident/stimulus/target.rb
 - lib/vident/stimulus/value.rb
 - lib/vident/stimulus_null.rb