clsx-ruby 1.1.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f20a56982120e4142d5932688887cc7f4b38a3596e01ce8aacf1f7b5b15f8d4
-  data.tar.gz: ebbd199c2d2ad139c2dda52680953778092b21708e01aef7b09d4619d932333a
+  metadata.gz: 102bb836f576baf8a09d29ce9eacbcfe3023ce9ba76d0099087d1978c4a6f451
+  data.tar.gz: 7d25f7931b2afad81609037e54ee004ffb02197aee6300547d8904249125a6c7
 SHA512:
-  metadata.gz: 5ed8a104aac715ac054d3399f6cf0c6e15a1b5a2df6307218c5f31172ebe7c1aca261d24b8b7ed23e3a06974002c2c1b9af7f857b4a4ebf4e90eea3694e75050
-  data.tar.gz: 83a0ea7711cab8e01b9eb8f71376af34e51d21bbbbd7da6091e1abe323d4145228c6e8ed44ec13f6421670ad1685a7857c531e198c100e553f77771d4183db45
+  metadata.gz: 574f8ee8bc63b7d4dbeaaae07a8232ea8fc0d0459f68d60eb99b2191c35060bc200530898c940f0b6f7f91753faab898b41813227347bc8108f2b599d8eb46ed
+  data.tar.gz: d5da4ba0eef261a1e19bfa83976c83e05ad36803538dccf1a5a090c7a54516c05dbda502948aa5b52f1c8f12deedf23e08bb2b26dafb852e81827233c9a99201

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## v1.2.0
+
+### Added
+
+- Optional Tailwind class merging via the `tailwind_merge` gem: `require 'clsx/tailwind_merge'` adds `twm`/`Twm[]` (and `Clsx.twm`) that resolve conflicting utilities (e.g. `px-2 px-4` → `px-4`). `clsx`/`cn` stay pure; the core gem stays zero-dependency unless the integration is required. Configure with `Clsx.merger = TailwindMerge::Merger.new(config: {...})`.
+
+### Changed
+
+- Faster `clsx`/`cn` for the common single-string and hash inputs via dispatch elision, fewer allocations, and cheaper whitespace scanning (no API or output change)
+
+## v1.1.3
+
+### Fixed
+
+- Normalize whitespace in class strings: tabs, newlines, leading/trailing spaces, and consecutive spaces are collapsed to single spaces (e.g., `clsx("foo\tbar")` returns `"foo bar"`)
+- Whitespace-only strings now correctly return `nil` (e.g., `clsx("   ")` returns `nil`)
+- Deduplicate class names across multi-token strings (e.g., `clsx("foo bar", "foo")` now returns `"foo bar"`)
+
 ## v1.1.2
 
 ### Changed

data/README.md

