vident-phlex 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fd97e08c66d8473338aded609cf45f63d982dddc72e376a598218a5224139c5
-  data.tar.gz: 15db0bb5c243e378327792710e491b49c93ab185a0286730e1420d8eae0de2e0
+  metadata.gz: c416c516698b5baa7fa1781d7214304c47e1538914d8ca223999ed445d31668a
+  data.tar.gz: d4a7734bd601437da2c0ae138af4fa842d3fb4f6e54d1c0eb63b248570ed6bff
 SHA512:
-  metadata.gz: e53d2df34d5720dbd801139e0326bc2837b6af70d4a6ef6a3bbe6b718c8021275931a5adae8b1ce409063aec68c9f286af5aa1ba434e91ca97dc812331506f73
-  data.tar.gz: 4ea8a5f6707e92a0340bb8f409d33533eac3cd509e4e4f0e108218d303cbb077e3965ec551c8f0f9a8bcfd4fd73e817b98f336923e02258aaf5d452507b242ba
+  metadata.gz: e42d3a768f1764c41ef278a40c0a568db966e029dcd010fa62dc6a53f0551842bb853caf375cbe67f6d2a3c5de32d7ff826a10cbf738850a7828950f8afbbc88
+  data.tar.gz: edd99c2f09799da5fe30f477c5ddb07d77d20c3a0820ef5d23e7e24ec493320ed45568756f8d7ca6fe812d573ac0aef4c07f774759cb89fa0dd52b7a4e432c87

data/CHANGELOG.md

@@ -6,6 +6,36 @@ 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
+
+- Base gem no longer fails to load when installed without the adapter gems — adapter requires moved to their own entry points (`lib/vident-phlex.rb`, `lib/vident-view_component.rb`) (#29).
+
+
 ## [2.0.0] - 2026-04-24
 
 Vident 2.0 is a ground-up rearchitecture of the DSL, attribute resolution, and composition model. The public shape of `stimulus do ... end`, `root_element`, `child_element`, outlets, props, and the `stimulus_*:` prop/kwarg API is preserved for common cases, but several internals and a handful of edge-case behaviours changed. See `doc/reviews/v1-gotchas.md` for the full list of fixed gotchas; the highlights are below.

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Vident
+  module Phlex
+    module Generators
+      class ComponentGenerator < ::Rails::Generators::NamedBase
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Scaffold a Vident Phlex component (.rb), 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: "ApplicationPhlexComponent",
+          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_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:phlex:component TaskCardComponent` to produce the
+        # same files as `g ... TaskCard` rather than `TaskCardComponentComponent`.
+        # Matches ViewComponent's own generator behaviour.
+        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/phlex/component/templates/component.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= component_class_name %> < <%= parent_class %>
+  prop :title, String
+
+<% if stimulus_block? -%>
+  stimulus do
+    values_from_props :title
+    action(:select).on(:click)
+  end
+
+<% end -%>
+  def view_template
+    root_element(class: "rounded border p-4") do
+      h3(class: "font-semibold") { @title }
+    end
+  end
+end
+<% end -%>

data/lib/generators/vident/phlex/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 < ActiveSupport::TestCase
+  test "renders the title" do
+    html = <%= component_class_name %>.new(title: "Hello").call
+    assert_includes html, "Hello"
+  end
+end
+<% end -%>

data/lib/generators/vident/phlex/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/phlex/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-phlex.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Entry point for the `vident-phlex` gem — loaded automatically by
+# `Bundler.require` when `gem "vident-phlex"` is in the Gemfile.
+
+require "phlex"
+require "vident"
+require "vident/phlex"

metadata

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