Introduce canonicalizeCandidates on the internal Design System (#19059)

This PR introduces a new `canonicalizeCandidates` function on the
internal Design System.

The big motivation to moving this to the core `tailwindcss` package is
that we can use this in various places:

- The Raycast extension
- The VS Code extension / language server
- 3rd party tools that use the Tailwind CSS design system APIs

> This PR looks very big, but **I think it's best to go over the changes
commit by commit**. Basically all of these steps already existed in the
upgrade tool, but are now moved to our core `tailwindcss` package.

Here is a list of all the changes:
- Added a new `canonicalizeCandidates` function to the design system
- Moved various migration steps to the core package. I inlined them in
the same file and because of that I noticed a specific pattern (more on
this later).
- Moved `printCandidate` tests to the `tailwindcss` package
- Setup tests for `canonicalizeCandidates` based on the existing tests
in the upgrade tool.

I noticed that all the migrations followed a specific pattern:

1. Parse the raw candidate into a `Candidate[]` AST
2. In a loop, try to migrate the `Candidate` to a new `Candidate` (this
often handled both the `Candidate` and its `Variant[]`)
3. If something changed, print the new `Candidate` back to a string, and
pass it to the next migration step.

While this makes sense in isolation, we are doing a lot of repeated work
by parsing, modifying, and printing the candidate multiple times. This
let me to introduce the `big refactor` commit. This changes the steps
to:

1. Up front, parse the raw candidate into a `Candidate[]` _once_.
2. Strip the variants and the important marker from the candidate. This
means that each migration step only has to deal with the base `utility`
and not care about the variants or the important marker. We can
re-attach these afterwards.
3. Instead of a `rawCandidate: string`, each migration step receives an
actual `Candidate` object (or a `Variant` object).
4. I also split up the migration steps for the `Candidate` and the
`Variant[]`.

All of this means that there is a lot less work that needs to be done.
We can also cache results between migrations. So `[@media_print]:flex`
and `[@media_print]:block` will result in `print:flex` and `print:block`
respectively, but the `[@media_print]` part is only migrated once across
both candidates.

One migration step relied on the `postcss-selector-parser` package to
parse selectors and attribute selectors. I didn't want to introduce a
package just for this, so instead used our own `SelectorParser` in the
migration and wrote a small `AttributeSelectorParser` that can parse the
attribute selector into a little data structure we can work with
instead.

If we want, we can split this PR up into smaller pieces, but since the
biggest chunk is moving existing code around, I think it's fairly doable
to review as long as you go commit by commit.

---

With this new API, we can turn:
```
[
  'bg-red-500',
  'hover:bg-red-500',
  '[@media_print]:bg-red-500',
  'hover:[@media_print]:bg-red-500',
  'bg-red-500/100',
  'hover:bg-red-500/100',
  '[@media_print]:bg-red-500/100',
  'hover:[@media_print]:bg-red-500/100',
  'bg-[var(--color-red-500)]',
  'hover:bg-[var(--color-red-500)]',
  '[@media_print]:bg-[var(--color-red-500)]',
  'hover:[@media_print]:bg-[var(--color-red-500)]',
  'bg-[var(--color-red-500)]/100',
  'hover:bg-[var(--color-red-500)]/100',
  '[@media_print]:bg-[var(--color-red-500)]/100',
  'hover:[@media_print]:bg-[var(--color-red-500)]/100',
  'bg-(--color-red-500)',
  'hover:bg-(--color-red-500)',
  '[@media_print]:bg-(--color-red-500)',
  'hover:[@media_print]:bg-(--color-red-500)',
  'bg-(--color-red-500)/100',
  'hover:bg-(--color-red-500)/100',
  '[@media_print]:bg-(--color-red-500)/100',
  'hover:[@media_print]:bg-(--color-red-500)/100',
  'bg-[color:var(--color-red-500)]',
  'hover:bg-[color:var(--color-red-500)]',
  '[@media_print]:bg-[color:var(--color-red-500)]',
  'hover:[@media_print]:bg-[color:var(--color-red-500)]',
  'bg-[color:var(--color-red-500)]/100',
  'hover:bg-[color:var(--color-red-500)]/100',
  '[@media_print]:bg-[color:var(--color-red-500)]/100',
  'hover:[@media_print]:bg-[color:var(--color-red-500)]/100',
  'bg-(color:--color-red-500)',
  'hover:bg-(color:--color-red-500)',
  '[@media_print]:bg-(color:--color-red-500)',
  'hover:[@media_print]:bg-(color:--color-red-500)',
  'bg-(color:--color-red-500)/100',
  'hover:bg-(color:--color-red-500)/100',
  '[@media_print]:bg-(color:--color-red-500)/100',
  'hover:[@media_print]:bg-(color:--color-red-500)/100',
  '[background-color:var(--color-red-500)]',
  'hover:[background-color:var(--color-red-500)]',
  '[@media_print]:[background-color:var(--color-red-500)]',
  'hover:[@media_print]:[background-color:var(--color-red-500)]',
  '[background-color:var(--color-red-500)]/100',
  'hover:[background-color:var(--color-red-500)]/100',
  '[@media_print]:[background-color:var(--color-red-500)]/100',
  'hover:[@media_print]:[background-color:var(--color-red-500)]/100'
]
```

Into their canonicalized form:
```
[
  'bg-red-500',
  'hover:bg-red-500',
  'print:bg-red-500',
  'hover:print:bg-red-500'
]
```

The list is also unique, so we won't end up with `bg-red-500 bg-red-500`
twice.

While the canonicalization itself is fairly fast, we still pay a **~1s**
startup cost for some migrations (once, and cached for the entire
lifetime of the design system). I would like to keep improving the
performance and the kinds of migrations we do, but I think this is a
good start.

The cost we pay is for:

1. Generating a full list of all possible utilities based on the
`getClassList` suggestions API.
2. Generating a full list of all possible variants.

The canonicalization step for this list takes **~2.9ms** on my machine.

Just for fun, if you use the `getClassList` API for intellisense that
generates all the suggestions and their modifiers, you get a list of
**263788** classes. If you canonicalize all of these, it takes
**~500ms** in total. So roughly **~1.9μs** per candidate.

This new API doesn't result in a performance difference for normal
Tailwind CSS builds.

The other potential concern is file size of the package. The generated
`tailwindcss.tgz` file changed like this:
```diff
- 684652 bytes (684.65 kB)
+ 749169 bytes (749.17 kB)
```
So the package increased by ~65 kB which I don't think is the end of the
world, but it is important for the `@tailwindcss/browser` build which we
don't want to grow unnecessarily. For this reason we remove some of the
code for the design system conditionally such that you don't pay this
cost in an environment where you will never need this API.

The `@tailwindcss/browser` build looks like this:
```shell
`dist/index.global.js 255.14 KB` (main)
`dist/index.global.js 272.61 KB` (before this change)
`dist/index.global.js 252.83 KB` (after this change, even smaller than on `main`)
```

Author: RobinMalfait

packages/@tailwindcss-browser/tsup.config.ts

@@ -13,4 +13,20 @@ export default defineConfig({
     'process.env.NODE_ENV': '"production"',
     'process.env.FEATURES_ENV': '"stable"',
   },
+  esbuildPlugins: [
+    {
+      name: 'patch-intellisense-apis',
+      setup(build) {
+        build.onLoad({ filter: /intellisense.ts$/ }, () => {
+          return {
+            contents: `
+              export function getClassList() { return [] }
+              export function getVariants() { return [] }
+              export function canonicalizeCandidates() { return [] }
+            `,
+          }
+        })
+      },
+    },
+  ],
 })

packages/@tailwindcss-upgrade/src/codemods/template/candidates.test.ts

@@ -1,5 +1,5 @@
 import { __unstable__loadDesignSystem } from '@tailwindcss/node'
-import { describe, expect, test } from 'vitest'
+import { expect, test } from 'vitest'
 import { spliceChangesIntoString } from '../../utils/splice-changes-into-string'
 import { extractRawCandidates } from './candidates'
 
@@ -82,116 +82,3 @@ test('replaces the right positions for a candidate', async () => {
       "
   `)
 })
-
-const candidates = [
-  // Arbitrary candidates
-  ['[color:red]', '[color:red]'],
-  ['[color:red]/50', '[color:red]/50'],
-  ['[color:red]/[0.5]', '[color:red]/[0.5]'],
-  ['[color:red]/50!', '[color:red]/50!'],
-  ['![color:red]/50', '[color:red]/50!'],
-  ['[color:red]/[0.5]!', '[color:red]/[0.5]!'],
-
-  // Static candidates
-  ['box-border', 'box-border'],
-  ['underline!', 'underline!'],
-  ['!underline', 'underline!'],
-  ['-inset-full', '-inset-full'],
-
-  // Functional candidates
-  ['bg-red-500', 'bg-red-500'],
-  ['bg-red-500/50', 'bg-red-500/50'],
-  ['bg-red-500/[0.5]', 'bg-red-500/[0.5]'],
-  ['bg-red-500!', 'bg-red-500!'],
-  ['!bg-red-500', 'bg-red-500!'],
-  ['bg-[#0088cc]/50', 'bg-[#0088cc]/50'],
-  ['bg-[#0088cc]/[0.5]', 'bg-[#0088cc]/[0.5]'],
-  ['bg-[#0088cc]!', 'bg-[#0088cc]!'],
-  ['!bg-[#0088cc]', 'bg-[#0088cc]!'],
-  ['bg-[var(--spacing)-1px]', 'bg-[var(--spacing)-1px]'],
-  ['bg-[var(--spacing)_-_1px]', 'bg-[var(--spacing)-1px]'],
-  ['bg-[var(--_spacing)]', 'bg-(--_spacing)'],
-  ['bg-(--_spacing)', 'bg-(--_spacing)'],
-  ['bg-[var(--\_spacing)]', 'bg-(--_spacing)'],
-  ['bg-(--\_spacing)', 'bg-(--_spacing)'],
-  ['bg-[-1px_-1px]', 'bg-[-1px_-1px]'],
-  ['p-[round(to-zero,1px)]', 'p-[round(to-zero,1px)]'],
-  ['w-1/2', 'w-1/2'],
-  ['p-[calc((100vw-theme(maxWidth.2xl))_/_2)]', 'p-[calc((100vw-theme(maxWidth.2xl))/2)]'],
-
-  // Keep spaces in strings
-  ['content-["hello_world"]', 'content-["hello_world"]'],
-  ['content-[____"hello_world"___]', 'content-["hello_world"]'],
-
-  // Do not escape underscores for url() and CSS variable in var()
-  ['bg-[no-repeat_url(/image_13.png)]', 'bg-[no-repeat_url(/image_13.png)]'],
-  [
-    'bg-[var(--spacing-0_5,_var(--spacing-1_5,_3rem))]',
-    'bg-(--spacing-0_5,var(--spacing-1_5,3rem))',
-  ],
-]
-
-const variants = [
-  ['', ''], // no variant
-  ['*:', '*:'],
-  ['focus:', 'focus:'],
-  ['group-focus:', 'group-focus:'],
-
-  ['hover:focus:', 'hover:focus:'],
-  ['hover:group-focus:', 'hover:group-focus:'],
-  ['group-hover:focus:', 'group-hover:focus:'],
-  ['group-hover:group-focus:', 'group-hover:group-focus:'],
-
-  ['min-[10px]:', 'min-[10px]:'],
-
-  // Normalize spaces
-  ['min-[calc(1000px_+_12em)]:', 'min-[calc(1000px+12em)]:'],
-  ['min-[calc(1000px_+12em)]:', 'min-[calc(1000px+12em)]:'],
-  ['min-[calc(1000px+_12em)]:', 'min-[calc(1000px+12em)]:'],
-  ['min-[calc(1000px___+___12em)]:', 'min-[calc(1000px+12em)]:'],
-
-  ['peer-[&_p]:', 'peer-[&_p]:'],
-  ['peer-[&_p]:hover:', 'peer-[&_p]:hover:'],
-  ['hover:peer-[&_p]:', 'hover:peer-[&_p]:'],
-  ['hover:peer-[&_p]:focus:', 'hover:peer-[&_p]:focus:'],
-  ['peer-[&:hover]:peer-[&_p]:', 'peer-[&:hover]:peer-[&_p]:'],
-
-  ['[p]:', '[p]:'],
-  ['[_p_]:', '[p]:'],
-  ['has-[p]:', 'has-[p]:'],
-  ['has-[_p_]:', 'has-[p]:'],
-
-  // Simplify `&:is(p)` to `p`
-  ['[&:is(p)]:', '[p]:'],
-  ['[&:is(_p_)]:', '[p]:'],
-  ['has-[&:is(p)]:', 'has-[p]:'],
-  ['has-[&:is(_p_)]:', 'has-[p]:'],
-
-  // Handle special `@` variants. These shouldn't be printed as `@-`
-  ['@xl:', '@xl:'],
-  ['@[123px]:', '@[123px]:'],
-]
-
-let combinations: [string, string][] = []
-
-for (let [inputVariant, outputVariant] of variants) {
-  for (let [inputCandidate, outputCandidate] of candidates) {
-    combinations.push([`${inputVariant}${inputCandidate}`, `${outputVariant}${outputCandidate}`])
-  }
-}
-
-describe('printCandidate()', () => {
-  test.each(combinations)('%s -> %s', async (candidate: string, result: string) => {
-    let designSystem = await __unstable__loadDesignSystem('@import "tailwindcss";', {
-      base: __dirname,
-    })
-
-    let candidates = designSystem.parseCandidate(candidate)
-
-    // Sometimes we will have a functional and a static candidate for the same
-    // raw input string (e.g. `-inset-full`). Dedupe in this case.
-    let cleaned = new Set([...candidates].map((c) => designSystem.printCandidate(c)))
-
-    expect([...cleaned]).toEqual([result])
-  })
-})