Skip to content

docs: Migration guide for the ThemeProvider/CustomProperties component #5013

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 9, 2022
Merged

docs: Migration guide for the ThemeProvider/CustomProperties component #5013

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cdd07ce
docs: Initial ThemeProvider/CustomProperties migration guide
aaronccasanova Feb 2, 2022
08f9899
Merge branch 'v9.0.0-major' of https://github.com/Shopify/polaris-rea…
aaronccasanova Feb 4, 2022
ac26889
Merge branch 'v9.0.0-major' of https://github.com/Shopify/polaris-rea…
aaronccasanova Feb 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 30 additions & 5 deletions documentation/guides/migrating-from-v8-to-v9.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

Polaris v9.0.0 ([full release notes](https://github.com/Shopify/polaris-react/releases/tag/v9.0.0)) features removal of the public scss api and removal of scss functions and mixins.

## ThemeProvider changes
## From `ThemeProvider` to `CustomProperties`

The `ThemeProvider` has been deprecated in favor of the new `CustomProperties` component. As a result, a number of internal components using the `ThemeProvider` have been updated to use the `CustomProperties` component and adjusted their prop interfaces accordingly (such as: `AppProvider`, `Popover`, etc.).
The `ThemeProvider` has been deprecated in favor of the new `CustomProperties` component. As a result, a number of internal components using the `ThemeProvider` have been updated to use `CustomProperties` and adjusted their prop interfaces accordingly (such as: `AppProvider`, `Popover`, etc.).

`polaris-react` no longer supports accepting and transforming a custom theme object to influence the component library. Polaris will now maintain a set of predefined color-schemes that meet the immediate needs of the admin and thus the following changes are required:
`@shopify/polaris` no longer supports custom theme objects used to influence the component library and will now maintain a set of predefined color-schemes that meet the immediate needs of the admin. Replace the `ThemeProvider` with the `CustomProperties` component and (optionally) set the `colorScheme` prop to `light` or `dark`:

```diff
- import {ThemeProvider} from '@shopify/polaris-react';
Expand All @@ -22,9 +22,15 @@ const App = (props) => (
)
```

As mentioned above, the `ThemeProvider` has been removed from the `AppProvider` and replaced with the `CustomProperties` component.
The `CustomProperties` component will generate Polaris custom properties (`--p-*`) based on the `colorScheme` prop and make them accessible to all it's descendants.

With that said, the `AppProvider` no longer accepts a custom theme object to forward to the `ThemeProvider`. However, similar behavior is still optionally exposed by forwarding the `colorScheme` prop to the `CustomProperties` component:
> Note: `colorScheme="inverse"` has been deprecated and requires authors to explicitly set `light` or `dark` values.

> IMPORTANT: We do not officially support dark mode at this time and the example above is simply representative of the current implementation.

## `AppProvider` changes

The `ThemeProvider` has been removed from the `AppProvider` and replaced with the `CustomProperties` component. Thus, the `AppProvider` no longer accepts a custom theme object. Remove the `theme` prop from the `AppProvider` and (optionally) set the `colorScheme` prop to `light` or `dark`:

```diff
import {AppProvider} from '@shopify/polaris-react';
Expand All @@ -39,6 +45,25 @@ const App = (props) => (
)
```

## Removed all theme types, constants, and utilities

A number of types, constants, and utilities have been removed with the deprecation of the `ThemeProvider` component:

- `ThemeContext` - React context
Copy link
Member

@BPScott BPScott Feb 2, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These only need to be documented if they were part of the public api that is exported from src/index.ts. If they weren't exported from there then consumers would have been incapable of accessing these values/types in the first place.

Copy link
Member Author

@aaronccasanova aaronccasanova Feb 3, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I considered removing this section or reformatting it since only UNSTABLE_toCssCustomPropertySyntax and UNSTABLE_Tokens are exported from src/index.ts. However, I kept it in to open up the discussion in the PR and see if we cared about folks possibly diving into the package's directories or accessing unexported types via index access types:

For example:

// Not exported from `src/index.ts` but accessible from the package
import {useTheme} from '@shopify/polaris/build/esm/utilities/theme'

or

// Not exported from 'src/index.ts' but accessible via index acess types
import {ThemeProviderProps} from '@shopify/polaris'

ThemeProviderProps['theme'] // ThemeConfig type (Very common is TS codebases)

Honestly, I'm not sure we need to worry about these edge cases, but figured it didn't hurt to include them.

- `useTheme` - React hook
- `Theme` - Type
- `ThemeConfig` - Type
- `ProcessThemeConfig` - Type
- `RoleColors` - Type
- `Role` - Type
- `AppThemeConfig` - Type
- `buildCustomProperties` - Utility
- `buildThemeContext` - Utility
- `toString` - Utility
- `toCssCustomPropertySyntax` - Utility
- `UNSTABLE_toCssCustomPropertySyntax` - Utility
- `UNSTABLE_Tokens` - Constant

## CSS custom properties

CSS custom properties that were renamed can be replaced with the new CSS custom property name.
Expand Down