vident 0.12.0 → 0.13.0

data/README.md

@@ -1,76 +1,448 @@
 # Vident
 
-**Vident** is a collection of gems that help you create **flexible** & **maintainable** component libraries for your Rails application.
+Vident is a collection of gems that provide a set of tools for building web applications with Ruby on Rails.
 
-<a href="https://github.com/stevegeek/vident"><img alt="Vident logo" src="https://raw.githubusercontent.com/stevegeek/vident/main/docs/images/logo-by-sd-256-colors.png" width="180" /></a>
+## Included Gems
 
-Vident also provides a neat Ruby DSL to make wiring up **Stimulus easier & less error prone** in your view components.
+- `vident`: The core Vident library
+- `vident-better_html`: Better HTML integration for Vident
+- `vident-phlex`: Phlex integration for Vident
+- `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-view_component`: ViewComponent integration for Vident
+- `vident-view_component-caching`: Caching support for Vident ViewComponents
 
-[`ViewComponent`](https://viewcomponent.org/) and [`Phlex`](https://phlex.fun) supported.
+## Directory Structure
 
-# Motivation
+The repository is structured like this:
 
-I love working with Stimulus, but I find manually crafting the data attributes for
-targets and actions error-prone and tedious. Vident aims to make this process easier
-and keep me thinking in Ruby.
+```
+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
+```
 
-Vident has been used with `ViewComponent` and `Phlex` in production apps for a while now 
-but is still evolving.
+### Running Tests
 
-I would love to get your feedback and contributions!
+To run tests for all gems:
 
-## Example
+```bash
+rake test
+```
+
+To run tests for a specific gem:
+
+```bash
+rake test:vident-phlex
+```
 
-The Greeter ViewComponent (that uses Vident):
+### Building and Installing Gems
 
-![docs/images/ex1.gif](docs/images/ex1.gif)
+To build all gems:
 
-Consider a component, the `GreeterComponent`:
+```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
+
+The gems are available as open source under the terms of the [MIT License](LICENSE.txt).
+
+---
+
+# Component Documentation
+
+## gem: vident-better_html
+
+# Vident::BetterHtml
+Short description and motivation.
+
+### Usage
+How to use my plugin.
 
 ```ruby
-# app/components/greeter_component.rb
+BetterHtml.config = BetterHtml::Config.new(YAML.load(File.read(".better-html.yml")))
 
-class GreeterComponent < ::Vident::ViewComponent::Base
-  renders_one :trigger, ButtonComponent
+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
+
+  def to_s
+    to_s_without_html_safe.html_safe
+  end
 end
 ```
 
-with ERB as follows:
+### Installation
+Add this line to your application's Gemfile:
 
-```erb
-<%# app/components/greeter_component.html.erb %>
+```ruby
+gem "vident-better_html"
+```
 
-<%# 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. %>
+And then execute:
+```bash
+$ bundle
+```
 
-<%= render root named_classes: {
-  pre_click: "text-md text-gray-500", # named classes are exposed to Stimulus as `data-<controller>-<name>-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 %>
-    ...
+Or install it yourself as:
+```bash
+$ gem install vident-better_html
+```
+
+---
+
+## gem: vident-phlex
+
+# Vident::Phlex
+
+[Phlex](https://phlex.fun/) powered [Vident](https://github.com/stevegeek/vident) components.
+
+```ruby
+class ApplicationComponent < ::Vident::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:
+
+```ruby
+gem "vident-phlex"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-phlex
+```
+
+---
+
+## gem: vident-tailwind
+
+# Vident::Tailwind
+Short description and motivation.
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-tailwind"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-tailwind
+```
+
+---
+
+## 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:
+
+```ruby
+gem "vident-typed-minitest"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-typed-minitest
+```
+
+---
+
+## gem: vident-typed-phlex
+
+# Vident::Typed::Phlex
+
+Adds typed attributes to Vident Phlex based components.
+
+```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:
+
+```ruby
+gem "vident-typed-phlex"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-typed-phlex
+```
+
+---
+
+## gem: vident-typed-view_component
+
+# Vident::Typed::ViewComponent
+
+Adds typed attributes to Vident ViewComponent components.
+
+```ruby
+class ApplicationComponent < ::Vident::Typed::ViewComponent::Base
+end
+```
+
+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`.
+
+Try them out by starting Rails:
+
+```bash
+cd test/dummy
+bundle install
+rails assets:precompile
+rails s
+```
+
+and visiting http://localhost:3000
+
+
+### 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.
+
+```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
+  end
+
+  def element_classes
+    [size_classes, shape_class, border? ? "border" : ""]
+  end
+
+  alias_method :image_avatar?, :url?
+
+  def shape_class
+    (shape == :circle) ? "rounded-full" : "rounded-md"
+  end
+
+  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
+
+  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
+  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 %>
+
 ```
 
-Now, imagine we render it in a view, and render a `ButtonComponent` in the `trigger` slot:
+Example usages:
 
 ```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) %>
+```
+
+
+The following is rendered when used `render AvatarComponent.new(initials: "SG", size: :small, border: true)`:
+
+```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>
+```
+
+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"})`:
+
+```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">
+```
+
+----
+
+![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.
+
+![ex1.gif](examples/ex1.gif)
+
+```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(
@@ -91,6 +463,8 @@ Now, imagine we render it in a view, and render a `ButtonComponent` in the `trig
        }
      ) %>
 <% end %>
+
+<!-- ... -->
 ```
 
 The output HTML of the above, using Vident, is:
@@ -118,193 +492,375 @@ The output HTML of the above, using Vident, is:
 </div>
 ```
 
-To see this example in more detail, see the [vident-typed-view_component](https://github.com/stevegeek/vident-typed-view_component/tree/main/test/dummy/app/components) test dummy app.
+Let's look at the components in more detail.
 
-# Vident is a collection of gems
+The main component is the `GreeterComponent`:
 
-The core gems are:
-
-- [`vident`](https://github.com/stevegeek/vident) to get the base functionality
-- [`vident-typed`](https://github.com/stevegeek/vident-typed) to optionally define typed attributes for your view components
+```ruby
+# app/components/greeter_component.rb
 
-Gems that provide support for `ViewComponent` and `Phlex`:
+class GreeterComponent < ::Vident::ViewComponent::Base
+  renders_one :trigger, ButtonComponent
+end
+```
 
-- [`vident-view_component`](https://github.com/stevegeek/vident-view_component) for using with `ViewComponent` and untyped attributes
-- [`vident-typed-view_component`](https://github.com/stevegeek/vident-typed-view_component) for using with `ViewComponent` and typed attributes
-- [`vident-phlex`](https://github.com/stevegeek/vident-phlex) for using with `Phlex` and untyped attributes
-- [`vident-typed-phlex`](https://github.com/stevegeek/vident-typed-phlex) for using with `Phlex` and typed attributes
+```erb
+<%# app/components/greeter_component.html.erb %>
 
-There is also:
+<%# 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. %>
 
-- [`vident-typed-minitest`](https://github.com/stevegeek/vident-typed-minitest) to get some test helpers for typed attributes (auto generates inputs to test attributes)
-- [`vident-better_html`](https://github.com/stevegeek/vident-better_html) to support `better_html` if you use it in your Rails app
-- [`vident-tailwind`](https://github.com/stevegeek/vident-tailwind) to get all the benefits of the amazing [`tailwind_merge`](https://github.com/gjtorikian/tailwind_merge/).
+<%= 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 %>
+<% end %>
 
-# Things still to do...
+```
 
-This is a work in progress. Here's what's left to do for first release:
+```js
+// app/components/greeter_component_controller.js
+
+import { Controller } from "@hotwired/stimulus"
+
+// 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();
+  }
+
+  clear() {
+    this.outputTarget.textContent = '...';
+    this.nameTarget.value = '';
+  }
+}
+```
 
-- Iterate on the interfaces and functionality
-- Add tests
-- Make the gem more configurable to fit more use cases
-- Create an example library of a few components for some design system
-  - Create a demo app with `lookbook` and those components
-- Add more documentation
+The slot renders a `ButtonComponent` component:
 
-# About Vident
+```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
+    end
+  end
+end
+```
 
-## What does Vident provide?
+```js  
+// app/components/button_component_controller.js
 
-- Base classes for your `ViewComponent` components or `Phlex` components that provides a helper to create the
-  all important 'root' element component (can be used with templated or template-less components).
+import { Controller } from "@hotwired/stimulus"
 
-- implementations of these root components for creating the 'root' element in your view components. Similar to `Primer::BaseComponent` but
-  exposes a simple API for configuring and adding Stimulus controllers, targets and actions. The root component also handles deduplication
- of classes, creating a unique ID, setting the element tag type, handling possible overrides set at the render site, and determining stimulus controller identifiers etc
+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");
+  }
+}
 
-- a way to define attributes for your components, either typed or untyped, with default values and optional validation.
+```
 
-### Various utilities
+### Usage
+How to use my plugin.
 
-Such as...
+### Installation
+Add this line to your application's Gemfile:
 
-- for Taiwind users, a mixin for your vident component which uses [tailwind_merge](https://github.com/gjtorikian/tailwind_merge) to merge TailwindCSS classes
-  so you can easily override classes when rendering a component.
-- a mixin for your Vident Components which provides a `#cache_key` method that can be used to generate a cache key for
-  fragment caching or etag generation.
-- a test helper for your typed Vident ViewComponents which can be used to generate good and bad attribute/params/inputs 
+```ruby
+gem "vident-typed-view_component"
+```
 
-## All the Features...
+And then execute:
+```bash
+$ bundle
+```
 
-- use Vident with `ViewComponent` or `Phlex` or your own view component system
-- A helper to create the root HTML element for your component, which then handles creation of attributes.
-- Component arguments are defined using the `attribute` method which allows you to define default values, (optionally) types and
-  if blank or nil values should be allowed.
-- You can use the same component in multiple contexts and configure the root element differently in each context by passing
-  options to the component when instantiating it.
-- Stimulus support is built in and sets a default controller name based on the component name.
-- Stimulus actions, targets and classes can be setup using a simple DSL to avoid hand crafting the data attributes.
-- Since data attribute names are generated from the component class name, you can rename easily refactor and move components without
-  having to update the data attributes in your views.
-- Components are rendered with useful class names and IDs to make debugging easier (autogenerated IDs are 'random' but deterministic so they
-  are the same each time a given view is rendered to avoid content changing/Etag changing).
-- (experimental) Support for fragment caching of components (`Vident::Caching` and `Vident::<ViewComponent | Phlex>::Caching`... implementation has caveats)
-- (experimental) A test helper to make testing components easier by utilising type information from the component arguments to render
-  automatically configured good and bad examples of the component.
-- (experimental) support for `better_html`
+Or install it yourself as:
+```bash
+$ gem install vident-typed-view_component
+```
 
+---
 
-## Installation
+## gem: vident-typed
 
-This gem (`vident`) provides only base functionality but there are a number of gems that provide additional functionality
-or an "out of the box" experience.
+# Vident::Typed
+Short description and motivation.
 
-It's a "pick your own adventure" approach. You decide what frameworks and features you want to use
-and add the gems as needed.
+### Usage
+How to use my plugin.
 
-First, add this line to your application's Gemfile:
+### Installation
+Add this line to your application's Gemfile:
 
-```ruby 
-gem 'vident'
+```ruby
+gem "vident-typed"
 ```
 
-Then go on to choose the gems you want to use:
-
-#### Q1. Do you want to use [`ViewComponent`](https://viewcomponent.org/) or [`Phlex`](https://www.phlex.fun/) for your view components?
-
-For ViewComponent use:
+And then execute:
+```bash
+$ bundle
+```
 
-- [`vident-view_component`](https://github.com/stevegeek/vident-view_component)
+Or install it yourself as:
+```bash
+$ gem install vident-typed
+```
 
-For Phlex use:
+---
 
-- [`vident-phlex`](https://github.com/stevegeek/vident-phlex)
+## gem: vident-view_component-caching
 
+# Vident::ViewComponent::Caching
+Short description and motivation.
 
-Note: you can also use both in the same app.
+### Usage
+How to use my plugin.
 
-For example, if you want to use ViewComponent and Phlex in the same app, you might end up with:
+### Installation
+Add this line to your application's Gemfile:
 
 ```ruby
-gem 'vident'
-gem 'vident-view_component'
-gem 'vident-phlex'
+gem "vident-view_component-caching"
 ```
 
-#### Q2. Do you want to build components where the attributes have runtime type checking (powered by [`dry-types`](https://github.com/dry-rb/dry-types))?
-
-If yes, then add `vident-typed` to your Gemfile:
+And then execute:
+```bash
+$ bundle
+```
 
-```ruby
-gem 'vident-typed'
+Or install it yourself as:
+```bash
+$ gem install vident-view_component-caching
 ```
 
-and then use the relavent `*-typed-*` gems for your chosen view component system:
+---
 
-- use [`vident-typed-view_component`](https://github.com/stevegeek/vident-typed-view_component)
-- and/or [`vident-typed-phlex`](https://github.com/stevegeek/vident-typed-phlex)
+## gem: vident-view_component
 
-Note you must also include the gem for the view component system you are using.
+# Vident::ViewComponent
 
-For example, for ViewComponent, you might end up with:
+[ViewComponent](https://viewcomponent.org/) powered [Vident](https://github.com/stevegeek/vident) components.
 
 ```ruby
-gem 'vident'
-gem 'vident-view_component'
-gem 'vident-typed'
-gem 'vident-typed-view_component'
+class ApplicationComponent < ::Vident::ViewComponent::Base
+end
 ```
 
-#### Q3. Do you use or want to use [BetterHTML](https://github.com/Shopify/better-html) in your Rails project?
+For more details see [vident](https://github.com/stevegeek/vident).
 
-If yes, then include [`vident-better_html`](https://github.com/stevegeek/vident-better_html) in your Gemfile alongside `better_html` and your vident gems of choice.
+### Examples
 
-```ruby
-...
-gem 'better_html'
-gem 'vident-better_html'
+Before we dive into a specific example note that there are some components implemented in the `test/dummy/app/components`.
+
+Try them out by starting Rails:
+
+```bash
+cd test/dummy
+bundle install
+rails assets:precompile
+rails s
 ```
 
-Note that `vident-better_html` automatically enables `better_html` support in Vident root components.
+and visiting http://localhost:3000
 
-### Q4. Do you use or want to use [TailwindCSS](https://tailwindcss.com/)?
 
-If yes, then consider adding [`vident-tailwind`](https://github.com/stevegeek/vident-tailwind) to your Gemfile alongside your vident gems of choice. 
+### A Vident component example (without Stimulus)
 
-```ruby
-...
-gem 'vident-tailwind'
-```
+First is an example component that uses `Vident::ViewComponent::Base` but no Stimulus features. 
 
-When creating your components you can then include `Vident::Tailwind` to get all the benefits of the amazing [`tailwind_merge`](https://github.com/gjtorikian/tailwind_merge/).
+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.
 
-### Q5. Did none of the above gems suit your needs?
+```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
+  end
+
+  def element_classes
+    [size_classes, shape_class, border? ? "border" : ""]
+  end
+
+  alias_method :image_avatar?, :url?
+
+  def shape_class
+    (shape == :circle) ? "rounded-full" : "rounded-md"
+  end
+
+  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
+
+  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
+  end
+end
+```
 
-You can always just use base `vident` gems and then roll your own solutions:
+```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 %>
+```
 
-- [`vident`](https://github.com/stevegeek/vident) to get the base functionality to mix with your own view component system
-- [`vident-typed`](https://github.com/stevegeek/vident-typed) to define typed attributes for your own view component system
+Example usages:
 
+```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"}) %>
+```
 
-## Documentation
+The following is rendered when used `render AvatarComponent.new(initials: "SG", size: :small, border: true)`:
 
-See the [docs](docs/) directory and visit the individual gem pages for more information.
+```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>
+```
 
-## Development
+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"})`:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```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">
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+----
 
-## Contributing
+![Example](examples/avatar.png)
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/stevegeek/vident. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/vident/blob/master/CODE_OF_CONDUCT.md).
+### Usage
+How to use my plugin.
 
-## License
+### Installation
+Add this line to your application's Gemfile:
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+```ruby
+gem "vident-view_component"
+```
 
-## Code of Conduct
+And then execute:
+```bash
+$ bundle
+```
 
-Everyone interacting in the Vident project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/vident/blob/master/CODE_OF_CONDUCT.md).
+Or install it yourself as:
+```bash
+$ gem install vident-view_component
+```