class_variants 0.0.8 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35b8ff14e7d3dfe7319d4fb4f09b78aec128422de09402e3504809ef5a0adacf
-  data.tar.gz: f4b9bd0eec1427ba964d6affd2d3ec0e84126070faadd60cb7b6e51e7979a2ba
+  metadata.gz: 0c8fd556b85ee91d2d2709e66af72e1d4017c5a20ba5884c49eed0c755f1a593
+  data.tar.gz: c6f77333c70953510eb23ab94846c2b2f9d1ae1a8b185c289ee3530060546651
 SHA512:
-  metadata.gz: 75f8bb22dafa4d3e67bcc198b804ce85a76705696d0f46f7d9a22fe7c2c97e7af9174304778c808cf00e502cac9f403d8b25d3c9be825b3e963bb042e24d593c
-  data.tar.gz: 201be369574e67efe1557b2e396fb2aa1e09faad3415d0b88efe9467d6a9137ede50c7b072d3859c09e5ed63eb1df6369748a1fb247146fca451a1a823878948
+  metadata.gz: c9f77343da5f6e521cd8a895cef3683a5fc65823b8df3f1f84d03adf38099fb6f51cfc191e24111d35f7ac95ef697e6a61b6dc37a547c50b4732e0863e78631f
+  data.tar.gz: 5a0db3c1db7f88ccc689fbaadc514aa04d73ef405e1ae05755a55918d16d1f1179ff9c736b11402da99e57917c393fd830801f6d78b87c07964d9dc951ac3f98

data/lib/class_variants/configuration.rb

@@ -0,0 +1,11 @@
+module ClassVariants
+  class Configuration
+    def process_classes_with(&block)
+      if block_given?
+        @process_classes_with = block
+      else
+        @process_classes_with
+      end
+    end
+  end
+end

data/lib/class_variants/helper.rb

@@ -0,0 +1,23 @@
+module ClassVariants
+  module Helper
+    module ClassMethods
+      def class_variants(...)
+        @_class_variants_instance = ClassVariants.build(...)
+      end
+
+      def _class_variants_instance
+        @_class_variants_instance
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def class_variants(...)
+      raise "You must configure class_variants in class definition" unless self.class._class_variants_instance
+
+      self.class._class_variants_instance.render(...)
+    end
+  end
+end

data/lib/class_variants/instance.rb

@@ -1,66 +1,108 @@
 module ClassVariants
   class Instance
-    attr_reader :base, :variants, :compound_variants, :defaults
-
-    # rubocop:disable Naming/VariableName
-    def initialize(classes = nil, base: nil, variants: {}, compoundVariants: [], compound_variants: [], defaults: {})
-      warn <<~MSG if classes
-        (ClassVariants) DEPRECATION WARNING: Use of positional argument for default classes is deprecated
-        and will be removed in the next version. Use the `base` keyword argument instead.
-      MSG
-
-      warn <<~MSG unless compoundVariants.empty?
-        (ClassVariants) DEPRECATION WARNING: Use of `compoundVariants` keyword argument is deprecated
-        and will be removed in the next version. Use the `compound_variant` instead.
-      MSG
-
-      @base = base || classes
-      @variants = expand_boolean_variants(variants)
-      @compound_variants = compound_variants.empty? ? compoundVariants : compound_variants
-      @defaults = defaults
+    def initialize(**options, &block)
+      raise ArgumentError, "Use of hash config and code block is not supported" if !options.empty? && block_given?
+
+      @base = options.empty? ? {} : {default: options.fetch(:base, nil)}
+      @variants = expand_variants(options.fetch(:variants, {})) + expand_compound_variants(options.fetch(:compound_variants, []))
+      @defaults = options.fetch(:defaults, {})
+
+      instance_eval(&block) if block_given?
     end
-    # rubocop:enable Naming/VariableName
 
-    def render(**overrides)
+    def render(slot = :default, **overrides)
+      classes = overrides.delete(:class)
+
       # Start with our default classes
-      result = [@base]
+      result = [@base[slot]]
 
       # Then merge the passed in overrides on top of the defaults
-      selected = @defaults.merge(overrides)
+      criteria = @defaults.merge(overrides)
 
