vident 0.6.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34159659a1af3114685b2170e3c2f9667f1b87cc1a03082f99abb45d2b86bec4
-  data.tar.gz: 4bf98392df9f0f4c531930bcd26245c91287d48065941374eb4715ccfa15d439
+  metadata.gz: 6907ba81655f5cf18c500edcdfa43c8786d8b2463573a1dadd0dd51ba1637ea3
+  data.tar.gz: 72964008e3a0c64172726f4edfe2ba030f66018a08713e8bad529eae4dda45d7
 SHA512:
-  metadata.gz: d5826f1ccef2cbfec3fe8fbf717e81441c438c5091d0ff60ff48a84272700bef7c4fdc33b9f51e4a6293cecae8d0d59802b03667d11eb8fd3c69ff25ca88d552
-  data.tar.gz: bd33d01fef040b09f5ca97a259d4e2f035d4fb4aead3c7a4115f758423ec247b676b8f37eee5b1a96fe8ba2dbb20dd0498c9e68fb2de972f3dd93dc9eca7885a
+  metadata.gz: dea9a3d4e70478870b829fe050cfbbcd89dad15866a4a4334d8661d217f56e30a47b81285f279008bfaf762a406e7356ca33d56c607e98a34ddde6b2bf26df13
+  data.tar.gz: ea963a8ba620e0c510c8e4fadf02eb0293159398c576dbd9554bffc01fd7bb930e7b9d31e2011710ab7a4c41a2929a2e8964cceee2bdfe35827a8dedcad148b4

data/README.md

@@ -1,33 +1,30 @@
 # Vident
 
-Vident helps you create flexible & maintainable component libraries for your application.
+**Vident** is a collection of gems that help you create **flexible** & **maintainable** component libraries for your Rails application.
 
