Fix non-deterministic variant sorting (#14835)

Right now our variant sorting is sensitive to the authoring order of
classes or the order in which we scan files because we weren't comparing
variant values when sorting.

This PR addresses this by:
- "default" values in variants appear first
- Then any named values
- Then any arbitrary values
- Finally, compare the values themselves when all else is equal

---------

Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Detect classes in new files when using `@tailwindcss/postcss` ([#14829](https://github.com/tailwindlabs/tailwindcss/pull/14829))
 - Fix crash when using `@source` containing `..` ([#14831](https://github.com/tailwindlabs/tailwindcss/pull/14831))
+- Ensure instances of the same variant with different values are always sorted deterministically (e.g. `data-focus:flex` and `data-active:flex`) ([#14835](https://github.com/tailwindlabs/tailwindcss/pull/14835))
 - _Upgrade (experimental)_: Install `@tailwindcss/postcss` next to `tailwindcss` ([#14830](https://github.com/tailwindlabs/tailwindcss/pull/14830))
 - _Upgrade (experimental)_: Remove whitespace around `,` separator when print arbitrary values ([#14838](https://github.com/tailwindlabs/tailwindcss/pull/14838))
 

packages/tailwindcss/src/compat/config.test.ts

@@ -1109,16 +1109,16 @@ test('creates variants for `data`, `supports`, and `aria` theme options at the s
       'print:flex',
     ]),
   ).toMatchInlineSnapshot(`
-    ".aria-polite\\:underline {
-      &[aria-live="polite"] {
-        text-decoration-line: underline;
-      }
-    }
-    .aria-hidden\\:flex {
+    ".aria-hidden\\:flex {
       &[aria-hidden="true"] {
         display: flex;
       }
     }
+    .aria-polite\\:underline {
+      &[aria-live="polite"] {
+        text-decoration-line: underline;
+      }
+    }
     .data-checked\\:underline {
       &[data-ui~="checked"] {
         text-decoration-line: underline;

packages/tailwindcss/src/compat/plugin-api.ts

@@ -156,12 +156,12 @@ export function buildPluginApi(
           if (a.kind !== 'functional' || z.kind !== 'functional') {
             return 0
           }
-          if (!a.value || !z.value) {
-            return 0
-          }
 
-          let aValue = options?.values?.[a.value.value] ?? a.value.value
-          let zValue = options?.values?.[z.value.value] ?? z.value.value
+          let aValueKey = a.value ? a.value.value : 'DEFAULT'
+          let zValueKey = z.value ? z.value.value : 'DEFAULT'
+
+          let aValue = options?.values?.[aValueKey] ?? aValueKey
+          let zValue = options?.values?.[zValueKey] ?? zValueKey
 
           if (options && typeof options.sort === 'function') {
             return options.sort(
@@ -170,11 +170,19 @@ export function buildPluginApi(
             )
           }
 
-          let aOrder = defaultOptionKeys.indexOf(a.value.value)
-          let zOrder = defaultOptionKeys.indexOf(z.value.value)
+          let aOrder = defaultOptionKeys.indexOf(aValueKey)
+          let zOrder = defaultOptionKeys.indexOf(zValueKey)
+
+          // Sort arbitrary values after configured values
+          aOrder = aOrder === -1 ? defaultOptionKeys.length : aOrder
+          zOrder = zOrder === -1 ? defaultOptionKeys.length : zOrder
+
+          if (aOrder !== zOrder) return aOrder - zOrder
 
-          if (aOrder - zOrder === 0) return aValue < zValue ? -1 : 1
-          return aOrder - zOrder
+          // SAFETY: The values don't need to be checked for equality as they
+          // are guaranteed to be unique since we sort a list of de-duped
+          // variants and different (valid) variants cannot produce the same AST.
+          return aValue < zValue ? -1 : 1
         },
       )
     },