Resolves#15799Resolves#14478
Part-of #15005
Adds a `:host` selector for the `@theme` layer. This is necessary for
the `@theme` layer to work correctly in shadow DOM.
Also updates the snapshots for the tests that were affected by this
change (in a separate commit).
## Test plan
Tested via the Vite playground:
<img width="1121" alt="Screenshot 2025-01-29 at 15 06 49"
src="https://github.com/user-attachments/assets/a7908135-5ff8-472f-a053-d2c6d5c81e1b"
/>
Additionally made sure that `@property` defaults also work across
Firefox, Chrome, and Safari (the `@property` definition from the root is
pulled in) and added a UI spec.
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
This PR fixes an issue where an empty selector list was valid when
defining a `@custom-variant`.
Given this input:
```css
@custom-variant foo ();
```
If you then use it with a utility such as `foo:flex`, then the following
(incorrect) CSS was generated:
```css
.foo\:flex {
{
display: flex;
}
}
```
Which is invalid CSS. This PR will now validate that that we have at
least _something_ and show an error accordingly.
This PR will remove the `force` variant. This was an experiment that we
accidentally shipped, but there is no documentation nor is there any
intellisense autocompletion for it.
This PR fixes the upgrade tool by properly migrating the
`leading-[<number>]` classes.
The issue is that `leading-[<number>]` maps to the number directly, but
if you use a bare value, then it's a multiplier for based on the
`--spacing` value.
E.g.:
*leading-[2]*:
```css
.leading-\[2\] {
--tw-leading: 2;
line-height: 2;
}
@property --tw-leading {
syntax: "*";
inherits: false;
}
```
*leading-2*:
```css
.leading-2 {
--tw-leading: calc(var(--spacing) * 2);
line-height: calc(var(--spacing) * 2);
}
@property --tw-leading {
syntax: "*";
inherits: false;
}
```
This PR will now prevent migrating arbitrary values to bare values for
`leading-*` utilities.
That said, this does introduce a small improvement where `leading-[1]`
is migrated to `leading-none`.
Fixes: https://github.com/tailwindlabs/tailwindcss/issues/15924
Resolves#15977
Our `@tailwindcss/browser` build is intended to run inside a `<script>`
tag inside browsers. Because of how variable assignment within
`<script>` tags work, all variables that were defined within that script
are currently assigned on the global namespace.
This is especially troublesome as eslint uses `$` as a valid mangling
character so importing the CDN build would now redefine `globalThis.$`
which collides with many very popular JavaScript libraries.
In order to avoid polluting the global namespace, this PR changes the
build step to emit an IIFE (so all vars defined are scroped to the
function closure instead of the global namespace).
## Test plan
- Ensure UI tests still work
- <img width="533" alt="Screenshot 2025-01-28 at 16 49 27"
src="https://github.com/user-attachments/assets/1e027451-f58b-4252-bf97-c016a90eb78b"
/>
Here is everything you need to know about this upgrade. Please take a
good look at what changed and the test results before merging this pull
request.
### What changed?
#### ✳️ bun (1.1.43 → 1.2.0) · [Repo](https://github.com/oven-sh/bun)
Sorry, we couldn't find anything useful about this release.
---
[Depfu](https://depfu.com) will automatically keep this PR
conflict-free, as long as you don't add any commits to this branch
yourself. You can also trigger a rebase manually by commenting with
`@depfu rebase`.
<details><summary>All Depfu comment commands</summary>
<blockquote><dl>
<dt>@depfu rebase</dt><dd>Rebases against your default branch and
redoes this update</dd>
<dt>@depfu recreate</dt><dd>Recreates this PR, overwriting any edits
that you've made to it</dd>
<dt>@depfu merge</dt><dd>Merges this PR once your tests are passing and
conflicts are resolved</dd>
<dt>@depfu cancel merge</dt><dd>Cancels automatic merging of this
PR</dd>
<dt>@depfu close</dt><dd>Closes this PR and deletes the branch</dd>
<dt>@depfu reopen</dt><dd>Restores the branch and reopens this PR (if
it's closed)</dd>
<dt>@depfu pause</dt><dd>Ignores all future updates for this dependency
and closes this PR</dd>
<dt>@depfu pause [minor|major]</dt><dd>Ignores all future minor/major
updates for this dependency and closes this PR</dd>
<dt>@depfu resume</dt><dd>Future versions of this dependency will
create PRs again (leaves this PR as is)</dd>
</dl></blockquote>
</details>
Co-authored-by: depfu[bot] <23717796+depfu[bot]@users.noreply.github.com>
This PR fixes a few problems with IntelliSense:
- Default installs suggest font weight utilities twice
- When setting `--font-weight-*: initial;` the default weights are still
suggested
- Setting `--spacing-*: initial;` still shows suggestions for utilities
using the spacing scale assuming it's multiplier-based. Removing the
`--spacing: …` key should make them entirely theme driven instead.
- The default container query variants like `@sm`, `@md`, etc… aren't
suggested. Only the `@min-sm` and `@max-sm` style ones are.
Fixes
https://github.com/tailwindlabs/tailwindcss-intellisense/issues/1133
Fixes
https://github.com/tailwindlabs/tailwindcss-intellisense/issues/1136Fixes#15811
---------
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
Closes#15220
This PR fixes an issue where the upgrade tool would not be able to load
some JavaScript config files across different drive letters on Windows.
The issue in detail is that `path.relative(…)` tries to build a relative
path but if the file is inside the same folder, it won't start the
relative path with a `./` so we manually appended it in case that it
isn't there. The issue on Windows specifically is that
`file.relative(…)` can also return a legit absolute path, e.g. when the
file is on a different drive. In this case we obviously don't want to
prefix a path with `./`.
## Test plan
To reproduce this issue, I checked out a Tailwind v3 project _on a
different drive letter than my Windows installation_. In that case, I
was adding a repo inside `D:` while `npm` was installed in `C:`. I then
run `npx @tailwindcss/upgrade` to reproduce the issue.
The fix was validated with a local `bun` run of the upgrade tool:
This PR fixes an issue where classes such as `text-sm/none` don't work
as expected. The reason for this is that `leading-none` is the only
hardcoded leading utility and is not coming from the `@theme`. This
means that `text-sm/none` tries to do a lookup for `none` but it won't
resolve.
This PR fixes that by allowing `none` as a modifier.
While working on this, I noticed that `text-sm/none` _did_ generate CSS:
```css
.text-sm\/none {
font-size: var(--text-sm);
}
```
Notice that the `line-height` is missing. This means that any modifier
that can't be resolved doesn't get the `line-height` set, but it _will_
generate CSS. In this case, no CSS should have been generated.
Otherwise, all of these generate CSS which will only bloat your CSS and
won't
work as expected. E.g.: `text-sm/foo`, `text-sm/bar`, and `text-sm/baz`:
```css
.text-sm\/bar {
font-size: var(--text-sm);
}
.text-sm\/baz {
font-size: var(--text-sm);
}
.text-sm\/foo {
font-size: var(--text-sm);
}
```
Fixes: #15911
Update the `open` variant to addtionally match the new `:open` pseudo
class.
See spec at https://drafts.csswg.org/selectors-4/#open-state
See Chromium intent to ship:
https://groups.google.com/a/chromium.org/g/blink-dev/c/Pdo4oOXYKcA
`:open` matches open `<details>` and `<dialog>` elements (already
covered by [open]), but also matches select elements with their picker
open and inputs with their picker open.
Thanks to `:is()` taking a forgiving selector list, this is safe to add
even with limited browser support.
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
This PR fixes an issue where we didn't always correctly validated
invalid CSS variables when using the CSS variable shorthand syntax.
This PR fixes that by ensuring we start with `--`. We can't validate
that the variable exists at runtime, but we can validate if it looks
like a valid CSS variable.
We can go a step further by validating if the CSS variable is valid
syntax (e.g.: all characters are valid), but we can introduce this if
this is causing actual issues in projects.
```
p-(a-b)
```
Used to compile to:
```css
.p-\(a-b\) {
padding: var(a-b);
}
```
But not anymore.
This PR adds `outline-color` to the transition-property again, and
updates the implementation for `outline-hidden`.
The `outline-hidden` will behave exactly the same as `outline-none`
_except_ in forced colors mode. In forced colors mode, `outline-hidden`
will force a 2px solid border.
Closes: #15591
Variants like this can't be easily negated by our current system:
```css
@custom-variant dark {
&.is-dark {
@slot;
}
@media (prefers-color-scheme: dark) {
@slot;
}
}
```
Right now it produces the following CSS which is logically incorrect:
```css
.utility-name {
&:not(.is-dark) {
/* ... */
}
@media not (prefers-color-scheme: dark) {
/* ... */
}
}
```
The correct CSS is this which requires moving things around:
```css
.utility-name {
@media not (prefers-color-scheme: dark) {
&:not(.is-dark) {
/* ... */
}
}
}
```
We're opting to disable this instead of generating incorrect CSS for
now. I'd like to bring this back in the future for simpler cases in the
future.
This PR replaces `@variant` with `@custom-variant` for registering
custom variants via your CSS.
In addition, this PR introduces `@variant` that can be used in your CSS
to use a variant while writing custom CSS.
E.g.:
```css
.btn {
background: white;
@variant dark {
background: black;
}
}
```
Compiles to:
```css
.btn {
background: white;
}
@media (prefers-color-scheme: dark) {
.btn {
background: black;
}
}
```
For backwards compatibility, the `@variant` rules that don't have a body
and are
defined inline:
```css
@variant hocus (&:hover, &:focus);
```
And `@variant` rules that are defined with a body and a `@slot`:
```css
@variant hocus {
&:hover, &:focus {
@slot;
}
}
```
Will automatically be upgraded to `@custom-variant` internally, so no
breaking changes are introduced with this PR.
---
TODO:
- [x] ~~Decide whether we want to allow multiple variants and if so,
what syntax should be used. If not, nesting `@variant <variant> {}` will
be the way to go.~~ Only a single `@variant <variant>` can be used, if
you want to use multiple, nesting should be used:
```css
.foo {
@variant hover {
@variant focus {
color: red;
}
}
}
```
This PR changes the syntax for the `--alpha(…)` function to look like
more modern CSS.
The arguments to apply an alpha to a color is using the `/` syntax
instead of the comma syntax.
```diff
- --alpha(color, 50%)
+ --alpha(color / 50%)
```
This syntax is now similar to modern `rgb(0 0 0 / 50%)` syntax in CSS.
Closes#15636Closes#15638Closes#15637
I noticed that I forgot to update the bundled `lightningcss`
dependencies in the `standalone` project. This makes sure we have the
same version everywhere.
This PR fixes an issue where functional utilities configured via CSS
don't resolve the values correctly.
We always fully resolved the values as-if a `@theme inline` was used.
We used to compile the following code:
```css
@theme {
--tab-size-github: 8;
}
@utility tab-* {
tab-size: --value(--tab-size);
}
```
Into:
```css
:root {
--tab-size-github: 8;
}
.tab-github {
tab-size: 8;
}
```
But it should be referencing the variable instead:
```css
:root {
--tab-size-github: 8;
}
.tab-github {
tab-size: var(--tab-size-github);
}
```
However, if you used `@theme inline reference`, it should inline the
value:
```css
@theme inline reference {
--tab-size-github: 8;
}
@utility tab-* {
tab-size: --value(--tab-size);
}
```
This will now correctly compile to:
```css
.tab-github {
tab-size: 8;
}
```
This PR fixes an issue if you want to reset a namespace like:
```css
@theme {
--color-*: initial;
}
```
That some formatters such as Biome won't allow this syntax. To solve
that, this PR allows you to use an escaped `*` character.
```css
@theme {
--color-\*: initial;
}
```
Fixes: #15602
This PR improves the upgrade tool to make sure that newly upgraded
`--spacing(2)` CSS functions is pretty printed to prevent unambiguous
looking classes (even though it compiles correctly).
If you have a class such as `m-[calc(100dvh-theme(spacing.2))]`, then we
used to convert it to `m-[calc(100dvh-calc(var(--spacing)*2))]`. But
recently we introduced the `--spacing(2)` CSS function which means that
the output now looks like this instead: `m-[calc(100dvh---spacing(2))]`.
The triple `-` is valid because the first `-` is the minus sign, the
next two `-` characters are from the function.
One solution is to introduce spaces via underscores:
```
m-[calc(100dvh_-_--spacing(2))]
```
But a simpler solution, is to wrap the `--spacing(2)` in parens to
remove the underscores and improve the readability of the `---`
characters.
```
m-[calc(100dvh-(--spacing(2)))]
```
Upgrading `lightningcss` to fix invalid `list-style: none` conversion.
I've also reverted the change to preflight while at it, since it's no
longer necessary.
This PR adds a `main` and `browser` field for the `@tailwindcss/browser`
package.
In the package, we do have the `exports` field setup, which is an
alternative to the `main` field according to the docs:
> The "exports" provides a modern alternative to "main" …
>
> —
https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#exports
However, if you look at the unpkg link:
https://unpkg.com/@tailwindcss/browser, it tries to load the `index.js`
file. This is probably a bug in the unpkg resolver.
That said, if you look at other CDNs such as esm.sh, it does resolve
correctly: https://esm.sh/@tailwindcss/browser
According to the npm docs:
> If `main` is not set, it defaults to `index.js` in the package's root
folder.
>
> —
https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#main
This explains why unpkg is trying to load the `index.js` file.
Additionally, the npm docs also mention the `browser` field:
> If your module is meant to be used client-side the browser field
should be used instead of the main field. This is helpful to hint users
that it might rely on primitives that aren't available in Node.js
modules. (e.g. window)
>
> —
https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#browser
So this PR also adds that field just to be sure.
Here is everything you need to know about this update. Please take a
good look at what changed and the test results before merging this pull
request.
### What changed?
#### ✳️ prettier (3.3.3 → 3.4.2) ·
[Repo](https://github.com/prettier/prettier) ·
[Changelog](https://github.com/prettier/prettier/blob/main/CHANGELOG.md)
<details>
<summary>Release Notes</summary>
<h4><a
href="https://github.com/prettier/prettier/releases/tag/3.4.2">3.4.2</a></h4>
<blockquote><p dir="auto">🔗 <a
href="https://bounce.depfu.com/github.com/prettier/prettier/blob/main/CHANGELOG.md#342">Changelog</a></p></blockquote>
<h4><a
href="https://github.com/prettier/prettier/releases/tag/3.4.1">3.4.1</a></h4>
<blockquote><p dir="auto">🔗 <a
href="https://bounce.depfu.com/github.com/prettier/prettier/blob/main/CHANGELOG.md#341">Changelog</a></p></blockquote>
<p><em>Does any of this look wrong? <a
href="https://depfu.com/packages/npm/prettier/feedback">Please let us
know.</a></em></p>
</details>
<details>
<summary>Commits</summary>
<p><a
href="52829385bc...cca946176c">See
the full diff on Github</a>. The new version differs by more commits
than we can show here.</p>
</details>
---
[Depfu](https://depfu.com) will automatically keep this PR
conflict-free, as long as you don't add any commits to this branch
yourself. You can also trigger a rebase manually by commenting with
`@depfu rebase`.
<details><summary>All Depfu comment commands</summary>
<blockquote><dl>
<dt>@depfu rebase</dt><dd>Rebases against your default branch and
redoes this update</dd>
<dt>@depfu recreate</dt><dd>Recreates this PR, overwriting any edits
that you've made to it</dd>
<dt>@depfu merge</dt><dd>Merges this PR once your tests are passing and
conflicts are resolved</dd>
<dt>@depfu cancel merge</dt><dd>Cancels automatic merging of this
PR</dd>
<dt>@depfu close</dt><dd>Closes this PR and deletes the branch</dd>
<dt>@depfu reopen</dt><dd>Restores the branch and reopens this PR (if
it's closed)</dd>
<dt>@depfu pause</dt><dd>Ignores all future updates for this dependency
and closes this PR</dd>
<dt>@depfu pause [minor|major]</dt><dd>Ignores all future minor/major
updates for this dependency and closes this PR</dd>
<dt>@depfu resume</dt><dd>Future versions of this dependency will
create PRs again (leaves this PR as is)</dd>
</dl></blockquote>
</details>
Co-authored-by: depfu[bot] <23717796+depfu[bot]@users.noreply.github.com>
Here is everything you need to know about this update. Please take a
good look at what changed and the test results before merging this pull
request.
### What changed?
#### ✳️ enhanced-resolve (5.17.1 → 5.18.0) ·
[Repo](https://github.com/webpack/enhanced-resolve)
<details>
<summary>Release Notes</summary>
<h4><a
href="https://github.com/webpack/enhanced-resolve/releases/tag/v5.18.0">5.18.0</a></h4>
<blockquote><h3 dir="auto">Features</h3>
<ul dir="auto">
<li>Added wildcards support for aliases</li>
</ul></blockquote>
<p><em>Does any of this look wrong? <a
href="https://depfu.com/packages/npm/enhanced-resolve/feedback">Please
let us know.</a></em></p>
</details>
<details>
<summary>Commits</summary>
<p><a
href="247edebc90...27e457a905">See
the full diff on Github</a>. The new version differs by 9 commits:</p>
<ul>
<li><a
href="27e457a905"><code>chore(release):
5.18.0</code></a></li>
<li><a
href="88ceebe3cc"><code>feat:
add wildcards support for aliases</code></a></li>
<li><a
href="35b67ce834"><code>feat:
add wildcards</code></a></li>
<li><a
href="4fbcfa1c83"><code>chore(deps):
bump cross-spawn from 7.0.3 to 7.0.6</code></a></li>
<li><a
href="572a54f0c6"><code>chore(deps):
bump cross-spawn from 7.0.3 to 7.0.6</code></a></li>
<li><a
href="af4e2fb155"><code>ci:
add Node.js v23</code></a></li>
<li><a
href="bf443c04ac"><code>ci:
add Node.js v23</code></a></li>
<li><a
href="72999caf00"><code>chore(deps):
bump micromatch from 4.0.5 to 4.0.8</code></a></li>
<li><a
href="fbee162cc2"><code>chore(deps):
bump micromatch from 4.0.5 to 4.0.8</code></a></li>
</ul>
</details>
---
[Depfu](https://depfu.com) will automatically keep this PR
conflict-free, as long as you don't add any commits to this branch
yourself. You can also trigger a rebase manually by commenting with
`@depfu rebase`.
<details><summary>All Depfu comment commands</summary>
<blockquote><dl>
<dt>@depfu rebase</dt><dd>Rebases against your default branch and
redoes this update</dd>
<dt>@depfu recreate</dt><dd>Recreates this PR, overwriting any edits
that you've made to it</dd>
<dt>@depfu merge</dt><dd>Merges this PR once your tests are passing and
conflicts are resolved</dd>
<dt>@depfu cancel merge</dt><dd>Cancels automatic merging of this
PR</dd>
<dt>@depfu close</dt><dd>Closes this PR and deletes the branch</dd>
<dt>@depfu reopen</dt><dd>Restores the branch and reopens this PR (if
it's closed)</dd>
<dt>@depfu pause</dt><dd>Ignores all future updates for this dependency
and closes this PR</dd>
<dt>@depfu pause [minor|major]</dt><dd>Ignores all future minor/major
updates for this dependency and closes this PR</dd>
<dt>@depfu resume</dt><dd>Future versions of this dependency will
create PRs again (leaves this PR as is)</dd>
</dl></blockquote>
</details>
Co-authored-by: depfu[bot] <23717796+depfu[bot]@users.noreply.github.com>
This PR makes sure that the `--theme(…)` CSS function can only be used
with the modern syntax. For backwards compatibility, the `theme(…)`
function must be used with the older dot notation.
This PR improves the codemod tool to simplify 2 things:
1. Whenever you have a `theme(…)` call, we try to change it to a
`var(…)`, but if that doesn't work for some reason, we will make sure to
at least convert it to the more modern `--theme(…)`.
2. When converting `theme(spacing.2)`, we used to convert it to
`calc(var(--spacing)*2)`, but now we will convert it to `--spacing(2)`
instead.
Closes#15438Closes#15560Closes#15561Closes#15562
This PR upgrades `lightningcss` to `1.29.0` and uses the [new feature
flag](304389600f)
to disable the light-dark function transpilation.
This PR fixes an issue where JavaScript plugins were still able to
contribute `@keyframes` when loaded inside an `@reference` import. This
was possible because we only gated the `addBase` API and not the
`addUtilities` one which also has a special branch to handle `@keyframe`
rules.
To make this work, we have to create a new instance of the plugin API
that has awareness of wether the plugin accessing it is inside reference
import mode.
## Test plan
Added a unit test that reproduces the issue observed via #15544
This PR fixes an issue where static utilities defined via `@utility`
wasn't possible if the name starts with `-`.
There are plenty of static utilities that start with `-`, but it wasn't
possible to register them via the `@utility` directive, only via the JS
API.
Example of a core utility that is now valid:
```css
@utility -inset-full {
inset: -100%;
}
```
This PR implements new CSS functions that you can use in your CSS (or
even in arbitrary value position).
For starters, we renamed the `theme(…)` function to `--theme(…)`. The
legacy `theme(…)` function is still available for backwards
compatibility reasons, but this allows us to be future proof since
`--foo(…)` is the syntax the CSS spec recommends. See:
https://drafts.csswg.org/css-mixins/
In addition, this PR implements a new `--spacing(…)` function, this
allows you to write:
```css
@import "tailwindcss";
@theme {
--spacing: 0.25rem;
}
.foo {
margin: --spacing(4):
}
```
This is syntax sugar over:
```css
@import "tailwindcss";
@theme {
--spacing: 0.25rem;
}
.foo {
margin: calc(var(--spacing) * 4);
}
```
If your `@theme` uses the `inline` keyword, we will also make sure to
inline the value:
```css
@import "tailwindcss";
@theme inline {
--spacing: 0.25rem;
}
.foo {
margin: --spacing(4):
}
```
Boils down to:
```css
@import "tailwindcss";
@theme {
--spacing: 0.25rem;
}
.foo {
margin: calc(0.25rem * 4); /* And will be optimised to just 1rem */
}
```
---
Another new function function we added is the `--alpha(…)` function that
requires a value, and a number / percentage value. This allows you to
apply an alpha value to any color, but with a much shorter syntax:
```css
@import "tailwindcss";
.foo {
color: --alpha(var(--color-red-500), 0.5);
}
```
This is syntax sugar over:
```css
@import "tailwindcss";
.foo {
color: color-mix(in oklab, var(--color-red-500) 50%, transparent);
}
```
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
Co-authored-by: Jonathan Reinink <jonathan@reinink.ca>
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]);
}
```
This PR adds a new `@reference "…"` API as an replacement for the
previously added [`@import "…"
reference`](https://github.com/tailwindlabs/tailwindcss/pull/15228). The
motivation for a distinct at rule is that `@import` is already handled
outside of Tailwind in some scenarios (e.g. when using in combination
with postcss-import, other pre-processors, or frameworks like Svelte).
While our implementation of hijacking the `media` attribute _works in
this cases_, it can cause annoying linter issues because tooling build
around `@import` does not know about our behavior.
To fix this, we've decided to move this mode into a separate at rule
that is passed-through in the other tooling. Here's an example of how
this would look like in Svelte:
```svelte
<h1>Hello world!</h1>
<style>
@reference './theme.css';
h1 {
color: var(--theme-color);
}
</style>
```
With this change, the Svelte linter would not be detecting unused CSS
from the `theme.css` file as it would if we'd rely on `@import`.
This PR fixes an issue where using an `@utility` before it is defined,
and _if_ that `@utility` contains `@apply`, that it won't result in the
expected output. But results in an `@apply` rule that is not
substituted. Additionally, if you have multiple levels of `@apply`, we
have to make sure that everything is applied (no pun intended) in the
right order.
Right now, the following steps are taken:
1. Collect all the `@utility` at-rules (and register them in the system
as utilities).
2. Substitute `@apply` on the AST (including `@utility`'s ASTs) with the
content of the utility.
3. Delete the `@utility` at-rules such that they are removed from the
CSS output itself.
The reason we do it in this order is because handling `@apply` during
`@utility`
handling means that we could rely on another `@utility` that is defined
later
and therefore the order of the utilities starts to matter. This is not a
bad
thing, but the moment you import multiple CSS files or plugins, this
could
become hard to manage.
Another important step is that when using `@utility foo`, the
implementation creates a `structuredClone` from its AST when first using
the utility. The reason we do that is because `foo` and `foo!` generate
different output and we don't want to accidentally mutate the same AST.
This structured clone is the start of the problem in the linked issue
(#15501).
If we don't do the structured clone, then substituting the `@apply`
rules would work, but then `foo` and `foo!` will generate the same
output, which is bad.
The linked issue has this structure:
```css
.foo {
@apply bar;
}
@utility bar {
@apply flex;
}
```
If we follow the steps above, this would substitute `@apply bar` first,
which
results in:
```css
.foo {
@apply flex;
}
```
But the `bar` utility, was already cloned (and cached) so now we end up
with an `@apply` rule that is not substituted.
To properly solve this problem, we have to make sure that we collect all
the `@apply` at-rules, and apply them in the correct order. To do this,
we run a topological sort on them which ensures that all the
dependencies are applied before substituting the current `@apply`.
This means that in the above example, in order to process `@apply bar`,
we have to process the `bar` utility first.
If we run into a circular dependency, then we will throw an error like
before. You'll notice that the error message in this PR is updated to a
different spot. This one is a bit easier to grasp because it shows the
error where the circular dependency _starts_ not where it _ends_ (and
completes the circle). The previous message was not wrong (since it's a
circle), but now it's a bit easier to reason about.
Fixes: #15501