-Vident makes using Stimulus with your [`ViewComponent`](https://viewcomponent.org/) or [`Phlex`](https://phlex.fun) components easier.
+<a href="https://github.com/stevegeek/vident"><img alt="Vident logo" src="https://raw.githubusercontent.com/stevegeek/vident/main/logo-by-sd-256-colors.png" width="180" /></a>
 
-## Things still to do...
+Vident also provides a neat Ruby DSL to make wiring up **Stimulus easier & less error prone** in your view components.
 
-This is a work in progress. Here's what's left to do for first release:
-
-- 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
-- split `vident` into `vident` + `vident-rails` gems (and maybe `vident-rspec`) (Phlex can be used outside of Rails)
-  - possibly also split into `vident-phlex` and `vident-view_component` gems ?
+[`ViewComponent`](https://viewcomponent.org/) and [`Phlex`](https://phlex.fun) supported.
 
 # Motivation
 
 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. 
+and keep me thinking in Ruby.
 
-I have been using Vident with `ViewComponent` in production apps for a while now and it has been constantly
-evolving.
+I have been using Vident with `ViewComponent` in production apps for a while now (and recently `Phlex`!) 
+and it has been constantly evolving.
 
 This gem is a work in progress and I would love to get your feedback and contributions!
 
+
+
+**The docs below need updating**
+
+
+
 ## What does Vident provide?
 
 - `Vident::Component`: A mixin for your `ViewComponent` components or `Phlex` components that provides the a helper to create the
@@ -35,10 +32,51 @@ This gem is a work in progress and I would love to get your feedback and contrib
 
 - `Vident::TypedComponent`: like `Vident::Component` but uses `dry-types` to define typed attributes for your components.
 
+### Various utilities
+
+- `Vident::Tailwind`: 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.
+
+- `Vident::Caching::CacheKey`: a mixin for your vident component which provides a `cache_key` method that can be used to generate a cache key for
+  fragment caching or etag generation.
+
 - `Vident::RootComponent::*` which are 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. Normally you create these
   using the `root` helper method on `Vident::Component`/`Vident::TypedComponent`.
 
+# Features
+
+- 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 (only with ViewComponent and with 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`
+
+
+## Things still to do...
+
+This is a work in progress. Here's what's left to do for first release:
+
+- 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
+- split `vident` into `vident` + `vident-rails` gems (and maybe `vident-rspec`) (Phlex can be used outside of Rails)
+    - possibly also split into `vident-phlex` and `vident-view_component` gems ?
+
+
 
 # Examples
 
@@ -58,7 +96,141 @@ rails s
 
 and visit http://localhost:3000
 
-## ViewComponent + Vident example
+
+## A Vident component example (without Stimulus)
+
+First is an example component that uses `Vident::TypedComponent` 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 < ViewComponent::Base
+  include ::Vident::TypedComponent
+  include ::Vident::Tailwind
+  include ::Vident::Caching::CacheKey
+
+  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 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: html_options
+           ) do %>
+  <% unless image_avatar? %>
+    <span class="<%= text_size_class %> font-medium leading-none text-white"><%= initials %></span>
+  <% end %>
+<% end %>
+
+```
+
+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`.
 
@@ -73,7 +245,7 @@ used to greet the user. At the same time the button changes to be a 'reset' butt
 <!-- ... -->
 
 <!-- render the Greeter ViewComponent (that uses Vident) -->
-<%= render ::GreeterComponent.new do |greeter| %>
+<%= 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.trigger(
        
@@ -100,7 +272,7 @@ used to greet the user. At the same time the button changes to be a 'reset' butt
 The output HTML of the above, using Vident, is:
 
 ```html 
-<div class="greeter-component" 
+<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" 
@@ -113,7 +285,7 @@ The output HTML of the above, using Vident, is:
           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">Greet</button>
+          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">
@@ -144,7 +316,8 @@ end
 
 <%= 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"
+  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 %>
@@ -257,31 +430,44 @@ export default class extends Controller {
 
 ## Installation
 
-Add this line to your application's Gemfile:
+This gem (`vident`) provides only base functionality but there are a number of gems that provide additional functionality
+or a "out of the box" experience.
 
-```ruby
-gem 'vident'
-```
+It's a "pick your own adventure" approach. You decide what frameworks and features you want to use
+and add the gems as needed.
 
-Also ensure you have installed your chosen view component library, eg:
+Start by asking yorself these questions:
 
-```ruby
-gem 'view_component'
-```
+_Q1. Do you want to use [`ViewComponent`](https://viewcomponent.org/) or [`Phlex`](https://www.phlex.fun/) for your view components?_
 
-or
+_Q2. Do you want to use attributes with runtime type checking (powered by [`dry-types`](https://github.com/dry-rb/dry-types)), or not?_
 
-```ruby
-gem 'phlex' # Must be version 0.5 or higher
-```
+Depending on your answer to Q1, you can choose from either the `*-view_component` or `*-phlex` gems,
+then depending on your answer to Q2, you can choose from either the untyped or `*-typed-*` gems.
 
-or **both**!
+Note you can also use some or all of them in the same app.
 
-If you want to use typed attributes you must also include `dry-struct`
+- [`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
+
+_Q3. Do you use or want to use [BetterHTML](https://github.com/Shopify/better-html) in your Rails project?_
+
+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.
+Note that `vident-better_html` automatically enables `better_html` support in Vident root components.
+
+_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. 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/).
+
+Finally if none of the above gems suit your needs, you can always just use base `vident` gems to roll your own
+solution:
+
+- [`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
 
-```ruby
-gem 'dry-struct'
-```
 
 And then execute:
 

data/Rakefile

@@ -1,14 +1,3 @@
-# frozen_string_literal: true
+require "bundler/setup"
 
 require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
-
-require "standard/rake"
-
-task default: %i[test standard]

data/lib/tasks/vident_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :vident do
+#   # Task goes here
+# end

data/lib/vident/attributes/not_typed.rb

@@ -15,6 +15,7 @@ module Vident
           options = self.class.attribute_options
           default = options&.dig(attr_name, :default)
           allow_nil = options[attr_name] ? options[attr_name].fetch(:allow_nil, true) : true
+
           if attributes&.include? attr_name
             value = attributes[attr_name]
             @__attributes[attr_name] = (value.nil? && default) ? default : value
@@ -41,6 +42,8 @@ module Vident
       class_methods do
         def inherited(subclass)
           subclass.instance_variable_set(:@attribute_ivar_names, @attribute_ivar_names.clone)
+          subclass.instance_variable_set(:@attribute_names, @attribute_names.clone)
+          subclass.instance_variable_set(:@attribute_options, @attribute_options.clone)
           super
         end
 

data/lib/vident/base.rb

@@ -33,15 +33,7 @@ module Vident
       end
 
       def identifier_name_path
-        if phlex_component?
-          name.remove("Views::").underscore
-        else
-          name.underscore
-        end
-      end
-
-      def phlex_component?
-        @phlex_component ||= ancestors.map(&:name).include?("Phlex::HTML")
+        name.underscore
       end
 
       private
@@ -52,7 +44,7 @@ module Vident
           def #{attr_name}
             #{@attribute_ivar_names[attr_name]}
           end
-
+  
           def #{attr_name}?
             #{@attribute_ivar_names[attr_name]}.present?
           end
@@ -95,25 +87,6 @@ module Vident
 
     # HTML and attribute definition and creation
 
-    # Helper to create the main element
-    def parent_element(**options)
-      @parent_element ||= begin
-        # Note: we cant mix phlex and view_component render contexts
-        klass = if self.class.phlex_component?
-          RootComponent::UsingPhlexHTML
-        else
-          RootComponent::UsingViewComponent
-        end
-        element_attrs = options
-          .except(:id, :element_tag, :html_options, :controller, :controllers, :actions, :targets, :named_classes, :data_maps)
-          .merge(
-            stimulus_options_for_component(options)
-          )
-        klass.new(**element_attrs)
-      end
-    end
-    alias_method :root, :parent_element
-
     # FIXME: if we call them before `root` we will setup the root element before we intended
     # The separation between component and root element is a bit messy. Might need rethinking.
     delegate :action, :target, :named_classes, to: :root
@@ -155,6 +128,12 @@ module Vident
 
     private
 
+    def parent_element_attributes(options)
+      options
+        .except(:id, :element_tag, :html_options, :controller, :controllers, :actions, :targets, :named_classes, :data_maps)
+        .merge(stimulus_options_for_component(options))
+    end
+
     # Prepare the stimulus attributes for a StimulusComponent
     def stimulus_options_for_component(options)
       {

data/lib/vident/component.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "./attributes/not_typed"
-
 module Vident
   module Component
     extend ActiveSupport::Concern

data/lib/vident/engine.rb

@@ -0,0 +1,15 @@
+module Vident
+  class Engine < ::Rails::Engine
+    lib_path = File.expand_path("../../../lib/", __FILE__)
+    config.autoload_paths << lib_path
+    config.eager_load_paths << lib_path
+
+    config.before_initialize do
+      Rails.autoloaders.each do |autoloader|
+        autoloader.inflector.inflect(
+          "version" => "VERSION"
+        )
+      end
+    end
+  end
+end