clsx-rails 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62267a91d9e4596cd5a4da9cf8569a0ac6420e6eb4368a099b64ed3a07e7bc18
-  data.tar.gz: a0d7c426b1aeea779d70a5a10cc800f9de7c5376cc3fcf5c27ae409c8ee07097
+  metadata.gz: bef11730f6fbfe63e305c35697e86117393c6114915d7b68853b3b2e12ee6737
+  data.tar.gz: d8244bf7d2fe9eaf563948b26eafbed1a4bd76aa17328aacd97ba2d513186a41
 SHA512:
-  metadata.gz: a0f10f1585daeeae9872a3e07faff6e427c453709dce9e2d698f9dca89073068eb0080fcf28c6a2d4d023c2fa68ecaf5810cdcaa12bc0728c868f88cb8c34fda
-  data.tar.gz: e3a77cfc660fe7295027d7447394c0b37602ba077ab6ea77c5d19cafdaa90109d1dd69d1128f3f8e504703fd996a3ced922d8185a1a4669656360df647de7e7f
+  metadata.gz: 7d99571d5e502310350a03aa3d2fc0da8f815f1bb8f33fa9bfd0e15da17439a26ab078d185c0c9fc7943ede6190dece4067d5d1996da71420fa9c1ee08438891
+  data.tar.gz: 38797c2478f8fe3da811851d79c00a3045aa629edaa4dd2b7708fd944793fc34b0a8e84ff342247ef1cba10befd1029777b42874673f4eeaf85ea11c2d95c0e7

data/CHANGELOG.md

@@ -6,6 +6,14 @@ 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

data/README.md

@@ -1,9 +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)
 
-> The fastest conditional CSS class builder for Rails — 2-4x faster drop-in replacement for `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).
 
-Adds `clsx` and `cn` helpers to all views automatically.
+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
 
@@ -14,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:
@@ -25,11 +45,11 @@ 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
 
-**2-4x 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 |
 |---|---|---|---|
@@ -42,19 +62,24 @@ That's it — `clsx` and `cn` are now available in all your views:
 
 <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 |
-| 2-4x 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')
@@ -76,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 %>
@@ -93,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
 ```
@@ -166,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+.

data/lib/clsx/rails/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clsx-rails
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -29,20 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.3
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.3
+        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.
@@ -78,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: The fastest conditional CSS class builder for Rails
 test_files: []