clsx-rails 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2da83a9921c3d24cf5c9743bcaf1a11a63bae43f38f7ba197116436f8b2471d5
-  data.tar.gz: 280c9dfc3fc501ce352d755d620f49ec4e58b8c6de7e976487cd80ccf358e700
+  metadata.gz: bef11730f6fbfe63e305c35697e86117393c6114915d7b68853b3b2e12ee6737
+  data.tar.gz: d8244bf7d2fe9eaf563948b26eafbed1a4bd76aa17328aacd97ba2d513186a41
 SHA512:
-  metadata.gz: 33c8950cb1a10e94b22fc4a442dba3181dab708f7d1d6abec2bbd0b42aae009832aebcbd1c963c6050fa0ba397f4e4f960743675679d7ad46c507a3b2d9efb52
-  data.tar.gz: 47bb02df172c9c3d98251234112eaaef97b150d39b49c1e51a1fc5caf6d41c310719af75de32be86a15e7cb3a6062dd67fdbbe90e2c9765d9f3907f51399737f
+  metadata.gz: 7d99571d5e502310350a03aa3d2fc0da8f815f1bb8f33fa9bfd0e15da17439a26ab078d185c0c9fc7943ede6190dece4067d5d1996da71420fa9c1ee08438891
+  data.tar.gz: 38797c2478f8fe3da811851d79c00a3045aa629edaa4dd2b7708fd944793fc34b0a8e84ff342247ef1cba10befd1029777b42874673f4eeaf85ea11c2d95c0e7

data/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+## v3.1.0 (2026-07-01)
+
+### Added
+- `twm` Tailwind class-merge helper, available in all views via clsx-ruby 1.2.0's optional `tailwind_merge` integration (opt-in: `require 'clsx/tailwind_merge'` + `Clsx.merger =`)
+
+### Changed
+- Require clsx-ruby `~> 1.2` (was `~> 1.1, >= 1.1.3`); picks up faster single-string and hash paths
+
+## v3.0.1 (2026-02-27)
+
+### Changed
+- Require clsx-ruby >= 1.1.3 for correct deduplication behavior
+- Updated benchmark numbers to reflect current performance (2-4x faster)
+
 ## v3.0.0 (2026-02-13)
 
 ### Added

data/README.md

@@ -1,8 +1,29 @@
 # clsx-rails [![Gem Version](https://img.shields.io/gem/v/clsx-rails)](https://rubygems.org/gems/clsx-rails) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/clsx-rails)](https://app.codecov.io/gh/svyatov/clsx-rails) [![CI](https://github.com/svyatov/clsx-rails/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/clsx-rails/actions?query=workflow%3ACI) [![GitHub License](https://img.shields.io/github/license/svyatov/clsx-rails)](LICENSE.txt)
 
