tailwind_merge 0.16.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3334600a104bc6b8efbe365c3be28e32944468f9cb5b1255fdefd4d106dd9540
-  data.tar.gz: 2f8c9a9b989c3e808767516bff6b040ed0c3a092a5fc427aaacaae4904523bcc
+  metadata.gz: 991c169d4f9e2e472db150202e1a6c523a7f4698ef04d576557d0bfd25ffef0e
+  data.tar.gz: f7f0e832b00f4dfbcb61e1460a53f80d2c438354a412c953f7ab3a59a78d9fdd
 SHA512:
-  metadata.gz: 7f8ad1a5e8dfc2386b81cf5f528e2b1b5ded8b9644dd942e777e3b356b0807d74397400c090b52aec68d54e93bc0bd8d672f9872795dd300b7e2b06b543701af
-  data.tar.gz: 33cc99d39060f7f2e6827d48f99bce9989df5771f0174eea1994133a25e05115855de5e4f138b763f7197801595c3ab8e13802291675786f782f7246429079dd
+  metadata.gz: 2d431e7225fb7720d7ef50f4998820f8be9c84c5944b686005f78ef90a27895552c98ae39f4e9093c8bb90f1577cac4dc3a4d9483badb6b8b04088df7b00a611
+  data.tar.gz: 996fe4b3bdf0bb8a8a4ddf2b3f9cf6c950879c38bac9ec39bfc4e6b65913f2f48764fc6923e625e0aefcdfcab985556e805dc0ff41f3381766be5c3d9a8d59df

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [v1.0.0] - 25-02-2025
+## What's Changed
+* Add matrix to test CI by @w-masahiro-ct in https://github.com/gjtorikian/tailwind_merge/pull/47
+* [breaking] Support Tailwind v4 by @gjtorikian in https://github.com/gjtorikian/tailwind_merge/pull/52
+
+
+**Full Changelog**: https://github.com/gjtorikian/tailwind_merge/compare/v0.16.0...v1.0.0
 # [v0.16.0] - 25-01-2025
 ## What's Changed
 * Fix and improve implementation by @w-masahiro-ct in https://github.com/gjtorikian/tailwind_merge/pull/50

data/README.md

