vident-view_component 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa78ec0f7f2aad87ee0b10d3f4d354d294332a29dc0b7ad9814b44791739cb06
-  data.tar.gz: da78bd43e7b73a5ce53e14126ad297950e6ab18bfb2ea3338ce37a4dbb4b68f4
+  metadata.gz: f8a28dd067143483f3c2e19e53665891d1d7044cb722bbb508cbc4a7b5efd987
+  data.tar.gz: b672d968e7b6916c1c8b57725917fa577b29574e1e0094b886dbdc21a281a7ae
 SHA512:
-  metadata.gz: 1c5d0e27e9ced3bbc2a94e72c4593c2bc3aa69527f64bcf24e86612bd2f6d32a3bb929ee9a87cd1331088eace2e619cd3c4d0491063d3b8db0945479fe9ab2c1
-  data.tar.gz: d3bb8e28b96a8b7e33bd538f1e4b0c01a377d7f806d6d625b9aee0e3908bfc60b65b73e6bcb2ec46bc25b1c3469aa82f381c87573a5054f3165beadad15b6721
+  metadata.gz: 8e102228d3387732845eabe708afb71dc4af84f7c4a810d22a34a5dbdc9855cb141c09658e09a3973653177dae44c10a1988f8ac30effe26feb51cc9df1ab48e
+  data.tar.gz: f0299d8efddff1c7bca06025c61c3f65e8064de8acb8d1c94ed79cc828444c5110b6ecf0f2fb02a58cbad46b8343779731035ac81d072f75483d954a6e302eab

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/view_component/component/component_generator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Vident
+  module ViewComponent
+    module Generators
+      class ComponentGenerator < ::Rails::Generators::NamedBase
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Scaffold a Vident ViewComponent (.rb + .html.erb), its Stimulus controller sidecar, and a unit test."
+
+        class_option :skip_stimulus, type: :boolean, default: false,
+          desc: "Omit the stimulus DSL block and the JS controller sidecar"
+        class_option :skip_controller, type: :boolean, default: false,
+          desc: "Omit the JS controller sidecar (keeps the stimulus DSL block)"
+        class_option :skip_test, type: :boolean, default: false,
+          desc: "Skip generating a unit test"
+        class_option :typescript, type: :boolean, default: false, aliases: "-t",
+          desc: "Emit a TypeScript controller (.ts) instead of JavaScript (.js)"
+        class_option :parent, type: :string, default: "ApplicationViewComponent",
+          desc: "Parent class for the component"
+
+        def create_component_file
+          template "component.rb.tt", File.join("app/components", class_path, "#{file_name}_component.rb")
+        end
+
+        def create_template_file
+          template "component.html.erb.tt", File.join("app/components", class_path, "#{file_name}_component.html.erb")
+        end
+
+        def create_controller_file
+          return if options[:skip_stimulus] || options[:skip_controller]
+          ext = options[:typescript] ? "ts" : "js"
+          template "controller.#{ext}.tt", File.join("app/components", class_path, "#{file_name}_component_controller.#{ext}")
+        end
+
+        def create_test_file
+          return if options[:skip_test]
+          template "component_test.rb.tt", File.join("test/components", class_path, "#{file_name}_component_test.rb")
+        end
+
+        private
+
+        # Allow `g vident:view_component:component TaskCardComponent` to produce
+        # the same files as `g ... TaskCard` rather than `TaskCardComponentComponent`.
+        def class_name
+          super.sub(/Component\z/, "")
+        end
+
+        def file_name
+          super.sub(/_component\z/, "")
+        end
+
+        def component_class_name
+          "#{class_name}Component"
+        end
+
+        def parent_class
+          options[:parent]
+        end
+
+        def stimulus_block?
+          !options[:skip_stimulus]
+        end
+      end
+    end
+  end
+end

data/lib/generators/vident/view_component/component/templates/component.html.erb.tt

@@ -0,0 +1,3 @@
+<%%= root_element do %>
+  <h3 class="font-semibold"><%%= title %></h3>
+<%% end %>

