add --default(…) to --value(…) support

This allows us to re-implement functional utilities with a default value
in CSS using `@utility`.

Used the explicit `--default()` argument of `--value()` for a few reasons.

1. It's explicit about being a falllback value. If you have `@utility
   foo-*`, then you want to be able to use `foo`, but `foo-bad` should
   not compile.
2. When `--value(…)` is used in (complex) property values (think a bunch
   of `calc(…)` expressions), then we don't need a separate property for
   this.

One of the ideas was to have a literal fallback:
```css
@Utility tab-* {
  tab-size: 4;
  tab-size: --value(number);
}
```

For `tab`, this would compile to:
```css
.tab {
  tab-size: 4;
}
```

For `tab-123`, this would compile to:
```css
.tab {
  tab-size: 4;
  tab-size: 123;
}
```
Getting rid of the `tab-size: 4` would be an option, but it's a common
pattern in real CSS for fallback values (think hex background color,
over a more modern `oklch` color).

For `tab-foo`, this would compile to:
```css
.tab {
  tab-size: 4;
}
```
Which means that we have an infinite amount classes that would result in
the same class, which is bad. We could special case this one because the
internal `value` would still be `null`, but it might be too confusing.

This syntax without the `--default` also means repetition of certain
properties.

Add `--modifier(…)` to the mix, and there is even more repetition going
on.

Another option to consider is that the default fallback is just another
option in the `--value(…, 4)`, but if a default fallback is a keyword,
then there is a chance that this might conflict with actual keywords we
interpret.

Author: RobinMalfait

packages/tailwindcss/src/utilities.test.ts

@@ -29540,6 +29540,98 @@ describe('custom utilities', () => {
       `)
     })
 
+    test('functional utilities require `--value(…)`', async () => {
+      let input = css`
+        @utility tab-* {
+          tab-size: 4;
+        }
+
+        @tailwind utilities;
+      `
+
+      expect(await compileCss(input, ['tab'])).toEqual('')
+    })
+
+    test('functional utilities must resolve a `--value(…)`', async () => {
+      let input = css`
+        @utility tab-* {
+          tab-size: --value(integer);
+        }
+
+        @tailwind utilities;
+      `
+
+      expect(await compileCss(input, ['tab-2.5'])).toEqual('')
+    })
+
+    test('functional utilities can use `--default(…)` in `--value(…)`', async () => {
+      let input = css`
+        @utility tab-* {
+          tab-size: --value(integer, --default(4));
+        }
+
+        @tailwind utilities;
+      `
+
+      expect(await compileCss(input, ['tab', 'tab-123'])).toMatchInlineSnapshot(`
+        ".tab {
+          tab-size: 4;
+        }
+
+        .tab-123 {
+          tab-size: 123;
+        }"
+      `)
+
+      expect(await compileCss(input, ['tab-foo'])).toEqual('')
+    })
+
+    test('functional utilities can use `--default(…)` in complex expressions', async () => {
+      let input = css`
+        @utility tab-* {
+          tab-size: calc(--value(integer, --default(4)) * 2);
+        }
+
+        @tailwind utilities;
+      `
+
+      expect(await compileCss(input, ['tab', 'tab-123'])).toMatchInlineSnapshot(`
+        ".tab {
+          tab-size: 8;
+        }
+
+        .tab-123 {
+          tab-size: 246;
+        }"
+      `)
+
+      expect(await compileCss(input, ['tab-foo'])).toEqual('')
+    })
+
+    test('functional utilities can use `--default(…)` with `--modifier(…)`', async () => {
+      let input = css`
+        @utility tab-* {
+          tab-size: --value(integer, --default(4));
+          line-height: --modifier(integer);
+        }
+
+        @tailwind utilities;
+      `
+
+      expect(await compileCss(input, ['tab', 'tab/25'])).toMatchInlineSnapshot(`
+        ".tab\\/25 {
+          tab-size: 4;
+          line-height: 25;
+        }
+
+        .tab {
+          tab-size: 4;
+        }"
+      `)
+
+      expect(await compileCss(input, ['tab/foo'])).toEqual('')
+    })
+
     test('modifiers', async () => {
       let input = css`
         @theme reference {

packages/tailwindcss/src/utilities.ts

@@ -5956,6 +5956,8 @@ export function createCssUtility(node: AtRule) {
     // - `--value(number)`            resolves a bare value of type number
     // - `--value([number])`          resolves an arbitrary value of type number
     // - `--value(--color)`           resolves a theme value in the `color` namespace
+    // - `--value(--default(4))`      resolves to a default value when only the
+    //                                root of the functional utility was used.
     // - `--value(number, [number])`  resolves a bare value of type number or an
     //                                arbitrary value of type number in order.
     //
@@ -6069,7 +6071,7 @@ export function createCssUtility(node: AtRule) {
             arg = arg.replace(/(-\*){2,}/g, '-*')
 
             // Ensure trailing `-*` exists if `-*` isn't present yet
-            if (arg[0] === '-' && arg[1] === '-' && !arg.includes('-*')) {
+            if (arg[0] === '-' && arg[1] === '-' && !arg.includes('(') && !arg.includes('-*')) {
               arg += '-*'
             }
 
@@ -6135,9 +6137,8 @@ export function createCssUtility(node: AtRule) {
         let value = candidate.value
         let modifier = candidate.modifier
 
-        // A value is required for functional utilities, if you want to accept
-        // just `tab-size`, you'd have to use a static utility.
-        if (value === null) return
+        // Functional CSS utilities must resolve at least one `--value(…)`.
+        // Use `--default(…)` inside `--value(…)` for the omitted-value case.
 
         // Whether `--value(…)` was used
         let usedValueFn = false
@@ -6185,7 +6186,9 @@ export function createCssUtility(node: AtRule) {
             if (valueNode.value === '--value') {
               usedValueFn = true
 
-              let resolved = resolveValueFunction(value, valueNode, designSystem)
+              let resolved = value
+                ? resolveValueFunction(value, valueNode, designSystem)
+                : resolveDefaultValueFunction(valueNode)
               if (resolved) {
                 resolvedValueFn = true
                 if (resolved.ratio) {
@@ -6233,8 +6236,9 @@ export function createCssUtility(node: AtRule) {
           node.value = ValueParser.toCss(valueAst)
         })
 
-        // Used `--value(…)` but nothing resolved
-        if (usedValueFn && !resolvedValueFn) return null
+        // Functional CSS utilities require `--value(…)`, and one of those
+        // branches must resolve for the candidate to be valid.
+        if (!usedValueFn || !resolvedValueFn) return null
 
         // Used `--modifier(…)` but nothing resolved
         if (usedModifierFn && !resolvedModifierFn) return null
@@ -6451,6 +6455,16 @@ function resolveValueFunction(
   }
 }
 
+function resolveDefaultValueFunction(
+  fn: ValueParser.ValueFunctionNode,
+): { nodes: ValueParser.ValueAstNode[]; ratio?: boolean } | undefined {
+  for (let arg of fn.nodes) {
+    if (arg.kind === 'function' && arg.value === '--default') {
+      return { nodes: arg.nodes }
+    }
+  }
+}
+
 function alphaReplacedShadowProperties(
   property: string,
   value: string,