@@ -34,18 +34,19 @@ For Rails integration (adds `clsx` and `cn` helpers to all views), see [clsx-rai
 
 ### 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-ruby | 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** |
+| Token | 4.7M i/s | 1.1M i/s | **4.2x** |
+| String array | 1.3M i/s | 452K i/s | **3.0x** |
+| String + hash | 1.8M i/s | 610K i/s | **2.9x** |
+| Utility string | 1.0M i/s | 371K i/s | **2.7x** |
+| Long utility | 561K i/s | 209K i/s | **2.7x** |
+| Utility + hash | 1.1M i/s | 457K i/s | **2.3x** |
+| Hash | 1.9M i/s | 936K i/s | **2.0x** |
 
-<sup>Ruby 4.0.1, Apple M1 Pro. Reproduce: `bundle exec ruby benchmark/run.rb`</sup>
+<sup>Ruby 4.0.5, Apple M1 Pro. 2.8× geomean; each row verified to produce output identical to Rails `class_names`. Reproduce: `bundle exec ruby benchmark/vs_rails.rb`</sup>
 
 ### More feature-rich than `class_names`
 
@@ -53,7 +54,7 @@ For Rails integration (adds `clsx` and `cn` helpers to all views), see [clsx-rai
 |---|---|---|
 | Conditional classes | ✅ | ✅ |
 | Auto-deduplication | ✅ | ✅ |
-| 3–8× faster | ✅ | ❌ |
+| 2–4× faster | ✅ | ❌ |
 | Returns `nil` when empty | ✅ | ❌ (returns `""`) |
 | Complex hash keys | ✅ | ❌ |
 | Framework-agnostic | ✅ | ❌ |
@@ -149,6 +150,11 @@ Clsx['foo', ['bar', { baz: false, bat: nil }, ['hello', ['world']]], 'cya']
 
 ## Framework Examples
 
+clsx is framework-agnostic. Any Ruby view object — ViewComponent, Phlex, or a plain object —
+gets `clsx`/`cn` by including `Clsx::Helper`; no adapter needed. For Rails ERB views, the
+companion [clsx-rails](https://github.com/svyatov/clsx-rails) gem auto-loads the helpers into
+ActionView.
+
 ### Rails
 
 ```erb
@@ -165,17 +171,27 @@ erb :"<div class='#{Clsx['nav', active: @active]}'>...</div>"
 
 ### ViewComponent
 
+Include the mixin once in your base component instead of per component:
+
 ```ruby
-class AlertComponent < ViewComponent::Base
+class ApplicationComponent < ViewComponent::Base
   include Clsx::Helper
+end
+```
 
-  def initialize(variant: :info, dismissible: false)
+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 classes
-    clsx("alert", "alert-#{@variant}", dismissible: @dismissible)
+    clsx("alert", "alert-#{@variant}", @html_class, dismissible: @dismissible)
   end
 end
 ```
@@ -204,23 +220,67 @@ class NavLink < ViewComponent::Base
 end
 ```
 
+#### 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-ruby itself stays dependency-free), then require the
+integration once at boot:
+
+```ruby
+# config/initializers/clsx.rb
+require 'clsx/tailwind_merge'
+
+# Optional: configure the merger (prefix, cache size, custom theme, …)
+Clsx.merger = TailwindMerge::Merger.new(config: { prefix: 'tw' })
+```
+
+This adds a merged variant — `twm` / `Twm[]` — the last conflicting utility wins.
+`clsx`/`cn` stay pure; only `twm`/`Twm` merge:
+
+```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)
+
+# Also available as a mixin method and a module method:
+include Clsx::Helper
+twm('px-2 px-4')       # => "px-4"
+Clsx.twm('px-2 px-4')  # => "px-4"
+```
+
 ### Phlex
 
+Include the mixin once in your base component, then merge caller-supplied attributes —
+clsx dedupes across every argument:
+
 ```ruby
-class Badge < Phlex::HTML
+class ApplicationComponent < Phlex::HTML
   include Clsx::Helper
+end
 
-  def initialize(color: :blue, pill: false)
+class Badge < ApplicationComponent
+  def initialize(color: :blue, pill: false, **attributes)
     @color = color
     @pill = pill
+    @attributes = attributes
   end
 
   def view_template
-    span(class: clsx("badge", "badge-#{@color}", pill: @pill)) { yield }
+    span(class: clsx("badge", "badge-#{@color}", @attributes[:class], pill: @pill)) { yield }
   end
 end
 ```
 
+Phlex's own `class: [...]` arrays and `mix` cover simple cases. Reach for clsx when you want
+hash-conditional syntax (`pill: @pill`) or cross-argument dedup when merging caller-supplied
+classes.
+
 ## Differences from JavaScript clsx
 
 1. **Returns `nil`** when no classes apply (not an empty string). This prevents rendering empty `class=""` attributes in template engines that skip `nil`:
@@ -228,9 +288,10 @@ 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:

data/lib/clsx/helper.rb

@@ -7,6 +7,11 @@ module Clsx
   #   include Clsx::Helper
   #   clsx('btn', active: @active)  # => "btn active"
   module Helper
+    # Single-pass scan for tab/newline. Collapses two consecutive `include?`
+    # scans into one regex match (no MatchData alloc). Space is checked
+    # separately first so the common "has a space" case still short-circuits.
+    TAB_OR_NEWLINE = /[\t\n]/
+
     # Build a CSS class string from an arbitrary mix of arguments.
     #
     # Falsy values (+nil+, +false+) and standalone +true+ are discarded.
@@ -26,12 +31,35 @@ module Clsx
     #   clsx(%w[foo bar], hidden: true)         # => "foo bar hidden"
     def clsx(*args)
       return nil if args.empty?
-      return clsx_single(args[0]) if args.size == 1
-      return clsx_string_hash(args[0], args[1]) if args.size == 2 && args[0].is_a?(String) && args[1].is_a?(Hash)
+
+      if args.size == 1
+        arg = args[0]
+        # Inline the two dominant single-arg shapes (String, Hash) so they skip
+        # the clsx_one dispatch. Other types fall through to clsx_one, which no
+        # longer re-checks String or Hash (already ruled out here).
+        if arg.is_a?(String)
+          return nil if arg.empty?
+          return arg unless arg.include?(' ') || arg.match?(TAB_OR_NEWLINE)
+
+          return clsx_dedup_str(arg)
+        end
+
+        return clsx_hash(arg) if arg.is_a?(Hash)
+
+        return clsx_one(arg)
+      end
+
+      if args.size == 2 && args[0].is_a?(String) && args[1].is_a?(Hash)
+        str = args[0]
+        return clsx_hash(args[1]) if str.empty?
+        return clsx_str_hash_full(str, args[1]) if str.include?(' ') || str.match?(TAB_OR_NEWLINE)
+
+        return clsx_str_hash(str, args[1])
+      end
 
       seen = {}
-      clsx_process(args, seen)
-      seen.empty? ? nil : seen.keys.join(' ')
+      clsx_walk(args, seen)
+      clsx_join(seen)
     end
 
     # (see #clsx)
@@ -39,131 +67,299 @@ module Clsx
 
     private
 
-    # Single-argument fast path — dispatches by type to avoid allocating
-    # a +seen+ hash when possible.
+    # Single-argument fast path for descriptors other than String and Hash,
+    # both of which are handled inline in {#clsx} — this method never sees them.
     #
-    # @param arg [String, Symbol, Hash, Array] single class descriptor
-    # @return [String] resolved class string
-    # @return [nil] when the argument produces no classes
-    def clsx_single(arg)
-      return (arg.empty? ? nil : arg) if arg.is_a?(String)
-      return arg.name if arg.is_a?(Symbol)
-      return clsx_simple_hash(arg) if arg.is_a?(Hash)
+    # @param arg [Object] single non-String, non-Hash class descriptor
+    # @return [String, nil]
+    def clsx_one(arg)
+      if arg.is_a?(Symbol)
+        s = arg.name
+        return s unless s.include?(' ') || s.match?(TAB_OR_NEWLINE)
+
+        return clsx_dedup_str(s)
+      end
 
       if arg.is_a?(Array)
         return nil if arg.empty?
 
-        if arg.all?(String)
-          seen = {}
-          arg.each { |s| seen[s] = true unless s.empty? }
-          return seen.empty? ? nil : seen.keys.join(' ')
-        end
-
         seen = {}
-        clsx_process(arg, seen)
-        return seen.empty? ? nil : seen.keys.join(' ')
+        clsx_walk(arg, seen)
+        return clsx_join(seen)
       end
 
-      return arg.to_s if arg.is_a?(Numeric)
       return nil if !arg || arg == true || arg.is_a?(Proc)
 
-      str = arg.to_s
-      str.empty? ? nil : str
+      s = arg.to_s
+      s.empty? ? nil : s
+    end
+
+    # Dedup and normalize a multi-token string. Handles whitespace-only
+    # input, leading/trailing whitespace, tabs, newlines, and duplicates.
+    #
+    # @param str [String] space-separated class string
+    # @return [String, nil]
+    def clsx_dedup_str(str)
+      parts = str.split
+      return nil if parts.empty?
+      return parts[0] if parts.length == 1
+      # Already canonical (single-spaced, no dup/leading/trailing/tab/newline)
+      # iff uniq! removed nothing and token count == space count + 1; then
+      # return str as-is and skip the join allocation.
+      return str if !parts.uniq! && parts.length == str.count(' ') + 1
+
+      parts.join(' ')
     end
 
-    # Hash-only fast path — no dedup needed since hash keys are unique.
-    # Falls back to {#clsx_process} on non-String/Symbol keys.
+    # Hash-only fast path using a string buffer, skipping cross-key dedup.
+    # Hash keys are unique, so the only way two distinct keys collide on a
+    # class name is a Symbol and a String of the same name (+:foo+ and
+    # +"foo"+ both yield "foo"). Hence on mixed key types — plus multi-token
+    # or complex (Array/Hash) keys — it falls back to {#clsx_hash_full}, which
+    # deduplicates.
     #
-    # @param hash [Hash{String, Symbol => Boolean}] class-name => condition pairs
-    # @return [String] resolved class string
-    # @return [nil] when no hash values are truthy
-    def clsx_simple_hash(hash)
+    # @param hash [Hash] class-name => condition pairs
+    # @return [String, nil]
+    def clsx_hash(hash)
       return nil if hash.empty?
 
       buf = nil
+      owned = false
+      key_type = nil
+
       hash.each do |key, value|
         next unless value
 
         if key.is_a?(Symbol)
-          str = key.name
-          buf ? (buf << ' ' << str) : (buf = str.dup)
+          return clsx_hash_full(hash) if key_type == :string
+
+          key_type = :symbol
+          s = key.name
+          return clsx_hash_full(hash) if s.include?(' ')
+
+          # Defer the dup: hold the first token by reference (frozen name or the
+          # caller's key) and only copy when a second token must be appended.
+          if buf
+            buf = buf.dup unless owned
+            owned = true
+            buf << ' ' << s
+          else
+            buf = s
+          end
         elsif key.is_a?(String)
           next if key.empty?
 
-          buf ? (buf << ' ' << key) : (buf = key.dup)
+          return clsx_hash_full(hash) if key_type == :symbol
+          return clsx_hash_full(hash) if key.include?(' ')
+
+          key_type = :string
+          if buf
+            buf = buf.dup unless owned
+            owned = true
+            buf << ' ' << key
+          else
+            buf = key
+          end
         else
-          seen = {}
-          clsx_process([hash], seen)
-          return seen.empty? ? nil : seen.keys.join(' ')
+          return clsx_hash_full(hash)
         end
       end
+
+      return nil unless buf
+      return clsx_dedup_str(buf) if buf.match?(TAB_OR_NEWLINE)
+
       buf
     end
 
-    # Fast path for +clsx('base', active: cond)+ — deduplicates only against
-    # the base string. Falls back to {#clsx_process} on non-String/Symbol keys.
+    # Hash fallback with full dedup via walker.
     #
-    # @param str [String] base class name
-    # @param hash [Hash{String, Symbol => Boolean}] class-name => condition pairs
-    # @return [String] resolved class string
-    # @return [nil] when no classes apply
-    def clsx_string_hash(str, hash)
-      return clsx_simple_hash(hash) if str.empty?
+    # @param hash [Hash] class-name => condition pairs
+    # @return [String, nil]
+    def clsx_hash_full(hash)
+      seen = {}
+      clsx_walk_hash(hash, seen)
+      clsx_join(seen)
+    end
 
+    # Fast path for +clsx('base', active: cond)+ pattern where base is a
+    # single token. Deduplicates via direct string comparison against +str+.
+    #
+    # A key containing a space forces the {#clsx_str_hash_full} fallback —
+    # whole-key comparison can't dedup tokens *inside* a multi-token key, and
+    # the trailing normalization only rescans for tab/newline. Tab/newline keys
+    # are kept and normalized by that trailing {#clsx_dedup_str} pass, which
+    # splits on all whitespace.
+    #
+    # @param str [String] base class name
+    # @param hash [Hash] class-name => condition pairs
+    # @return [String, nil]
+    def clsx_str_hash(str, hash)
       buf = str.dup
+      key_type = nil
+
       hash.each do |key, value|
         next unless value
 
         if key.is_a?(Symbol)
+          return clsx_str_hash_full(str, hash) if key_type == :string
+
+          key_type = :symbol
           s = key.name
-          buf << ' ' << s unless s == str
+          return clsx_str_hash_full(str, hash) if s.include?(' ')
+
+          next if s == str
+
+          buf << ' ' << s
         elsif key.is_a?(String)
-          buf << ' ' << key unless key.empty? || key == str
+          return clsx_str_hash_full(str, hash) if key_type == :symbol
+
+          key_type = :string
+          next if key.empty?
+
+          return clsx_str_hash_full(str, hash) if key.include?(' ')
+
+          next if key == str
+
+          buf << ' ' << key
         else
-          seen = { str => true }
-          clsx_process([hash], seen)
-          return seen.size == 1 ? str : seen.keys.join(' ')
+          return clsx_str_hash_full(str, hash)
         end
       end
+
+      return clsx_dedup_str(buf) if buf.match?(TAB_OR_NEWLINE)
+
       buf
     end
 
-    # General-purpose recursive walker. Processes hash keys inline for simple
-    # types (String/Symbol) to avoid deferred-array allocation. Only complex
-    # keys (Array, nested Hash) recurse.
+    # Full str+hash dedup using array lookup. Splits the base string once,
+    # then checks hash keys against the parts array via linear search.
+    # Falls back to Hash dedup on mixed key types or complex keys.
     #
-    # @param args [Array<String, Symbol, Hash, Array, Numeric, nil, false>] nested arguments
+    # @param str [String] base class name (contains spaces)
+    # @param hash [Hash] class-name => condition pairs
+    # @return [String, nil]
+    def clsx_str_hash_full(str, hash)
+      parts = str.split
+      return clsx_hash(hash) if parts.empty?
+      return clsx_str_hash_full_walk(parts, hash) if parts.length == 1
+
+      buf = if parts.uniq! || parts.length != str.count(' ') + 1
+              parts.join(' ')
+            else
+              str.dup
+            end
+
+      key_type = nil
+
+      hash.each do |key, value|
+        next unless value
+
+        if key.is_a?(Symbol)
+          return clsx_str_hash_full_walk(parts, hash) if key_type == :string
+
+          key_type = :symbol
+          s = key.name
+          return clsx_str_hash_full_walk(parts, hash) if s.include?(' ') || s.match?(TAB_OR_NEWLINE)
+
+          next if parts.include?(s)
+
+          buf << ' ' << s
+        elsif key.is_a?(String)
+          return clsx_str_hash_full_walk(parts, hash) if key_type == :symbol
+
+          key_type = :string
+          next if key.empty?
+          return clsx_str_hash_full_walk(parts, hash) if key.include?(' ') || key.match?(TAB_OR_NEWLINE)
+
+          next if parts.include?(key)
+
+          buf << ' ' << key
+        else
+          return clsx_str_hash_full_walk(parts, hash)
+        end
+      end
+
+      buf
+    end
+
+    # Hash-based fallback for str+hash when array lookup can't handle it.
+    #
+    # @param parts [Array<String>] pre-split base tokens
+    # @param hash [Hash] class-name => condition pairs
+    # @return [String, nil]
+    def clsx_str_hash_full_walk(parts, hash)
+      seen = {}
+      parts.each { |s| seen[s] = true }
+      clsx_walk_hash(hash, seen)
+      clsx_join(seen)
+    end
+
+    # General-purpose recursive walker. Stores strings as-is; normalization
+    # and dedup are handled by {#clsx_join} after walking.
+    #
+    # @param args [Array] nested arguments to walk
     # @param seen [Hash{String => true}] accumulator for deduplication
     # @return [void]
-    def clsx_process(args, seen)
+    def clsx_walk(args, seen)
       args.each do |arg|
         if arg.is_a?(String)
           seen[arg] = true unless arg.empty?
         elsif arg.is_a?(Symbol)
           seen[arg.name] = true
         elsif arg.is_a?(Array)
-          clsx_process(arg, seen)
+          clsx_walk(arg, seen)
         elsif arg.is_a?(Hash)
-          arg.each do |key, value|
-            next unless value
-
-            if key.is_a?(Symbol)
-              seen[key.name] = true
-            elsif key.is_a?(String)
-              seen[key] = true unless key.empty?
-            else
-              clsx_process([key], seen)
-            end
-          end
-        elsif arg.is_a?(Numeric)
-          seen[arg.to_s] = true
+          clsx_walk_hash(arg, seen)
         elsif !arg || arg == true || arg.is_a?(Proc)
           next
         else
-          str = arg.to_s
-          seen[str] = true unless str.empty?
+          s = arg.to_s
+          seen[s] = true unless s.empty?
+        end
+      end
+    end
+
+    # Hash-specific walker — avoids wrapping hash in an array for recursion.
+    #
+    # @param hash [Hash] hash to walk
+    # @param seen [Hash{String => true}] accumulator
+    # @return [void]
+    def clsx_walk_hash(hash, seen)
+      return if hash.empty?
+
+      hash.each do |key, value|
+        next unless value
+
+        if key.is_a?(Symbol)
+          seen[key.name] = true
+        elsif key.is_a?(String)
+          seen[key] = true unless key.empty?
+        elsif key.is_a?(Array)
+          clsx_walk(key, seen)
+        elsif key.is_a?(Hash)
+          clsx_walk_hash(key, seen)
+        elsif !key || key == true || key.is_a?(Proc)
+          next
+        else
+          s = key.to_s
+          seen[s] = true unless s.empty?
         end
       end
     end
+
+    # Post-join dedup and normalization: detects multi-token entries via
+    # space count mismatch or tab/newline presence, then splits and rebuilds.
+    #
+    # @param seen [Hash{String => true}] token accumulator
+    # @return [String, nil] space-joined class string
+    def clsx_join(seen)
+      return nil if seen.empty?
+
+      result = seen.keys.join(' ')
+      return result if result.count(' ') + 1 == seen.size && !result.match?(TAB_OR_NEWLINE)
+
+      normalized = result.split.uniq.join(' ')
+      normalized.empty? ? nil : normalized
+    end
   end
 end

data/lib/clsx/tailwind_merge.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'clsx'
+require 'tailwind_merge'
+
+# Opt-in Tailwind merging. Requiring this file (once, at boot) pulls in the
+# {https://github.com/gjtorikian/tailwind_merge tailwind_merge} gem and adds a
+# merged variant of +clsx+ — {Clsx.twm}, the {Helper#twm} mixin method, and the
+# +Twm[]+ shortcut — that resolves conflicting Tailwind utilities
+# (e.g. +"px-2 px-4"+ becomes +"px-4"+).
+#
+# +clsx+/+cn+ are left untouched and stay pure; only +twm+/+Twm+ merge. Without
+# requiring this file the core gem carries no dependency.
+#
+# @example
+#   require 'clsx/tailwind_merge'
+#   Twm['px-2 px-4']  # => "px-4"
+#
+# @example Custom merger (configure once at boot)
+#   Clsx.merger = TailwindMerge::Merger.new(config: { prefix: 'tw' })
+module Clsx
+  @merger_mutex = Mutex.new
+
+  class << self
+    # @param merger [#merge] a preconfigured merger (or +nil+ to reset to the lazy default)
+    # @return [#merge, nil]
+    attr_writer :merger
+
+    # Process-wide merger, built once. Building a {TailwindMerge::Merger} is
+    # expensive, so double-checked locking constructs it exactly once even under
+    # concurrent first use; after that the lock is never taken again.
+    #
+    # @return [#merge]
+    def merger
+      @merger || @merger_mutex.synchronize { @merger ||= TailwindMerge::Merger.new }
+    end
+  end
+
+  # Adds the merged {#twm} variant to the {Helper} mixin.
+  module Helper
+    # Like {#clsx}, but pipes the result through {Clsx.merger} to resolve
+    # conflicting Tailwind utilities. Returns +nil+ (skipping the merger) when no
+    # classes apply, matching {#clsx}.
+    #
+    # @return [String, nil]
+    #
+    # @example
+    #   twm('px-2 px-4')                 # => "px-4"
+    #   twm('px-2', 'px-4', hidden: c)   # => "px-4"
+    def twm(*)
+      classes = clsx(*)
+      classes && Clsx.merger.merge(classes)
+    end
+  end
+
+  # Bracket shortcut for {Helper#twm}, mirroring {Clsx.[]}.
+  module Twm
+    # (see Helper#twm)
+    def self.[](*)
+      Clsx.twm(*)
+    end
+  end
+end
+
+# Short top-level shortcut — only defined if +Twm+ is not already taken.
+Twm = Clsx::Twm unless Object.const_defined?(:Twm)

data/lib/clsx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clsx
-  VERSION = '1.1.2'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clsx-ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -23,6 +23,7 @@ files:
 - README.md
 - lib/clsx.rb
 - lib/clsx/helper.rb
+- lib/clsx/tailwind_merge.rb
 - lib/clsx/version.rb
 homepage: https://github.com/svyatov/clsx-ruby
 licenses:
@@ -45,7 +46,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 Ruby
 test_files: []