@@ -2,7 +2,8 @@
 
 Utility function to efficiently merge [Tailwind CSS](https://tailwindcss.com/) classes without style conflicts. Essentially, a Ruby port of [tailwind-merge](https://github.com/dcastil/tailwind-merge).
 
-Supports Tailwind v3.0 up to v3.4.
+- Version 1.0 and above supports Tailwind v4.0+.
+- Versions below that support from v3.0 up to v3.4.
 
 ## Installation
 
@@ -14,6 +15,8 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install tailwind_merge
 
+## Usage
+
 To use it, pass in a single string:
 
 ```ruby
@@ -96,7 +99,7 @@ The order of standard modifiers does not matter for tailwind-merge.
 ### Supports arbitrary values
 
 ```ruby
-@merger.merge("bg-black bg-[color:var(--mystery-var)]") # → "bg-[color:var(--mystery-var)]"
+@merger.merge("bg-black bg-(--my-color) bg-[color:var(--mystery-var)]") # → "bg-[color:var(--mystery-var)]"
 @merger.merge("grid-cols-[1fr,auto] grid-cols-2") # → "grid-cols-2"
 ```
 
@@ -136,8 +139,8 @@ The order of standard modifiers does not matter for tailwind-merge.
 ### Supports important modifier
 
 ```ruby
-@merger.merge("!p-3 !p-4 p-5") # → "!p-4 p-5"
-@merger.merge("!right-2 !-inset-x-1") # → "!-inset-x-1"
+@merger.merge("p-3! p-4! p-5") # → "p-4! p-5"
+@merger.merge("right-2! -inset-x-1!") # → "-inset-x-1!"
 ```
 
 ## Supports postfix modifiers
@@ -183,18 +186,16 @@ The `tailwind_merge` config is different from the Tailwind config because it's e
 
 ## Configuration
 
-The `tailwind_merge` config is an object with several keys:
+The `tailwind_merge` config is an object with several keys. All of these values are optional.
 
 ```ruby
 tailwind_merge_config = {
-  # ↓ *Optional* Define how many values should be stored in cache.
+  # Define how many values should be stored in cache.
   cache_size: 500,
-  # ↓ *Optional* Enable or disable caching nil values.
+  # Enable or disable caching nil values.
   ignore_empty_cache: true,
-  # ↓ *Optional* modifier separator from Tailwind config
-  separator: ":",
-  # ↓ *Optional* prefix from Tailwind config
-  prefix: "tw-",
+  # Prefix from your Tailwind config
+  prefix: "tw",
   theme: {
     # Theme scales are defined here
     # This is not the theme object from your Tailwind config
@@ -204,7 +205,10 @@ tailwind_merge_config = {
   },
   conflicting_class_groups: {
     # Conflicts between class groups are defined here
-  }
+  },
+  # Modifiers whose order among multiple modifiers should be preserved because their
+  # order changes which element gets targeted. Overrides default value.
+  order_sensitive_modifiers: [],
 }
 ```
 
@@ -278,65 +282,91 @@ If a class group _creates_ a conflict, it means that if it appears in a class li
 
 When we think of our example, the `px` class group creates a conflict which is received by the class groups `pr` and `pl`. This way `px-3` removes a preceding `pr-4`, but not the other way around.
 
+### Postfix modifiers conflicting with class groups
+
+Tailwind CSS allows postfix modifiers for some classes. E.g. you can set font-size and line-height together with `text-lg/7` with `/7` being the postfix modifier. This means that any line-height classes preceding a font-size class with a modifier should be removed.
+For this tailwind-merge has the `conflicting_class_groups` object in its config with the same shape as `conflicting_class_groups` explained in the [section above](#conflicting-class-groups). This time the key is the ID of a class group whose modifier _creates_ a conflict and the value is an array of IDs of class groups which _receive_ the conflict.
+
+```ruby
+conflicting_class_groups = {
+  "font-size": ["leading"],
+};
+```
+
+### Order-sensitive modifiers
+
+In Tailwind CSS, not all modifiers behave the same when you stack them.
+
+In most cases the order of modifiers doesn't matter. E.g. `hover:focus:bg-red-500` and `focus:hover:bg-red-500` behave the same and in the context of tailwind-merge, you'd want them both to override each other. tailwind-merge sorts the modifiers internally to be able to override classes with the same modifiers, even if they are in a different order.
+
+However, there are some modifiers where the order matters, e.g. the direct children modifier `*`. The class `*:hover:text-red-500` modifies the text color of a child if that particular child is hovered, but the class `hover:*:text-red-500` modifies the text color of all direct children if the parent is hovered. In this case, you would want tailwind-merge to preserve both classes although they have the same modifiers, just in a different order.
+
+To know which modifiers are order-sensitive, tailwind-merge has the `orderSensitiveModifiers` property in its config. `twMerge` is pre-configured with all the order-sensitive modifiers that Tailwind CSS has by default. You'll only need to configure this property if you add your own order-sensitive modifiers or change the meaning of the default order-sensitive modifiers.
+
 ### Theme
 
-In the Tailwind config you can modify theme scales. `tailwind_merge` follows the same keys for the theme scales, but doesn't support all of them. It only supports theme scales which are used in multiple class groups. At the moment these are:
-
-- `colors`
-- `spacing`
-- `blur`
-- `brightness`
-- `borderColor`
-- `borderRadius`
-- `borderSpacing`
-- `borderWidth`
-- `contrast`
-- `grayscale`
-- `hueRotate`
-- `invert`
-- `gap`
-- `gradientColorStops`
-- `gradientColorStopPositions`
-- `inset`
-- `margin`
-- `opacity`
-- `padding`
-- `saturate`
-- `scale`
-- `sepia`
-- `skew`
-- `space`
-- `translate`
-
-If you modified one of these theme scales in your Tailwind config, you can add all your keys right here and tailwind-merge will take care of the rest. For example, to add custom spaces and margin, you would provide the following `theme`:
+In the Tailwind config you can modify your theme variable namespace to add classes with custom values. tailwind-merge follows the same naming scheme as Tailwind CSS for its theme scales:
+
+| Tailwind CSS namespace | tailwind-merge theme key |
+| ---------------------- | ------------------------ |
+| `--color-*`            | `color`                  |
+| `--font-*`             | `font`                   |
+| `--text-*`             | `text`                   |
+| `--font-weight-*`      | `font-weight`            |
+| `--tracking-*`         | `tracking`               |
+| `--leading-*`          | `leading`                |
+| `--breakpoint-*`       | `breakpoint`             |
+| `--container-*`        | `container`              |
+| `--spacing-*`          | `spacing`                |
+| `--radius-*`           | `radius`                 |
+| `--shadow-*`           | `shadow`                 |
+| `--inset-shadow-*`     | `inset-shadow`           |
+| `--drop-shadow-*`      | `drop-shadow`            |
+| `--blur-*`             | `blur`                   |
+| `--perspective-*`      | `perspective`            |
+| `--aspect-*`           | `aspect`                 |
+| `--ease-*`             | `ease`                   |
+| `--animate-*`          | `animate`                |
+
+If you modified one of the theme namespaces in your Tailwind config, you need to add the variable names to the `theme` object in tailwind-merge as well so that tailwind-merge knows about them.
+
+E.g. let's say you added the variable `--text-huge-af: 100px` to your Tailwind config which enables classes like `text-huge-af`. To make sure that tailwind-merge merges these classes correctly, you need to configure tailwind-merge like this:
 
 ```ruby
 merger = TailwindMerge::Merger.new(config: {
-  theme: {
-    "spacing" => ["my-space"],
-    "margin" => ["my-margin"]
+ theme: {
+    # ↓ `text` is the key of the namespace `--text-*`
+    #      ↓ `huge-af` is the variable name in the namespace
+    text: ["huge-af"],
   }
 })
 ```
 
-If you modified other theme scales, you need to figure out the class group to modify in the [default config](#getdefaultconfig).
-
 ### Validators
 
 Here's a brief summary for each validator:
 
-- `IS_LENGTH` checks whether a class part is a number (`3`, `1.5`), a fraction (`3/4`), or one of the strings `px`, `full` or `screen`.
+- `IS_ANY` always returns true. Be careful with this validator as it might match unwanted classes. I use it primarily to match colors or when I'm certain there are no other class groups in a namespace.
+- `IS_ANY_NON_ARBITRARY` checks if the class part is not an arbitrary value or arbitrary variable.
+- `IS_ARBITRARY_IMAGE` checks whether class part is an arbitrary value which is an iamge, e.g. by starting with `image:`, `url:`, `linear-gradient(` or `url(` (`[url('/path-to-image.png')]`, `image:var(--maybe-an-image-at-runtime)]`) which is necessary for background-image classNames.
 - `IS_ARBITRARY_LENGTH` checks for arbitrary length values (`[3%]`, `[4px]`, `[length:var(--my-var)]`).
+- `IS_ARBITRARY_NUMBER` checks whether class part is an arbitrary value which starts with `number:` or is a number (`[number:var(--value)]`, `[450]`) which is necessary for font-weight and stroke-width classNames.
+- `IS_ARBITRARY_POSITION` checks whether class part is an arbitrary value which starts with `position:` (`[position:200px_100px]`) which is necessary for background-position classNames.
+- `IS_ARBITRARY_SHADOW` checks whether class part is an arbitrary value which starts with the same pattern as a shadow value (`[0_35px_60px_-15px_rgba(0,0,0,0.3)]`), namely with two lengths separated by a underscore, optionally prepended by `inset`.
+- `IS_ARBITRARY_SIZE` checks whether class part is an arbitrary value which starts with `size:` (`[size:200px_100px]`) which is necessary for background-size classNames.
+- `IS_ARBITRARY_VALUE` checks whether the class part is enclosed in brackets (`[something]`)
+- `IS_ARBITRARY_VARIABLE` checks whether the class part is an arbitrary variable (`(--my-var)`)
+- `IS_ARBITRARY_VARIABLE_FAMILYNAME` checks whether class part is an arbitrary variable with the `family-name` label (`(family-name:--my-font)`)
+- `IS_ARBITRARY_VARIABLE_IMAGE` checks whether class part is an arbitrary variable with the `image` or `url` label (`(image:--my-image)`)
+- `IS_ARBITRARY_VARIABLE_LENGTH` checks whether class part is an arbitrary variable with the `length` label (`(length:--my-length)`)
+- `IS_ARBITRARY_VARIABLE_POSITION` checks whether class part is an arbitrary variable with the `position` label (`(position:--my-position)`)
+- `IS_ARBITRARY_VARIABLE_SHADOW` checks whether class part is an arbitrary variable with the `shadow` label or not label at all (`(shadow:--my-shadow)`, `(--my-shadow)`)
+- `IS_ARBITRARY_VARIABLE_SIZE` checks whether class part is an arbitrary variable with the `size`, `length` or `percentage` label (`(size:--my-size)`)
+- `IS_FRACTION` checks whether class part is a fraction of two numbers (`1/2`, `127/256`)
 - `IS_INTEGER` checks for integer values (`3`).
+- `IS_NUMBER` checks for numbers (`3`, `1.5`)
 - `IS_PERCENT` checks for percent values (`12.5%`) which is used for color stop positions.
-- `IS_ARBITRARY_VALUE` checks whether the class part is enclosed in brackets (`[something]`)
 - `IS_TSHIRT_SIZE`checks whether class part is a T-shirt size (`sm`, `xl`), optionally with a preceding number (`2xl`).
-- `IS_ARBITRARY_SIZE` checks whether class part is an arbitrary value which starts with `size:` (`[size:200px_100px]`) which is necessary for background-size classNames.
-- `IS_ARBITRARY_POSITION` checks whether class part is an arbitrary value which starts with `position:` (`[position:200px_100px]`) which is necessary for background-position classNames.
-- `IS_ARBITRARY_IMAGE` checks whether class part is an arbitrary value which is an iamge, e.g. by starting with `image:`, `url:`, `linear-gradient(` or `url(` (`[url('/path-to-image.png')]`, `image:var(--maybe-an-image-at-runtime)]`) which is necessary for background-image classNames.
-- `IS_ARBITRARY_NUMBER` checks whether class part is an arbitrary value which starts with `number:` or is a number (`[number:var(--value)]`, `[450]`) which is necessary for font-weight classNames.
-- `IS_ARBITRARY_SHADOW` checks whether class part is an arbitrary value which starts with the same pattern as a shadow value (`[0_35px_60px_-15px_rgba(0,0,0,0.3)]`), namely with two lengths separated by a underscore, optionally prepended by `inset`.
-- `IS_ANY` always returns true. Be careful with this validator as it might match unwanted classes. I use it primarily to match colors or when it's certain there are no other class groups in a namespace.
 
 ## Performance
 

data/lib/tailwind_merge/{class_utils.rb → class_group_utils.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module TailwindMerge
-  class ClassUtils
+  class ClassGroupUtils
     attr_reader :class_map
 
     CLASS_PART_SEPARATOR = "-"
@@ -58,50 +58,28 @@ module TailwindMerge
     end
 
     private def create_class_map(config)
-      prefix = config[:prefix]
+      theme = config[:theme]
+      class_groups = config[:class_groups]
       class_map = {
         next_part: {},
         validators: [],
       }
 
-      prefixed_class_group_entries = get_prefixed_class_group_entries(
-        config[:class_groups].map { |group_id, group_classes| [group_id, group_classes] },
-        prefix,
-      )
-
-      prefixed_class_group_entries.each do |class_group_id, class_group|
-        process_classes_recursively(class_group, class_map, class_group_id)
+      class_groups.each do |(class_group_id, class_group)|
+        process_classes_recursively(class_group, class_map, class_group_id, theme)
       end
 
       class_map
     end
 
-    private def get_prefixed_class_group_entries(class_group_entries, prefix)
-      return class_group_entries if prefix.nil?
-
-      class_group_entries.map do |class_group_id, class_group|
-        prefixed_class_group = class_group.map do |class_definition|
-          if class_definition.is_a?(String)
-            "#{prefix}#{class_definition}"
-          elsif class_definition.is_a?(Hash)
-            class_definition.transform_keys { |key| "#{prefix}#{key}" }
-          else
-            class_definition
-          end
-        end
-
-        [class_group_id, prefixed_class_group]
-      end
-    end
-
-    private def process_classes_recursively(class_group, class_part_object, class_group_id)
+    private def process_classes_recursively(class_group, class_part_object, class_group_id, theme)
       class_group.each do |class_definition|
         if class_definition.is_a?(String)
           class_part_object_to_edit = class_definition.empty? ? class_part_object : get_class_part(class_part_object, class_definition)
           class_part_object_to_edit[:class_group_id] = class_group_id
         elsif class_definition.is_a?(Proc)
           if from_theme?(class_definition)
-            process_classes_recursively(class_definition.call(@config), class_part_object, class_group_id)
+            process_classes_recursively(class_definition.call(@config), class_part_object, class_group_id, theme)
           else
             class_part_object[:validators] << {
               validator: class_definition,
@@ -114,6 +92,7 @@ module TailwindMerge
               nested_class_group,
               get_class_part(class_part_object, key),
               class_group_id,
+              theme,
             )
           end
         end