diff --git a/documentation/guides/README.md b/documentation/guides/README.md new file mode 100644 index 00000000000..eaf4525843a --- /dev/null +++ b/documentation/guides/README.md @@ -0,0 +1,3 @@ +# Guides + +Migration guides for upgrading from v11 to v12 and onwards are hosted on our documentation site at https://polaris.shopify.com/version-guides. diff --git a/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.md b/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.md index c261e06c4a3..105741daa0e 100644 --- a/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.md +++ b/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.md @@ -3,6 +3,7 @@ title: Migrating from v11 to v12 description: Polaris v12.0.0 prop replacement, removal of components, renamed components, and token changes. navTitle: v12 icon: ColorsMajor +collapsibleTOC: true order: 1 --- @@ -10,15 +11,121 @@ order: 1 {frontmatter.description} -[Full release notes](https://github.com/Shopify/polaris/releases/tag/v12.0.0) +## Getting started + +Upgrading to Polaris v12 from v11 requires several automated and manual migrations of token, component, and component prop names that have been removed, replaced, or renamed. The bulk of migrations are automated using the [@shopify/polaris-migrator](/tools/polaris-migrator) CLI tool, with the edge cases handled by find and replace in your code editor using provided RegExp searches. You can reference the [recommended migration workflow](#migration-workflow) or [glossary](#glossary) sections for additional migration support. + +Not on v11 yet either? Check out our other [migration guides](https://github.com/Shopify/polaris/tree/main/documentation/guides) to get up to date. + + + +> Note: If you've installed `polaris-icons`, [`stylelint-polaris`](https://polaris.shopify.com/tools/stylelint-polaris#version-matchups), or `polaris-tokens` independently, you will also need to upgrade those to the versions we released along with v12.0.0. + +- [What's new in this version](/whats-new/version-12) +- [v12.0.0 release notes](https://github.com/Shopify/polaris/releases/tag/@shopify/polaris@12.0.0) + +## Migration workflow + +When running token and component migrations, we recommend the following workflow: + +### 1️⃣ Automated migrations using Polaris Migrator + +Follow the migration guide sections below where we have the [@shopify/polaris-migrator](/tools/polaris-migrator) commands scaffolded for you to paste into your terminal. Be sure to update the `` placeholder in the commands to your own app's relevant path, e.g., `{app,packages}/**/*.{css,scss}`. The file extensions can be adjusted depending on what migrations you are running. For example, component migrations can be run on `*.{ts,tsx}` files while token migrations can be run on `*.{css,scss}` files. + +```bash +# Example migration +npx @shopify/polaris-migrator ... +# Stash files with "polaris-migrator:" comments +git stash push $(grep -r -l "polaris-migrator:" $(git ls-files -m)) +# Stage all migrated files without "polaris-migrator:" comments +git add . +# Format staged files only +git diff --staged --name-only | xargs npx prettier --write +# Commit automatic migration +git commit -m "Migrate X custom properties from Polaris v11 to v12" +``` + +The polaris migrator could insert comments or skip instances that are unsafe to automatically migrate. You will need to resolve those issues in the next manual migration step. + +### 2️⃣ Manual migrations using migrator comments and RegExp code search + +Now, you need to validate the automatic migration and manually update any outstanding issues. The migration guide sections may have additional resources to help you resolve the migrations manually, such as `💡 Migration example`, `➡️ Replacement mappings` tables, and descriptions of what the automated migrations are doing. + +#### Resolve `polaris-migrator:` comments + +Unstash the polaris migrator comments if you stashed any in step 1. + +```bash +git stash pop +``` + +Go through each of the changed files and search for `polaris-migrator:` comments. Migrate the instance the comment refers to, then delete the comment. + +#### Validate with RegExp + +Next, search for each of the token RegExp searches which are found under the `✅ Post-migration RegExp validation` toggle in the guide. Update any outstanding migrations until there are no more results for the RegExp search. If you're unsure on how to search in a code editor using RegExp, check out the [glossary](#glossary). + +```bash +# Stage all manually migrated files +git add . +# Format staged files only +git diff --staged --name-only | xargs npx prettier --write +# Optional: run stylelint if using stylelint-polaris and running migrations on stylesheets +npx stylelint +# Commit manual migrations +git commit -m "Manually migrate X custom properties from Polaris v11 to v12" +``` + +### Glossary + + + +- **``**: [glob]() path for the `polaris-migrator` to run codemods on. e.g.: `{app,packages}/**/*.{css,scss}` +- **[@shopify/polaris-migrator](/tools/polaris-migrator)**: CLI codemod tool to do the bulk of migrations for you +- **Automatic migration or codemod**: A transformation that runs on your codebase programmatically. These are used to execute a bulk of the necessary migrations on your codebase to reduce the amount of manual migrations needed +- **[RegExp](https://en.wikipedia.org/wiki/Regular_expression)**: Short for regular expression, a sequence of characters used to match text. If you use a code editor like VSCode, you can follow a tutorial like [this one](https://itnext.io/vscode-find-and-replace-regex-super-powers-c7f8be0fa80f) to learn how to search your code using RegExp +- **✅ Post-migration RegExp validation**: After you run an automated migration using the `polaris-migrator`, the migrator may quick exit or miss edge cases. You can use the RegExp search snippets to find and manually migrate the stragglers +- **➡️ Token replacement mappings (or other mapping tables)**: These tables show you at a glance what our migrators are finding and replacing. They are useful to cross reference when dealing with edge cases and manual migrations +- **🔔 Stepped migration**: These are migrations that must be run in a specific order due to overlapping replacement values. These migrations have been broken out into steps that can be targeted using the `--step` flag when running the migration +- **💡 Migration example**: A simple diff showing how the migration should be modifying your code +- ``` + + ``` + + ## Component migrations ### Avatar -`npx @shopify/polaris-migrator v12-react-avatar-component ` +#### Rename `size` prop values + +`, + }} +/> + + + + prop`, + code: String.raw`\w](?:[^>]|\n)*?size`, + }} +/> -- Replace the `size` prop with the new mapping below + + + | Before | After | | ------------------------- | ----------- | @@ -29,310 +136,1409 @@ order: 1 | `size="xl-experimental"` | `size="xl"` | | `size="2xl-experimental"` | `size="xl"` | -### Badge + -- Replace `status` with `tone` + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Badge" --from="status" --to="tone"` +```diff +- +- +- +- +- +- ++ ++ ++ ++ ++ ++ +``` + + -- Replace `statusAndProgressLabelOverride` with `toneAndProgressLabelOverride` +### Badge -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Badge" --from="statusAndProgressLabelOverride" --to="toneAndProgressLabelOverride"` +#### Replace `status` prop with `tone` -### IndexTable.Row + --componentName="Badge" --from="status" --to="tone"`, + }} +/> -- Replace `status` with `tone` + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="IndexTable.Row" --from="status" --to="tone"` + prop`, + code: String.raw`\w](?:[^>]|\n)*?status`, + }} +/> -- Replace `subdued` with `tone` + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="IndexTable.Row" --from="subdued" --to="tone" --toValue="subdued"` + -### Layout.Section +```diff +- ++ +``` -- One third: + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Layout.Section" --from="oneThird" --to="variant" --toValue="oneThird"` +#### Replace `statusAndProgressLabelOverride` prop with `toneAndProgressLabelOverride` -- One half: + --componentName="Badge" --from="statusAndProgressLabelOverride" --to="toneAndProgressLabelOverride"`, + }} +/> -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Layout.Section" --from="oneHalf" --to="variant" --toValue="oneHalf"` + -- Full width: + prop`, + code: String.raw`\w](?:[^>]|\n)*?statusAndProgressLabelOverride`, + }} +/> -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Layout.Section" --from="fullWidth" --to="variant" --toValue="fullWidth"` + -- Secondary, becomes oneThird: + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Layout.Section" --from="secondary" --to="variant" --toValue="oneThird"` +```diff +- ++ +``` -### TextField + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="TextField" --from="borderless" --to="variant" --toValue="borderless"` +### IndexTable.Row -### Box +**🔔 Stepped migration**: You must run the `color` -> `tone` migration before running the tone rename migrations. -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Box" --from="borderRadiusEndStart" --to="borderEndStartRadius"` +#### Step 1: Replace `status` prop with `tone` -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Box" --from="borderRadiusEndEnd" --to="borderEndEndRadius"` + --componentName="IndexTable.Row" --from="status" --to="tone"`, + }} +/> -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Box" --from="borderRadiusStartStart" --to="borderStartStartRadius"` + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Box" --from="borderRadiusStartEnd" --to="borderStartEndRadius"` + prop`, + code: String.raw`\w](?:[^>]|\n)*?status`, + }} +/> -### HorizontalStack + -`npx @shopify/polaris-migrator react-rename-component --renameFrom="HorizontalStack" --renameTo="InlineStack" --renamePropsFrom="HorizontalStackProps" --renamePropsTo="InlineStackProps"` + -### VerticalStack +```diff +- ++ +``` -`npx @shopify/polaris-migrator react-rename-component --renameFrom="VerticalStack" --renameTo="BlockStack" --renamePropsFrom="VerticalStackProps" --renamePropsTo="BlockStackProps"` + -### HorizontalGrid +#### Step 2: Replace `subdued` prop with `tone` -`npx @shopify/polaris-migrator react-rename-component --renameFrom="HorizontalGrid" --renameTo="InlineGrid" --renamePropsFrom="HorizontalGridProps" --renamePropsTo="InlineGridProps"` + --componentName="IndexTable.Row" --from="subdued" --to="tone" --toValue="subdued"`, + }} +/> -### Button + -- connectedDisclosure: [See the updated split example](/components/actions/button) + prop`, + code: String.raw`\w](?:[^>]|\n)*?subdued`, + }} +/> -- Boolean props to `variant` and `tone` + -`npx @shopify/polaris-migrator v12-react-update-button-component ` + -### ButtonGroup +```diff +- ++ +``` -- Spacing + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="ButtonGroup" --from="spacing" --to="gap"` +### Layout.Section -- Segmented +#### Replace `oneThird` prop with `variant="oneThird"` -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="ButtonGroup" --from="segmented" --to="variant" --toValue="segmented"` + --componentName="Layout.Section" --from="oneThird" --to="variant" --toValue="oneThird"`, + }} +/> -### Banner + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Banner" --from="status" --to="tone"` + prop`, + code: String.raw`\w](?:[^>]|\n)*?oneThird`, + }} +/> -### Icon + -- Backdrop is not a pattern in the new Polaris design language. If you must use a backdrop on your icon, use Box. + -```tsx - - - +```diff +- ++ ``` -- Color + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Icon" --from="color" --to="tone"` +#### Replace `oneHalf` prop with `variant="oneHalf"` -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Icon" --from="tone" --to="tone" --fromValue="warning" --toValue="caution"` + --componentName="Layout.Section" --from="oneHalf" --to="variant" --toValue="oneHalf"`, + }} +/> -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Icon" --from="tone" --to="tone" --fromValue="highlight" --toValue="info"` + -### Text + prop`, + code: String.raw`\w](?:[^>]|\n)*?oneHalf`, + }} +/> -- Color + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Text" --from="color" --to="tone"` + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Text" --from="tone" --to="tone" --fromValue="warning" --toValue="caution"` +```diff +- ++ +``` -### Modal + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Modal" --from="small" --to="size" --toValue="small"` +#### Replace `fullWidth` prop with `variant="fullWidth"` -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Modal" --from="large" --to="size" --toValue="large"` + --componentName="Layout.Section" --from="fullWidth" --to="variant" --toValue="fullWidth"`, + }} +/> -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="Modal" --from="fullScreen" --to="size" --toValue="fullScreen"` + -### List + prop`, + code: String.raw`\w](?:[^>]|\n)*?fullWidth`, + }} +/> -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="List" --from="spacing" --to="gap"` + -### DescriptionList + -`npx @shopify/polaris-migrator react-rename-component-prop --componentName="DescriptionList" --from="spacing" --to="gap"` +```diff +- ++ +``` -### AppProvider + -The `AppProvider`'s `features` prop no longer accepts the keys `polarisSummerEditions2023` and `polarisSummerEditions2023ShadowBevelOptOut`. You should be able to remove the `features` prop completely from your Polaris `AppProvider` since there aren't any feature flags in Polaris for v12. +#### Replace `secondary` prop with `variant="oneThird"` -### Text + --componentName="Layout.Section" --from="secondary" --to="variant" --toValue="oneThird"`, + }} +/> -The `Text` component no longer supports `headingXs` and `heading4xl` as options for the `variant` prop. You will need to manually update usage of `` to `` instead. Similarly, usage of `` need to be manually updated to ``. + -## Token migrations + prop`, + code: String.raw`\w](?:[^>]|\n)*?secondary`, + }} +/> -The following tokens have either been renamed or removed. You will need to replace any instances of them with their new name or value equivalents. Please review each token section for migrations that can be run to resolve these breaking changes. + -### Border + + +```diff +- ++ +``` + + + +### TextField + +#### Replace `borderless` prop with `variant="borderless"` + + --componentName="TextField" --from="borderless" --to="variant" --toValue="borderless"`, + }} +/> + + -#### Migration + prop`, + code: String.raw`\w](?:[^>]|\n)*?borderless`, + }} +/> -To replace these deprecated `border` custom properties, you can run the [v12-styles-replace-custom-property-border](https://polaris.shopify.com/tools/polaris-migrator#v12-styles-replace-custom-property-border) migration. Please reference the [recommended token migration workflow](#recommended-token-migration-workflow) section below for additional migration support. + + + ```diff -- border-radius: var(--p-border-radius-1); -+ border-radius: var(--p-border-radius-100); +- ++ ``` + + +### Box + +#### Replace `borderRadius${cornerPosition}` prop with `border${cornerPosition}Radius` + +This border radius property rename aligns with [CSS border radius constituent properties](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius#constituent_properties) to be consistent with other Polaris component APIs as well as wider web conventions. + + --componentName="Box" --from="borderRadiusEndStart" --to="borderEndStartRadius"`, + }} +/> + + --componentName="Box" --from="borderRadiusEndEnd" --to="borderEndEndRadius"`, + }} +/> + + --componentName="Box" --from="borderRadiusStartStart" --to="borderStartStartRadius"`, + }} +/> + + --componentName="Box" --from="borderRadiusStartEnd" --to="borderStartEndRadius"`, + }} +/> + + + + prop`, + code: String.raw`\w](?:[^>]|\n)*?borderRadiusEndStart`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?borderRadiusEndEnd`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?borderRadiusStartStart`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?borderRadiusStartEnd`, + }} +/> + + + + + ```diff -- border-width: var(--p-border-width-1); -+ border-width: var(--p-border-width-025); +- ++ ``` -```sh -npx @shopify/polaris-migrator v12-styles-replace-custom-property-border -``` + -#### Post-migration validation +### HorizontalStack -After migrating use the following RegExp to check for any additional instances of `border` custom properties across all file types: +#### Rename `HorizontalStack` component to `InlineStack` -``` -(?:--p-border-radius-0-experimental|--p-border-radius-05|--p-border-radius-1|--p-border-radius-1_5-experimental|--p-border-radius-2|--p-border-radius-3|--p-border-radius-4|--p-border-radius-5|--p-border-radius-6|--p-border-width-1|--p-border-width-1-experimental|--p-border-width-2|--p-border-width-2-experimental|--p-border-width-3|--p-border-width-4|--p-border-width-5)(?![\w-]) -``` +Directional components now use `Inline` and `Block` naming conventions which are defined by [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). This ensures consistency with other Polaris component APIs as well as wider web conventions. -``` -\w](?:[^>]|\n)*?borderRadius -``` + --renameFrom="HorizontalStack" --renameTo="InlineStack" --renamePropsFrom="HorizontalStackProps" --renamePropsTo="InlineStackProps"`, + }} +/> -``` -\w](?:[^>]|\n)*?borderRadius -``` + -``` -\w](?:[^>]|\n)*?borderRadiusEndStart -``` + component`, + code: String.raw`HorizontalStack`, + }} +/> -``` -\w](?:[^>]|\n)*?borderRadiusEndEnd -``` + -``` -\w](?:[^>]|\n)*?borderRadiusStartStart -``` + -``` -\w](?:[^>]|\n)*?borderRadiusStartEnd +```diff +- ++ ``` -``` -\w](?:[^>]|\n)*?borderRadius -``` + -``` -\w](?:[^>]|\n)*?borderWidth -``` +### VerticalStack -``` -\w](?:[^>]|\n)*?borderBlockStartWidth -``` +#### Rename `VerticalStack` component to `BlockStack` -``` -\w](?:[^>]|\n)*?borderBlockEndWidth -``` +Directional components now use `Inline` and `Block` naming conventions which are defined by [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). This ensures consistency with other Polaris component APIs as well as wider web conventions. -``` -\w](?:[^>]|\n)*?borderInlineStartWidth -``` + --renameFrom="VerticalStack" --renameTo="BlockStack" --renamePropsFrom="VerticalStackProps" --renamePropsTo="BlockStackProps"`, + }} +/> -``` -\w](?:[^>]|\n)*?borderInlineEndWidth -``` + -``` -\w](?:[^>]|\n)*?outlineWidth -``` + component`, + code: String.raw`VerticalStack`, + }} +/> -``` -\w](?:[^>]|\n)*?borderWidth + + + + +```diff +- ++ ``` -#### Replacement maps + -| Deprecated Token | Replacement Value | -| ------------------------------------ | ----------------------- | -| `--p-border-radius-0-experimental` | `--p-border-radius-0` | -| `--p-border-radius-05` | `--p-border-radius-050` | -| `--p-border-radius-1` | `--p-border-radius-100` | -| `--p-border-radius-1_5-experimental` | `--p-border-radius-150` | -| `--p-border-radius-2` | `--p-border-radius-200` | -| `--p-border-radius-3` | `--p-border-radius-300` | -| `--p-border-radius-4` | `--p-border-radius-400` | -| `--p-border-radius-5` | `--p-border-radius-500` | -| `--p-border-radius-6` | `--p-border-radius-750` | -| `--p-border-width-1` | `--p-border-width-025` | -| `--p-border-width-1-experimental` | `--p-border-width-0165` | -| `--p-border-width-2` | `--p-border-width-050` | -| `--p-border-width-2-experimental` | `--p-border-width-025` | -| `--p-border-width-3` | `--p-border-width-050` | -| `--p-border-width-4` | `--p-border-width-100` | -| `--p-border-width-5` | `--p-border-width-100` | +### HorizontalGrid -### Color +#### Rename `HorizontalGrid` component to `InlineGrid` + +Directional components now use `Inline` and `Block` naming conventions which are defined by [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). This ensures consistency with other Polaris component APIs as well as wider web conventions. + + --renameFrom="HorizontalGrid" --renameTo="InlineGrid" --renamePropsFrom="HorizontalGridProps" --renamePropsTo="InlineGridProps"`, + }} +/> + + + + component`, + code: String.raw`HorizontalGrid`, + }} +/> -#### Migration + -To replace these deprecated `color` custom properties, you can run the [v12-styles-replace-custom-property-color](https://polaris.shopify.com/tools/polaris-migrator#v12-styles-replace-custom-property-color) migration. Please reference the [recommended token migration workflow](#recommended-token-migration-workflow) section below for additional migration support. + ```diff -- color: var(--p-color-bg); -+ color: var(--p-color-bg-surface); +- ++ ``` -**⚠️ Important**: The color migration needs to be run in 4 sequential steps due to overlapping `color` token names and context dependent manual migrations. + -#### Step 1 +### Button -```sh -npx @shopify/polaris-migrator v12-styles-replace-custom-property-color --step=1 -``` +#### Consolidate boolean props to `variant` and `tone` + +The `Button` component has been updated to replace deprecated `connectedDisclosure`, `outline`, `destructive`, `primary`, `primarySuccess`, `plain`, and `monochrome` props with a new `variant` prop that supports multiple variation options. + +`, + }} +/> + + + + prop`, + code: String.raw`\w](?:[^>]|\n)*?connectedDisclosure`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?destructive`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?outline`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?monochrome`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?plain`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?primary`, + }} +/> + + prop`, + code: String.raw`\w](?:[^>]|\n)*?primarySuccess`, + }} +/> + + + + + +| Old variant | New variant | +| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `plain=true` | `variant="plain"` | +| `primary=true` | `variant="primary"` | +| `primary=true` + `plain=true` | `variant="tertiary"` | +| `monochrome=true` + `plain=true` | `variant="monochromePlain"` \*
This will be deprecated in a future release, please use a different variant if possible | +| `destructive=true` | `variant="primary"` + `tone="critical"` | +| `primarySuccess=true` | `variant="primary"` + `tone="success"` | +| `destructive=true` + `outline=true` | `tone="critical"` | +| `destructive=true` + `plain=true` | `variant="plain"` + `tone="critical"` | +| `monochrome=true` | | +| `outline=true` | | + + + + -After migrating use the following RegExp to check for any additional instances of `color` custom properties across all file types: +```diff +-