Add relative option for replace-text-component migration (#7529)

<!--
  ☝️How to write a good PR title:
- Prefix it with [ComponentName] (if applicable), for example: [Button]
  - Start with a verb, for example: Add, Delete, Improve, Fix…
  - Give as much context as necessary and as little as possible
  - Prefix it with [WIP] while it’s a work in progress
-->

### WHY are these changes introduced?

We'd like to run component migrations on `polaris-react` which uses
relative component imports.

<!--
  Context about the problem that’s being addressed.
-->

### WHAT is this pull request doing?

This adds the ability to run the `replace-text-component` migration on
relative paths:

```diff
- import {DisplayText} from "../../DisplayText";
+ import {Text} from "../../Text"
```
<!--
  Summary of the changes committed.

Before / after screenshots are appreciated for UI changes. Make sure to
include alt text that describes the screenshot.

If you include an animated gif showing your change, wrapping it in a
details tag is recommended. Gifs usually autoplay, which can cause
accessibility issues for people reviewing your PR:

    <details>
      <summary>Summary of your gif(s)</summary>
      <img src="..." alt="Description of what the gif shows">
    </details>
-->

<!-- ℹ️ Delete the following for small / trivial changes -->

### How to 🎩

🖥 [Local development
instructions](https://github.com/Shopify/polaris/blob/main/README.md#local-development)
🗒 [General tophatting
guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md)
📄 [Changelog
guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog)

<!--
  Give as much information as needed to experiment with the component
  in the playground.
-->

<details>
<summary>Copy-paste this code in
<code>playground/Playground.tsx</code>:</summary>

```jsx
import React from 'react';
import {Page} from '../src';

export function Playground() {
  return (
    <Page title="Playground">
      {/* Add the code you want to test in here */}
    </Page>
  );
}
```

</details>

### 🎩 checklist

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [ ] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [ ] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [ ] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

Co-authored-by: Lo Kim <lo.kim@shopify.com>

Author: sam-b-rose

.changeset/old-mayflies-clean.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris-migrator': minor
+---
+
+Add relative option for replace-text-component migration

polaris-migrator/src/migrations/replace-text-component/replace-text-component.ts

@@ -1,24 +1,32 @@
-import type {API, FileInfo} from 'jscodeshift';
+import type {API, FileInfo, Options} from 'jscodeshift';
 
 import {hasImportDeclaration} from '../../utilities/imports';
 
 import {replaceDisplayText} from './steps/replace-display-text';
 import {replaceOther} from './steps/replace-other';
 import {replaceTextStyle} from './steps/replace-text-style';
 
+export interface MigrationOptions extends Options {
+  relative: boolean;
+}
+
 export default function replaceTextComponent(
   file: FileInfo,
   {jscodeshift: j}: API,
+  options: MigrationOptions,
 ) {
   const source = j(file.source);
 
-  if (!hasImportDeclaration(j, source, '@shopify/polaris')) {
+  if (
+    !options.relative &&
+    !hasImportDeclaration(j, source, '@shopify/polaris')
+  ) {
     return file.source;
   }
 
-  replaceDisplayText(j, source);
-  replaceOther(j, source);
-  replaceTextStyle(j, source);
+  replaceDisplayText(j, source, options);
+  replaceOther(j, source, options);
+  replaceTextStyle(j, source, options);
 
   return source.toSource();
 }

polaris-migrator/src/migrations/replace-text-component/steps/replace-display-text.ts

@@ -7,16 +7,16 @@ import {
   insertJSXAttribute,
 } from '../../../utilities/jsx';
 import {
-  renameImportSpecifier,
   getImportSpecifierName,
-  hasImportSpecifier,
-  removeImportSpecifier,
+  normalizeImportSourcePaths,
+  updateImports,
 } from '../../../utilities/imports';
+import type {MigrationOptions} from '../replace-text-component';
 
 const displayTextSizeMap = {
-  small: 'headingXl',
-  medium: 'heading2xl',
-  large: 'heading3xl',
+  small: 'headingLg',
+  medium: 'headingXl',
+  large: 'heading2xl',
   extraLarge: 'heading4xl',
 };
 
@@ -26,17 +26,27 @@ const displayTextSizeMap = {
 export function replaceDisplayText<NodeType = ASTNode>(
   j: JSCodeshift,
   source: Collection<NodeType>,
+  options: MigrationOptions,
 ) {
-  if (hasImportSpecifier(j, source, 'Text', '@shopify/polaris')) {
-    removeImportSpecifier(j, source, 'DisplayText', '@shopify/polaris');
-  } else {
-    renameImportSpecifier(j, source, 'DisplayText', 'Text', '@shopify/polaris');
-  }
+  const sourcePaths = normalizeImportSourcePaths(j, source, {
+    relative: options.relative,
+    from: 'DisplayText',
+    to: 'Text',
+  });
+
+  if (!sourcePaths) return;
 
   const localElementName =
-    getImportSpecifierName(j, source, 'DisplayText', '@shopify/polaris') ||
+    getImportSpecifierName(j, source, 'DisplayText', sourcePaths.from) ||
     'DisplayText';
 
+  updateImports(j, source, {
+    fromSpecifier: 'DisplayText',
+    toSpecifier: 'Text',
+    fromSourcePath: sourcePaths.from,
+    toSourcePath: sourcePaths.to,
+  });
+
   source.findJSXElements(localElementName).forEach((element) => {
     replaceJSXElement(j, element, 'Text');
     replaceJSXAttributes(j, element, 'size', 'variant', displayTextSizeMap);

polaris-migrator/src/migrations/replace-text-component/steps/replace-other.ts

@@ -7,19 +7,19 @@ import {
   insertJSXAttribute,
 } from '../../../utilities/jsx';
 import {
-  renameImportSpecifier,
   getImportSpecifierName,
-  hasImportSpecifier,
-  removeImportSpecifier,
+  normalizeImportSourcePaths,
+  updateImports,
 } from '../../../utilities/imports';
+import type {MigrationOptions} from '../replace-text-component';
 
 const components = {
   Heading: {
-    variant: 'headingLg',
+    variant: 'headingMd',
     as: 'h2',
   },
   Subheading: {
-    variant: 'headingSm',
+    variant: 'headingXs',
     as: 'h3',
   },
   Caption: {
@@ -38,24 +38,30 @@ const components = {
 export function replaceOther<NodeType = ASTNode>(
   j: JSCodeshift,
   source: Collection<NodeType>,
+  options: MigrationOptions,
 ) {
+  const relative = options.relative;
+
   Object.entries(components).forEach(([componentName, {variant, as}]) => {
-    if (hasImportSpecifier(j, source, 'Text', '@shopify/polaris')) {
-      removeImportSpecifier(j, source, componentName, '@shopify/polaris');
-    } else {
-      renameImportSpecifier(
-        j,
-        source,
-        componentName,
-        'Text',
-        '@shopify/polaris',
-      );
-    }
+    const sourcePaths = normalizeImportSourcePaths(j, source, {
+      relative,
+      from: componentName,
+      to: 'Text',
+    });
+
+    if (!sourcePaths) return;
 
     const localElementName =
-      getImportSpecifierName(j, source, componentName, '@shopify/polaris') ||
+      getImportSpecifierName(j, source, componentName, sourcePaths.from) ||
       componentName;
 
+    updateImports(j, source, {
+      fromSpecifier: componentName,
+      toSpecifier: 'Text',
+      fromSourcePath: sourcePaths.from,
+      toSourcePath: sourcePaths.to,
+    });
+
     source.findJSXElements(localElementName).forEach((element) => {
       replaceJSXElement(j, element, 'Text');
       insertJSXAttribute(j, element, 'variant', variant);

polaris-migrator/src/migrations/replace-text-component/steps/replace-text-style.ts

@@ -10,11 +10,13 @@ import {
 } from '../../../utilities/jsx';
 import {
   insertImportSpecifier,
-  renameImportSpecifier,
   getImportSpecifierName,
   hasImportSpecifier,
-  removeImportSpecifier,
+  insertImportDeclaration,
+  normalizeImportSourcePaths,
+  updateImports,
 } from '../../../utilities/imports';
+import type {MigrationOptions} from '../replace-text-component';
 
 const variationMap = {
   strong: {fontWeight: 'bold'},
@@ -31,17 +33,27 @@ const variationMap = {
 export function replaceTextStyle<NodeType = ASTNode>(
   j: JSCodeshift,
   source: Collection<NodeType>,
+  options: MigrationOptions,
 ) {
-  if (hasImportSpecifier(j, source, 'Text', '@shopify/polaris')) {
-    removeImportSpecifier(j, source, 'TextStyle', '@shopify/polaris');
-  } else {
-    renameImportSpecifier(j, source, 'TextStyle', 'Text', '@shopify/polaris');
-  }
+  const sourcePaths = normalizeImportSourcePaths(j, source, {
+    relative: options.relative,
+    from: 'TextStyle',
+    to: 'Text',
+  });
+
+  if (!sourcePaths) return;
 
   const localElementName =
-    getImportSpecifierName(j, source, 'TextStyle', '@shopify/polaris') ||
+    getImportSpecifierName(j, source, 'TextStyle', sourcePaths.from) ||
     'TextStyle';
 
+  updateImports(j, source, {
+    fromSpecifier: 'TextStyle',
+    toSpecifier: 'Text',
+    fromSourcePath: sourcePaths.from,
+    toSourcePath: sourcePaths.to,
+  });
+
   source.findJSXElements(localElementName).forEach((element) => {
     replaceJSXElement(j, element, 'Text');
     insertJSXAttribute(j, element, 'variant', 'bodyMd');
@@ -50,10 +62,29 @@ export function replaceTextStyle<NodeType = ASTNode>(
       .forEach((literal) => {
         const currentValue = literal.node.value as keyof typeof variationMap;
         if (currentValue === 'code') {
+          const inlineTextSourcePath = options.relative
+            ? sourcePaths.from.replace('TextStyle', 'InlineCode')
+            : '@shopify/polaris';
+
           if (
-            !hasImportSpecifier(j, source, 'InlineCode', '@shopify/polaris')
+            !hasImportSpecifier(j, source, 'InlineCode', inlineTextSourcePath)
           ) {
-            insertImportSpecifier(j, source, 'InlineCode', '@shopify/polaris');
+            if (options.relative) {
+              insertImportDeclaration(
+                j,
+                source,
+                'InlineCode',
+                inlineTextSourcePath,
+                sourcePaths.to,
+              );
+            } else {
+              insertImportSpecifier(
+                j,
+                source,
+                'InlineCode',
+                inlineTextSourcePath,
+              );
+            }
           }
 
           const InlineCode = j.jsxElement(

polaris-migrator/src/migrations/replace-text-component/tests/replace-components-relative.input.tsx

@@ -0,0 +1,31 @@
+// @ts-nocheck
+import React from 'react';
+
+import {DisplayText} from '../DisplayText';
+import {Heading} from '../Heading';
+import {Subheading} from '../Subheading';
+import {Caption} from '../Caption';
+import {TextStyle} from '../TextStyle';
+import {VisuallyHidden} from '../VisuallyHidden';
+
+export function App() {
+  return (
+    <>
+      <DisplayText size="extraLarge">Display text</DisplayText>
+      <DisplayText size="large">Display text</DisplayText>
+      <DisplayText size="medium">Display text</DisplayText>
+      <DisplayText size="small">Display text</DisplayText>
+      <Heading element="h1">Heading</Heading>
+      <Heading>Heading</Heading>
+      <Subheading element="h2">Subheading</Subheading>
+      <Subheading>Subheading</Subheading>
+      <Caption>Caption</Caption>
+      <TextStyle variation="strong">Strong</TextStyle>
+      <TextStyle variation="positive">Positive</TextStyle>
+      <TextStyle variation="negative">Negative</TextStyle>
+      <TextStyle variation="warning">Warning</TextStyle>
+      <TextStyle variation="code">Code</TextStyle>
+      <VisuallyHidden>Hidden text</VisuallyHidden>
+    </>
+  );
+}

polaris-migrator/src/migrations/replace-text-component/tests/replace-components-relative.output.tsx

@@ -0,0 +1,57 @@
+// @ts-nocheck
+import React from 'react';
+
+import {Text} from '../Text';
+import {InlineCode} from '../InlineCode';
+
+export function App() {
+  return (
+    <>
+      <Text variant="heading4xl" as="p">
+        Display text
+      </Text>
+      <Text variant="heading2xl" as="p">
+        Display text
+      </Text>
+      <Text variant="headingXl" as="p">
+        Display text
+      </Text>
+      <Text variant="headingLg" as="p">
+        Display text
+      </Text>
+      <Text as="h1" variant="headingMd">
+        Heading
+      </Text>
+      <Text variant="headingMd" as="h2">
+        Heading
+      </Text>
+      <Text as="h2" variant="headingXs">
+        Subheading
+      </Text>
+      <Text variant="headingXs" as="h3">
+        Subheading
+      </Text>
+      <Text variant="bodySm" as="p">
+        Caption
+      </Text>
+      <Text variant="bodyMd" fontWeight="bold" as="span">
+        Strong
+      </Text>
+      <Text variant="bodyMd" color="success" as="span">
+        Positive
+      </Text>
+      <Text variant="bodyMd" color="critical" as="span">
+        Negative
+      </Text>
+      <Text variant="bodyMd" color="warning" as="span">
+        Warning
+      </Text>
+      <Text variant="bodyMd" as="span">
+        <InlineCode>Code</InlineCode>
+      </Text>
+      <Text variant="bodySm" as="span" visuallyHidden>
+        Hidden text
+      </Text>
+    </>
+  );
+}

polaris-migrator/src/migrations/replace-text-component/tests/replace-components.output.tsx

@@ -7,15 +7,15 @@ export function App() {
       <Text variant="heading4xl" as="p">
         Display text
       </Text>
-      <Text variant="heading3xl" as="p">
-        Display text
-      </Text>
       <Text variant="heading2xl" as="p">
         Display text
       </Text>
       <Text variant="headingXl" as="p">
         Display text
       </Text>
+      <Text variant="headingLg" as="p">
+        Display text
+      </Text>
       <Text as="h1" variant="headingLg">
         Heading
       </Text>

polaris-migrator/src/migrations/replace-text-component/tests/replace-text-component.test.ts

@@ -1,11 +1,14 @@
 import {check} from '../../../utilities/testUtils';
 
 const migration = 'replace-text-component';
-const fixtures = ['replace-components'];
+const fixtures = ['replace-components-relative'];
 
 for (const fixture of fixtures) {
   check(__dirname, {
     fixture,
     migration,
+    options: {
+      relative: fixture.includes('relative') ? true : undefined,
+    },
   });
 }