Add migration for sass z-index fn (#7310)

WHY are these changes introduced?
Part of #7211 

WHAT is this pull request doing?
Adding a replace-sass-z-index migration script.

Running npx @shopify/polaris-migrator replace-sass-z-index "**/*.scss"
will target z-index function usage and do the following:

* If more than one argument exists we assume the code is invoking
z-index to map-get on a custom sass map. In this case, we add a comment
with a migration warning and code snippet replacing the
`legacy-polaris-v8.z-index` usage with `map-get`
* If there's a calculation in the same declaration but the
`legacy-polaris-v8.z-index` invocation is valid and corresponds to a
polaris token, we add a comment with a migration warning and a code
snippet replacing that invocation with a css variable invocation
pointing at the corresponding polaris-token.
* If its just a valid `legacy-polaris-v8.z-index` invocation that
corresponds to an existing polaris token, we replace it with a
css-variable invocation pointing at the corresponding polaris-token.
* Otherwise we ignore the declaration. 

Things our codemod doesn't presently understand but should: 
* interpolations. `calc(#{legacy-polaris-v8.z-index} + 1)` for example
is completely ignored by our code. As post-css interprets this as an
invocation of a function called `#{legacy-polaris-v8.z-index`. It
doesn't seem to understand interpolations at the moment. We can probably
use something like style-lint's
[hasInterpolation](https://github.dev/stylelint/stylelint/blob/eee9deb35190f46c5f964769d521fef5d7d1d7a8/lib/utils/__tests__/hasInterpolation.test.js#L5)
to work around this, (ty @aaronccasanova), but not something we should
worry about for first pass imo.

Co-authored-by: Aaron Casanova <[email protected]>

Author: gwyneplaine

.changeset/hot-trains-laugh.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris-migrator': minor
+---
+
+Add sass z-index migration

polaris-migrator/README.md

@@ -168,6 +168,58 @@ Replace lengths (`px`, `rem`) and legacy Sass functions (`rem()`,`border()`, `bo
 npx @shopify/polaris-migrator replace-border-declarations <path>
 ```
 
+### `replace-sass-z-index`
+
+Replace the legacy Sass `z-index()` function with the supported CSS custom property token equivalent (ex: `var(--p-z-1)`).
+
+Any invocations of `z-index()` that correspond to a z-index design-token i.e. `--p-z-1` will be replaced with a css variable declaration.
+This includes invocations to the `$fixed-element-stacking-order` sass map i.e. `z-index(modal, $fixed-element-stacking-order)`.
+
+```diff
+- .decl-1 {
+-   z-index: z-index(content);
+- }
+- .decl-2 {
+-   z-index: z-index(modal, $fixed-element-stacking-order)
+- }
++ decl-1 {
++   z-index: var(--p-z-1);
++ }
++ .decl-2 {
++   z-index: var(--p-z-11)
++ }
+```
+
+Invocations of `z-index` within an arithmetic expression will be appended with a comment for review and manual migration.
+Generally in these instances you'll want to wrap the suggested code change in a `calc` however this may defer on a case by case basis in your codebase.
+
+```diff
+.decl-3 {
++  /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
++  /* z-index: var(--p-z-1) + 1 */
+  z-index: z-index(content) + 1
+}
+```
+
+Invocations of `z-index` with a custom sass map property, will also be appended with a comment for review and manual migration.
+
+```diff
+.decl-3 {
++  /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
++  /* z-index: map.get($custom-sass-map, modal) */
+  z-index: z-index(modal, $custom-sass-map)
+}
+```
+
+In these cases you may also want to run `npx sass-migrator module <path> --migrate-deps --load-path <load-path>` to ensure that
+`map.get` is in scope\*\*.
+
+Be aware that this may also create additional code changes in your codebase, we recommend running this only if there are large number of instances of migrations from `z-index` to `map.get`. Otherwise it may be easier to add `use 'sass:map'` to the top of your `.scss` file manually.
+
+```sh
+npx @shopify/polaris-migrator replace-sass-spacing <path>
+```
+
 ## Creating a migration
 
 ### Setup

polaris-migrator/src/migrations/replace-sass-z-index/replace-sass-z-index.ts

@@ -0,0 +1,135 @@
+import postcss, {Plugin} from 'postcss';
+import type {API, FileInfo, Options} from 'jscodeshift';
+import valueParser, {FunctionNode, Node} from 'postcss-value-parser';
+
+import {
+  NamespaceOptions,
+  namespace,
+  hasSassFunction,
+  isSassFunction,
+  hasNumericOperator,
+} from '../../utilities/sass';
+import {POLARIS_MIGRATOR_COMMENT} from '../../constants';
+
+interface PluginOptions extends Options, NamespaceOptions {}
+
+const processed = Symbol('processed');
+
+const zIndexMap = {
+  content: '--p-z-1',
+  overlay: '--p-z-2',
+};
+
+const fixedElementStackingOrder = {
+  'global-ribbon': '--p-z-3',
+  'top-bar': '--p-z-4',
+  'context-bar': '--p-z-5',
+  'small-screen-loading-bar': '--p-z-6',
+  'nav-backdrop': '--p-z-7',
+  nav: '--p-z-8',
+  'skip-to-content': '--p-z-9',
+  backdrop: '--p-z-10',
+  modal: '--p-z-11',
+  toast: '--p-z-12',
+};
+
+function isValidElement<
+  MapType extends typeof zIndexMap | typeof fixedElementStackingOrder,
+>(element: unknown, mapObj: MapType): element is keyof typeof mapObj {
+  return Object.keys(mapObj).includes(element as string);
+}
+
+const hasMoreThanOneArgument = (node: FunctionNode) => node.nodes.length > 1;
+
+const plugin = (options: PluginOptions = {}): Plugin => {
+  const namespacedZIndex = namespace('z-index', options);
+  const namespacedFixedElementStackingOrder = namespace(
+    '$fixed-element-stacking-order',
+    options,
+  );
+  return {
+    postcssPlugin: 'replace-sass-z-index',
+    Declaration(decl) {
+      // @ts-expect-error - Skip if processed so we don't process it again
+      if (decl[processed]) return;
+
+      const parsedValue = valueParser(decl.value);
+
+      if (!hasSassFunction(namespacedZIndex, parsedValue)) return;
+
+      let containsUnknownSecondArgument = false;
+
+      parsedValue.walk((node: Node) => {
+        if (!isSassFunction(namespacedZIndex, node)) return;
+        if (hasMoreThanOneArgument(node)) {
+          // If there's more than one argument to the zIndex fn
+          // We assume they're passing in a custom map
+          // In this case its unlikely this will resolve to a polaris token value
+          // transform legacy zIndex usage to map-get and move on.
+
+          const [key, _, map] = node.nodes;
+          if (
+            map.value === namespacedFixedElementStackingOrder &&
+            isValidElement(key.value, fixedElementStackingOrder)
+          ) {
+            const fixedElementStackingOrderToken =
+              fixedElementStackingOrder[key.value];
+            node.value = 'var';
+            node.nodes = [
+              {
+                type: 'word',
+                value: fixedElementStackingOrderToken,
+                sourceIndex: node.nodes[0]?.sourceIndex ?? 0,
+                sourceEndIndex: fixedElementStackingOrderToken.length,
+              },
+            ];
+          } else {
+            // map.get arguments are in the reverse order to z-index arguments.
+            // map.get expects the map object first, and the key second.
+            containsUnknownSecondArgument = true;
+            node.value = 'map.get';
+            node.nodes.reverse();
+          }
+        } else {
+          const element = node.nodes[0]?.value ?? '';
+          if (!isValidElement<typeof zIndexMap>(element, zIndexMap)) return;
+          const zIndexCustomProperty = zIndexMap[element];
+
+          node.value = 'var';
+          node.nodes = [
+            {
+              type: 'word',
+              value: zIndexCustomProperty,
+              sourceIndex: node.nodes[0]?.sourceIndex ?? 0,
+              sourceEndIndex: zIndexCustomProperty.length,
+            },
+          ];
+        }
+      });
+
+      if (hasNumericOperator(parsedValue) || containsUnknownSecondArgument) {
+        // Insert comment if the declaration value contains calculations
+        // or if the invocation of zIndex has more than one argument
+        decl.before(postcss.comment({text: POLARIS_MIGRATOR_COMMENT}));
+        decl.before(
+          postcss.comment({text: `${decl.prop}: ${parsedValue.toString()};`}),
+        );
+      } else {
+        decl.value = parsedValue.toString();
+      }
+
+      // @ts-expect-error - Mark the declaration as processed
+      decl[processed] = true;
+    },
+  };
+};
+
+export default function replaceSassZIndex(
+  fileInfo: FileInfo,
+  _: API,
+  options: Options,
+) {
+  return postcss(plugin(options)).process(fileInfo.source, {
+    syntax: require('postcss-scss'),
+  }).css;
+}

polaris-migrator/src/migrations/replace-sass-z-index/tests/replace-sass-z-index.input.scss

@@ -0,0 +1,40 @@
+$someElement: (
+  someKey: 1000;,
+);
+
+.scenario-1 {
+  z-index: z-index(content) + 1;
+  background-color: var(--p-background);
+}
+
+.scenario-2 {
+  z-index: z-index(overlay) + 1;
+  background-color: var(--p-background);
+}
+
+.scenario-3 {
+  z-index: z-index(content);
+  background-color: var(--p-background);
+}
+
+.scenario-4 {
+  z-index: z-index(overlay);
+  background-color: var(--p-background);
+}
+
+.scenario-5 {
+  z-index: z-index(someKey, $someElement);
+  background-color: var(--p-background);
+}
+
+.scenario-6 {
+  z-index: calc(z-index(overlay) + z-index(content));
+}
+
+.scenario-7 {
+  z-index: calc(#{z-index(dev-ui, $fixed-element-stacking-order)} + 1);
+}
+
+.scenario-8 {
+  z-index: z-index(modal, $fixed-element-stacking-order);
+}

polaris-migrator/src/migrations/replace-sass-z-index/tests/replace-sass-z-index.output.scss

@@ -0,0 +1,48 @@
+$someElement: (
+  someKey: 1000;,
+);
+
+.scenario-1 {
+  /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
+  /* z-index: var(--p-z-1) + 1; */
+  z-index: z-index(content) + 1;
+  background-color: var(--p-background);
+}
+
+.scenario-2 {
+  /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
+  /* z-index: var(--p-z-2) + 1; */
+  z-index: z-index(overlay) + 1;
+  background-color: var(--p-background);
+}
+
+.scenario-3 {
+  z-index: var(--p-z-1);
+  background-color: var(--p-background);
+}
+
+.scenario-4 {
+  z-index: var(--p-z-2);
+  background-color: var(--p-background);
+}
+
+.scenario-5 {
+  /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
+  /* z-index: map.get($someElement, someKey); */
+  z-index: z-index(someKey, $someElement);
+  background-color: var(--p-background);
+}
+
+.scenario-6 {
+  /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
+  /* z-index: calc(var(--p-z-2) + var(--p-z-1)); */
+  z-index: calc(z-index(overlay) + z-index(content));
+}
+
+.scenario-7 {
+  z-index: calc(#{z-index(dev-ui, $fixed-element-stacking-order)} + 1);
+}
+
+.scenario-8 {
+  z-index: var(--p-z-11);
+}

polaris-migrator/src/migrations/replace-sass-z-index/tests/replace-sass-z-index.test.ts

@@ -0,0 +1,17 @@
+import {check} from '../../../utilities/testUtils';
+
+const migration = 'replace-sass-z-index';
+const fixtures = ['replace-sass-z-index', '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-sass-z-index/tests/with-namespace.input.scss

@@ -0,0 +1,48 @@
+@use 'global-styles/legacy-polaris-v8';
+$someElement: (
+  someKey: 1000;,
+);
+
+.scenario-1 {
+  z-index: legacy-polaris-v8.z-index(content) + 1;
+  background-color: var(--p-background);
+}
+
+.scenario-2 {
+  z-index: legacy-polaris-v8.z-index(overlay) + 1;
+  background-color: var(--p-background);
+}
+
+.scenario-3 {
+  z-index: legacy-polaris-v8.z-index(content);
+  background-color: var(--p-background);
+}
+
+.scenario-4 {
+  z-index: legacy-polaris-v8.z-index(overlay);
+  background-color: var(--p-background);
+}
+
+.scenario-5 {
+  z-index: legacy-polaris-v8.z-index(someKey, $someElement);
+  background-color: var(--p-background);
+}
+
+.scenario-6 {
+  z-index: calc(
+    legacy-polaris-v8.z-index(overlay) + legacy-polaris-v8.z-index(content)
+  );
+}
+
+.scenario-7 {
+  z-index: calc(
+    #{legacy-polaris-v8.z-index(dev-ui, $fixed-element-stacking-order)} + 1
+  );
+}
+
+.scenario-8 {
+  z-index: legacy-polaris-v8.z-index(
+    modal,
+    legacy-polaris-v8.$fixed-element-stacking-order
+  );
+}