view_component-contrib 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cebcea7442b79ea935dd0039c361e813b597c8f63a15a9cd90407635a6a96856
-  data.tar.gz: 98e1aeecc1354a1e619bf75c765aa64f0051ac5ff4d7d0c81fb42425e7da7ae5
+  metadata.gz: 814046bee78131bac6659eaa62160b6dfef169d48d1c5850c03dbe6a00a2ad0f
+  data.tar.gz: ef1ec7cfb3f71bf4db995be3a564dcfc0ff04e72d3c4e116515d216de18b38e8
 SHA512:
-  metadata.gz: 427691d12a38bfcab3c0861506aade1ada63422badb1b207e5fff49cd72bc66c8a6aadfd220b51385ef5abc2166061cd8333afbf14e915058e98bf2899438ad5
-  data.tar.gz: 5eb44287d55acb724d458d6eca667296787215cafced750c9071834ee2203b89327d93ff983b1b2e9879b961e13eb8b5d4f2af237c690a4c3f6bc6cbdaa6654c
+  metadata.gz: 9a5d578dfc44e7318da343a0aefe65946cce2399675d92646fd33db8e7494040d16433a3c409a08185d04c249fbc538e494175dce593a6bde19e27d254926d42
+  data.tar.gz: d01e0bf7f11d866aaab42dafb040e7ee45e4257524888b7bb6768b399d2db03c971867e6b14d839c1a66f7e37d9fe71982e287c8280b3a16811891bc61ee4723

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## master
 
+## 0.2.0 (2023-11-07)
+
+- Introduce style variants. ([@palkan][])
+
+- **Require Ruby 2.7+**. ([@palkan][])
+
+- Add system tests to generator. ([@palkan][])
+
+- Drop Webpack-related stuff from the generator. ([@palkan][])
+
 ## 0.1.6 (2023-11-07)
 
 - Support preview classes named `<component|partial>_preview.rb`. ([@palkan][])

data/README.md

@@ -32,7 +32,6 @@ The command above:
 - Configure `view_component` paths.
 - Adds `ApplicationViewComponent` and `ApplicationViewComponentPreview` classes.
 - Configures testing framework (RSpec or Minitest).
-- Adds required JS/CSS configuration.
 - **Adds a custom generator to create components**.
 
 The custom generator would allow you to create all the required component files in a single command:
