Ensure multiple --value(…) or --modifier(…) calls don't delete subsequent declarations (#17273)

This PR fixes a bug in the handling of `@utility`. Essentially if you
had a declaration where you used a `--modifier(…)` _and_ a `--value(…)`
and both caused the declaration to be removed, the declaration after the
current one would be removed as well.

This happened because 2 reasons:

1. Once we removed the declaration when we handled `--modifier(…)`, we
didn't stop the walk and kept going.
2. The `replaceWith(…)` code allows you to call the function multiple
times but immediately mutates the AST. This means that if you call it
multiple times that you are potentially removing / updating nodes
followed by the current one.

E.g.:

```css
@Utility mask-r-* {
  --mask-right: linear-gradient(to left, transparent, black --value(percentage));
  --mask-right: linear-gradient(
    to left,
    transparent calc(var(--spacing) * --modifier(integer)),
    black calc(var(--spacing) * --value(integer))
  );
  mask-image: var(--mask-linear), var(--mask-radial), var(--mask-conic);
}
```

If this is used as `mask-r-10%`, then the first definition of
`--mask-right` is kept, but the second definition of `--mask-right` is
deleted because both `--modifier(integer)` and `--value(integer)` do not
result in a valid value.

However, the `mask-image` declaration was also removed because the
`replaceWith(…)` function was called twice. Once for
`--modifier(integer)` and once for `--value(integer)`.

# Test plan

1. Added a test to cover this case.
2. Existing tests pass.
3. Added a hard error if we call `replaceWith(…)` multiple times.

Author: RobinMalfait

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Pre-process `<template lang="…">` in Vue files ([#17252](https://github.com/tailwindlabs/tailwindcss/pull/17252))
 - Remove redundant `line-height: initial` from Preflight ([#15212](https://github.com/tailwindlabs/tailwindcss/pull/15212))
 - Prevent segfault when loaded in a worker thread on Linux ([#17276](https://github.com/tailwindlabs/tailwindcss/pull/17276))
+- Ensure multiple `--value(…)` or `--modifier(…)` calls don't delete subsequent declarations ([#17273](https://github.com/tailwindlabs/tailwindcss/pull/17273))
 
 ## [4.0.14] - 2025-03-13
 

packages/tailwindcss/src/ast.ts

@@ -149,6 +149,7 @@ export function walk(
         context,
         path,
         replaceWith(newNode) {
+          if (replacedNode) return
           replacedNode = true
 
           if (Array.isArray(newNode)) {

packages/tailwindcss/src/compat/selector-parser.ts

@@ -98,6 +98,7 @@ export function walk(
       visit(node, {
         parent,
         replaceWith(newNode) {
+          if (replacedNode) return
           replacedNode = true
 
           if (Array.isArray(newNode)) {

packages/tailwindcss/src/utilities.test.ts

@@ -17961,6 +17961,38 @@ describe('custom utilities', () => {
         }"
       `)
     })
+
+    // This originated from a bug. Essentially in the second `--mask-right` we
+    // call both `--modifier(…)` and `--value(…)`. The moment we processed
+    // `--modifier(…)` it deleted the `--mask-right` declaration (expected
+    // behavior). But we didn't properly stop so the `--value(…)` was still
+    // processed and also tried to remove the `--mask-right` declaration.
+    //
+    // This test now ensures that we only remove/replace a declaration once.
+    test('declaration nodes are only replaced/removed once', async () => {
+      let input = css`
+        @utility mask-r-* {
+          --mask-right: linear-gradient(to left, transparent, black --value(percentage));
+          --mask-right: linear-gradient(
+            to left,
+            transparent calc(var(--spacing) * --modifier(integer)),
+            black calc(var(--spacing) * --value(integer))
+          );
+          mask-image: var(--mask-linear), var(--mask-radial), var(--mask-conic);
+        }
+
+        @tailwind utilities;
+      `
+
+      expect(await compileCss(input, ['mask-r-20%'])).toMatchInlineSnapshot(`
+        ".mask-r-20\\% {
+          --mask-right: linear-gradient(to left, transparent, black 20%);
+          -webkit-mask-image: var(--mask-linear), var(--mask-radial), var(--mask-conic);
+          -webkit-mask-image: var(--mask-linear), var(--mask-radial), var(--mask-conic);
+          mask-image: var(--mask-linear), var(--mask-radial), var(--mask-conic);
+        }"
+      `)
+    })
   })
 
   test('resolve value based on `@theme`', async () => {

packages/tailwindcss/src/utilities.ts

@@ -4885,7 +4885,7 @@ export function createCssUtility(node: AtRule) {
                 // declaration can be removed.
                 if (modifier === null) {
                   replaceDeclarationWith([])
-                  return ValueParser.ValueWalkAction.Skip
+                  return ValueParser.ValueWalkAction.Stop
                 }
 
                 usedModifierFn = true

packages/tailwindcss/src/value-parser.ts

@@ -69,6 +69,7 @@ export function walk(
       visit(node, {
         parent,
         replaceWith(newNode) {
+          if (replacedNode) return
           replacedNode = true
 
           if (Array.isArray(newNode)) {