-> Rails view helper for constructing CSS class strings conditionally. Powered by [clsx-ruby](https://github.com/svyatov/clsx-ruby).
-
-Automatically adds `clsx` and `cn` helpers to all Rails views. The fastest alternative to Rails `class_names`.
+> The fastest conditional CSS class builder for Rails — 2–4x faster drop-in replacement for `class_names`.  
+> Powered by [clsx-ruby](https://github.com/svyatov/clsx-ruby).
+
+Auto-loads `clsx` and `cn` helpers into every Rails view. Zero configuration.
+
+## Contents
+
+- [Quick Start](#quick-start)
+- [Why clsx-rails?](#why-clsx-rails)
+  - [Blazing fast](#blazing-fast)
+  - [More feature-rich than `class_names`](#more-feature-rich-than-class_names)
+- [Usage](#usage)
+  - [Input types](#input-types)
+  - [Template engines](#template-engines)
+- [Framework Integration](#framework-integration)
+  - [Tailwind CSS](#tailwind-css)
+    - [Merging conflicting utilities](#merging-conflicting-utilities)
+  - [ViewComponent](#viewcomponent)
+  - [Phlex](#phlex)
+- [Differences from JavaScript clsx](#differences-from-javascript-clsx)
+- [Supported Versions](#supported-versions)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Quick Start
 
@@ -13,7 +34,7 @@ bundle add clsx-rails
 Or add it manually to the Gemfile:
 
 ```ruby
-gem 'clsx-rails', '~> 3.0'
+gem 'clsx-rails', '~> 3.1'
 ```
 
 That's it — `clsx` and `cn` are now available in all your views:
@@ -24,36 +45,41 @@ That's it — `clsx` and `cn` are now available in all your views:
 <% end %>
 ```
 
-## Why clsx-rails over Rails `class_names`?
+## Why clsx-rails?
 
-### Faster
+### Blazing fast
 
-**3-8x faster** than Rails `class_names` across every scenario:
+**2–4x faster** than Rails `class_names` — never slower, on realistic markup:
 
 | Scenario | clsx | Rails `class_names` | Speedup |
 |---|---|---|---|
-| Single string | 7.6M i/s | 911K i/s | **8.5x** |
-| String + hash | 2.4M i/s | 580K i/s | **4.1x** |
-| String array | 1.4M i/s | 357K i/s | **4.0x** |
-| Multiple strings | 1.5M i/s | 414K i/s | **3.7x** |
-| Hash | 2.2M i/s | 670K i/s | **3.3x** |
-| Mixed types | 852K i/s | 367K i/s | **2.3x** |
+| String array | 1.2M i/s | 317K i/s | **3.9x** |
+| Multiple strings | 1.3M i/s | 346K i/s | **3.8x** |
+| Single string | 2.3M i/s | 812K i/s | **2.9x** |
+| Mixed types | 901K i/s | 331K i/s | **2.7x** |
+| Hash | 1.7M i/s | 684K i/s | **2.4x** |
+| String + hash | 1.2M i/s | 550K i/s | **2.1x** |
 
 <sup>Ruby 4.0.1, Apple M1 Pro. Reproduce: `bundle exec ruby benchmark/run.rb`</sup>
 
-### More features
+### More feature-rich than `class_names`
 
 | Feature | clsx-rails | Rails `class_names` |
 |---|---|---|
-| Conditional classes | yes | yes |
-| Auto-deduplication | yes | yes |
-| 3-8x faster | yes | no |
-| Returns `nil` when empty | yes | no (returns `""`) |
-| Complex hash keys | yes | no |
-| Short `cn` alias | yes | no |
+| Conditional classes | ✅ | ✅ |
+| Auto-deduplication | ✅ | ✅ |
+| 2–4× faster | ✅ | ❌ |
+| Returns `nil` when empty | ✅ | ❌ (returns `""`) |
+| Complex hash keys | ✅ | ❌ |
+| Tailwind conflict merge (`twm`) | ✅ | ❌ |
+| Short `cn` alias | ✅ | ❌ |
 
 ## Usage
 
+`clsx` and its `cn` alias are available in every view — no `include`, no setup.
+
+### Input types
+
 ```ruby
 # Strings (variadic)
 clsx('foo', true && 'bar', 'baz')
@@ -75,14 +101,31 @@ cn(['foo', nil, false, 'bar'])
 clsx(['foo'], ['', nil, false, 'bar'], [['baz', [['hello'], 'there']]])
 # => 'foo bar baz hello there'
 
+# Symbols
+clsx(:foo, :'bar-baz')
+# => 'foo bar-baz'
+
+# Numbers
+clsx(1, 2, 3)
+# => '1 2 3'
+
+# Multi-token strings (deduplicated)
+clsx('a b', 'b c')
+# => 'a b c'
+
+# Whitespace is normalized; blank/whitespace-only => nil
+clsx("  a\tb\n\nc  ")
+# => 'a b c'
+
 # Kitchen sink (with nesting)
 cn('foo', ['bar', { baz: false, bat: nil }, ['hello', ['world']]], 'cya')
 # => 'foo bar hello world cya'
 ```
 
-### ERB
+### Template engines
 
 ```erb
+<%# ERB %>
 <%= tag.div class: clsx('foo', 'baz', 'is-active': @active) do %>
   Hello, world!
 <% end %>
@@ -92,68 +135,137 @@ cn('foo', ['bar', { baz: false, bat: nil }, ['hello', ['world']]], 'cya')
 </div>
 ```
 
-### HAML
-
 ```haml
+-# HAML
 %div{class: clsx('foo', 'baz', 'is-active': @active)}
   Hello, world!
 ```
 
-### Slim
-
 ```slim
+/ Slim
 div class=clsx('foo', 'baz', 'is-active': @active)
   | Hello, world!
 ```
 
-## Framework Examples
+## Framework Integration
 
-### ViewComponent
+Plain Rails views (ERB, HAML, Slim) get `clsx`/`cn` automatically. ViewComponent and Phlex
+render in their own object hierarchies, so include `Clsx::Helper` once in your base class.
+
+### Tailwind CSS
+
+Compose conditional utilities without string juggling:
 
 ```ruby
-class AlertComponent < ViewComponent::Base
-  def initialize(variant: :info, dismissible: false)
-    @variant = variant
-    @dismissible = dismissible
+class NavLink < ViewComponent::Base
+  include Clsx::Helper
+
+  def initialize(active: false)
+    @active = active
   end
 
   def classes
-    clsx("alert", "alert-#{@variant}", dismissible: @dismissible)
+    clsx(
+      'px-3 py-2 rounded-md text-sm font-medium transition-colors',
+      'text-white bg-indigo-600': @active,
+      'text-gray-300 hover:text-white hover:bg-gray-700': !@active
+    )
   end
 end
 ```
 
-### Phlex
+#### Merging conflicting utilities
+
+`clsx`/`cn` keep every class, so conflicting Tailwind utilities both survive:
+
+```ruby
+clsx('px-2 px-4') # => 'px-2 px-4'
+```
+
+For conflict resolution, opt into the [`tailwind_merge`](https://github.com/gjtorikian/tailwind_merge)
+gem. Add it to your `Gemfile` (clsx-rails itself pulls in only clsx-ruby), then require the
+integration once at boot:
+
+```ruby
+# Gemfile
+gem 'tailwind_merge'
+
+# config/initializers/clsx.rb
+require 'clsx/tailwind_merge'
+
+# Optional: configure the merger (prefix, cache size, custom theme, …)
+Clsx.merger = TailwindMerge::Merger.new
+```
+
+This adds a merged variant — `twm` — available in every view alongside `clsx`/`cn`.
+`clsx`/`cn` stay pure; only `twm` merges, and the last conflicting utility wins:
+
+```ruby
+twm('px-2 px-4')                       # => 'px-4'
+twm('p-4', 'p-2', 'bg-red', 'bg-blue') # => 'p-2 bg-blue'
+clsx('px-2 px-4')                      # => 'px-2 px-4' (unchanged)
+```
+
+It accepts the same arguments as `clsx` (strings, hashes, arrays, nesting), then merges:
 
 ```ruby
-class Badge < Phlex::HTML
+twm(['px-2', 'rounded'], 'px-4', 'px-6': active) # => 'rounded px-6' (when active)
+
+# Also available as a bracket API and a module method:
+Twm['px-2 px-4']       # => 'px-4'
+Clsx.twm('px-2 px-4')  # => 'px-4'
+```
+
+### ViewComponent
+
+Include the mixin once in your base component instead of per component:
+
+```ruby
+class ApplicationComponent < ViewComponent::Base
   include Clsx::Helper
+end
+```
 
-  def initialize(color: :blue, pill: false)
-    @color = color
-    @pill = pill
+Accept a caller-supplied `class:` and merge it — clsx dedupes across every argument, so
+callers can extend or repeat classes safely:
+
+```ruby
+class AlertComponent < ApplicationComponent
+  def initialize(variant: :info, dismissible: false, class: nil)
+    @variant = variant
+    @dismissible = dismissible
+    @html_class = binding.local_variable_get(:class) # `class` is a Ruby keyword
   end
 
-  def view_template
-    span(class: clsx("badge", "badge-#{@color}", pill: @pill)) { yield }
+  def classes
+    clsx("alert", "alert-#{@variant}", @html_class, dismissible: @dismissible)
   end
 end
 ```
 
-### Tailwind CSS
+```erb
+<div class="<%= classes %>">...</div>
+```
+
+### Phlex
+
+Include the mixin once in your base component, then merge caller-supplied attributes —
+clsx dedupes across every argument:
 
 ```ruby
-class NavLink < ViewComponent::Base
-  def initialize(active: false)
-    @active = active
+class ApplicationComponent < Phlex::HTML
+  include Clsx::Helper
+end
+
+class Badge < ApplicationComponent
+  def initialize(color: :blue, pill: false, **attributes)
+    @color = color
+    @pill = pill
+    @attributes = attributes
   end
 
-  def classes
-    clsx(
-      'px-3 py-2 rounded-md text-sm font-medium transition-colors',
-      'text-white bg-indigo-600': @active,
-      'text-gray-300 hover:text-white hover:bg-gray-700': !@active
-    )
+  def view_template
+    span(class: clsx("badge", "badge-#{@color}", @attributes[:class], pill: @pill)) { yield }
   end
 end
 ```
@@ -165,30 +277,27 @@ end
    clsx(nil, false) # => nil
    ```
 
-2. **Deduplication** — duplicate classes are automatically removed:
+2. **Deduplication** — Duplicate classes are automatically removed, even across multi-token strings:
    ```ruby
-   clsx('foo', 'foo') # => 'foo'
+   clsx('foo', 'foo')      # => 'foo'
+   clsx('foo bar', 'foo')  # => 'foo bar'
    ```
 
-3. **Falsy values** — in Ruby only `false` and `nil` are falsy, so `0`, `''`, `[]`, `{}` are all truthy:
+3. **Falsy values** — In Ruby only `false` and `nil` are falsy, so `0`, `''`, `[]`, `{}` are all truthy:
    ```ruby
    clsx('foo' => 0, bar: []) # => 'foo bar'
    ```
 
-4. **Complex hash keys** — any valid `clsx` input works as a hash key:
+4. **Complex hash keys** — Any valid `clsx` input works as a hash key:
    ```ruby
    clsx([{ foo: true }, 'bar'] => true) # => 'foo bar'
    ```
 
-5. **Ignored values** — boolean `true` and `Proc`/lambda objects are silently ignored:
+5. **Ignored values** — Boolean `true` and `Proc`/lambda objects are silently ignored:
    ```ruby
    clsx('', proc {}, -> {}, nil, false, true) # => nil
    ```
 
-## Looking for a framework-agnostic version?
-
-See [clsx-ruby](https://github.com/svyatov/clsx-ruby) — works with Rails, Sinatra, Hanami, or plain Ruby.
-
 ## Supported Versions
 
 Ruby 3.2+ and Rails 7.2+.
@@ -196,9 +305,9 @@ Ruby 3.2+ and Rails 7.2+.
 ## Development
 
 ```bash
-bin/setup                            # install dependencies
-bundle exec rake test                # run tests
-bundle exec ruby benchmark/run.rb   # run benchmarks
+bin/setup                          # install dependencies
+bundle exec rake test              # run tests
+bundle exec ruby benchmark/run.rb  # run benchmarks
 ```
 
 ## Contributing

data/lib/clsx/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Clsx
   module Rails
-    VERSION = '3.0.0'
+    VERSION = '3.1.0'
   end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: clsx-rails
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Leonid Svyatov
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -29,16 +29,17 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-description: Adds clsx and cn helpers to all Rails views for constructing CSS class
-  strings conditionally
+        version: '1.2'
+description: Build CSS class strings from conditional expressions, hashes, arrays,
+  or nested structures. 2-4x faster drop-in replacement for Rails class_names. Supports
+  ViewComponent, Phlex, and Tailwind CSS.
 email:
 - leonid@svyatov.com
 executables: []
@@ -54,7 +55,6 @@ homepage: https://github.com/svyatov/clsx-rails
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/svyatov/clsx-rails
   source_code_uri: https://github.com/svyatov/clsx-rails
   changelog_uri: https://github.com/svyatov/clsx-rails/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
@@ -72,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.12
 specification_version: 4
-summary: Rails view helper integration for clsx-ruby
+summary: The fastest conditional CSS class builder for Rails
 test_files: []