add initial documentation, update map-get to map.get for easier migration

Author: gwyneplaine

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

@@ -84,12 +84,12 @@ const plugin = (options: PluginOptions = {}): Plugin => {
               },
             ];
           } 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.value = 'map.get';
             node.nodes.reverse();
           }
-          // map-get arguments are in the reverse order to z-index arguments.
-          // map-get expects the map object first, and the key second.
         } else {
           const element = node.nodes[0]?.value ?? '';
           if (!isValidElement<typeof zIndexMap>(element, zIndexMap)) return;

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

@@ -28,7 +28,7 @@ $someElement: (
 
 .scenario-5 {
   /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
-  /* z-index: map-get($someElement, someKey); */
+  /* z-index: map.get($someElement, someKey); */
   z-index: z-index(someKey, $someElement);
   background-color: var(--p-background);
 }

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

@@ -29,7 +29,7 @@ $someElement: (
 
 .scenario-5 {
   /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. */
-  /* z-index: map-get($someElement, someKey); */
+  /* z-index: map.get($someElement, someKey); */
   z-index: legacy-polaris-v8.z-index(someKey, $someElement);
   background-color: var(--p-background);
 }