From 3d0606b82d582752f87b543e9bd4fa4afca389c7 Mon Sep 17 00:00:00 2001
From: Philipp Spiess <hello@philippspiess.com>
Date: Thu, 6 Mar 2025 15:20:12 +0100
Subject: [PATCH] Fix sorting of classes that have undefined declarations
 (#16995)

Closes #16973

Declaration values of `undefined` are an implementation detail and
skipped when printing the CSS. Thus, these should not count towards the
sort order at a..

## Test plan

- See added regression test
---
 CHANGELOG.md                               |  4 +++
 packages/tailwindcss/src/compile.ts        |  4 ++-
 packages/tailwindcss/src/index.test.ts     | 37 ++++++++++++++++++++++
 packages/tailwindcss/src/utilities.test.ts | 14 ++++----
 4 files changed, 51 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5e6ba791a..093c2aae4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - _Experimental_: Add `user-valid` and `user-invalid` variants ([#12370](https://github.com/tailwindlabs/tailwindcss/pull/12370))
 - _Experimental_: Add `wrap-anywhere`, `wrap-break-word`, and `wrap-normal` utilities ([#12128](https://github.com/tailwindlabs/tailwindcss/pull/12128))
 
+### Fixed
+
+- Ensure utilities are sorted based on their actual property order ([#16995](https://github.com/tailwindlabs/tailwindcss/pull/16995))
+
 ## [4.0.11] - 2025-03-06
 
 ### Fixed
diff --git a/packages/tailwindcss/src/compile.ts b/packages/tailwindcss/src/compile.ts
index cd822b368..6530541a0 100644
--- a/packages/tailwindcss/src/compile.ts
+++ b/packages/tailwindcss/src/compile.ts
@@ -326,7 +326,9 @@ function getPropertySort(nodes: AstNode[]) {
     let node = q.shift()!
     if (node.kind === 'declaration') {
       // Empty strings should still be counted, e.g.: `--tw-foo:;` is valid
-      if (node.value !== undefined) count++
+      if (node.value === undefined) continue
+
+      count++
 
       if (seenTwSort) continue
 
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
index 4c97475a3..c23354153 100644
--- a/packages/tailwindcss/src/index.test.ts
+++ b/packages/tailwindcss/src/index.test.ts
@@ -1051,6 +1051,43 @@ describe('sorting', () => {
       }"
     `)
   })
+
+  // https://github.com/tailwindlabs/tailwindcss/issues/16973
+  it('should not take undefined values into account when sorting', async () => {
+    expect(
+      await compileCss(
+        css`
+          @theme {
+            --text-sm: 0.875rem;
+            --text-sm--line-height: calc(1.25 / 0.875);
+          }
+          @tailwind utilities;
+          @utility fancy-text {
+            font-size: var(--text-4xl);
+            line-height: var(--text-4xl--line-height);
+            font-weight: var(--font-weight-bold);
+          }
+        `,
+        ['fancy-text', 'text-sm'],
+      ),
+    ).toMatchInlineSnapshot(`
+      ":root, :host {
+        --text-sm: .875rem;
+        --text-sm--line-height: calc(1.25 / .875);
+      }
+
+      .fancy-text {
+        font-size: var(--text-4xl);
+        line-height: var(--text-4xl--line-height);
+        font-weight: var(--font-weight-bold);
+      }
+
+      .text-sm {
+        font-size: var(--text-sm);
+        line-height: var(--tw-leading, var(--text-sm--line-height));
+      }"
+    `)
+  })
 })
 
 describe('Parsing theme values from CSS', () => {
diff --git a/packages/tailwindcss/src/utilities.test.ts b/packages/tailwindcss/src/utilities.test.ts
index 9cf0f943a..615956c4f 100644
--- a/packages/tailwindcss/src/utilities.test.ts
+++ b/packages/tailwindcss/src/utilities.test.ts
@@ -15036,11 +15036,6 @@ test('text', async () => {
       --leading-snug: 1.375;
     }
 
-    .text-sm {
-      font-size: var(--text-sm);
-      line-height: var(--tw-leading, var(--text-sm--line-height));
-    }
-
     .text-\\[10px\\]\\/none {
       font-size: 10px;
       line-height: 1;
@@ -15071,6 +15066,11 @@ test('text', async () => {
       line-height: calc(var(--spacing) * 6);
     }
 
+    .text-sm {
+      font-size: var(--text-sm);
+      line-height: var(--tw-leading, var(--text-sm--line-height));
+    }
+
     .text-sm\\/6 {
       font-size: var(--text-sm);
       line-height: calc(var(--spacing) * 6);
@@ -16748,11 +16748,11 @@ describe('custom utilities', () => {
     expect(optimizeCss(compiled).trim()).toMatchInlineSnapshot(`
       "@layer utilities {
         .text-sm {
-          font-size: var(--text-sm, .875rem);
-          line-height: var(--tw-leading, var(--text-sm--line-height, 1.25rem));
           font-size: var(--text-sm, .8755rem);
           line-height: var(--text-sm--line-height, 1.255rem);
           text-rendering: optimizeLegibility;
+          font-size: var(--text-sm, .875rem);
+          line-height: var(--tw-leading, var(--text-sm--line-height, 1.25rem));
         }
       }"
     `)