-      selected.each do |variant_type, variant|
-        # dig the classes out and add them to the result
-        result << @variants.dig(variant_type, variant)
-      end
+      @variants.each do |candidate|
+        next unless candidate[:slot] == slot
 
-      @compound_variants.each do |compound_variant|
-        if (compound_variant.keys - [:class]).all? { |key| selected[key] == compound_variant[key] }
-          result << compound_variant[:class]
+        if (candidate.keys - [:class, :slot]).all? { |key| criteria[key] == candidate[key] }
+          result << candidate[:class]
         end
       end
 
+      # add the passed in classes to the result
+      result << classes
+
       # Compact out any nil values we may have dug up
       result.compact!
 
       # Return the final token list
-      result.join " "
+      with_classess_processor(result.join(" "))
     end
 
     private
 
-    def expand_boolean_variants(variants)
-      expanded = variants.map do |key, value|
-        case value
+    def base(klass = nil, &block)
+      raise ArgumentError, "Use of positional argument and code block is not supported" if klass && block_given?
+
+      if block_given?
+        with_slots(&block).each do |slot|
+          @base[slot[:slot]] = slot[:class]
+        end
+      else
+        @base[:default] = klass
+      end
+    end
+
+    def variant(**options, &block)
+      raise ArgumentError, "Use of class option and code block is not supported" if options.key?(:class) && block_given?
+
+      if block_given?
+        with_slots(&block).each do |slot|
+          @variants << options.merge(slot)
+        end
+      else
+        @variants << options.merge(slot: :default)
+      end
+    end
+
+    def defaults(**options)
+      @defaults = options
+    end
+
+    def slot(name = :default, **options)
+      raise ArgumentError, "class option is required" unless options.key?(:class)
+
+      @slots << options.merge(slot: name)
+    end
+
+    def with_slots
+      @slots = []
+      yield
+      @slots
+    end
+
+    def expand_variants(variants)
+      variants.flat_map do |property, values|
+        case values
         when String
-          s_key = key.to_s
-          {s_key.delete_prefix("!").to_sym => {!s_key.start_with?("!") => value}}
+          {property.to_s.delete_prefix("!").to_sym => !property.to_s.start_with?("!"), :class => values, :slot => :default}
         else
-          {key => value}
+          values.map do |key, value|
+            {property => key, :class => value, :slot => :default}
+          end
         end
       end
+    end
+
+    def expand_compound_variants(compound_variants)
+      compound_variants.map do |compound_variant|
+        compound_variant.merge(slot: :default)
+      end
+    end
 
-      expanded.reduce do |output, next_variant|
-        output.merge!(next_variant) { |_key, v1, v2| v1.merge!(v2) }
+    def with_classess_processor(classes)
+      if ClassVariants.configuration.process_classes_with.respond_to?(:call)
+        ClassVariants.configuration.process_classes_with.call(classes)
+      else
+        classes
       end
     end
   end

data/lib/class_variants/version.rb

@@ -1,3 +1,3 @@
 module ClassVariants
-  VERSION = "0.0.8".freeze
+  VERSION = "1.0.0".freeze
 end

data/lib/class_variants.rb

@@ -1,10 +1,20 @@
 require "class_variants/version"
 require "class_variants/action_view/helpers"
+require "class_variants/configuration"
 require "class_variants/instance"
+require "class_variants/helper"
 require "class_variants/railtie" if defined?(Rails)
 
 module ClassVariants
   class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure(&block)
+      yield(configuration)
+    end
+
     def build(...)
       Instance.new(...)
     end

data/lib/generators/class_variants/install/USAGE

@@ -0,0 +1,2 @@
+Description:
+    Generates initializer file for configure ClassVariants in your application.

data/lib/generators/class_variants/install/install_generator.rb

@@ -0,0 +1,11 @@
+module ClassVariants
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "class_variants.rb", "config/initializers/class_variants.rb"
+      end
+    end
+  end
+end

data/lib/generators/class_variants/install/templates/class_variants.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# ClassVariants.configure do |config|
+#   # allow to post process classes with an external utility like TailwindMerger
+#   config.process_classes_with do |classes|
+#     TailwindMerge::Merger.new.merge(classes)
+#   end
+# end