@@ -94,6 +93,8 @@ ActiveSupport.on_load(:view_component) do
 end
 ```
 
+You can still continue using preview clases with the `_preview.rb` suffix, they would work as before.
+
 #### Reducing previews boilerplate
 
 In most cases, previews contain only the `default` example and a very simple template (`= render Component.new(**options)`).
@@ -180,9 +181,109 @@ end
 
 If you need more control over your template, you can add a custom `preview.html.*` template (which will be used for all examples in this preview), or even create an example-specific `previews/example.html.*` (e.g. `previews/mobile.html.erb`).
 
+## Style variants
+
+Since v0.2.0, we provide a custom extentions to manage CSS classes and their combinations—**Style Variants**. This is especially useful for project using CSS frameworks such as TailwindCSS.
+
+The idea is to define variants schema in the component class and use it to compile the resulting list of CSS classes. (Inspired by [Tailwind Variants](https://www.tailwind-variants.org) and [CVA variants](https://cva.style/docs/getting-started/variants)).
+
+Consider an example:
+
+```ruby
+class ButtonComponent < ViewComponent::Base
+  include ViewComponentContrib::StyleVariants
+
+  style do
+    base {
+      %w[
+        font-medium bg-blue-500 text-white rounded-full
+      ]
+    }
+    variants {
+      color {
+        primary { %w[bg-blue-500 text-white] }
+        secondary { %w[bg-purple-500 text-white] }
+      }
+      size {
+        sm { "text-sm" }
+        md { "text-base" }
+        lg { "px-4 py-3 text-lg" }
+      }
+    }
+    defaults { {size: :md, color: :primary} }
+  end
+
+  attr_reader :size, :color
+
+  def initialize(size: nil, color: nil)
+    @size = size
+    @color = color
+  end
+end
+```
+
+Now, in the template, you can use the `#style` method and pass the variants to it:
+
+```erb
+<button class="<%= style(size:, color:) %>">Click me</button>
+```
+
+Passing `size: :lg` and `color: :secondary` would result in the following HTML:
+
+```html
+<button class="font-medium bg-purple-500 text-white rounded-full px-4 py-3 text-lg">Click me</button>
+```
+
+**NOTE:** If you pass `nil`, the default value would be used.
+
+You can define multiple style sets in a single component:
+
+```ruby
+class ButtonComponent < ViewComponent::Base
+  include ViewComponentContrib::StyleVariants
+
+  # default component styles
+  style do
+    # ...
+  end
+
+  style :image do
+    variants {
+      orient {
+        portrait { "w-32 h-32" }
+        landscape { "w-64 h-32" }
+      }
+    }
+  end
+end
+```
+
+And in the template:
+
+```erb
+<div>
+  <button class="<%= style(size:, theme:) %>">Click me</button>
+  <img src="..." class="<%= style(:image, orient: :portrait) %>">
+</div>
+```
+
+Finally, you can inject into the class list compilation process to add your own logic:
+
+```ruby
+class ButtonComponent < ViewComponent::Base
+  include ViewComponentContrib::StyleVariants
+
+  # You can provide either a proc or any other callable object
+  style_config.postprocess_with do |classes|
+    # classes is an array of CSS classes
+    TailwindMerge.call(classes).join(" ")
+  end
+end
+```
+
 ## Organizing assets (JS, CSS)
 
