class_variants 0.0.8 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35b8ff14e7d3dfe7319d4fb4f09b78aec128422de09402e3504809ef5a0adacf
-  data.tar.gz: f4b9bd0eec1427ba964d6affd2d3ec0e84126070faadd60cb7b6e51e7979a2ba
+  metadata.gz: ffcbc4e2fd078ac3b22bd391226eec4fc4429bcee10237613f1736bfcff08b6f
+  data.tar.gz: 4101b943cfd16a259d52e978c3081788451fcd1336ae44644b027aeebb1a4f34
 SHA512:
-  metadata.gz: 75f8bb22dafa4d3e67bcc198b804ce85a76705696d0f46f7d9a22fe7c2c97e7af9174304778c808cf00e502cac9f403d8b25d3c9be825b3e963bb042e24d593c
-  data.tar.gz: 201be369574e67efe1557b2e396fb2aa1e09faad3415d0b88efe9467d6a9137ede50c7b072d3859c09e5ed63eb1df6369748a1fb247146fca451a1a823878948
+  metadata.gz: 3dd5e798a846188944d4fe74342414ccfa180ba6fa319a0e1f2b0ab775f4c32c4d0a5c1129a42c52dce44765cd981db20b5a222b6605989ade32e39a7693fb5f
+  data.tar.gz: e3eb94faf2f8ad63b6d96fe322b274c77e8a4b2e9fcc2123e267d2b6580398fd06122b73841dbd1a1aea9709667b1afec8ab8c3bce3eecfb4db7e6d409907a76

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Adrian Marin
+Copyright (c) 2025 Adrian Marin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/class_variants/action_view/helpers.rb

@@ -1,8 +1,8 @@
 module ClassVariants
   module ActionView
     module Helpers
-      def class_variants(classes, **args)
-        ClassVariants::Instance.new classes, **args
+      def class_variants(...)
+        ClassVariants::Instance.new(...)
       end
     end
   end

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(...)
+        singleton_class.instance_variable_get(:@_class_variants_instance).merge(...)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.singleton_class.instance_variable_set(:@_class_variants_instance, ClassVariants::Instance.new)
+      base.define_singleton_method(:inherited) do |subclass|
+        subclass.singleton_class.instance_variable_set(
+          :@_class_variants_instance, base.singleton_class.instance_variable_get(:@_class_variants_instance).dup
+        )
+      end
+    end
+
+    def class_variants(...)
+      self.class.singleton_class.instance_variable_get(:@_class_variants_instance).render(...)
+    end
+  end
+end

data/lib/class_variants/instance.rb

@@ -1,66 +1,132 @@
 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(...)
+      @bases = []
+      @variants = []
+      @defaults = {}
+
+      merge(...)
+    end
+
+    def dup
+      self.class.new.tap do |copy|
+        copy.instance_variable_set(:@bases, @bases.dup)
+        copy.instance_variable_set(:@variants, @variants.dup)
+        copy.instance_variable_set(:@defaults, @defaults.dup)
+      end
+    end
+
+    def merge(**options, &block)
+      raise ArgumentError, "Use of hash config and code block is not supported" if !options.empty? && block_given?
+
+      (base = options.fetch(:base, nil)) && @bases << {class: base, slot: :default}
+      @variants += [
+        expand_variants(options.fetch(:variants, {})),
+        expand_compound_variants(options.fetch(:compound_variants, []))
+      ].inject(:+)
+      @defaults.merge!(options.fetch(:defaults, {}))
+
+      instance_eval(&block) if block_given?
+
+      self
     end
-    # rubocop:enable Naming/VariableName
 
-    def render(**overrides)
+    def render(slot = :default, **overrides)
+      classes = overrides.delete(:class)
+      result = []
+
       # Start with our default classes
-      result = [@base]
+      @bases.each do |base|
+        result << base[:class] if base[:slot] == slot
+      end
 
       # 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|
