cva_rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 340542305df7017584d5b8f4a44248108469d9fb01a71374caf5d875420adc77
+  data.tar.gz: 7996e799b372442959a8ffe91403a1368aa43de261bc1f31498e0009ed5431d6
+SHA512:
+  metadata.gz: 85a6b919b6f6a4d9158f1b3f80291169eecb134bfd78778a574fc3854262e127a754b56020da9c9357352ae189faeb5ba2fc217d2b67657607714ba530a1e437
+  data.tar.gz: 65a8b684ea4f181234a7e34afa7e638f5427cce23cd148c1468a1ce6145245800528f5a2dc02a2344d90197b01497687e3fcedca1790e43410e024985bbcb0ad

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TODO: Write your name
+
+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,243 @@
+# cva_rails [![codecov](https://codecov.io/gh/defvova/cva_rails/branch/main/graph/badge.svg?token=SUOCE7FAYF)](https://codecov.io/gh/defvova/cva_rails) [![CI](https://github.com/defvova/cva_rails/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/defvova/cva_rails/actions?query=workflow%3ACI) [![GitHub License](https://img.shields.io/github/license/defvova/cva_rails)](LICENSE.txt)
+
+> A tiny and simple gem for variant-based styling logic.
+
+This gem offers a lightweight and straightforward solution for managing dynamic class names and
+style variants in Ruby on Rails applications. It draws inspiration from the popular
+[<strong>C</strong>lass <strong>V</strong>ariance <strong>A</strong>uthority (CVA)](https://github.com/joe-bell/cva) package from the JavaScript ecosystem.
+
+By defining a collection of named style rules, the gem helps developers easily handle conditional styling based on schemas and runtime parameters. It’s particularly useful when working with complex UI states requiring dynamic styling.
+
+## Supported Ruby and Rails versions
+
+Ruby 3.1+ and Rails 7.0+ are supported.
+
+<strong>Dependency: [clsx-rails](https://github.com/svyatov/clsx-rails)</strong>
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add cva_rails
+```
+
+Or add it manually to the Gemfile:
+
+```ruby
+gem 'cva_rails', '~> 1.0'
+```
+
+## Usage
+
+The cva method allows you to define and manage class variants for your components efficiently.
+
+Syntax
+```ruby
+cva(base_classes, variants)
+```
+
+1.  base_classes (String or Array)
+A set of base CSS classes applied to the component by default.
+2.  variants (Hash)
+Defines the available style variants and their possible values.
+
+Example Usage
+```ruby
+# app/components/alert_component.rb
+class Alert
+  include Cva::Helper
+
+  cva("relative w-full rounded-lg border px-4 py-3 text-sm "\
+      "[&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground [&>svg~*]:pl-7", {
+    variants: {
+      variant: {
+        primary: "bg-background text-foreground",
+        destructive:
+          "border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive",
+      },
+      size: {
+        small: "px-3 py-2",
+        medium: "px-5 py-4"
+      }
+    },
+  })
+end
+```
+
+Rendered in a view as:
+
+```erb
+<div class="<%= Alert.variants({ variant: :primary, size: :small }) %>"></div>
+<div class="<%= Alert.variants({ variant: :destructive, size: :medium }) %>"></div>
+```
+
+How it works
+```ruby
+Alert.variants({ variant: :primary, size: :small })
+```
+This method call combines the base classes of the Alert component with the classes defined for the :primary and :small variants.
+- The base classes are always applied to the component.
+- The selected variant classes (:primary and :small) are conditionally added, resulting in a combined class list.
+
+This approach helps manage styling variations cleanly and efficiently.
+
+## Compound Components
+
+For larger, more complex components, you may end up wanting to create a set of composable components that work together.
+
+```ruby
+class BtnComponent
+  include Cva::Helper
+
+  cva("border px-4 py-2", {
+    variants: {
+      size: {
+        small: "text-sm",
+        medium: "text-base"
+      },
+      color: {
+        green: "text-green-100",
+        blue: "text-blue-100"
+      }
+    },
+    compound_variants: [
+      {
+        size: :small,
+        class: "h-10"
+      }
+    ]
+  })
+end
+
+BtnComponent.variants({ size: :medium, color: :green }) # => border px-4 py-2 text-green-100 text-base
+BtnComponent.variants({ size: :small, color: :green })  # => border px-4 py-2 text-green-100 text-base h-10
+```
+
+## Default Variants
+
+You can define default variants in the schema to
+automatically apply specific styles when no variant is explicitly provided.
+
+```ruby
+class BtnComponent
+  include Cva::Helper
+
+  cva("border px-4 py-2", {
+    variants: {
+      size: {
+        small: "text-sm",
+        medium: "text-base"
+      },
+      color: {
+        green: "text-green-100",
+        blue: "text-blue-100"
+      }
+    },
+    compound_variants: [
+      {
+        size: :small,
+        class: "h-10"
+      }
+    ],
+    default_variants: {
+      size: :medium,
+      color: :green
+    }
+  })
+end
+
+BtnComponent.variants # => border px-4 py-2 text-green-100 text-base
+```
+
+## Example with TailwindCSS, [ViewComponent](https://viewcomponent.org/) and [TailwindMerge](https://github.com/gjtorikian/tailwind_merge)
+
+ViewComponent is a framework for creating reusable, testable & encapsulated view components, built to integrate seamlessly with Ruby on Rails.
+TailwindMerge is utility function to efficiently merge Tailwind CSS classes without style conflicts.
+
+```ruby
+# app/components/button_component.rb
+
+class ButtonComponent < ViewComponent::Base
+  include Cva::Helper
+
+  cva("inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm "\
+      "font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 "\
+      "focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 "\
+      "[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0", {
+        variants: {
+          variant: {
+            default:
+              "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+            destructive:
+              "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+            outline:
+              "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+            secondary:
+              "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
+            ghost: "hover:bg-accent hover:text-accent-foreground",
+            link: "text-primary underline-offset-4 hover:underline",
+          },
+          size: {
+            default: "h-9 px-4 py-2",
+            sm: "h-8 rounded-md px-3 text-xs",
+            lg: "h-10 rounded-md px-8",
+            icon: "h-9 w-9",
+          },
+        }
+      })
+
+  erb_template <<-ERB
+    <a href="<%= @href %>" class="<%= TailwindMerge::Merger.new.merge(variants(@style_variants)) %>"><%= content %></a>
+  ERB
+
+  def initialize(href:, style_variants = {})
+    @href = href
+    @style_variants = style_variants
+  end
+end
+```
+
+Rendered in a view as:
+
+```erb
+<%= render(ButtonComponent.new(href: submit_path, { variant: :outline, size: :lg })) do %>
+  Submit
+<% end %>
+```
+
+Returning:
+```html
+<a href="/submit" class="base classes + outline classes + size classes">Submit</a>
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version, push git commits and the created tag,
+and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Conventional Commits
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.
+
+Types of commits are:
+- `feat`: a new feature
+- `fix`: a bug fix
+- `perf`: code that improves performance
+- `chore`: updating build tasks, configs, formatting etc; no code change
+- `docs`: changes to documentation
+- `refactor`: refactoring code
+- `test`: changes to test
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/defvova/cva_rails.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/cva/helper.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Cva
+  # This module provides functionality for managing variants
+  # and class names dynamically based on a schema and parameters.
+  #
+  module Helper
+    extend ActiveSupport::Concern
+
+    included do
+      extend Clsx::Helper
+      class_attribute :cva_data
+    end
+
+    class_methods do # rubocop:disable Metrics/BlockLength
+      # Defines the base class names and variant schema for a given class.
+      # This data is shared through the class and
+      # can be accessed to build variant-specific class names dynamically.
+      #
+      # @param base [Array<String> | String] Base class names applied to the object/component.
+      # @param schema [Hash] Schema for defining variants, default variants, and compound variants.
+      #
+      # @return [void]
+      #
+      # @example
+      #   class Button
+      #     include Cva::Helper
+      #
+      #     cva(['px-4', 'py-2 bg-red-100'], {
+      #       variants: {
+      #         size: {
+      #           small: ["text-sm", "py-1", "px-2"],
+      #           medium: ["text-base", "h-4"]
+      #         }
+      #       },
+      #       compound_variants: [
+      #         {
+      #           size: :medium,
+      #           class: "hover:bg-blue-100"
+      #         }
+      #       ],
+      #       default_variants: {
+      #         size: :small
+      #       }
+      #     })
+      #   end
+      #
+      def cva(base, schema = {})
+        schema = {} if schema.nil?
+
+        validate_type(schema[:variants], Hash, "schema variants")
+        validate_type(schema[:compound_variants], Array, "schema compound_variants")
+        validate_type(schema[:default_variants], Hash, "schema default_variants")
+
+        self.cva_data = { base:, schema: schema.transform_keys(&:to_sym) }.freeze
+      end
+
+      # Builds a variants of class names based on the given parameters,
+      # including base classes, variant-specific classes, and compound variant classes.
+      #
+      # @param params [Hash<Symbol, String | Symbol>] A hash of user-specified variants and an optional custom class.
+      #
+      # @return [Array<String>] A combined array of class names based on the base, variant, and compound rules.
+      #
+      # **Expected Keys in params**
+      #   - Keys matching those defined in variants schema.
+      #   - :class (Optional) – Custom class to be included.
+      #
+      # @example
+      #   class Button
+      #     include Cva::Helper
+      #
+      #     cva(...)
+      #   end
+      #
+      #   # show.html.erb
+      #   <%= link_to 'Button', '#', class: Button.variants({ size: :medium, class: 'w-10' }) %>
+      #
+      #   # output:
+      #     <a href='#' class="px-4 py-2 bg-red-100 text-base h-4 w-10">Button</a>
+      #
+      def variants(params = {})
+        base_classes = cva_data[:base]
+        variant_classes = build_variant_class_names(params)
+        compound_classes = build_compound_variant_class_names(params)
+
+        clsx(base_classes, variant_classes, compound_classes, params[:class])
+      end
+
+      private
+
+      # Generates an array of class names based on individual variant keys.
+      #
+      # @param params [Hash<Symbol, String | Symbol>] Parameters specifying which variants to apply.
+      #
+      # @return [Array<String>] Class names associated with specified or default variants.
+      #
+      def build_variant_class_names(params)
+        variants = cva_data.dig(:schema, :variants)
+        return [] if variants.nil?
+
+        variants.keys.flat_map do |key|
+          selected_variant = params.fetch(key, cva_data.dig(:schema, :default_variants, key))
+          variants.dig(key, selected_variant&.to_sym)
+        end.compact
+      end
+
+      # Generates an array of class names based on compound variant rules
+      # if the conditions match the given parameters.
+      #
+      # @param params [Hash<Symbol, String | Symbol>] Parameters specifying variant values.
+      #
+      # @return [Array<String>] Class names for matching compound variants.
+      #
+      def build_compound_variant_class_names(params)
+        compound_variants = cva_data.dig(:schema, :compound_variants) || []
+        compound_variants.each_with_object([]) do |compound_variant, acc|
+          next unless compound_variant.except(:class) <= params
+
+          acc << compound_variant[:class]
+        end
+      end
+
+      # Validates the type of a given value, raising an error if the type does not match the expected type.
+      #
+      # @param value [Object] The value to be validated. Can be any object, including `nil`.
+      # @param expected_type [Class] The expected class/type of the value (e.g., `Hash`, `Array`, `String`).
+      # @param description [String] A description of the value being validated, used in the error message.
+      #
+      # @raise [ArgumentError] If the value is not `nil` and does not match the expected type.
+      #
+      def validate_type(value, expected_type, description)
+        return if value.nil? || value.is_a?(expected_type)
+
+        raise ArgumentError,
+              "Expected a #{expected_type} for #{description}, but got #{value.class}. " \
+              "Please ensure the #{description} is properly formatted."
+      end
+    end
+  end
+end

data/lib/cva/version.rb

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

data/lib/cva_rails.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "action_view"
+require "clsx-rails"
+
+require_relative "cva/version"
+require_relative "cva/helper"
+
+# :nodoc:
+module Cva
+  ActiveSupport.on_load(:action_view) { include Helper }
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: cva_rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Volodymyr Partytskyi
+bindir: exe
+cert_chain: []
+date: 2025-02-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: clsx-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A Rails helper designed to generate and manage multiple style or configuration
+  variants for components, enabling flexible and dynamic customization based on provided
+  parameters.
+email:
+- volodymyr.partytskyi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/cva/helper.rb
+- lib/cva/version.rb
+- lib/cva_rails.rb
+homepage: https://github.com/defvova/cva_rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/defvova/cva_rails
+  source_code_uri: https://github.com/defvova/cva_rails
+  changelog_uri: https://github.com/defvova/cva_rails/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.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: cva(Class Variance Authority) for rails views.
+test_files: []