RubyGems - vident-phlex - Versions diffs - 0.13.1 → 1.0.0.alpha1 - Mend

vident-phlex 0.13.1 → 1.0.0.alpha1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +24 -0
data/README.md +521 -665
data/lib/vident/phlex/html.rb +49 -6
data/lib/vident/phlex.rb +0 -2
metadata +6 -8
data/lib/vident/phlex/core.rb +0 -29
data/lib/vident/phlex/root_component.rb +0 -55

data/README.md CHANGED Viewed

@@ -1,851 +1,707 @@
 # Vident
-Vident is a collection of gems that provide a set of tools for building web applications with Ruby on Rails.
+A powerful Ruby gem for building interactive, type-safe components in Rails applications with seamless [Stimulus.js](https://stimulus.hotwired.dev/) integration.
-## Included Gems
+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/).
-The core gems:
+## Table of Contents
-- `vident`: The core Vident library
-- `vident-phlex`: Phlex integration for Vident
-- `vident-view_component`: ViewComponent integration for Vident
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Component DSL](#component-dsl)
+- [Stimulus Integration](#stimulus-integration)
+- [Advanced Features](#advanced-features)
+- [Testing](#testing)
+- [Contributing](#contributing)
-Note that you can use both `Phlex` and `ViewComponent` in the same application if desired.
+## Introduction
-And then optional extra features:
+Vident is a collection of gems that enhance Rails view components with:
-- `vident-tailwind`: Tailwind CSS integration for Vident
-- `vident-typed`: Type system for Vident components
-- `vident-typed-minitest`: Minitest integration for typed Vident components
-- `vident-typed-phlex`: Phlex integration for typed Vident components
-- `vident-typed-view_component`: ViewComponent integration for typed Vident
-- `vident-better_html`: Better HTML integration for Vident
+- **Type-safe properties** using the Literal gem
+- **First-class [Stimulus.js](https://stimulus.hotwired.dev/) integration** for interactive behaviors
+- **Support for both [ViewComponent](https://viewcomponent.org/) and [Phlex](https://www.phlex.fun/)** rendering engines
+- **Intelligent CSS class management** with built-in Tailwind CSS merging
+- **Component caching** for improved performance
+- **Declarative DSL** for clean, maintainable component code
-## Directory Structure
+### Why Vident?
-The repository is structured like this:
+Stimulus.js is a powerful framework for adding interactivity to HTML, but managing the data attributes can be cumbersome,
+and refactoring can be error-prone (as say controller names are repeated in many places).
-```
-vident/
-├── lib/                       # All gem code
-│   ├── vident.rb              # Core entry point
-│   ├── vident-phlex.rb        # Gem entry points
-│   ├── vident-better_html.rb
-│   ├── vident/                # Shared code
-│       ├── base.rb
-│       ├── phlex/             # Phlex integration
-│       ├── better_html/       # Better HTML integration
-│       └── ...
-├── test/                      # All tests
-│   ├── vident/                # Core tests
-│   ├── vident-phlex/          # Tests for each gem
-│   └── ...
-├── docs/                      # Documentation
-├── examples/                  # Examples
-├── vident.gemspec            # Gemspec for core gem
-├── vident-phlex.gemspec      # Gemspecs for each gem
-└── ...
-```
-## Development
-### Setting Up Development Environment
-```bash
-# Clone the repository
-git clone https://github.com/stevegeek/vident.git
-cd vident
-# Install dependencies
-bundle install
-```
-### Running Tests
-To run tests for all gems:
-```bash
-rake test
-```
-To run tests for a specific gem:
-```bash
-rake test:vident-phlex
-```
-### Building and Installing Gems
-To build all gems:
-```bash
-rake build
-```
-To install all gems locally:
-```bash
-rake install
-```
-## Contributing
-1. Fork the repository
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
-## License
+Vident simplifies this by providing a declarative DSL for defining Stimulus controllers, actions, targets, and values
+directly within your component classes so you don't need to manually craft data attributes in your templates.
-The gems are available as open source under the terms of the [MIT License](LICENSE.txt).
+Vident also ensures that your components are flexible: for example you can easily add to, or override configuration,
+classes etc at the point of rendering.
----
+Vident's goal is to make building UI components more maintainable, and remove some of the boilerplate code of Stimulus
+without being over-bearing or including too much magic.
-# Component Documentation
+## Installation
----
-## gem: vident-typed-view_component
-# Vident::Typed::ViewComponent
-Adds typed attributes to Vident ViewComponent components.
+Add the core gem and your preferred rendering engine integration to your Gemfile:
 ```ruby
-class ApplicationComponent < ::Vident::Typed::ViewComponent::Base
-end
-```
+# Core gem (required)
+gem "vident"
-For more details see [vident](https://github.com/stevegeek/vident).
-### Examples
-Before we dive into a specific example note that there are some components implemented in `test/dummy/app/components`.
+# Choose your rendering engine (at least one required)
+gem "vident-view_component"  # For ViewComponent support
+gem "vident-phlex"           # For Phlex support
+```
-Try them out by starting Rails:
+Then run:
 ```bash
-cd test/dummy
 bundle install
-rails assets:precompile
-rails s
 ```
-and visiting http://localhost:3000
+## Quick Start
-### A Vident component example (without Stimulus)
-First is an example component that uses `Vident::Typed::ViewComponent::Base` but no Stimulus features.
-It is an avatar component that can either be displayed as an image or as initials.
-It supports numerous sizes and shapes and can optionally have a border. It also generates a cache key for use in fragment caching or etag generation.
+Here's a simple example of a Vident component using ViewComponent:
 ```ruby
-class AvatarComponent < ::Vident::Typed::ViewComponent::Base
-  include ::Vident::Tailwind
-  include ::Vident::Caching
-  no_stimulus_controller
-  with_cache_key :attributes
-  attribute :url, String, allow_nil: true, allow_blank: false
-  attribute :initials, String, allow_blank: false
-  attribute :shape, Symbol, in: %i[circle square], default: :circle
-  attribute :border, :boolean, default: false
-  attribute :size, Symbol, in: %i[tiny small normal medium large x_large xx_large], default: :normal
-  private
-  def default_html_options
-    if image_avatar?
-      { class: "inline-block object-contain", src: url, alt: t(".image") }
-    else
-      { class: "inline-flex items-center justify-center bg-gray-500" }
-    end
+# app/components/button_component.rb
+class ButtonComponent < Vident::ViewComponent::Base
+  # Define typed properties
+  prop :text, String, default: "Click me"
+  prop :url, _Nilable(String)
+  prop :style, Symbol, in: [:primary, :secondary], default: :primary
+  prop :clicked_count, Integer, default: 0
+  # Configure Stimulus integration
+  stimulus do
+    actions [:click, :handle_click]
+    # Static values
+    values loading_duration: 1000
+    # Map the clicked_count prop as a Stimulus value
+    values_from_props :clicked_count
+    # Dynamic values using procs (evaluated in component context)
+    values item_count: -> { @items.count }
+    values api_url: -> { Rails.application.routes.url_helpers.api_items_path }
+    # Static and dynamic classes
+    classes loading: "opacity-50 cursor-wait"
+    classes size: -> { @items.count > 10 ? "large" : "small" }
   end
-  def element_classes
-    [size_classes, shape_class, border? ? "border" : ""]
+  def call
+    root_element do
+      @text
+    end
   end
-  alias_method :image_avatar?, :url?
-  def shape_class
-    (shape == :circle) ? "rounded-full" : "rounded-md"
-  end
+  private
-  def size_classes
-    case size
-    when :tiny
-      "w-6 h-6"
-    when :small
-      "w-8 h-8"
-    when :medium
-      "w-12 h-12"
-    when :large
-      "w-14 h-14"
-    when :x_large
-      "sm:w-24 sm:h-24 w-16 h-16"
-    when :xx_large
-      "sm:w-32 sm:h-32 w-24 h-24"
-    else
-      "w-10 h-10"
-    end
+  def root_element_attributes
+    {
+      element_tag: @url ? :a : :button,
+      html_options: { href: @url }.compact
+    }
   end
-  def text_size_class
-    case size
-    when :tiny
-      "text-xs"
-    when :small
-      "text-xs"
-    when :medium
-      "text-lg"
-    when :large
-      "sm:text-xl text-lg"
-    when :extra_large
-      "sm:text-2xl text-xl"
-    else
-      "text-medium"
+  def element_classes
+    base_classes = "btn"
+    case @style
+    when :primary
+      "#{base_classes} btn-primary"
+    when :secondary
+      "#{base_classes} btn-secondary"
     end
   end
 end
 ```
-```erb
-<%= render root(
-             element_tag: image_avatar? ? :img : :div,
-             html_options: default_html_options
-           ) do %>
-  <% unless image_avatar? %>
-    <span class="<%= text_size_class %> font-medium leading-none text-white"><%= initials %></span>
-  <% end %>
-<% end %>
-```
+Add the corresponding Stimulus controller would be:
-Example usages:
+```javascript
+// app/javascript/controllers/button_component_controller.js
+// Can also be "side-car" in the same directory as the component, see the documentation for details
+import { Controller } from "@hotwired/stimulus"
-```erb
-<!-- These will render -->
-<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", initials: "AB" size: :large) %>
-<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", html_options: {alt: "My alt text", class: "object-scale-down"}) %>
-<%= render AvatarComponent.new(initials: "SG", size: :small) %>
-<%= render AvatarComponent.new(initials: "SG", size: :large, html_options: {class: "border-2 border-red-600"}) %>
-<!-- These will raise an error -->
-<!-- missing initals -->
-<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", size: :large) %>
-<!-- initials blank -->
-<%= render AvatarComponent.new(initials: "", size: :large) %>
- <!-- invalid size -->
-<%= render AvatarComponent.new(initials: "SG", size: :foo_bar) %>
+export default class extends Controller {
+  static values = {
+    clickedCount: Number,
+    loadingDuration: Number
+  }
+  static classes = ["loading"]
+  handleClick(event) {
+    // Increment counter
+    this.clickedCountValue++
+    // Add loading state
+    this.element.classList.add(this.loadingClass)
+    this.element.disabled = true
+    // Use the loading duration from the component
+    setTimeout(() => {
+      this.element.classList.remove(this.loadingClass)
+      this.element.disabled = false
+      // Update text to show count
+      this.element.textContent = `${this.element.textContent} (${this.clickedCountValue})`
+    }, this.loadingDurationValue)
+  }
+}
 ```
+Use the component in your views:
-The following is rendered when used `render AvatarComponent.new(initials: "SG", size: :small, border: true)`:
+```erb
+<!-- Default clicked count of 0 -->
+<%= render ButtonComponent.new(text: "Save", style: :primary) %>
-```html
-<div class="avatar-component w-8 h-8 rounded-full border inline-flex items-center justify-center bg-gray-500" id="avatar-component-9790427-12">
-  <span class="text-xs font-medium leading-none text-white">SG</span>
-</div>
-```
+<!-- Pre-set clicked count -->
+<%= render ButtonComponent.new(text: "Submit", style: :primary, clicked_count: 5) %>
-The following is rendered when used `render AvatarComponent.new(url: "https://i.pravatar.cc/300", initials: "AB", html_options: {alt: "My alt text", class: "block"})`:
+<!-- Link variant -->
+<%= render ButtonComponent.new(text: "Cancel", url: "/home", style: :secondary) %>
-```html
-<img src="https://i.pravatar.cc/300" alt="My alt text" class="avatar-component w-10 h-10 rounded-full object-contain block" id="avatar-component-7083941-11">
+<!-- Override things -->
+<%= render ButtonComponent.new(text: "Cancel", url: "/home" classes: "bg-red-900", html_options: {role: "button"}) %>
 ```
-----
+The rendered HTML includes all Stimulus data attributes:
-![Example](examples/avatar.png)
-### Another ViewComponent + Vident example with Stimulus
-Consider the following ERB that might be part of an application's views. The app uses `ViewComponent`, `Stimulus` and `Vident`.
-The Greeter is a component that displays a text input and a button. When the button is clicked, the text input's value is
-used to greet the user. At the same time the button changes to be a 'reset' button, which resets the greeting when clicked again.
+```html
+<!-- First button with default count -->
+<button class="bg-blue-500 hover:bg-blue-700 text-white"
+        data-controller="button-component"
+        data-action="click->button-component#handleClick"
+        data-button-component-clicked-count-value="0"
+        data-button-component-loading-duration-value="1000"
+        data-button-component-loading-class="opacity-50 cursor-wait"
+        id="button-component-123">
+  Save
+</button>
+<!-- Second button with pre-set count -->
+<button class="bg-blue-500 hover:bg-blue-700 text-white"
+        data-controller="button-component"
+        data-action="click->button-component#handleClick"
+        data-button-component-clicked-count-value="5"
+        data-button-component-loading-duration-value="1000"
+        data-button-component-loading-class="opacity-50 cursor-wait"
+        id="button-component-456">
+  Submit
+</button>
+```
+## Core Concepts
+### Component Properties
+Vident uses the Literal gem to provide type-safe component properties:
-![ex1.gif](examples/ex1.gif)
+```ruby
+class CardComponent < Vident::ViewComponent::Base
+  # Basic property with type
+  prop :title, String
+  # Property with default value
+  prop :subtitle, String, default: ""
+  # Nullable property
+  prop :image_url, _Nilable(String)
+  # Property with validation
+  prop :size, _Union(:small, :medium, :large), default: :medium
+  # Boolean property (creates predicate method)
+  prop :featured, _Boolean, default: false
+end
+```
-```erb
-<%# app/views/home/index.html.erb %>
-<!-- ... -->
-<!-- render the Greeter ViewComponent (that uses Vident) -->
-<%= render ::GreeterComponent.new(cta: "Hey!", html_options: {class: "my-4"}) do |greeter| %>
-  <%# this component has a slot called `trigger` that renders a `ButtonComponent` (which also uses Vident) %>
-  <% greeter.with_trigger(
-       # The button component has attributes that are typed
-       before_clicked: "Greet",
-       after_clicked: "Greeted! Reset?",
-       # A stimulus action is added to the button that triggers the `greet` action on the greeter stimulus controller.
-       # This action will be added to any defined on the button component itself
-       actions: [
-         greeter.action(:click, :greet),
-       ],
-       # We can also override the default button classes of our component, or set other HTML attributes
-       html_options: {
-         class: "bg-red-500 hover:bg-red-700"
-       }
-     ) %>
-<% end %>
+### Built-in Properties
-<!-- ... -->
-```
+Every Vident component includes these properties:
-The output HTML of the above, using Vident, is:
-```html
-<div class="greeter-component py-2 my-4"
-     data-controller="greeter-component"
-     data-greeter-component-pre-click-class="text-md text-gray-500"
-     data-greeter-component-post-click-class="text-xl text-blue-700"
-     id="greeter-component-1599855-6">
-  <input type="text"
-         data-greeter-component-target="name"
-         class="shadow appearance-none border rounded py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline">
-  <button class="button-component ml-4 whitespace-no-wrap bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded bg-red-500 hover:bg-red-700"
-          data-controller="button-component"
-          data-action="click->greeter-component#greet button-component#changeMessage"
-          data-button-component-after-clicked-message="Greeted! Reset?"
-          data-button-component-before-clicked-message="Greet"
-          id="button-component-7799479-7">Hey!</button>
-  <!-- you can also use the `target_tag` helper to render targets -->
-  <span class="ml-4 text-md text-gray-500"
-        data-greeter-component-target="output">
-    ...
-  </span>
-</div>
-```
+- `element_tag` - The HTML tag for the root element (default: `:div`)
+- `id` - The component's DOM ID (auto-generated if not provided)
+- `classes` - Additional CSS classes
+- `html_options` - Hash of HTML attributes
-Let's look at the components in more detail.
+### Root Element Rendering
-The main component is the `GreeterComponent`:
+The `root_element` helper method renders your component's root element with all configured attributes:
 ```ruby
-# app/components/greeter_component.rb
+# In your component class
+def element_classes
+  ["card", featured? ? "card-featured" : nil]
+end
+private
-class GreeterComponent < ::Vident::ViewComponent::Base
-  renders_one :trigger, ButtonComponent
+def root_element_attributes
+  {
+    html_options: { role: "article", "aria-label": title }
+  }
 end
 ```
 ```erb
-<%# app/components/greeter_component.html.erb %>
-<%# Rendering the `root` element creates a tag which has stimulus `data-*`s, a unique id & other attributes set. %>
-<%# The stimulus controller name (identifier) is derived from the component name, and then used to generate the relavent data attribute names. %>
-<%= render root named_classes: {
-  pre_click: "text-md text-gray-500", # named classes are exposed to Stimulus as `data-<controller>-<n>-class` attributes
-  post_click: "text-xl text-blue-700",
-  html_options: {class: "py-2"}
-} do |greeter| %>
-  <%# `greeter` is the root element and exposes methods to generate stimulus targets and actions %>
-  <input type="text"
-         <%= greeter.as_target(:name) %>
-         class="shadow appearance-none border rounded py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline">
-  <%# Render the slot %>
-  <%= trigger %>
-  <%# you can also use the `target_tag` helper to render targets %>
-  <%= greeter.target_tag(
-        :span,
-        :output,
-        # Stimulus named classes can be referenced to set class attributes at render time
-        class: "ml-4 #{greeter.named_classes(:pre_click)}"
-      ) do %>
-    ...
-  <% end %>
+<%# In your template %>
+<%= root_element do %>
+  <h2><%= title %></h2>
+  <p><%= subtitle %></p>
 <% end %>
 ```
-```js
-// app/components/greeter_component_controller.js
+## Component DSL
-import { Controller } from "@hotwired/stimulus"
+### ViewComponent Integration
-// This is a Stimulus controller that is automatically registered for the `GreeterComponent`
-// and is 'sidecar' to the component. You can see that while in the ERB we use Ruby naming conventions
-// with snake_case Symbols, here they are converted to camelCase names. We can also just use camelCase
-// in the ERB if we want.
-export default class extends Controller {
-  static targets = [ "name", "output" ]
-  static classes = [ "preClick", "postClick" ]
-  greet() {
-    this.clicked = !this.clicked;
-    this.outputTarget.classList.toggle(this.preClickClasses, !this.clicked);
-    this.outputTarget.classList.toggle(this.postClickClasses, this.clicked);
-    if (this.clicked)
-      this.outputTarget.textContent = `Hello, ${this.nameTarget.value}!`
-    else
-      this.clear();
-  }
+```ruby
+class MyComponent < Vident::ViewComponent::Base
+  # Component code
+end
-  clear() {
-    this.outputTarget.textContent = '...';
-    this.nameTarget.value = '';
-  }
-}
+# Or with an application base class
+class ApplicationComponent < Vident::ViewComponent::Base
+  # Shared configuration
+end
+class MyComponent < ApplicationComponent
+  # Component code
+end
 ```
-The slot renders a `ButtonComponent` component:
+### Phlex Integration
 ```ruby
-# app/components/button_component.rb
-class ButtonComponent < ::Vident::Typed::ViewComponent::Base
-  # The attributes can specify an expected type, a default value and if nil is allowed.
-  attribute :after_clicked, String, default: "Greeted!"
-  attribute :before_clicked, String, allow_nil: false
-  # This example is a templateless ViewComponent.
-  def call
-    # The button is rendered as a <button> tag with an click action on its own controller.
-    render root(
-      element_tag: :button,
-      # We can define actions as arrays of Symbols, or pass manually manually crafted strings.
-      # Here we specify the action name only, implying an action on the current components controller
-      # and the default event type of `click`.
-      actions: [:change_message],
-      # Alternatively: [:click, :change_message] or ["click", "changeMessage"] or even "click->button-component#changeMessage"
-      # A couple of data values are also set which will be available to the controller
-      data_maps: [{after_clicked_message: after_clicked, before_clicked_message: before_clicked}],
-      # The <button> tag has a default styling set directly on it. Note that
-      # if not using utility classes, you can style the component using its
-      # canonical class name (which is equal to the component's stimulus identifier),
-      # in this case `button-component`.
-      html_options: {class: "ml-4 whitespace-no-wrap bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"}
-    ) do
-      @before_clicked
+class MyComponent < Vident::Phlex::HTML
+  def view_template
+    root do
+      h1 { "Hello from Phlex!" }
     end
   end
 end
 ```
-```js
-// app/components/button_component_controller.js
-import { Controller } from "@hotwired/stimulus"
-export default class extends Controller {
-  // The action is in camelCase.
-  changeMessage() {
-    this.clicked = !this.clicked;
-    // The data attributes have their naming convention converted to camelCase.
-    this.element.textContent = this.clicked ? this.data.get("afterClickedMessage") : this.data.get("beforeClickedMessage");
-  }
-}
+## Stimulus Integration
-```
+Vident provides comprehensive Stimulus.js integration to add interactivity to your components.
-### Usage
-How to use my plugin.
+### Declarative Stimulus DSL
-### Installation
-Add this line to your application's Gemfile:
+Use the `stimulus` block for clean, declarative configuration:
 ```ruby
-gem "vident-typed-view_component"
-```
-And then execute:
-```bash
-$ bundle
-```
-Or install it yourself as:
-```bash
-$ gem install vident-typed-view_component
+class ToggleComponent < Vident::ViewComponent::Base
+  prop :expanded, _Boolean, default: false
+  stimulus do
+    # Define actions the controller responds to
+    actions :toggle, :expand, :collapse
+    # Define targets for DOM element references
+    targets :button, :content
+    # Define static values
+    values animation_duration: 300
+    # Define dynamic values using procs (evaluated in component context)
+    values item_count: -> { @items.count }
+    values current_state: proc { expanded? ? "open" : "closed" }
+    # Map values from component props
+    values_from_props :expanded
+    # Define CSS classes for different states
+    classes expanded: "block",
+            collapsed: "hidden",
+            transitioning: "opacity-50"
+  end
+end
 ```
----
-## gem: vident-view_component
-# Vident::ViewComponent
+### Dynamic Values and Classes with Procs
-[ViewComponent](https://viewcomponent.org/) powered [Vident](https://github.com/stevegeek/vident) components.
+The Stimulus DSL supports dynamic values and classes using procs or lambdas that are evaluated in the component instance context:
 ```ruby
-class ApplicationComponent < ::Vident::ViewComponent::Base
+class DynamicComponent < Vident::ViewComponent::Base
+  prop :items, _Array(Hash), default: -> { [] }
+  prop :loading, _Boolean, default: false
+  prop :user, _Nilable(User)
+  stimulus do
+    # Mix static and dynamic values in a single call
+    values(
+      static_config: "always_same",
+      item_count: -> { @items.count },
+      loading_state: proc { @loading ? "loading" : "idle" },
+      user_role: -> { @user&.role || "guest" },
+      api_endpoint: -> { Rails.application.routes.url_helpers.api_items_path }
+    )
+    # Mix static and dynamic classes
+    classes(
+      base: "component-container",
+      loading: -> { @loading ? "opacity-50 cursor-wait" : "" },
+      size: proc { @items.count > 10 ? "large" : "small" },
+      theme: -> { current_user&.dark_mode? ? "dark" : "light" }
+    )
+    # Dynamic actions and targets
+    actions -> { @loading ? [] : [:click, :submit] }
+    targets -> { @expanded ? [:content, :toggle] : [:toggle] }
+  end
+  private
+  def current_user
+    @current_user ||= User.current
+  end
 end
 ```
-For more details see [vident](https://github.com/stevegeek/vident).
-### Examples
+Procs have access to instance variables, component methods, and Rails helpers.
-Before we dive into a specific example note that there are some components implemented in the `test/dummy/app/components`.
+**Important**: Each proc returns a single value for its corresponding stimulus attribute. If a proc returns an array, that entire array is treated as a single value, not multiple separate values. To provide multiple values for an attribute, use multiple procs or mix procs with static values:
-Try them out by starting Rails:
-```bash
-cd test/dummy
-bundle install
-rails assets:precompile
-rails s
+```ruby
+stimulus do
+  # Single proc returns a single value (even if it's an array)
+  actions -> { @expanded ? [:click, :submit] : :click }
+  # Multiple procs provide multiple values
+  actions -> { @can_edit ? :edit : nil },
+          -> { @can_delete ? :delete : nil },
+          :cancel  # static value
+  # This results in: [:edit, :delete, :cancel] (assuming both conditions are true)
+end
 ```
-and visiting http://localhost:3000
-### A Vident component example (without Stimulus)
-First is an example component that uses `Vident::ViewComponent::Base` but no Stimulus features.
+### Scoped Custom Events
-It is an avatar component that can either be displayed as an image or as initials. It supports numerous sizes and shapes and can optionally have a border. It also generates a cache key for use in fragment caching or etag generation.
+Vident provides helper methods to generate scoped event names for dispatching custom events that are unique to your component:
 ```ruby
-class AvatarComponent < ::Vident::ViewComponent::Base
-  include ::Vident::Tailwind
-  include ::Vident::Caching
-  no_stimulus_controller
-  with_cache_key :attributes
-  attribute :url, allow_nil: true
-  attribute :initials, allow_nil: false
-  attribute :shape, default: :circle
-  attribute :border, default: false
-  attribute :size, default: :normal
-  private
-  def default_html_options
-    if image_avatar?
-      { class: "inline-block object-contain", src: url, alt: t(".image") }
-    else
-      { class: "inline-flex items-center justify-center bg-gray-500" }
-    end
+class MyComponent < Vident::ViewComponent::Base
+  stimulus do
+    # Define an action that responds to a scoped event
+    actions [stimulus_scoped_event_on_window(:data_loaded), :handle_data_loaded]
   end
-  def element_classes
-    [size_classes, shape_class, border? ? "border" : ""]
+  def handle_click
+    # Dispatch a scoped event from JavaScript
+    # This would generate: "my-component:dataLoaded"
+    puts stimulus_scoped_event(:data_loaded)
+    # For window events, this generates: "my-component:dataLoaded@window"
+    puts stimulus_scoped_event_on_window(:data_loaded)
   end
+end
-  alias_method :image_avatar?, :url?
+# Available as both class and instance methods:
+MyComponent.stimulus_scoped_event(:data_loaded)      # => "my-component:dataLoaded"
+MyComponent.new.stimulus_scoped_event(:data_loaded)  # => "my-component:dataLoaded"
+```
-  def shape_class
-    (shape == :circle) ? "rounded-full" : "rounded-md"
-  end
+This is useful for:
+- Dispatching events from Stimulus controllers to communicate between components
+- Creating unique event names that won't conflict with other components
+- Setting up window-level event listeners with scoped names
-  def size_classes
-    case size
-    when :tiny
-      "w-6 h-6"
-    when :small
-      "w-8 h-8"
-    when :medium
-      "w-12 h-12"
-    when :large
-      "w-14 h-14"
-    when :x_large
-      "sm:w-24 sm:h-24 w-16 h-16"
-    when :xx_large
-      "sm:w-32 sm:h-32 w-24 h-24"
-    else
-      "w-10 h-10"
-    end
-  end
+### Manual Stimulus Configuration
-  def text_size_class
-    case size
-    when :tiny
-      "text-xs"
-    when :small
-      "text-xs"
-    when :medium
-      "text-lg"
-    when :large
-      "sm:text-xl text-lg"
-    when :extra_large
-      "sm:text-2xl text-xl"
-    else
-      "text-medium"
-    end
+For more control, configure Stimulus attributes manually:
+```ruby
+class CustomComponent < Vident::ViewComponent::Base
+  private
+  def root_element_attributes
+    {
+      element_tag: :article,
+      stimulus_controllers: ["custom", "analytics"],
+      stimulus_actions: [
+        [:click, :handleClick],
+        [:custom_event, :handleCustom]
+      ],
+      stimulus_values: {
+        endpoint: "/api/data",
+        refresh_interval: 5000
+      },
+      stimulus_targets: {
+        container: true
+      }
+    }
   end
 end
 ```
+or you can use tag helpers to generate HTML with Stimulus attributes:
 ```erb
-<%= render root(
-             element_tag: image_avatar? ? :img : :div,
-             html_options: default_html_options
-           ) do %>
-  <% unless image_avatar? %>
-    <span class="<%= text_size_class %> font-medium leading-none text-white"><%= initials %></span>
+  <%= content_tag(:input, type: "text", class: "...", data: {**greeter.stimulus_target(:name)}) %>
+  <%= content_tag(:button, @cta, class: "...", data: {**greeter.stimulus_action([:click, :greet])}) do %>
+    <%= @cta %>
   <% end %>
-<% end %>
-```
+  <%= content_tag(:span, class: "...", data: {**greeter.stimulus_target(:output)}) %>
-Example usages:
+  <%# OR use the vident tag helper  %>
-```erb
-<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", initials: "AB" size: :large) %>
-<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", html_options: {alt: "My alt text", class: "object-scale-down"}) %>
-<%= render AvatarComponent.new(initials: "SG", size: :small) %>
-<%= render AvatarComponent.new(initials: "SG", size: :large, html_options: {class: "border-2 border-red-600"}) %>
+  <%= greeter.tag(:input, stimulus_target: :name, type: "text", class: "...") %>
+  <%= greeter.tag(:button, stimulus_action: [:click, :greet], class: "...") do %>
+    <%= @cta %>
+  <% end %>
+  <%= greeter.tag(:span, stimulus_target: :output, class: "...") %>
 ```
-The following is rendered when used `render AvatarComponent.new(initials: "SG", size: :small, border: true)`:
+or in your Phlex templates:
-```html
-<div class="avatar-component w-8 h-8 rounded-full border inline-flex items-center justify-center bg-gray-500" id="avatar-component-9790427-12">
-  <span class="text-xs font-medium leading-none text-white">SG</span>
-</div>
+```ruby
+root_element do |greeter|
+  input(type: "text", data: {**greeter.stimulus_target(:name)}, class: %(...))
+  trigger_or_default(greeter)
+  greeter.tag(:span, stimulus_target: :output, class: "ml-4 #{greeter.class_list_for_stimulus_classes(:pre_click)}") do
+    plain %( ... )
+  end
+end
 ```
-The following is rendered when used `render AvatarComponent.new(url: "https://i.pravatar.cc/300", initials: "AB", html_options: {alt: "My alt text", class: "block"})`:
+or directly in the ViewComponent template (eg with ERB) using the `as_stimulus_*` helpers
-```html
-<img src="https://i.pravatar.cc/300" alt="My alt text" class="avatar-component w-10 h-10 rounded-full object-contain block" id="avatar-component-7083941-11">
+```erb
+  <%# HTML embellishment approach, most familiar to working with HTML in ERB, but is injecting directly into open HTML tags... %>
+  <input type="text"
+         <%= greeter.as_stimulus_targets(:name) %>
+         class="...">
+  <button <%= greeter.as_stimulus_actions([:click, :greet]) %>
+          class="...">
+    <%= @cta %>
+  </button>
+  <span <%= greeter.as_stimulus_targets(:output) %> class="..."></span>
 ```
-----
-![Example](examples/avatar.png)
+### Stimulus Helpers in Templates
-### Usage
-How to use my plugin.
+Vident provides helper methods for generating Stimulus attributes:
-### Installation
-Add this line to your application's Gemfile:
-```ruby
-gem "vident-view_component"
+```erb
+<%= render root do |component| %>
+  <!-- Create a target -->
+  <div <%= component.as_target(:content) %>>
+    Content here
+  </div>
+  <!-- Create an action -->
+  <button <%= component.as_action(:click, :toggle) %>>
+    Toggle
+  </button>
+  <!-- Use the tag helper -->
+  <%= component.tag :div, stimulus_target: :output, class: "mt-4" do %>
+    Output here
+  <% end %>
+  <!-- Multiple targets/actions -->
+  <input <%= component.as_targets(:input, :field) %>
+         <%= component.as_actions([:input, :validate], [:change, :save]) %>>
+<% end %>
 ```
-And then execute:
-```bash
-$ bundle
-```
+### Stimulus Outlets
-Or install it yourself as:
-```bash
-$ gem install vident-view_component
-```
+Connect components via Stimulus outlets:
----
-## gem: vident-better_html
-# Vident::BetterHtml
-Short description and motivation.
-### Usage
-How to use my plugin.
+### Stimulus Controller Naming
-```ruby
-BetterHtml.config = BetterHtml::Config.new(YAML.load(File.read(".better-html.yml")))
+Vident automatically generates Stimulus controller names based on your component class:
-BetterHtml.configure do |config|
-  config.template_exclusion_filter = proc { |filename| !filename.start_with?(Rails.root.to_s) }
-end
-# ViewComponent needs to do this hack to work in certain cases
-# see https://github.com/Shopify/better-html/pull/98
-class BetterHtml::HtmlAttributes
-  alias_method :to_s_without_html_safe, :to_s
+- `ButtonComponent` → `button-component`
+- `Admin::UserCardComponent` → `admin--user-card-component`
+- `MyApp::WidgetComponent` → `my-app--widget-component`
-  def to_s
-    to_s_without_html_safe.html_safe
-  end
-end
-```
+### Working with Child Components
-### Installation
-Add this line to your application's Gemfile:
+Setting Stimulus configuration between parent and child components:
 ```ruby
-gem "vident-better_html"
-```
-And then execute:
-```bash
-$ bundle
+class ParentComponent < Vident::ViewComponent::Base
+  renders_one :a_nested_component, ButtonComponent
+  stimulus do
+    actions :handleTrigger
+  end
+end
 ```
-Or install it yourself as:
-```bash
-$ gem install vident-better_html
+```erb
+<%= root_element do |parent| %>
+  <% parent.with_a_nested_component(
+    text: "Click me",
+    stimulus_actions: [
+      parent.stimulus_action(:click, :handleTrigger)
+    ]
+  ) %>
+<% end %>
 ```
----
+This creates a nested component that once clicked triggers the parent components `handleTrigger` action.
-## gem: vident-phlex
+## Other Features
-# Vident::Phlex
+### Custom Element Tags
-[Phlex](https://phlex.fun/) powered [Vident](https://github.com/stevegeek/vident) components.
+Change the root element tag dynamically:
 ```ruby
-class ApplicationComponent < ::Vident::Phlex::HTML
+class LinkOrButtonComponent < Vident::ViewComponent::Base
+  prop :url, _Nilable(String)
+  private
+  def root_element_attributes
+    {
+      element_tag: url? ? :a : :button,
+      html_options: {
+        href: url,
+        type: url? ? nil : "button"
+      }.compact
+    }
+  end
 end
 ```
-For more details see [vident](https://github.com/stevegeek/vident).
-### Usage
-How to use my plugin.
+### Intelligent Class Management
-### Installation
-Add this line to your application's Gemfile:
+Vident intelligently merges CSS classes from multiple sources:
 ```ruby
-gem "vident-phlex"
-```
-And then execute:
-```bash
-$ bundle
+class StyledComponent < Vident::ViewComponent::Base
+  prop :variant, Symbol, default: :default
+  private
+  # Classes on the root element
+  def element_classes
+    ["base-class", variant_class]
+  end
+  def variant_class
+    case @variant
+    when :primary then "text-blue-600 bg-blue-100"
+    when :danger then "text-red-600 bg-red-100"
+    else "text-gray-600 bg-gray-100"
+    end
+  end
+end
 ```
-Or install it yourself as:
-```bash
-$ gem install vident-phlex
+Usage:
+```erb
+<!-- All classes are intelligently merged -->
+<%= render StyledComponent.new(
+  variant: :primary,
+  classes: "rounded-lg shadow"
+) %>
+<!-- Result: class="base-class text-blue-600 bg-blue-100 rounded-lg shadow" -->
 ```
----
-## gem: vident-tailwind
-# Vident::Tailwind
-Short description and motivation.
-### Usage
-How to use my plugin.
+### Tailwind CSS Integration
-### Installation
-Add this line to your application's Gemfile:
+Vident includes built-in support for Tailwind CSS class merging when the `tailwind_merge` gem is available:
 ```ruby
-gem "vident-tailwind"
-```
-And then execute:
-```bash
-$ bundle
-```
-Or install it yourself as:
-```bash
-$ gem install vident-tailwind
+class TailwindComponent < Vident::ViewComponent::Base
+  prop :size, Symbol, default: :medium
+  private
+  def element_classes
+    # Conflicts with size_class will be resolved automatically
+    "p-2 text-sm #{size_class}"
+  end
+  def size_class
+    case @size
+    when :small then "p-1 text-xs"
+    when :large then "p-4 text-lg"
+    else "p-2 text-base"
+    end
+  end
+end
 ```
----
+### Component Caching
-## gem: vident-typed-minitest
-# Vident::Typed::Minitest
-Short description and motivation.
-### Usage
-How to use my plugin.
-### Installation
-Add this line to your application's Gemfile:
+Enable fragment caching for expensive components:
 ```ruby
-gem "vident-typed-minitest"
-```
-And then execute:
-```bash
-$ bundle
+class ExpensiveComponent < Vident::ViewComponent::Base
+  include Vident::Caching
+  with_cache_key :to_h  # Cache based on all attributes
+  # or
+  with_cache_key :id, :updated_at  # Cache based on specific attributes
+end
 ```
-Or install it yourself as:
-```bash
-$ gem install vident-typed-minitest
+```erb
+<% cache component.cache_key do %>
+  <%= render component %>
+<% end %>
 ```
----
-## gem: vident-typed-phlex
-# Vident::Typed::Phlex
+## Testing
-Adds typed attributes to Vident Phlex based components.
+Vident components work seamlessly with testing frameworks that support ViewComponent or Phlex.
-```ruby
-class ApplicationComponent < ::Vident::Typed::Phlex::HTML
-end
-```
-For more details see [vident](https://github.com/stevegeek/vident).
-### Usage
-How to use my plugin.
-### Installation
-Add this line to your application's Gemfile:
+## Development
-```ruby
-gem "vident-typed-phlex"
-```
+### Running Tests
-And then execute:
 ```bash
-$ bundle
+# Run all tests
+bin/rails test
 ```
-Or install it yourself as:
-```bash
-$ gem install vident-typed-phlex
-```
+### Local Development
----
+```bash
+# Clone the repository
+git clone https://github.com/stevegeek/vident.git
+cd vident
+# Install dependencies
+bundle install
-## gem: vident-typed
+# Run the dummy app
+cd test/dummy
+rails s
+```
-# Vident::Typed
-Short description and motivation.
+## Contributing
-### Usage
-How to use my plugin.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Write tests for your changes
+4. Commit your changes (`git commit -am 'Add new feature'`)
+5. Push to the branch (`git push origin feature/my-new-feature`)
+6. Create a Pull Request
-### Installation
-Add this line to your application's Gemfile:
+## License
-```ruby
-gem "vident-typed"
-```
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
-And then execute:
-```bash
-$ bundle
-```
+## Credits
-Or install it yourself as:
-```bash
-$ gem install vident-typed
-```
+Vident is maintained by [Stephen Ierodiaconou](https://github.com/stevegeek).
----
+Special thanks to the ViewComponent and Phlex communities for their excellent component frameworks that Vident builds upon.