-**NOTE*: This section assumes the usage of Webpack, Vite or other _frontend_ builder (e.g., not Sprockets).
+**NOTE**: This section assumes the usage of Vite or Webpack. See [this discussion](https://github.com/palkan/view_component-contrib/discussions/14) for other options.
 
 We store JS and CSS files in the same sidecar folder:
 
@@ -203,6 +304,18 @@ import "./index.css"
 
 In the root of the `components` folder we have the `index.js` file, which loads all the components:
 
+- With Vite:
+
+```js
+// With Vite
+import.meta.glob("./**/index.js").forEach((path) => {
+  const mod = await import(path);
+  mod.default();
+});
+```
+
+- With Webpack:
+
 ```js
 // components/index.js
 const context = require.context(".", true, /index.js$/)
@@ -211,12 +324,11 @@ context.keys().forEach(context);
 
 ### Using with StimulusJS
 
-You can define Stimulus controllers right in the `index.js` file using the following approach:
+You can define Stimulus controllers right in the component folder in the `controller.js` file:
 
 ```js
-import "./index.css"
 // We reserve Controller for the export name
-import { Controller as BaseController } from "stimulus";
+import { Controller as BaseController } from "@hotwired/stimulus";
 
 export class Controller extends BaseController {
   connect() {
@@ -225,20 +337,60 @@ export class Controller extends BaseController {
 }
 ```
 
-Then, we need to update the `components/index.js` to automatically register controllers:
+Then, in your Stimulus entrypoint, you can load and register your component controllers as follows:
+
+- With Vite:
 
 ```js
-// We recommend putting Stimulus application instance into its own
-// module, so you can use it for non-component controllers
+import { Application } from "@hotwired/stimulus";
 
-// init/stimulus.js
+const application = Application.start();
+
+// Configure Stimulus development experience
+application.debug = false;
+window.Stimulus = application;
+
+// Generic controllers
+const genericControllers = import.meta.globEager(
+  "../controllers/**/*_controller.js"
+);
+
+for (let path in genericControllers) {
+  let module = genericControllers[path];
+  let name = path
+    .match(/controllers\/(.+)_controller\.js$/)[1]
+    .replaceAll("/", "-")
+    .replaceAll("_", "-");
+
+  application.register(name, module.default);
+}
+
+// Controllers from components
+const controllers = import.meta.globEager(
+  "./../../app/frontend/components/**/controller.js"
+);
+
+for (let path in controllers) {
+  let module = controllers[path];
+  let name = path
+    .match(/app\/frontend\/components\/(.+)\/controller\.js$/)[1]
+    .replaceAll("/", "-")
+    .replaceAll("_", "-");
+  application.register(name, module.default);
+}
+
+export default application;
+```
+
+- With Webpack:
+
+```js
 import { Application } from "stimulus";
 export const application = Application.start();
 
-// components/index.js
-import { application } from "../init/stimulus";
+// ... other controllers
 
-const context = require.context(".", true, /index.js$/)
+const context = require.context("./../../app/frontend/components/", true, /controllers.js$/)
 context.keys().forEach((path) => {
   const mod = context(path);
 
@@ -248,9 +400,10 @@ context.keys().forEach((path) => {
   // Convert path into a controller identifier:
   //   example/index.js -> example
   //   nav/user_info/index.js -> nav--user-info
-  const identifier = path.replace(/^\.\//, '')
-    .replace(/\/index\.js$/, '')
-    .replace(/\//g, '--');
+  const identifier = path
+    .match(/app\/frontend\/components\/(.+)\/controller\.js$/)[1]
+    .replaceAll("/", "-")
+    .replaceAll("_", "-");
 
   application.register(identifier, mod.Controller);
 });
@@ -265,6 +418,8 @@ class ApplicationViewComponent
   def identifier
     @identifier ||= self.class.name.sub("::Component", "").underscore.split("/").join("--")
   end
+
+  alias_method :controller_name, :identifier
 end
 ```
 
@@ -272,7 +427,7 @@ And now in your template:
 
 ```erb
 <!-- component.html -->
-<div data-controller="<%= identifier %>">
+<div data-controller="<%= controller_name %>">
 </div>
 ```
 
@@ -495,11 +650,6 @@ And the template looks like this now:
 
 You can use the `#wrapped` method on any component inherited from `ApplicationViewComponent` to wrap it automatically:
 
-## ToDo list
-
-- Better preview tools (w/o JS deps 😉).
-- Hotwire-related extensions.
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/view_component_contrib/style_variants.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module ViewComponentContrib
+  # Organize style in variants that can be combined.
+  # Inspired by https://www.tailwind-variants.org and https://cva.style/docs/getting-started/variants
+  #
+  # Example:
+  #
+  #   class ButtonComponent < ViewComponent::Base
+  #     include ViewComponentContrib::StyleVariants
+  #
+  #     erb_template <<~ERB
+  #       <button class="<%= style(size: 'sm', color: 'secondary') %>">Click me</button>
+  #     ERB
+  #
+  #     style do
+  #       base {
+  #         %w(
+  #           font-medium bg-blue-500 text-white rounded-full
+  #         )
+  #       }
+  #       variants {
+  #         color {
+  #           primary { %w(bg-blue-500 text-white) }
+  #           secondary  { %w(bg-purple-500 text-white) }
+  #         }
+  #         size {
+  #           sm { "text-sm" }
+  #           md { "text-base" }
+  #           lg { "px-4 py-3 text-lg" }
+  #         }
+  #       }
+  #       defaults { {size: :md, color: :primary} }
+  #    end
+  #
+  #    attr_reader :size, :color
+  #
+  #    def initialize(size: :md, color: :primary)
+  #      @size = size
+  #      @color = color
+  #    end
+  #  end
+  #
+  module StyleVariants
+    class VariantBuilder
+      attr_reader :unwrap_blocks
+
+      def initialize(unwrap_blocks = true)
+        @unwrap_blocks = unwrap_blocks
+        @variants = {}
+      end
+
+      def build(&block)
+        instance_eval(&block)
+        @variants
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        true
+      end
+
+      def method_missing(name, &block)
+        return super unless block_given?
+
+        @variants[name] = if unwrap_blocks
+          VariantBuilder.new(false).build(&block)
+        else
+          block
+        end
+      end
+    end
+
+    class StyleSet
+      def initialize(&init_block)
+        @base_block = nil
+        @defaults = {}
+        @variants = {}
+
+        instance_eval(&init_block) if init_block
+      end
+
+      def base(&block)
+        @base_block = block
+      end
+
+      def defaults(&block)
+        @defaults = block.call.freeze
+      end
+
+      def variants(&block)
+        @variants = VariantBuilder.new(true).build(&block)
+      end
+
+      def compile(**variants)
+        acc = Array(@base_block&.call || [])
+
+        @defaults.merge(variants.compact).each do |variant, value|
+          variant = @variants.dig(variant, value) || next
+          styles = variant.is_a?(::Proc) ? variant.call : variant
+          acc.concat(Array(styles))
+        end
+
+        acc
+      end
+    end
+
+    class StyleConfig # :nodoc:
+      DEFAULT_POST_PROCESSOR = ->(compiled) { compiled.join(" ") }
+
+      attr_reader :postprocessor
+
+      def initialize
+        @styles = {}
+        @postprocessor = DEFAULT_POST_PROCESSOR
+      end
+
+      def define(name, &block)
+        styles[name] = StyleSet.new(&block)
+      end
+
+      def compile(name, **variants)
+        styles[name]&.compile(**variants).then do |compiled|
+          next unless compiled
+
+          postprocess(compiled)
+        end
+      end
+
+      # Allow defining a custom postprocessor
+      def postprocess_with(callable = nil, &block)
+        @postprocessor = callable || block
+      end
+
+      private
+
+      attr_reader :styles
+
+      def postprocess(compiled) = postprocessor.call(compiled)
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Returns the name of the default style set based on the class name:
+      #  MyComponent::Component => my_component
+      #  Namespaced::MyComponent => my_component
+      def default_style_name
+        @default_style_name ||= name.demodulize.sub(/(::Component|Component)$/, "").underscore.presence || "component"
+      end
+
+      def style(name = default_style_name, &block)
+        style_config.define(name.to_sym, &block)
+      end
+
+      def style_config
+        @style_config ||=
+          if superclass.respond_to?(:style_config)
+            superclass.style_config.dup
+          else
+            StyleConfig.new
+          end
+      end
+    end
+
+    def style(name = self.class.default_style_name, **variants)
+      self.class.style_config.compile(name.to_sym, **variants)
+    end
+  end
+end

data/lib/view_component_contrib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ViewComponentContrib # :nodoc:all
-  VERSION = "0.1.6"
+  VERSION = "0.2.0"
 end

data/lib/view_component_contrib.rb

@@ -11,6 +11,7 @@ module ViewComponentContrib
   autoload :TranslationHelper, "view_component_contrib/translation_helper"
   autoload :WrapperComponent, "view_component_contrib/wrapper_component"
   autoload :WrappedHelper, "view_component_contrib/wrapped_helper"
+  autoload :StyleVariants, "view_component_contrib/style_variants"
 
   autoload :Base, "view_component_contrib/base"
   autoload :Preview, "view_component_contrib/preview"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component-contrib
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-07 00:00:00.000000000 Z
+date: 2023-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: view_component
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.15.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -156,6 +156,7 @@ files:
 - lib/view_component_contrib/preview/default_template.rb
 - lib/view_component_contrib/preview/sidecarable.rb
 - lib/view_component_contrib/railtie.rb
+- lib/view_component_contrib/style_variants.rb
 - lib/view_component_contrib/translation_helper.rb
 - lib/view_component_contrib/version.rb
 - lib/view_component_contrib/wrapped_helper.rb
@@ -177,7 +178,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="