clsx-ruby 1.1.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7af7dbc1bf63dae86a10afc293087f0528b82d479e0f4cc2e82a6944c79c8ed4
-  data.tar.gz: 2ed149e30e3da918e403697ea511ca597c6bece1bbb2965ae6dd02e0d054a4b8
+  metadata.gz: 102bb836f576baf8a09d29ce9eacbcfe3023ce9ba76d0099087d1978c4a6f451
+  data.tar.gz: 7d25f7931b2afad81609037e54ee004ffb02197aee6300547d8904249125a6c7
 SHA512:
-  metadata.gz: 37be556d78cb762df769303b6143e7872fd0bc67f26110720e31cf34238d3c657cab2f09b39f899163babcd7086c044d281d157261cb73736e7fcf4fe81d6b05
-  data.tar.gz: 6c5af47dba54f7d17fa5ba00a8f9bd2e96f34581cdd3f3544702b93699ec9bb0f5068147e294b5cff976341f64aa56353f2713b90929dbdfd443a5d83a62560e
+  metadata.gz: 574f8ee8bc63b7d4dbeaaae07a8232ea8fc0d0459f68d60eb99b2191c35060bc200530898c940f0b6f7f91753faab898b41813227347bc8108f2b599d8eb46ed
+  data.tar.gz: d5da4ba0eef261a1e19bfa83976c83e05ad36803538dccf1a5a090c7a54516c05dbda502948aa5b52f1c8f12deedf23e08bb2b26dafb852e81827233c9a99201

data/CHANGELOG.md

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

data/README.md

@@ -34,18 +34,19 @@ For Rails integration (adds `clsx` and `cn` helpers to all views), see [clsx-rai
 
 ### Blazing fast
 
-**2-3x 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 |
 |---|---|---|---|
-| String array | 1.3M i/s | 369K i/s | **3.4x** |
-| Multiple strings | 1.3M i/s | 408K i/s | **3.3x** |
-| Single string | 2.4M i/s | 893K i/s | **2.7x** |
-| Mixed types | 912K i/s | 358K i/s | **2.5x** |
-| Hash | 1.7M i/s | 672K i/s | **2.5x** |
-| String + hash | 1.2M i/s | 565K i/s | **2.1x** |
+| 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 | ✅ | ✅ |
-| 2–3× 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`:

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,29 @@ module Clsx
     #   clsx(%w[foo bar], hidden: true)         # => "foo bar hidden"
     def clsx(*args)
       return nil if args.empty?
-      return clsx_one(args[0]) if args.size == 1
+
+      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.include?("\t") || str.include?("\n") # rubocop:disable Layout/EmptyLineAfterGuardClause
+        return clsx_str_hash_full(str, args[1]) if str.include?(' ') || str.match?(TAB_OR_NEWLINE)
+
         return clsx_str_hash(str, args[1])
       end
 
@@ -45,31 +67,19 @@ module Clsx
 
     private
 
-    # Single-argument fast path — dispatches by type, handles multi-token
-    # string dedup without allocating a walker Hash for simple cases.
+    # 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 [Object] single class descriptor
+    # @param arg [Object] single non-String, non-Hash class descriptor
     # @return [String, nil]
     def clsx_one(arg)
-      if arg.is_a?(String)
-        return nil if arg.empty?
-        return arg unless arg.include?(' ') || arg.include?("\t") || arg.include?("\n")
-
-        parts = arg.split
-        return nil if parts.empty?
-        return parts[0] if parts.length == 1
-        return arg if !parts.uniq! && parts.length == arg.count(' ') + 1 # rubocop:disable Layout/EmptyLineAfterGuardClause
-        return parts.join(' ')
-      end
-
       if arg.is_a?(Symbol)
         s = arg.name
-        return s unless s.include?(' ') || s.include?("\t") || s.include?("\n") # rubocop:disable Layout/EmptyLineAfterGuardClause
+        return s unless s.include?(' ') || s.match?(TAB_OR_NEWLINE)
+
         return clsx_dedup_str(s)
       end
 
-      return clsx_hash(arg) if arg.is_a?(Hash)
-
       if arg.is_a?(Array)
         return nil if arg.empty?
 
@@ -93,13 +103,20 @@ module Clsx
       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 using string buffer. Falls back to Hash dedup
-    # on mixed key types, multi-token keys, or complex 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] class-name => condition pairs
     # @return [String, nil]
@@ -107,6 +124,7 @@ module Clsx
       return nil if hash.empty?
 
       buf = nil
+      owned = false
       key_type = nil
 
       hash.each do |key, value|
@@ -119,7 +137,15 @@ module Clsx
           s = key.name
           return clsx_hash_full(hash) if s.include?(' ')
 
-          buf ? (buf << ' ' << s) : (buf = s.dup)
+          # 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?
 
@@ -127,14 +153,20 @@ module Clsx
           return clsx_hash_full(hash) if key.include?(' ')
 
           key_type = :string
-          buf ? (buf << ' ' << key) : (buf = key.dup)
+          if buf
+            buf = buf.dup unless owned
+            owned = true
+            buf << ' ' << key
+          else
+            buf = key
+          end
         else
           return clsx_hash_full(hash)
         end
       end
 
       return nil unless buf
-      return clsx_dedup_str(buf) if buf.include?("\t") || buf.include?("\n")
+      return clsx_dedup_str(buf) if buf.match?(TAB_OR_NEWLINE)
 
       buf
     end
@@ -150,7 +182,13 @@ module Clsx
     end
 
     # Fast path for +clsx('base', active: cond)+ pattern where base is a
-    # single token. Deduplicates via direct string comparison.
+    # 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
@@ -188,7 +226,7 @@ module Clsx
         end
       end
 
-      return clsx_dedup_str(buf) if buf.include?("\t") || buf.include?("\n")
+      return clsx_dedup_str(buf) if buf.match?(TAB_OR_NEWLINE)
 
       buf
     end
@@ -221,7 +259,7 @@ module Clsx
 
           key_type = :symbol
           s = key.name
-          return clsx_str_hash_full_walk(parts, hash) if s.include?(' ') || s.include?("\t") || s.include?("\n")
+          return clsx_str_hash_full_walk(parts, hash) if s.include?(' ') || s.match?(TAB_OR_NEWLINE)
 
           next if parts.include?(s)
 
@@ -231,7 +269,7 @@ module Clsx
 
           key_type = :string
           next if key.empty?
-          return clsx_str_hash_full_walk(parts, hash) if key.include?(' ') || key.include?("\t") || key.include?("\n")
+          return clsx_str_hash_full_walk(parts, hash) if key.include?(' ') || key.match?(TAB_OR_NEWLINE)
 
           next if parts.include?(key)
 
@@ -318,7 +356,7 @@ module Clsx
       return nil if seen.empty?
 
       result = seen.keys.join(' ')
-      return result if result.count(' ') + 1 == seen.size && !result.include?("\t") && !result.include?("\n")
+      return result if result.count(' ') + 1 == seen.size && !result.match?(TAB_OR_NEWLINE)
 
       normalized = result.split.uniq.join(' ')
       normalized.empty? ? nil : normalized

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.3'
+  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.3
+  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: []