+          @bases << slot
+        end
+      else
+        @bases << {slot: :default, class: 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.1.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

@@ -8,7 +8,6 @@ Inspired by [variant-classnames](https://github.com/mattvalleycodes/variant-clas
 
 * [DRY up your tailwind CSS using this awesome gem](https://www.youtube.com/watch?v=cFcwNH6x77g)
 
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -34,36 +33,38 @@ $ gem install class_variants
 We create an object from the class or helper where we define the configuration using four arguments:
 
 1. The `base` keyword argument with default classes that should be applied to each variant.
-1. The `variants` keyword argument where we declare the variants with their option and classes.
-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
+2. The `variants` keyword argument where we declare the variants with their option and classes.
+3. The `compound_variants` keyword argument where we declare the compound variants with their conditions and classes
+4. The `defaults` keyword argument (optional) where we declare the default value for each variant.
 
-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 +79,7 @@ button_classes.render
 button_classes.render(color: :red, size: :xl, icon: true)
 ```
 
-### Compound Variants
+## Compound Variants
 
 ```ruby
 button_classes = ClassVariants.build(
@@ -100,11 +101,185 @@ 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>
+```
+
+## Merge definitions
+
+```ruby
+alert_classes = ClassVariants.build(base: "bg-white")
+alert_classes.merge(base: "text-black")
+alert_classes.render # => "bg-white text-black"
+```
+
+## 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
 # Somewhere in your helpers
-def button_classes(classes, **args)
+def button_classes
   class_variants(
     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: {
@@ -137,14 +312,68 @@ end
 
 ### Output
 
-![](sample.jpg)
+### ![](sample.jpg)
+
+## 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: "bg-white",
+    variants: {
+      color: {
+        red: "text-red",
+        blue: "text-blue"
+      }
+    }
+  )
+end
+
+MyClass.new.class_variants(color: :red, class: "shadow") # => "bg-white text-red shadow"
+```
+
+This helper supports class inheritance, so that the subclass receives a copy of the class_variants config that the parent class had at the time of inheritance. From that point on, the settings are kept separate for both. Successive calls to class_variants helper method, will cause the configuration to be merged.
+
+```ruby
+class A
+  include ClassVariants::Helper
+
+  class_variants(base: "bg-red")
+end
+
+class B < A
+  class_variants(base: "text-black")
+end
+
+A.class_variants(base: "text-white")
+
+A.new.class_variants # => "bg-red text-white"
+B.new.class_variants # => "bg-red text-black"
+```
+
+## `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. If you're using Rails, you can put this in an initializer.
+
+```ruby
+ClassVariants.configure do |config|
+  config.process_classes_with do |classes|
+    TailwindMerge::Merger.new.merge(classes)
+  end
+end
+```
 
 ## Other packages
 
- - [`active_storage-blurhash`](https://github.com/avo-hq/active_storage-blurhash) - A plug-n-play [blurhash](https://blurha.sh/) integration for images stored in ActiveStorage
- - [`avo`](https://github.com/avo-hq/avo) - Build Content management systems with Ruby on Rails
- - [`prop_initializer`](https://github.com/avo-hq/prop_initializer) - A flexible tool for defining properties on Ruby classes.
- - [`stimulus-confetti`](https://github.com/avo-hq/stimulus-confetti) - The easiest way to add confetti to your StimulusJS app
+- [`active_storage-blurhash`](https://github.com/avo-hq/active_storage-blurhash) - A plug-n-play [blurhash](https://blurha.sh/) integration for images stored in ActiveStorage
+- [`avo`](https://github.com/avo-hq/avo) - Build Content management systems with Ruby on Rails
+- [`prop_initializer`](https://github.com/avo-hq/prop_initializer) - A flexible tool for defining properties on Ruby classes.
+- [`stimulus-confetti`](https://github.com/avo-hq/stimulus-confetti) - The easiest way to add confetti to your StimulusJS app
 
 ## Try Avo ⭐️
 
@@ -155,12 +384,13 @@ If you enjoyed this gem try out [Avo](https://github.com/avo-hq/avo). It helps d
 ## Contributing
 
 1. Fork it `git clone https://github.com/avo-hq/class_variants`
-1. Create your feature branch `git checkout -b my-new-feature`
-1. Commit your changes `git commit -am 'Add some feature'`
-1. Push to the branch `git push origin my-new-feature`
-1. Create new Pull Request
+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 new Pull Request
 
 ## License
+
 This package is available as open source under the terms of the MIT License.
 
 ## Cutting a release

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: class_variants
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 1.1.0
 platform: ruby
 authors:
 - Adrian Marin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-24 00:00:00.000000000 Z
+date: 2025-01-20 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: