cva-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4322ef5c0b4f017974740f1bf2225df026a5a25d3454faa6932c123360027581
+  data.tar.gz: 4e63179ef8681baa49d0706bc940bcbf68f11a7c8081d4d7c8cf4b90fa2c15f8
+SHA512:
+  metadata.gz: c406ea44133b09a583787b2394839e54fcae64bcd5ca8ea7872d82ddde757f882abe1e6989d55947c46caee27dd6941bfe6f2722204f378ea59b2ee014ce3266
+  data.tar.gz: 65f610c2141e1218e682430499f6d069cb32257cdb538a2033a66a79265159d165bf73265be0277a6e786613ef77262d642e0581535a77e980ef5aa2c48fff4f

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-28
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andrii Malyshko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# cva (Class Variance Authority)
+
+This is a Ruby port of [cva.style](https://github.com/joe-bell/cva) JS library.
+It is a tool for conditionally concatenating CSS classes.
+
+The CVA (Class Variance Authority) pattern is based on the idea that there's
+a limited number of states (variants) your CSS component can hold. Each state
+is described with a CSS class or a set of classes. You then provide a set of
+variants as an input, and get back a final list of CSS classes.
+
+The library aims to be both CSS framework and view renderer agnostic. You can
+use it with atomic CSS (Tailwind), entity-based CSS (BEM), in component based
+rendering (ViewComponent, Phlex) or plain Rails/Hanami etc views.
+
+It should not be confused with the general purpose CSS concatenators like
+[clsx](https://github.com/svyatov/clsx-ruby) or Rails `class_names`. Those
+accept raw CSS classes as an input, whereas this library requires you to work
+with a limited number of design tokens (variants).
+
+## Status
+
+Production ready.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add cva-ruby
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install cva-ruby
+```
+
+## Usage
+
+### ViewComponent
+
+```ruby
+# app/components/button_component.rb
+
+class ButtonComponent < ViewComponent::Base
+  # the helper generates `cva_class_name` method
+  include Cva::ModelHelper.new(
+    base: "button",
+    variants: {
+      intent: {
+        primary: "button--primary",
+        secondary: "button--secondary"
+      }
+    }
+  )
+
+  # calling `cva_class_name(intent: :primary)` returns "button button--primary"
+  def initialize(title:, intent:)
+    @title = title
+    @class_name = cva_class_name(intent:)
+  end
+end
+```
+
+```erb
+<% # app/components/button_component.html.erb %>
+
+<button title="<%= @title %>" class="<%= @class_name %>">
+  <%= content %>
+</button>
+```
+
+```erb
+<% # app/views/posts/index.html.erb %>
+
+<%= render(ButtonComponent.new(title: "my title", intent: :primary)) do %>
+  Hello, Button!
+<% end %>
+```
+
+Rendering the view gets you:
+
+```html
+<button title="my title" class="button button--primary">
+  Hello, Button!
+</button>
+```
+
+### Plain views
+
+```ruby
+# config/initializers/cva.rb
+
+class AppCva
+  # default `cva_class_name` method name is overridden
+  include Cva::ModelHelper.new(
+    method_name: "button",
+    base: "button",
+    variants: {
+      intent: {
+        primary: "button--primary",
+        secondary: "button--secondary"
+      }
+    }
+  )
+
+  # you can include as many as you need as long as method names do not collide
+  include Cva::ModelHelper.new(
+    method_name: "tooltip",
+    base: "tooltip",
+    variants: {
+      position: {
+        top: "tooltip--top",
+        left: "tooltip--left"
+      }
+    }
+  )
+end
+```
+
+```ruby
+# app/helpers/application_helper.rb
+
+module ApplicationHelper
+  # the method name can be anything really
+  def cva
+    @cva ||= AppCva.new
+  end
+end
+```
+
+```erb
+<% # app/views/application/_button.html.erb %>
+
+<button class="<%= cva.button(intent: :primary) %>">
+  Oh hello!
+</button>
+```
+
+### With Tailwind
+
+When using Tailwind CSS, you will need a custom class merger that skips
+conficting classes. Pick one of the existing libraries:
+
+- https://github.com/abuisman/tail_merge
+- https://github.com/gjtorikian/tailwind_merge
+
+An example integration:
+
+```ruby
+# config/initializers/cva.rb
+
+require "tail_merge"
+
+class CvaTailwindMerger
+  def call(classes)
+    TailMerge.merge(classes)
+  end
+end
+
+Cva::Config.merger_class = CvaTailwindMerger
+```
+
+## Documentation
+
+Start with [Component](https://rubydoc.info/gems/cva-ruby/Cva/Component), then move
+to [ModelHelper](https://rubydoc.info/gems/cva-ruby/Cva/ModelHelper).
+
+## Similar works
+
+- https://github.com/defvova/cva_rails
+- https://github.com/palkan/view_component-contrib#style-variants
+
+Compared to them, this library has less moving parts and no dependencies
+(still, you will need a custom merger for usage with Tailwind).
+
+The functionality is pretty much the same among all of the libraries.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rake test` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+See `bundle exec rake -T` for the list of all available commands.
+
+## Issues
+
+Use [Github issues](https://github.com/nashbridges/cva-ruby/issues) to file a ticket.
+
+## Contributing
+
+This project is open source and close contribution. I don't have mental
+capacity to accept features I don't need.
+
+You are still allowed to reuse and/or modify the code as you wish.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]
+
+desc "Continuously rerun tests when source/test files change"
+task "test:watch" do
+  sh "bin/retest --notify"
+end
+
+desc "Start YARD server at localhost:8808"
+task "doc:server" do
+  sh "bin/yard server --reload"
+end

data/lib/cva/cache.rb

@@ -0,0 +1,44 @@
+module Cva
+  # A default implementation of cache for {Component#render}. Based on Hash.
+  #
+  # @note Each {Component} instance gets its own {Cache} instance, i.e. the
+  #   cache is not shared.
+  #
+  # Component#render is quite fast. The caching is performed only to avoid
+  # useless work: {Component}'s state is immutable, and there's not many
+  # permutations you can get from it.
+  #
+  # When the default implementation is used (which is in-memory one), make sure
+  # a {Component} instance is long-lived, so that it can benefit from caching.
+  # With {ModelHelper} this is true by default, no extra action is needed.
+  #
+  # In case you might want to override caching, e.g. to skip it during testing,
+  # the best way to do it is via global config:
+  #
+  #  ```
+  #  # config/initializers/cva.rb
+  #
+  #  class CvaNoCache
+  #    def fetch(value)
+  #      value
+  #    end
+  #  end
+  #
+  #  Cva::Config.cache_class = CvaNoCache
+  #  ```
+  class Cache
+    def initialize
+      @storage = {}
+    end
+
+    # @yield executes the block when cache is missed
+    # @yieldreturn value that should be cached
+    def fetch(value)
+      @storage.fetch(value) do
+        result = yield
+        @storage[value] = result
+        result
+      end
+    end
+  end
+end

data/lib/cva/component.rb

@@ -0,0 +1,614 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Cva
+  # The class builds a string list of CSS classes for a CSS component. First,
+  # you initialize the instance with all the states (aka variants) that the
+  # component can be in, along with the corresponding classes. Then you pass
+  # exact variants into {#render}, which gets you back a string of concatenated
+  # classes matching the state.
+  #
+  # The class is not responsible for rendering component's markup. You handle
+  # the latter in a template and/or view component.
+  #
+  # The class is immutable. {#render} does not perform side effects, except
+  # for looking into cache (see {Cache}).
+  #
+  # @example
+  #   button = Cva::Component.new(
+  #     base: "button",
+  #     variants: {
+  #       size: {
+  #         small: "button--small",
+  #         medium: "button--medium",
+  #         large: "button--large",
+  #       }
+  #     }
+  #   )
+  #
+  #   button.render(size: :large) # => "button button--large"
+  #
+  class Component
+    # @!visibility private
+    VARIANTS_VALIDATION_MESSAGE = <<~'EOF'
+      :variants should be a Hash in a form of
+      {
+        variant1: {
+          condition1: 'condition-1-class',                    # a string
+          condition2: ['condition-2-class', 'another-class'], # an array of strings is also fine
+          condition3: ->(base) { "#{base}_class" }            # or a proc-like object accepting base class and returning a string or an array of strings
+          condition4: nil,                                    # `nil` means a no-op condition
+        },
+        variant2: {...},
+      }
+    EOF
+
+    # @!visibility private
+    BASE_VALIDATION_MESSAGE = <<~EOF
+      base should be a string, or an array of strings, or nil
+    EOF
+
+    # @!visibility private
+    BASE_IS_REQUIRED_FOR_PROC_VALIDATION_MESSAGE = <<~EOF
+      base is required when condition is proc-like, either explicitly, or implicitly
+      (via defaults in :base config)
+    EOF
+
+    # @!visibility private
+    SINGLE_ARGUMENT_PROC_VALIDATION_MESSAGE = <<~EOF
+      if condition is proc-like, it has to accept a single string argument (the base class will be passed during evaluation)
+    EOF
+
+    # @!visibility private
+    DEFAULT_VARIANTS_VALIDATION_MESSAGE = <<~EOF
+      :default_variants should be a Hash in a form of
+      {
+        variant1: :condition1_for_variant1,
+        variant2: :condition3_for_variant2,
+      }
+      where both variants and their conditions should be already known (defined by you
+      in :variants config)
+    EOF
+
+    # @!visibility private
+    COMPOUND_VARIANTS_VALIDATION_MESSAGE = <<~EOF
+      :compound_variants should be an array where each element is a Hash in form of
+      {
+        variant1: :condition1_for_variant1,                             # AND condition1
+        variant2: [:condition2_for_variant2, :condition3_for_variant2], # AND (condition2 OR condition3)
+        class: 'compound-variant-class' # can also be an array of strings, or proc returning string or array of strings
+      }
+      where both variants and their conditions should be already known (defined by you
+      in :variants config).
+    EOF
+
+    # @!visibility private
+    RENDER_VARIANTS_VALIDATION_MESSAGE = <<~EOF
+      keyword arguments should be in a form of
+        variant1: :condition1_for_variant1,
+        variant2: :condition3_for_variant2,
+      where both variants and their conditions should be already known (defined by you
+      in :variants config).
+      Input should provide all the variants, either explicitly, or implicitly (via defaults
+      in :default_variants config).
+    EOF
+
+    # A map of variants, default_variants, compound_variants and base
+    attr_reader :config
+
+    # A cache instance to hold results of {#render} invocation. See {Cache}
+    # @return [#fetch]
+    attr_reader :cache
+
+    # A CSS class merger instance. See {Merger}
+    # @return [#call]
+    attr_reader :merger
+
+    # @param variants [{VariantKey => {OptionKey => String, Array<String>,
+    #   #call, nil}}] a map of variants and their options to CSS classes. \
+    #   A variant combines a group of options, so the map is nested. Think of
+    #   a variant as a dimension of states in the CSS component. For a button
+    #   component it can be "size" (small, medium, large) or "visual"
+    #   (outlined, solid). Variant and option keys can be anything, but usually
+    #   symbols are used.
+    #   ```
+    #     {
+    #       visual: {
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     }
+    #   ```
+    #   When a variant option resolves to multiple classes, you can specify
+    #   them as an array of strings. It has the same effect as you would pass
+    #   the classes as a long string list, but allows for a nice formatting:
+    #   ```
+    #     {
+    #       visual: {
+    #         outlined: [
+    #           "border-1",
+    #           "border-color-blue",
+    #           "border-radius-2",
+    #         ]
+    #       }
+    #     }
+    #   ```
+    #   or even nicer:
+    #   ```
+    #     {
+    #       visual: {
+    #         outlined: %w[
+    #           border-1
+    #           border-color-blue
+    #           border-radius-2
+    #         ]
+    #       }
+    #     }
+    #   ```
+    #   Passing `nil` as a class value means this variant option is an empty
+    #   one. This is commonly used with boolean options when only `true`
+    #   corresponds to something meaningful (notice the usage of `=>`, so that
+    #   the keys are booleans, and not symbols):
+    #   ```
+    #     {
+    #       badge: {
+    #         true => "button--badge",
+    #         false => nil, # no class is added to the output for this option
+    #       }
+    #     }
+    #   ```
+    #   If you have more than 2 options with one being empty, a common approach
+    #   is to name it as "unset":
+    #   ```
+    #     {
+    #       visual: {
+    #         unset: nil,
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     }
+    #   ```
+    #   You can pass lambda (or generally any object that responds to #call) as
+    #   a class name. When resolved, the lambda receives base class as an input
+    #   and should return a class or an array of classes. This is only useful in
+    #   cases when you override base class in #render.
+    #   ```
+    #     {
+    #       visual: {
+    #         outlined: ->(base) { "#{base}--outlined" },
+    #         solid: ->(base) { "#{base}--solid" },
+    #       }
+    #     }
+    #   ```
+    #
+    # @param base [String, Array<String>] a CSS class, or an array of classes
+    #   that should be included into every output. You can override it in #render.
+    #
+    # @param default_variants [{VariantKey => OptionKey}] a map of variants and
+    #   their options that should be used by default in every output. You can
+    #   override it in #render.
+    #   ```
+    #     {
+    #       visual: :solid,
+    #       size: :medium,
+    #       badge: false,
+    #     }
+    #   ```
+    #
+    # @param compound_variants [Array<{VariantKey, :class => OptionKey,
+    #   Array<OptionKey>, String, Array<String>, #call}>] a list of CSS classes
+    #   that should be applied only for a specific combination of variants.\
+    #   The class is passed under the `:class` key, and it allows the same format as
+    #   in `:variants` (a string, an array of string, or an object that responds
+    #   to #call). \
+    #   Here the class is added to the output when both `:size` is `:large` and
+    #   `:badge` is `true`:
+    #   ```
+    #   [{
+    #     size: :large, # if size is `:small` or `:medium`, this compound variant is not applied
+    #     badge: true,  # or if badge is `false`, this compound variant is off too
+    #     class: "button--large-with-badge",
+    #   }]
+    #   ```
+    #   You can pass an array of option keys, that means any of the options is fine:
+    #   ```
+    #   [{
+    #     size: [:small, :medium],
+    #     visual: :solid,
+    #     class: "button--small-solid-or-medium-solid",
+    #   }]
+    #   ```
+    #
+    # @param cache [#fetch] (see {#cache})
+    #
+    # @param merger [#call] (see {#merger})
+    #
+    # @raise [ArgumentError] if input does not match the schema
+    def initialize(
+      variants:,
+      base: nil,
+      default_variants: nil,
+      compound_variants: nil,
+      cache: Config.cache_class.new,
+      merger: Config.merger_class.new
+    )
+      @config = {}
+      config[:variants] = validate_and_coerce_config_variants!(variants)
+      config[:base] = validate_and_coerce_config_base!(base)
+      config[:default_variants] = validate_and_coerce_config_default_variants!(default_variants)
+      config[:compound_variants] = validate_and_coerce_config_compound_variants!(compound_variants)
+      @cache = cache
+      @merger = merger
+    end
+
+    # @param base [String, Array<String>] overrides (or sets) base CSS class or classes
+    #
+    # @param variants [{VariantKey => OptionKey}] currently chosen variants. Overrides
+    #   `:default_variants` if those were set in {#initialize}
+    #
+    # @return [String] space-delimitered list of CSS classes.
+    #
+    # @raise [ArgumentError] if base and/or variants do not match the schema, or some
+    #   variant keys are missing
+    #
+    # @example Simple variants
+    #   button = Cva::Component.new(
+    #     variants: {
+    #       size: {
+    #         small: "button--small",
+    #         medium: "button--medium",
+    #         large: "button--large",
+    #       },
+    #       visual: {
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     }
+    #   )
+    #
+    #   button.render(size: :small, visual: :solid) # => "button--small button--solid"
+    #   button.render(visual: :solid, size: :small) # => "button--small button--solid" <-- order is preserved
+    #   button.render(size: :medium) # => ERROR! `:visual` variant is missing
+    #   button.render(size: :medium, visual: :text) # => ERROR! `:visual` variant option was not declared in config
+    #
+    # @example Base
+    #   button = Cva::Component.new(
+    #     base: "button",
+    #     variants: {
+    #       visual: {
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     }
+    #   )
+    #
+    #   button.render(visual: :outlined) # => "button button--outlined"
+    #   button.render(visual: :solid) # => "button button--solid"
+    #
+    # @example Array of CSS classes
+    #   button = Cva::Component.new(
+    #     variants: {
+    #       visual: {
+    #         outlined: [
+    #           "border-1",
+    #           "border-color-blue",
+    #           "border-radius-2",
+    #         ]
+    #       }
+    #     }
+    #   )
+    #
+    #   button.render(visual: :outlined) # => "border-1 border-color-blue border-radius-2"
+    #
+    # @example `nil` as CSS class
+    #   button = Cva::Component.new(
+    #     variants: {
+    #       visual: {
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       },
+    #       badge: {
+    #         true => "button--badge",
+    #         false => nil,
+    #       }
+    #     }
+    #   )
+    #
+    #   button.render(visual: outlined, badge: true) # => "button--outlined button--badge"
+    #   button.render(visual: outlined, badge: false) # => "button--outlined"
+    #
+    # @example Default variants
+    #   button = Cva::Component.new(
+    #     variants: {
+    #       size: {
+    #         small: "button--small",
+    #         medium: "button--medium",
+    #         large: "button--large",
+    #       },
+    #       visual: {
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     },
+    #     default_variants: {
+    #       size: :medium,
+    #       visual: :solid,
+    #     }
+    #   )
+    #
+    #   button.render # => "button--medium button--solid"
+    #   button.render(size: :large) # => "button--large button--solid"
+    #   button.render(size: :small, visual: :outlined) # => "button--small button--outlined"
+    #
+    # @example Skip variant with the "unset" pattern
+    #   button = Cva::Component.new(
+    #     variants: {
+    #       size: {
+    #         small: "button--small",
+    #         medium: "button--medium",
+    #         large: "button--large",
+    #       },
+    #       visual: {
+    #         unset: nil,
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     },
+    #     default_variants: {
+    #       size: :medium,
+    #       visual: :solid,
+    #     }
+    #   )
+    #
+    #   button.render # => "button--medium button--solid"
+    #   button.render(visual: :unset) # => "button--medium"
+    #
+    # @example Compound variants
+    #   button = Cva::Component.new(
+    #     variants: {
+    #       size: {
+    #         small: "button--small",
+    #         medium: "button--medium",
+    #         large: "button--large",
+    #       },
+    #       visual: {
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     },
+    #     compound_variants: [{
+    #       size: :small,
+    #       visual: :solid,
+    #       class: "button--small-and-solid",
+    #     }]
+    #   )
+    #
+    #   button.render(size: :small, visual: :solid) # => "button--small button--solid button--small-and-solid"
+    #   button.render(size: :medium, visual: :solid) # => "button--medium button--solid"
+    #   button.render(size: :small, visual: :outlined) # => "button--small button--outlined"
+    #
+    # @example Compound variants with variant options array
+    #   button = Cva::Component.new(
+    #     variants: {
+    #       size: {
+    #         small: "button--small",
+    #         medium: "button--medium",
+    #         large: "button--large",
+    #       },
+    #       visual: {
+    #         outlined: "button--outlined",
+    #         solid: "button--solid",
+    #       }
+    #     },
+    #     compound_variants: [{
+    #       size: [:small, :medium],
+    #       visual: :solid,
+    #       class: "button--small-or-medium-size-and-solid",
+    #     }]
+    #   )
+    #
+    #   button.render(size: :small, visual: :solid) # => "button--small button--solid button--small-or-medium-size-and-solid"
+    #   button.render(size: :medium, visual: :solid) # => "button--medium button--solid button--small-or-medium-size-and-solid"
+    #   button.render(size: :small, visual: :outlined) # => "button--small button--outlined"
+    #
+    # @example lamdba as CSS class + base override
+    #   button = Cva::Component.new(
+    #     base: "button",
+    #     variants: {
+    #       visual: {
+    #         outlined: ->(base) { "#{base}--outlined" },
+    #         solid: ->(base) { "#{base}--solid" },
+    #       }
+    #     }
+    #   )
+    #
+    #   button.render(visual: outlined) # => "button button--outlined"
+    #   button.render("superbutton", visual: outlined) # => "superbutton superbutton--outlined"
+    def render(base = nil, **variants)
+      cache.fetch([base, variants]) do
+        final_base = validate_and_coerce_render_base!(base)
+        input_variants = validate_and_coerce_render_variants!(variants)
+
+        class_names = [
+          final_base
+        ]
+
+        config[:variants].each_pair do |config_variant, config_conditions|
+          condition = input_variants.fetch(config_variant)
+          class_name = config_conditions.fetch(condition)
+          class_names << resolve_potentially_callable_class_name!(class_name, base: final_base)
+        end
+
+        config[:compound_variants].each do |compound_variant|
+          compound_variant => {class: class_name, **variant_conditions}
+          if variant_conditions.all? { |variant, conditions| conditions.include?(input_variants.fetch(variant)) }
+            class_names << resolve_potentially_callable_class_name!(class_name, base: final_base)
+          end
+        end
+
+        merger.call(class_names.flatten)
+      end
+    end
+
+    private def validate_non_empty_hash!(hash)
+      case hash
+      in {**rest} if rest.size > 0
+        hash
+      end
+    end
+
+    private def validate_and_coerce_class_name!(a_class, allow_empty: true)
+      case a_class
+      in String
+        Array(a_class)
+      in [*strings] if strings.all?(String) && (allow_empty || strings.size > 0)
+        a_class
+      end
+    end
+
+    private def validate_and_coerce_potentially_callable_class_name!(a_class, allow_empty: true)
+      if a_class.respond_to?(:call)
+        begin
+          result = a_class.call("TEST PROBE")
+        rescue ArgumentError
+          raise ArgumentError, SINGLE_ARGUMENT_PROC_VALIDATION_MESSAGE
+        end
+
+        validate_and_coerce_class_name!(result, allow_empty:)
+        a_class
+      else
+        validate_and_coerce_class_name!(a_class, allow_empty:)
+      end
+    end
+
+    private def validate_variants_conditions!(variants_conditions)
+      if !variants_conditions.each_pair.all? { |variant, condition| config[:variants].dig(variant, condition) }
+        raise NoMatchingPatternError
+      end
+    end
+
+    private def validate_and_coerce_config_variants!(input)
+      validate_non_empty_hash!(input)
+
+      input.transform_values do |conditions|
+        validate_non_empty_hash!(conditions)
+
+        conditions.transform_values do |value|
+          if value.nil?
+            []
+          else
+            validate_and_coerce_potentially_callable_class_name!(value)
+          end
+        end
+      end
+    rescue NoMatchingPatternError
+      raise ArgumentError, VARIANTS_VALIDATION_MESSAGE
+    end
+
+    private def validate_and_coerce_config_base!(input)
+      if input.nil?
+        return []
+      end
+
+      validate_and_coerce_class_name!(input)
+    rescue NoMatchingPatternError
+      raise ArgumentError, BASE_VALIDATION_MESSAGE
+    end
+
+    private def validate_and_coerce_config_default_variants!(input)
+      if input.nil?
+        return {}
+      end
+
+      input => Hash
+      validate_variants_conditions!(input)
+
+      input
+    rescue NoMatchingPatternError
+      raise ArgumentError, DEFAULT_VARIANTS_VALIDATION_MESSAGE
+    end
+
+    private def validate_and_coerce_config_variants_conditions!(variants_conditions)
+      if variants_conditions.size == 0
+        raise NoMatchingPatternError
+      end
+
+      coerced_variant_condition_pairs = variants_conditions.map do |variant, condition|
+        coerced_condition = Array(condition)
+
+        if coerced_condition.size == 0
+          raise NoMatchingPatternError
+        end
+
+        if !coerced_condition.all? { |condition| config[:variants].dig(variant, condition) }
+          raise NoMatchingPatternError
+        end
+
+        [variant, coerced_condition]
+      end
+
+      coerced_variant_condition_pairs.flatten(0).to_h
+    end
+
+    private def validate_and_coerce_config_compound_variants!(input)
+      if input.nil?
+        return []
+      end
+
+      input => Array
+      input.map do |compound_variant|
+        compound_variant => {class: class_name, **variant_conditions}
+
+        final_variants_conditions = validate_and_coerce_config_variants_conditions!(variant_conditions)
+        final_class = validate_and_coerce_potentially_callable_class_name!(class_name, allow_empty: false)
+
+        {class: final_class, **final_variants_conditions}
+      end
+    rescue NoMatchingPatternError
+      raise ArgumentError, COMPOUND_VARIANTS_VALIDATION_MESSAGE
+    end
+
+    private def validate_and_coerce_render_base!(base)
+      if base.nil?
+        return config[:base]
+      end
+
+      validate_and_coerce_class_name!(base)
+    rescue NoMatchingPatternError
+      raise ArgumentError, BASE_VALIDATION_MESSAGE
+    end
+
+    private def validate_and_coerce_render_variants!(input)
+      validate_variants_conditions!(input)
+
+      full_variants_conditions = {
+        **config[:default_variants],
+        **input
+      }
+
+      if full_variants_conditions.keys.sort != config[:variants].keys.sort
+        raise NoMatchingPatternError
+      end
+
+      full_variants_conditions
+    rescue NoMatchingPatternError
+      raise ArgumentError, RENDER_VARIANTS_VALIDATION_MESSAGE
+    end
+
+    private def resolve_potentially_callable_class_name!(class_name, base:)
+      if class_name.respond_to?(:call)
+        if base.size == 0
+          raise ArgumentError, BASE_IS_REQUIRED_FOR_PROC_VALIDATION_MESSAGE
+        end
+
+        base.map do |each_base|
+          resolved_class_name = class_name.call(each_base)
+          resolved_class_name
+        end
+      else
+        class_name
+      end
+    end
+  end
+end

data/lib/cva/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "merger"
+require_relative "cache"
+
+module Cva
+  # Allows to define {Component#initialize} dependencies in a global way.
+  module Config
+    class << self
+      # instance of this class will be injected as `:merger`. Defaults to {Merger}.
+      attr_accessor :merger_class
+
+      # instance of this class will be injected as `:cache`. Defaults to {Cache}.
+      attr_accessor :cache_class
+    end
+
+    self.merger_class = Merger
+    self.cache_class = Cache
+  end
+end

data/lib/cva/merger.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Cva
+  # A default implementation of CSS classes merger for {Component#render}. The logic is simple:
+  # input elements are joined with space as is.
+  #
+  # When using the library with Tailwind, you'll need a merger with deduplicating behavior.
+  # You may want to wrap one of the existing libraries:
+  #
+  # - https://github.com/abuisman/tail_merge
+  # - https://github.com/gjtorikian/tailwind_merge
+  #
+  # An example integration:
+  #
+  # ```
+  # # config/initializers/cva.rb
+  #
+  # require "tail_merge"
+  #
+  # class CvaTailwindMerger
+  #   def call(classes)
+  #     TailMerge.merge(classes)
+  #   end
+  # end
+  #
+  # Cva::Config.merger_class = CvaTailwindMerger
+  # ```
+  class Merger
+    # @param classes [Array<String>] a list of CSS classes resolved in {Component#render}
+    # @return [String] final string of CSS classes
+    def call(classes)
+      classes.join(" ")
+    end
+  end
+end