data/readme.md

@@ -38,32 +38,34 @@ We create an object from the class or helper where we define the configuration u
 1. The `compound_variants` keyword argument where we declare the compound variants with their conditions and classes
 1. The `defaults` keyword argument (optional) where we declare the default value for each variant.
 
-## Example
-
-Below we implement the [button component](https://tailwindui.com/components/application-ui/elements/buttons) from Tailwind UI.
+Below we'll implement the [button component](https://tailwindui.com/components/application-ui/elements/buttons) from Tailwind UI.
 
 ```ruby
 # Define the variants and defaults
 button_classes = ClassVariants.build(
   base: "inline-flex items-center rounded border border-transparent font-medium text-white hover:text-white shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2",
   variants: {
+    color: {
+      indigo: "bg-indigo-600 hover:bg-indigo-700 focus:ring-indigo-500",
+      red: "bg-red-600 hover:bg-red-700 focus:ring-red-500",
+      blue: "bg-blue-600 hover:bg-blue-700 focus:ring-blue-500",
+    },
     size: {
       sm: "px-2.5 py-1.5 text-xs",
       md: "px-3 py-2 text-sm",
       lg: "px-4 py-2 text-sm",
       xl: "px-4 py-2 text-base",
     },
-    color: {
-      indigo: "bg-indigo-600 hover:bg-indigo-700 focus:ring-indigo-500",
-      red: "bg-red-600 hover:bg-red-700 focus:ring-red-500",
-      blue: "bg-blue-600 hover:bg-blue-700 focus:ring-blue-500",
-    },
+    compound_variants: [
+      { color: :red,  border: true, class: "border-red-800"  },
+      { color: :blue, border: true, class: "border-blue-800" }
+    ]
     # A variant whose value is a string will be expanded into a hash that looks
     # like  { true => "classes" }
-    block: "w-full justify-center",
+    icon: "w-full justify-center",
     # Unless the key starts with !, in which case it will expand into
     # { false => "classes" }
-    "!block": "w-auto",
+    "!icon": "w-auto",
   },
   defaults: {
     size: :md,
@@ -78,7 +80,7 @@ button_classes.render
 button_classes.render(color: :red, size: :xl, icon: true)
 ```
 
-### Compound Variants
+## Compound Variants
 
 ```ruby
 button_classes = ClassVariants.build(
@@ -100,6 +102,172 @@ button_classes.render(color: :red) # => "inline-flex items-center rounded bg-red
 button_classes.render(color: :red, border: true) # => "inline-flex items-center rounded bg-red-600 border border-red-600"
 ```
 
+## Override classes with `render`
+
+We can also override the builder classes in the `render` method.
+
+```ruby
+button_classes = ClassVariants.build(
+  base: "inline-flex items-center rounded",
+  variants: { ... },
+)
+
+button_classes.render(color: :red, class: "block")
+```
+
+Now, the `block` class will be appended to the classes bus.
+
+If you're using the [`tailwind_merge`](#tailwind_merge) plugin it will override the `inline-flex` class.
+
+## Block configurations
+
+You might have scenarios where you have more advanced conditionals and you'd like to configure the classes using the block notation.
+
+```ruby
+alert_classes = ClassVariants.build do
+  # base
+  base "..."
+
+  # variant
+  variant color: :red, class: "..."
+
+  # compound variant
+  variant type: :button, color: :red, class: "..."
+
+  # defaults
+  defaults color: :red, type: :button
+end
+
+# usage
+alert_classes.render(color: :red, type: :button)
+```
+
+## Slots
+
+You might have components which have multiple slots or places where you'd like to use conditional classes.
+`class_variants` supports that through slots.
+
+```ruby
+# Example
+
+alert_classes = ClassVariants.build do
+  # base with slots
+  base do
+    slot :head, class: "..."
+    slot :body, class: "..."
+  end
+
+  # variant with slots
+  variant color: :red do
+    slot :head, class: "..."
+    slot :body, class: "..."
+  end
+
+  # compound variant with slots
+  variant type: :button, color: :red do
+    slot :head, class: "..."
+    slot :body, class: "..."
+  end
+
+  # set defaults
+  defaults color: :red, type: :button
+end
+```
+
+```erb
+<div>
+  <div class="<%= alert_classes.render(:head) %>">
+    Head of alert
+  </div>
+  <div class="<%= alert_classes.render(:body) %>">
+    Body of alert
+  </div>
+</div>
+```
+
+## Full API
+
+```ruby
+# Configuration
+alert_classes = ClassVariants.build(
+  base: "...",
+  variants: {
+    color: {
+      red: "...",
+      black: "..."
+    },
+    type: {
+      button: "...",
+      link: "..."
+    }
+  },
+  compound_variants: [],
+  defaults: {
+    color: :red,
+    type: :button
+  }
+) do
+  # base without slots
+  base "..."
+
+  # base with slots
+  base do
+    slot :head, class: "..."
+    slot :body, class: "..."
+  end
+
+  # variant without slots
+  variant color: :red, class: "..."
+
+  # variant with slots
+  variant color: :red do
+    slot :head, class: "..."
+    slot :body, class: "..."
+  end
+
+  # compound variant without slots
+  variant type: :button, color: :red, class: "..."
+
+  # compound variant with slots
+  variant type: :button, color: :red do
+    slot :head, class: "..."
+    slot :body, class: "..."
+  end
+
+  # option 1 (my favorite)
+  defaults color: :red, type: :button
+
+  # option 2
+  defaults do
+    color :red
+    type :button
+  end
+end
+
+# Usage
+
+# renders the defaults
+alert_classes.render
+
+# render default slot with custom variants
+alert_classes.render(color: :red)
+
+# render slot with defaults variants
+alert_classes.render(:body)
+
+# render slot with custom variants
+alert_classes.render(:body, color: :red)
+
+# if slot not exist, throw error? return empty classes?
+alert_classes.render(:non_existent_slot, color: :red)
+
+# render default slot with custom class (will be merged)
+alert_classes.render(class: "...")
+
+# render slot with custom class (will be merged)
+alert_classes.render(:body, class: "...")
+```
+
 ## Use with Rails
 
 ```ruby
@@ -135,6 +303,36 @@ end
 <%= link_to :Avo, "https://avohq.io", class: button_classes.render(color: :red, size: :xl) %>
 ```
 
+## Helper module
+
+If you're developing something more complex you might want to use composition more. You might want to use the helper module for that.
+
+```ruby
+class MyClass
+  include ClassVariants::Helper
+
+  class_variants {
+    base: {},
+    variants: {}
+  }
+end
+
+MyClass.new.class_variants(:container, color: :red, class: "shadow")
+```
+
+## `tailwind_merge`
+
+By default, the classes are merged using `concat`, but you can use the awesome [TailwindMerge](https://github.com/gjtorikian/tailwind_merge) gem.
+Install the gem using `bundle add tailwind_merge` and use this configuration to enable it.
+
+```ruby
+ClassVariants.configure do |config|
+  config.process_classes_with do |classes|
+    TailwindMerge::Merger.new.merge(classes)
+  end
+end
+```
+
 ### Output
 
 ![](sample.jpg)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: class_variants
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 1.0.0
 platform: ruby
 authors:
 - Adrian Marin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-24 00:00:00.000000000 Z
+date: 2024-11-13 00:00:00.000000000 Z
 dependencies: []
 description: Easily configure styles and apply them as classes.
 email: adrian@adrianthedev.com
@@ -19,9 +19,14 @@ files:
 - LICENSE
 - lib/class_variants.rb
 - lib/class_variants/action_view/helpers.rb
+- lib/class_variants/configuration.rb
+- lib/class_variants/helper.rb
 - lib/class_variants/instance.rb
 - lib/class_variants/railtie.rb
 - lib/class_variants/version.rb
+- lib/generators/class_variants/install/USAGE
+- lib/generators/class_variants/install/install_generator.rb
+- lib/generators/class_variants/install/templates/class_variants.rb.tt
 - readme.md
 homepage: https://github.com/avo-hq/class_variants
 licenses: