Collapse multiple utilities (#19147)

Some commits look like a lot of changes, but they just move things
around, so best to use `?w=1` when viewing commit by commit.

This PR adds a new feature to the `designSystem.canonicalizeCandidates`
to collapse multiple utilities to fewer utilities. To make this
possible, we also have to convert some logical properties to physical
properties (controllable via an option).

```ts
ds.canonicalizeCandidates(['w-4', 'h-4'], {
  collapse: true // Default `true`
  logicalToPhysical: true // Default `true`
}) // → ['size-4']
```

We can already compute the signature of each utility, where if two
utilities have the same signature they are considered the same.

However it's kind of impossible to generate all combinations of all
utilities ever to figure out if there is a potential collapse possible.
Even if we just focus on the incoming list of candidates, there could
still be a lot of classes. So instead we have to be a bit more clever.

First, we group candidates together by the used variants and if the
important `!` flag was used. We can improve this in the future, but for
now we won't even try to combine `hover:w-4 h-4`.

Next, for each candidate, we figure out which property and value it
uses. We can build up a lookup table for this. We already did this
process for all utilities in the system as well.

The lookup table for `w-4 h-4 p-4` might look something like this.

```json
{
  "width": {
    "16px": ["w-4", "size-4"],
  },
  "height": {
    "16px": ["h-4", "size-4"],
  },
  "padding": {
    "16px": ["p-4"],
  }
}
```

Next, we can build groups of candidates where an intersection exists in
the lookup table. In the example above, we can see that `w-4` and `h-4`
both map to `size-4` for the value `16px`. So we can group these two
candidates. The `p-4`d doesn't intersect with anything else, so it
remains alone. This also means that we only have to generate
combinations for two candidates (2^2 = 4) instead of three (2^3 = 8). In
practice, your class list might have many classes, so keeping this
number low is important.

When we generate combinations, we will generate the most amount of
candidates first so we have the largest collapse possible. We also stop
when we reach <= 1 combinations because we need at least two candidates
to collapse.

Since this uses the internal design system, if you have custom
`@utility`s, this will work as expected.

```css
@Utility example {
  @apply border rounded p-4;
}
```

If you then use:
```html
<div class="border m-0 rounded p-4"></div>
```

Then we can collapse this to:
```html
<div class="example m-0"></div>
```

But even if we used:
```html
<div class="border m-0 rounded pt-4 pb-4 px-4"></div>
```

It would still collapse to:
```html
<div class="example m-0"></div>
```

...because the `pt-4` and `pb-4` can collapse to `py-4`, and `py-4` and
`px-4` can collapse to `p-4`.

This is also where that logical to physical conversion comes into play,
because while `pt-4` and `pb-4` set the physical `padding-top` and
`padding-bottom` properties. The `py-4` utility sets the logical
`padding-block` property. So we internally transform `padding-block` to
the `padding-top` and `padding-bottom` physical properties. The funny
thing is that this logical to physical conversion actually means that we
will convert `pt-4` and `pb-4` from _physical_ to _logical_ properties,
because we converted to `py-4`...

In _most_ cases it's fine, and even preferred to use `py-1` over `pt-1
pb-1`, but in case it's not, then you can disable the
`logicalToPhysical` option.

## Test plan

Added some dedicated tests for this new functionality.

Author: RobinMalfait

packages/tailwindcss/src/canonicalize-candidates.test.ts

@@ -27,6 +27,12 @@ const designSystems = new DefaultMap((base: string) => {
   })
 })
 
+const DEFAULT_CANONICALIZATION_OPTIONS: CanonicalizeOptions = {
+  rem: 16,
+  collapse: true,
+  logicalToPhysical: true,
+}
+
 describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s', (strategy) => {
   let testName = '`%s` → `%s` (%#)'
   if (strategy === 'with-variant') {
@@ -68,7 +74,7 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
     input: string,
     candidate: string,
     expected: string,
-    options?: CanonicalizeOptions,
+    options: CanonicalizeOptions = DEFAULT_CANONICALIZATION_OPTIONS,
   ) {
     candidate = prepare(candidate)
     expected = prepare(expected)
@@ -88,6 +94,30 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
     }
   }
 
+  async function expectCombinedCanonicalization(
+    input: string,
+    candidates: string,
+    expected: string,
+    options: CanonicalizeOptions = DEFAULT_CANONICALIZATION_OPTIONS,
+  ) {
+    let preparedCandidates = candidates.split(/\s+/g).map(prepare)
+    let preparedExpected = expected.split(/\s+/g).map(prepare)
+
+    if (strategy === 'prefix') {
+      input = input.replace("@import 'tailwindcss';", "@import 'tailwindcss' prefix(tw);")
+    }
+
+    let designSystem = await designSystems.get(__dirname).get(input)
+    let actual = designSystem.canonicalizeCandidates(preparedCandidates, options)
+
+    try {
+      expect(actual).toEqual(preparedExpected)
+    } catch (err) {
+      if (err instanceof Error) Error.captureStackTrace(err, expectCombinedCanonicalization)
+      throw err
+    }
+  }
+
   /// ----------------------------------
 
   test.each([
@@ -269,7 +299,7 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
       ['[color:oklch(62.3%_0.214_259.815)]/50', 'text-primary'],
 
       // Arbitrary property to arbitrary value
-      ['[max-height:20px]', 'max-h-[20px]'],
+      ['[max-height:20%]', 'max-h-[20%]'],
 
       // Arbitrary property to bare value
       ['[grid-column:2]', 'col-2'],
@@ -914,6 +944,37 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
       await expectCanonicalization(input, candidate, expected)
     })
   })
+
+  test.each([
+    // 4 to 1
+    ['mt-1 mr-1 mb-1 ml-1', 'm-1'],
+
+    // 2 to 1
+    ['mt-1 mb-1', 'my-1'],
+
+    // Different order as above
+    ['mb-1 mt-1', 'my-1'],
+
+    // To completely different utility
+    ['w-4 h-4', 'size-4'],
+
+    // Do not touch if not operating on the same variants
+    ['hover:w-4 h-4', 'hover:w-4 h-4'],
+
+    // Arbitrary properties to combined class
+    ['[width:_16px_] [height:16px]', 'size-4'],
+
+    // Arbitrary properties to combined class with modifier
+    ['[font-size:14px] [line-height:1.625]', 'text-sm/relaxed'],
+  ])(
+    'should canonicalize multiple classes `%s` into a shorthand `%s`',
+    async (candidates, expected) => {
+      let input = css`
+        @import 'tailwindcss';
+      `
+      await expectCombinedCanonicalization(input, candidates, expected)
+    },
+  )
 })
 
 describe('theme to var', () => {