move migrate-deprecated-utilities to core

Author: RobinMalfait

packages/@tailwindcss-upgrade/src/codemods/template/migrate-deprecated-utilities.ts

@@ -12,7 +12,6 @@ import { migrateArbitraryVariants } from './migrate-arbitrary-variants'
 import { migrateAutomaticVarInjection } from './migrate-automatic-var-injection'
 import { migrateCamelcaseInNamedValue } from './migrate-camelcase-in-named-value'
 import { migrateCanonicalizeCandidate } from './migrate-canonicalize-candidate'
-import { migrateDeprecatedUtilities } from './migrate-deprecated-utilities'
 import { migrateDropUnnecessaryDataTypes } from './migrate-drop-unnecessary-data-types'
 import { migrateEmptyArbitraryValues } from './migrate-handle-empty-arbitrary-values'
 import { migrateLegacyArbitraryValues } from './migrate-legacy-arbitrary-values'
@@ -41,7 +40,6 @@ export const DEFAULT_MIGRATIONS: Migration[] = [
   migrateVariantOrder, // sync, v3 → v4, Has to happen before migrations that modify variants
   migrateAutomaticVarInjection, // sync, v3 → v4
   migrateLegacyArbitraryValues, // sync, v3 → v4 (could also consider it a v4 optimization)
-  migrateDeprecatedUtilities, // sync, v4 (deprecation map, order-none → order-0)
   migrateModernizeArbitraryValues, // sync, v3 and v4 optimizations, split up?
   migrateArbitraryVariants, // sync, v4
   migrateDropUnnecessaryDataTypes, // sync, v4 (I think this can be dropped?)

packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts

@@ -494,6 +494,34 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
       await expectCanonicalization(input, candidate, expected)
     })
   })
+
+  describe('deprecated utilities', () => {
+    test('`order-none` → `order-0`', async () => {
+      let candidate = 'order-none'
+      let expected = 'order-0'
+
+      let input = css`
+        @import 'tailwindcss';
+      `
+
+      await expectCanonicalization(input, candidate, expected)
+    })
+
+    test('`order-none` → `order-none` with custom implementation', async () => {
+      let candidate = 'order-none'
+      let expected = 'order-none'
+
+      let input = css`
+        @import 'tailwindcss';
+
+        @utility order-none {
+          order: none; /* imagine this exists */
+        }
+      `
+
+      await expectCanonicalization(input, candidate, expected)
+    })
+  })
 })
 
 describe('theme to var', () => {

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

@@ -36,6 +36,7 @@ const CANONICALIZATIONS = [
   themeToVar,
   arbitraryUtilities,
   bareValueUtilities,
+  deprecatedUtilities,
   print,
 ]
 
@@ -428,6 +429,14 @@ function parseCandidate(designSystem: DesignSystem, input: string) {
   )
 }
 
+function printUnprefixedCandidate(designSystem: DesignSystem, candidate: Candidate) {
+  let candidateString = designSystem.printCandidate(candidate)
+
+  return designSystem.theme.prefix && candidateString.startsWith(`${designSystem.theme.prefix}:`)
+    ? candidateString.slice(designSystem.theme.prefix.length + 1)
+    : candidateString
+}
+
 // ----
 
 const baseReplacementsCache = new DefaultMap<DesignSystem, Map<string, Candidate>>(
@@ -811,3 +820,48 @@ function bareValueUtilities(designSystem: DesignSystem, rawCandidate: string): s
     }
   }
 }
+
+// ----
+
+const DEPRECATION_MAP = new Map([['order-none', 'order-0']])
+
+function deprecatedUtilities(designSystem: DesignSystem, rawCandidate: string): string {
+  let signatures = computeUtilitySignature.get(designSystem)
+
+  for (let readonlyCandidate of designSystem.parseCandidate(rawCandidate)) {
+    // The below logic makes use of mutation. Since candidates in the
+    // DesignSystem are cached, we can't mutate them directly.
+    let candidate = structuredClone(readonlyCandidate) as Writable<typeof readonlyCandidate>
+
+    // Create a basic stripped candidate without variants or important flag. We
+    // will re-add those later but they are irrelevant for what we are trying to
+    // do here (and will increase cache hits because we only have to deal with
+    // the base utility, nothing more).
+    let targetCandidate = baseCandidate(candidate)
+    let targetCandidateString = printUnprefixedCandidate(designSystem, targetCandidate)
+
+    let replacementString = DEPRECATION_MAP.get(targetCandidateString) ?? null
+    if (replacementString === null) return rawCandidate
+
+    let legacySignature = signatures.get(targetCandidateString)
+    if (typeof legacySignature !== 'string') return rawCandidate
+
+    let replacementSignature = signatures.get(replacementString)
+    if (typeof replacementSignature !== 'string') return rawCandidate
+
+    // Not the same signature, not safe to migrate
+    if (legacySignature !== replacementSignature) return rawCandidate
+
+    let [replacement] = parseCandidate(designSystem, replacementString)
+
+    // Re-add the variants and important flag from the original candidate
+    return designSystem.printCandidate(
+      Object.assign(structuredClone(replacement), {
+        variants: candidate.variants,
+        important: candidate.important,
+      }),
+    )
+  }
+
+  return rawCandidate
+}