data/lib/cva/model_helper.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "component"
+
+module Cva
+  # A syntax-sugar module. Removes boilerplate of instantiating and rendering
+  # the {Component} within a class, e.g. a ViewComponent.
+  #
+  # Instead of resorting to global variables (which is fine in case you are
+  # careful with namespacing):
+  #
+  # ```
+  # class ButtonComponent < ViewComponent::Base
+  #   BUTTON = Cva::Component.new(
+  #     base: "button",
+  #     variants: {
+  #       intent: {
+  #         primary: "button--primary",
+  #         secondary: "button--secondary"
+  #       }
+  #     }
+  #   )
+  #
+  #   def initialize(title:, intent:)
+  #     @title = title
+  #     @class_name = BUTTON.render(intent:)
+  #   end
+  # end
+  # ```
+  #
+  # the same can be written as:
+  #
+  # ```
+  # class ButtonComponent < ViewComponent::Base
+  #   # The helper generates `cva_class_name` method, which delegates to
+  #   # Component#render under the hood
+  #   include Cva::ModelHelper.new(
+  #     base: "button",
+  #     variants: {
+  #       intent: {
+  #         primary: "button--primary",
+  #         secondary: "button--secondary"
+  #       }
+  #     }
+  #   )
+  #
+  #   def initialize(title:, intent:)
+  #     @title = title
+  #     @class_name = cva_class_name(intent:)
+  #   end
+  # end
+  # ```
+  #
+  # All the {ModelHelper#initialize} params are passed straight to {Component#initialize},
+  # except for `method_name`, which allows to override the name of the generated method:
+  #
+  # ```
+  # class ButtonComponent < ViewComponent::Base
+  #   include Cva::ModelHelper.new(
+  #     method_name: "button_class",
+  #     base: "button",
+  #     variants: {
+  #       intent: {
+  #         primary: "button--primary",
+  #         secondary: "button--secondary"
+  #       }
+  #     }
+  #   )
+  #
+  #   def initialize(title:, intent:)
+  #     @title = title
+  #     @class_name = button_class(intent:)
+  #   end
+  # end
+  # ```
+  class ModelHelper < Module
+    def initialize(method_name: "cva_class_name", **component_options)
+      # Prepare a closure.
+      # This `component` instance is shared by every class instance that includes
+      # this module. It is exactly what we want in regards to performance:
+      # calls to `render` are typical regardless of a particular instance,
+      # so component's cache will be used in 99% cases.
+      component = Component.new(**component_options)
+
+      define_method(method_name) do |*args, **kwargs|
+        component.render(*args, **kwargs)
+      end
+    end
+  end
+end

data/lib/cva/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cva
+  VERSION = "0.1.0"
+end

data/lib/cva-ruby.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "cva/version"
+require_relative "cva/component"
+require_relative "cva/model_helper"

data/lib/cva.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "cva-ruby"

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: cva-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrii Malyshko
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  This is a Ruby port of cva.style JS library. The CVA (Class Variance Authority)
+  pattern is based on the idea that there's a limited number of states
+  (variants) your CSS component can hold. Each state is described with a CSS
+  class or a set of classes. You then provide a set of variants as an input,
+  and get back a final list of CSS classes.
+email:
+- pleasesendmeaspam@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/cva-ruby.rb
+- lib/cva.rb
+- lib/cva/cache.rb
+- lib/cva/component.rb
+- lib/cva/config.rb
+- lib/cva/merger.rb
+- lib/cva/model_helper.rb
+- lib/cva/version.rb
+homepage: https://github.com/nashbridges/cva-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nashbridges/cva-ruby
+  source_code_uri: https://github.com/nashbridges/cva-ruby
+  changelog_uri: https://github.com/nashbridges/cva-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A tool for conditionally concatenating CSS classes
+test_files: []