Add migration to replace static mixins with declarations (#7216)

Author: aaronccasanova

.changeset/lovely-boats-relate.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris-migrator': minor
+---
+
+Add migration to replace static mixins with declarations

polaris-migrator/README.md

@@ -85,6 +85,20 @@ Replace legacy static breakpoint mixins with the new Polaris [media query variab
 npx @shopify/polaris-migrator replace-static-breakpoint-mixins <path>
 ```
 
+### `replace-static-mixins-with-declarations`
+
+Replace legacy static mixins with their corresponding declarations and CSS custom properties.
+
+```diff
+- @include text-emphasis-normal;
++ color: var(--p-text);
++ font-weight: var(--p-font-weight-regular);
+```
+
+```sh
+npx @shopify/polaris-migrator replace-static-mixins-with-declarations <path>
+```
+
 ## Creating a migration
 
 ### Setup

polaris-migrator/src/migrations/replace-static-mixins-with-declarations/replace-static-mixins-with-declarations.ts

@@ -0,0 +1,62 @@
+import {FileInfo, API, Options} from 'jscodeshift';
+import postcss, {Plugin} from 'postcss';
+
+import {NamespaceOptions, getNamespacePattern} from '../../utilities/sass';
+import {isKeyOf} from '../../utilities/type-guards';
+
+/** Mapping of static mixins to replacement declarations */
+const staticMixins = {
+  // Note: The below mixins do accept arguments, but the logic has
+  // since been removed from the mixins.
+  'text-emphasis-subdued': {
+    color: 'var(--p-text-subdued)',
+  },
+  'text-emphasis-strong': {
+    'font-weight': 'var(--p-font-weight-semibold)',
+  },
+  'text-emphasis-normal': {
+    color: 'var(--p-text)',
+    'font-weight': 'var(--p-font-weight-regular)',
+  },
+};
+
+interface PluginOptions extends Options, NamespaceOptions {}
+
+const plugin = (options: PluginOptions = {}): Plugin => {
+  const namespacePattern = getNamespacePattern(options);
+
+  const namespacedMixinRegExp = new RegExp(
+    String.raw`^${namespacePattern}([\w-]+)`,
+  );
+
+  return {
+    postcssPlugin: 'replace-static-mixins-with-declarations',
+    AtRule(atRule) {
+      if (atRule.name !== 'include') return;
+
+      // Extract mixin name e.g. name from `@include name;` or `@include name();`
+      const mixinName = atRule.params.match(namespacedMixinRegExp)?.[1];
+
+      if (!isKeyOf(staticMixins, mixinName)) return;
+
+      atRule.replaceWith(
+        ...Object.entries(staticMixins[mixinName]).map(([prop, value]) =>
+          postcss.decl({
+            prop,
+            value,
+          }),
+        ),
+      );
+    },
+  };
+};
+
+export default function replaceStaticMixinsWithDeclarations(
+  fileInfo: FileInfo,
+  _: API,
+  options: Options,
+) {
+  return postcss(plugin(options)).process(fileInfo.source, {
+    syntax: require('postcss-scss'),
+  }).css;
+}

polaris-migrator/src/migrations/replace-static-mixins-with-declarations/tests/replace-static-mixins-with-declarations.input.scss

@@ -0,0 +1,15 @@
+.normal {
+  @include text-emphasis-normal;
+}
+
+.strong {
+  @include text-emphasis-strong;
+}
+
+.subdued {
+  @include text-emphasis-subdued;
+}
+
+.subdued-with-args {
+  @include text-emphasis-subdued(green);
+}

polaris-migrator/src/migrations/replace-static-mixins-with-declarations/tests/replace-static-mixins-with-declarations.output.scss

@@ -0,0 +1,16 @@
+.normal {
+  color: var(--p-text);
+  font-weight: var(--p-font-weight-regular);
+}
+
+.strong {
+  font-weight: var(--p-font-weight-semibold);
+}
+
+.subdued {
+  color: var(--p-text-subdued);
+}
+
+.subdued-with-args {
+  color: var(--p-text-subdued);
+}

polaris-migrator/src/migrations/replace-static-mixins-with-declarations/tests/replace-static-mixins-with-declarations.test.ts

@@ -0,0 +1,17 @@
+import {check} from '../../../utilities/testUtils';
+
+const migration = 'replace-static-mixins-with-declarations';
+const fixtures = ['replace-static-mixins-with-declarations', 'with-namespace'];
+
+for (const fixture of fixtures) {
+  check(__dirname, {
+    fixture,
+    migration,
+    extension: 'scss',
+    options: {
+      namespace: fixture.includes('with-namespace')
+        ? 'legacy-polaris-v8'
+        : undefined,
+    },
+  });
+}

polaris-migrator/src/migrations/replace-static-mixins-with-declarations/tests/with-namespace.input.scss

@@ -0,0 +1,17 @@
+@use 'global-styles/legacy-polaris-v8';
+
+.normal {
+  @include legacy-polaris-v8.text-emphasis-normal;
+}
+
+.strong {
+  @include legacy-polaris-v8.text-emphasis-strong;
+}
+
+.subdued {
+  @include legacy-polaris-v8.text-emphasis-subdued;
+}
+
+.subdued-with-args {
+  @include legacy-polaris-v8.text-emphasis-subdued(green);
+}

polaris-migrator/src/migrations/replace-static-mixins-with-declarations/tests/with-namespace.output.scss

@@ -0,0 +1,18 @@
+@use 'global-styles/legacy-polaris-v8';
+
+.normal {
+  color: var(--p-text);
+  font-weight: var(--p-font-weight-regular);
+}
+
+.strong {
+  font-weight: var(--p-font-weight-semibold);
+}
+
+.subdued {
+  color: var(--p-text-subdued);
+}
+
+.subdued-with-args {
+  color: var(--p-text-subdued);
+}