vident 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34159659a1af3114685b2170e3c2f9667f1b87cc1a03082f99abb45d2b86bec4
-  data.tar.gz: 4bf98392df9f0f4c531930bcd26245c91287d48065941374eb4715ccfa15d439
+  metadata.gz: fec9413d88c42202dce9386932c39b6caee8add4a12bc3983447226785da0e3c
+  data.tar.gz: aaf6f4626cd32a21ed12b372a1d340e5a8056c37e20e059052053a0ce56a59cb
 SHA512:
-  metadata.gz: d5826f1ccef2cbfec3fe8fbf717e81441c438c5091d0ff60ff48a84272700bef7c4fdc33b9f51e4a6293cecae8d0d59802b03667d11eb8fd3c69ff25ca88d552
-  data.tar.gz: bd33d01fef040b09f5ca97a259d4e2f035d4fb4aead3c7a4115f758423ec247b676b8f37eee5b1a96fe8ba2dbb20dd0498c9e68fb2de972f3dd93dc9eca7885a
+  metadata.gz: 26fc4e800be45c42a08ea263d7d26bac7f47d987044525d2da3dee52ceed5e799cb1a1372ca94a0d039961702b252d7ddd42c5f387477888fb8e09e12ff06fcd
+  data.tar.gz: 3cf469fcdc2851ea4da8dd683b47642aacd7dadce53b77a0a450d882a7b61a1897054386ac213f756ea6be2784afd5d4afeed348a7b58fc818daaadf418b933a

data/CHANGELOG.md

@@ -13,6 +13,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
+## [0.7.0] - 2023-03-08  
+
+### Added
+
+- new `Vident::Tailwind` module which uses [tailwind_merge](https://github.com/gjtorikian/tailwind_merge) to merge TailwindCSS classes
+
+### Changed
+
+- Removed a dependency on intenal constants from `phlex`
+
 ## [0.6.3] - 2023-03-03
 
 ### Fixed

data/Gemfile

@@ -19,6 +19,7 @@ gem "dry-struct"
 
 gem "phlex-rails"
 gem "better_html"
+gem "tailwind_merge"
 
 # FIXME: versions greater than 2.74 cause issues: https://github.com/ViewComponent/view_component/pull/1571
 gem "view_component", "2.74.1"

data/README.md

@@ -4,19 +4,6 @@ Vident helps you create flexible & maintainable component libraries for your app
 
 Vident makes using Stimulus with your [`ViewComponent`](https://viewcomponent.org/) or [`Phlex`](https://phlex.fun) components easier.
 
-## 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 ?
-
 # Motivation
 
 I love working with Stimulus, but I find manually crafting the data attributes for
@@ -35,10 +22,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 +86,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 +235,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 +262,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 +275,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 +306,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 %>

data/lib/vident/attributes/typed.rb

@@ -7,7 +7,7 @@ if Gem.loaded_specs.has_key? "dry-struct"
   require_relative "./typed_niling_struct"
 
   module Vident
-    # Adapts Dry Types to confinus Typed Attributes. We use dry-struct (see ::Core::NilingStruct) but
+    # Adapts Dry Types to confinus Typed Attributes. We use dry-struct (see TypedNilingStruct) but
     # we could probably also use dry-initializer directly, saving us from maintaining the schema.
     module Attributes
       module Typed

data/lib/vident/caching/cache_key.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 # Rails fragment caching works by either expecting the cached key object to respond to `cache_key` or for that object
-# to be an array or hash. In our case the object maybe an instance of Core::Presenter so here we add a default
-# `cache_key` implementation.
+# to be an array or hash.
 module Vident
   module Caching
     module CacheKey

data/lib/vident/root_component/using_phlex_html.rb

@@ -11,9 +11,10 @@ if Gem.loaded_specs.has_key? "phlex"
           include UsingBetterHTML
         end
 
-        VALID_TAGS = Set[
-          *(Phlex::HTML::VoidElements::REGISTERED_ELEMENTS.keys + Phlex::HTML::StandardElements::REGISTERED_ELEMENTS.keys)
-        ].freeze
+        STANDARD_ELEMENTS = [:a, :abbr, :address, :article, :aside, :b, :bdi, :bdo, :blockquote, :body, :button, :caption, :cite, :code, :colgroup, :data, :datalist, :dd, :del, :details, :dfn, :dialog, :div, :dl, :dt, :em, :fieldset, :figcaption, :figure, :footer, :form, :g, :h1, :h2, :h3, :h4, :h5, :h6, :head, :header, :hgroup, :html, :i, :iframe, :ins, :kbd, :label, :legend, :li, :main, :map, :mark, :menuitem, :meter, :nav, :noscript, :object, :ol, :optgroup, :option, :output, :p, :path, :picture, :pre, :progress, :q, :rp, :rt, :ruby, :s, :samp, :script, :section, :select, :slot, :small, :span, :strong, :style, :sub, :summary, :sup, :svg, :table, :tbody, :td, :template_tag, :textarea, :tfoot, :th, :thead, :time, :title, :tr, :u, :ul, :video, :wbr].freeze
+        VOID_ELEMENTS = [:area, :br, :embed, :hr, :img, :input, :link, :meta, :param, :source, :track, :col].freeze
+
+        VALID_TAGS = Set[*(STANDARD_ELEMENTS + VOID_ELEMENTS)].freeze
 
         # Create a tag for a target with a block containing content
         def target_tag(tag_name, targets, **options, &block)

data/lib/vident/tailwind.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+
+module Vident
+  module Tailwind
+    # Adds a utility class merge specifically for Tailwind, allowing you to more easily specify class overrides
+    # without having to worry about the specificity of the classes.
+    def produce_style_classes(class_names)
+      ::TailwindMerge::Merger.new.merge(dedupe_view_component_classes(class_names))
+    end
+  end
+end

data/lib/vident/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vident
-  VERSION = "0.6.3"
+  VERSION = "0.7.0"
 end

data/lib/vident.rb

@@ -33,7 +33,7 @@ require_relative "vident/base"
 require_relative "vident/component"
 require_relative "vident/typed_component"
 require_relative "vident/caching/cache_key"
-
+require_relative "vident/tailwind" if Gem.loaded_specs.has_key? "tailwind_merge"
 require_relative "vident/testing/attributes_tester"
 require_relative "vident/testing/auto_test"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vident
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-03 00:00:00.000000000 Z
+date: 2023-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -47,6 +47,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/avatar.png
 - examples/ex1.gif
 - lib/tasks/vident.rake
 - lib/vident.rb
@@ -63,6 +64,7 @@ files:
 - lib/vident/root_component/using_phlex_html.rb
 - lib/vident/root_component/using_view_component.rb
 - lib/vident/stable_id.rb
+- lib/vident/tailwind.rb
 - lib/vident/test_case.rb
 - lib/vident/testing/attributes_tester.rb
 - lib/vident/testing/auto_test.rb