Add functional utility syntax (#15455)

This PR adds support for functional utilities constructed via CSS.

# Registering functional utilities in CSS

To register a functional utility in CSS, use the `@utility potato-*`
syntax, where the `-*` signals that this is a functional utility:

```css
@Utility tab-* {
  tab-size: --value(--tab-size-*);
}
```

## Resolving values

The special `--value(…)` function is used to resolve the utility value.

### Resolving against `@theme` values

To resolve the value against a set of theme keys, use
`--value(--theme-key-*)`:

```css
@theme {
  --tab-size-1: 1;
  --tab-size-2: 2;
  --tab-size-4: 4;
  --tab-size-github: 8;
}

@Utility tab-* {
  /* tab-1, tab-2, tab-4, tab-github */
  tab-size: --value(--tab-size-*);
}
```

### Bare values

To resolve the value as a bare value, use `--value({type})`, where
`{type}` is the data type you want to validate the bare value as:

```css
@Utility tab-* {
  /* tab-1, tab-76, tab-971 */
  tab-size: --value(integer);
}
```

### Arbitrary values

To support arbitrary values, use `--value([{type}])` (notice the square
brackets) to tell Tailwind which types are supported as an arbitrary
value:

```css
@Utility tab-* {
  /* tab-[1], tab-[76], tab-[971] */
  tab-size: --value([integer]);
}
```

### Supporting theme values, bare values, and arbitrary values together

All three forms of the `--value(…)` function can be used within a rule
as multiple declarations, and any declarations that fail to resolve will
be omitted in the output:

```css
@theme {
  --tab-size-github: 8;
}

@Utility tab-* {
  tab-size: --value([integer]);
  tab-size: --value(integer);
  tab-size: --value(--tab-size-*);
}
```

This makes it possible to treat the value differently in each case if
necessary, for example translating a bare integer to a percentage:

```css
@Utility opacity-* {
  opacity: --value([percentage]);
  opacity: calc(--value(integer) * 1%);
  opacity: --value(--opacity-*);
}
```

The `--value(…)` function can also take multiple arguments and resolve
them left to right if you don't need to treat the return value
differently in different cases:

```css
@theme {
  --tab-size-github: 8;
}

@Utility tab-* {
  tab-size: --value(--tab-size-*, integer, [integer]);
}

@Utility opacity-* {
  opacity: calc(--value(integer) * 1%);
  opacity: --value(--opacity-*, [percentage]);
}
```

### Negative values

To support negative values, register separate positive and negative
utilities into separate declarations:

```css
@Utility inset-* {
  inset: calc(--var(--spacing) * --value([percentage], [length]));
}

@Utility -inset-* {
  inset: calc(--var(--spacing) * --value([percentage], [length]) * -1);
}
```

## Modifiers

Modifiers are handled using the `--modifier(…)` function which works
exactly like the `--value(…)` function but operates on a modifier if
present:

```css
@Utility text-* {
  font-size: --value(--font-size-*, [length]);
  line-height: --modifier(--line-height-*, [length], [*]);
}
```

If a modifier isn't present, any declaration depending on a modifier is
just not included in the output.

## Fractions

To handle fractions, we rely on the CSS `ratio` data type. If this is
used with `--value(…)`, it's a signal to Tailwind to treat the value +
modifier as a single value:

```css
/* The CSS `ratio` type is our signal to treat the value + modifier as a fraction */
@Utility aspect-* {
  /* aspect-square, aspect-3/4, aspect-[7/9] */
  aspect-ratio: --value(--aspect-ratio-*, ratio, [ratio]);
}
```

Author: RobinMalfait

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add `@tailwindcss/browser` package to run Tailwind CSS in the browser ([#15558](https://github.com/tailwindlabs/tailwindcss/pull/15558))
 - Add `@reference "…"` API as a replacement for the previous `@import "…" reference` option ([#15565](https://github.com/tailwindlabs/tailwindcss/pull/15565))
+- Add functional utility syntax ([#15455](https://github.com/tailwindlabs/tailwindcss/pull/15455))
 
 ### Fixed
 

packages/tailwindcss/src/index.ts

@@ -26,12 +26,12 @@ import { substituteFunctions } from './css-functions'
 import * as CSS from './css-parser'
 import { buildDesignSystem, type DesignSystem } from './design-system'
 import { Theme, ThemeOptions } from './theme'
+import { createCssUtility } from './utilities'
 import { segment } from './utils/segment'
 import { compoundsForSelectors } from './variants'
 export type Config = UserConfig
 
 const IS_VALID_PREFIX = /^[a-z]+$/
-const IS_VALID_UTILITY_NAME = /^[a-z][a-zA-Z0-9/%._-]*$/
 
 type CompileOptions = {
   base?: string
@@ -174,25 +174,20 @@ async function parseCss(
         throw new Error('`@utility` cannot be nested.')
       }
 
-      let name = node.params
-
-      if (!IS_VALID_UTILITY_NAME.test(name)) {
+      if (node.nodes.length === 0) {
         throw new Error(
-          `\`@utility ${name}\` defines an invalid utility name. Utilities should be alphanumeric and start with a lowercase letter.`,
+          `\`@utility ${node.params}\` is empty. Utilities should include at least one property.`,
         )
       }
 
-      if (node.nodes.length === 0) {
+      let utility = createCssUtility(node)
+      if (utility === null) {
         throw new Error(
-          `\`@utility ${name}\` is empty. Utilities should include at least one property.`,
+          `\`@utility ${node.params}\` defines an invalid utility name. Utilities should be alphanumeric and start with a lowercase letter.`,
         )
       }
 
-      customUtilities.push((designSystem) => {
-        designSystem.utilities.static(name, () => structuredClone(node.nodes))
-      })
-
-      return
+      customUtilities.push(utility)
     }
 
     // Collect paths from `@source` at-rules

packages/tailwindcss/src/intellisense.test.ts

@@ -437,3 +437,69 @@ test('Custom at-rule variants do not show up as a value under `group`', async ()
   expect(not.values).toContain('variant-3')
   expect(not.values).toContain('variant-4')
 })
+
+test('Custom functional @utility', async () => {
+  let input = css`
+    @import 'tailwindcss/utilities';
+
+    @theme reference {
+      --tab-size-1: 1;
+      --tab-size-2: 2;
+      --tab-size-4: 4;
+      --tab-size-github: 8;
+
+      --text-xs: 0.75rem;
+      --text-xs--line-height: calc(1 / 0.75);
+
+      --leading-foo: 1.5;
+      --leading-bar: 2;
+    }
+
+    @utility tab-* {
+      tab-size: --value(--tab-size);
+    }
+
+    @utility example-* {
+      font-size: --value(--text);
+      line-height: --value(--text- * --line-height);
+      line-height: --modifier(--leading);
+    }
+
+    @utility -negative-* {
+      margin: --value(--tab-size- *);
+    }
+  `
+
+  let design = await __unstable__loadDesignSystem(input, {
+    loadStylesheet: async (_, base) => ({
+      base,
+      content: '@tailwind utilities;',
+    }),
+  })
+
+  let classMap = new Map(design.getClassList())
+  let classNames = Array.from(classMap.keys())
+
+  expect(classNames).toContain('tab-1')
+  expect(classNames).toContain('tab-2')
+  expect(classNames).toContain('tab-4')
+  expect(classNames).toContain('tab-github')
+
+  expect(classNames).not.toContain('-tab-1')
+  expect(classNames).not.toContain('-tab-2')
+  expect(classNames).not.toContain('-tab-4')
+  expect(classNames).not.toContain('-tab-github')
+
+  expect(classNames).toContain('-negative-1')
+  expect(classNames).toContain('-negative-2')
+  expect(classNames).toContain('-negative-4')
+  expect(classNames).toContain('-negative-github')
+
+  expect(classNames).not.toContain('--negative-1')
+  expect(classNames).not.toContain('--negative-2')
+  expect(classNames).not.toContain('--negative-4')
+  expect(classNames).not.toContain('--negative-github')
+
+  expect(classNames).toContain('example-xs')
+  expect(classMap.get('example-xs')?.modifiers).toEqual(['foo', 'bar'])
+})

packages/tailwindcss/src/theme.ts

@@ -68,7 +68,7 @@ export class Theme {
     }
   }
 
-  keysInNamespaces(themeKeys: ThemeKey[]): string[] {
+  keysInNamespaces(themeKeys: Iterable<ThemeKey>): string[] {
     let keys: string[] = []
 
     for (let namespace of themeKeys) {