data/lib/generators/vident/view_component/component/templates/component.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= component_class_name %> < <%= parent_class %>
+  prop :title, String, reader: :public
+
+<% if stimulus_block? -%>
+  stimulus do
+    values_from_props :title
+    action(:select).on(:click)
+  end
+
+<% end -%>
+  def root_element_attributes
+    {html_options: {class: "rounded border p-4"}}
+  end
+end
+<% end -%>

data/lib/generators/vident/view_component/component/templates/component_test.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+<% module_namespacing do -%>
+class <%= component_class_name %>Test < ViewComponent::TestCase
+  test "renders the title" do
+    render_inline(<%= component_class_name %>.new(title: "Hello"))
+    assert_text "Hello"
+  end
+end
+<% end -%>

data/lib/generators/vident/view_component/component/templates/controller.js.tt

@@ -0,0 +1,11 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values = {
+    title: String,
+  }
+
+  select(event) {
+    this.dispatch("selected", { detail: { title: this.titleValue } })
+  }
+}

data/lib/generators/vident/view_component/component/templates/controller.ts.tt

@@ -0,0 +1,13 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values = {
+    title: String,
+  }
+
+  declare readonly titleValue: string
+
+  select(event: Event): void {
+    this.dispatch("selected", { detail: { title: this.titleValue } })
+  }
+}

data/lib/vident/view_component/base.rb

@@ -72,42 +72,6 @@ module Vident
         end
       end
 
-      def as_stimulus_targets(...) = to_data_attribute_string(**stimulus_targets(...).to_h)
-
-      def as_stimulus_target(...) = to_data_attribute_string(**stimulus_target(...).to_h)
-
-      def as_stimulus_actions(...) = to_data_attribute_string(**stimulus_actions(...).to_h)
-
-      def as_stimulus_action(...) = to_data_attribute_string(**stimulus_action(...).to_h)
-
-      def as_stimulus_controllers(...) = to_data_attribute_string(**stimulus_controllers(...).to_h)
-
-      def as_stimulus_controller(...) = to_data_attribute_string(**stimulus_controller(...).to_h)
-
-      def as_stimulus_outlets(...) = to_data_attribute_string(**stimulus_outlets(...).to_h)
-
-      def as_stimulus_outlet(...) = to_data_attribute_string(**stimulus_outlet(...).to_h)
-
-      def as_stimulus_values(...) = to_data_attribute_string(**stimulus_values(...).to_h)
-
-      def as_stimulus_value(...) = to_data_attribute_string(**stimulus_value(...).to_h)
-
-      def as_stimulus_params(...) = to_data_attribute_string(**stimulus_params(...).to_h)
-
-      def as_stimulus_param(...) = to_data_attribute_string(**stimulus_param(...).to_h)
-
-      def as_stimulus_classes(...) = to_data_attribute_string(**stimulus_classes(...).to_h)
-
-      def as_stimulus_class(...) = to_data_attribute_string(**stimulus_class(...).to_h)
-
-      alias_method :as_target, :as_stimulus_target
-      alias_method :as_action, :as_stimulus_action
-      alias_method :as_controller, :as_stimulus_controller
-      alias_method :as_outlet, :as_stimulus_outlet
-      alias_method :as_value, :as_stimulus_value
-      alias_method :as_param, :as_stimulus_param
-      alias_method :as_class, :as_stimulus_class
-
       private
 
       def generate_child_element(tag_name, stimulus_data_attributes, options, &block)
@@ -121,20 +85,6 @@ module Vident
           view_context.content_tag(tag_name, nil, options)
         end
       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
-
-      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
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vident-view_component
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
@@ -55,14 +55,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.1
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.1
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +93,12 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/generators/vident/view_component/component/component_generator.rb
+- lib/generators/vident/view_component/component/templates/component.html.erb.tt
+- lib/generators/vident/view_component/component/templates/component.rb.tt
+- lib/generators/vident/view_component/component/templates/component_test.rb.tt
+- lib/generators/vident/view_component/component/templates/controller.js.tt
+- lib/generators/vident/view_component/component/templates/controller.ts.tt
 - lib/vident-view_component.rb
 - lib/vident/view_component.rb
 - lib/vident/view_component/base.rb