Add functional utility syntax

[RobinMalfait]

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:

@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-*):

@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:

@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:

@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:

@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:

@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:

@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:

@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:

@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:

/* 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]);
}

[imjeehoo]

In Resolving against @theme values, is tab-3 valid by somehow inferring from tab-1 or is it typo of tab-4?

[thecrypticace]

it was a typo — fixed.