polaris

Enhancements

• Updated Popover to focus the correct element when closed (#2255)
• Updated the type of the title prop in ChoiceList from string to ReactNode (#2355)
• Added disabled prop to Filters component (#2389)
• Added helpText prop to Filters component (#2389)

Bug fixes

• Fixed an issue where types were not generated for a JSON config file (#2361)

Development workflow

• Enabled maintainers running yarn dev to hide yarn splash reports from the console by running DISABLE_SPLASH=1 yarn dev (#2372)
• Updated to sewing-kit 0.112.0 and eslint 6 and updated vscode config to use the eslint plugin to format js/ts files (#2369)

Code quality

• Migrated Popover to use hooks (#2386)

Enhancements

• Added unstable telemetry API to gather analytics about icon usage (#2368)

Bug fixes

• Fixed an accessibility issue with TextField multiline where aria-multiline would be set to an invalid type number (#2351)
• Revert #2231 as it breaks middle aligned popovers (#2237)
• Fixed alignement of disclosure icons on ResourceItem (#2370)

Bug fixes

• Fixed a bug with TextField which caused infinite layout and high CPU load in Safari, related to WebKit Bug 194332 (#2379)
• Fixed an accessibility issue with TextField multiline where aria-multiline would be set to an invalid type number (#2351)
• Fixed alignment of disclosure icons on ResourceItem (#2370)

Documentation

• Updated the AppProvider section in the Polaris v3 to v4 migration guide (#2312)
• Updated the Using translations section in the AppProvider README (#2312)

Development workflow

• Removed the need to upload assets with each release (#2346)

Code quality

• Migrated FilterValueSelector to use hooks instead of withAppProvider (#2156)
• Added useIsMountedRef hook to use while building components (#2167)

Bug fixes

• Fixed a bug with Button which caused infinite layout and high CPU load in Safari, related to WebKit Bug 194332 (#2350)

Enhancements

• Updated OptionList section title to match ActionList section title (#2300)
• Added pressed state to Button (#2148)
• Updated the type of the label prop in ChoiceList (nested prop of choices) from string to ReactNode (#2325).

Bug fixes

• Fixed actionGroups to only render MenuActions when actions are provided in the Page (#2266)
• Fixed PositionedOverlay incorrectly calculating Topbar.UserMenu Popover width (#2231)
• Fixed recolor-icon Sass mixin to properly scope $secondary-color to the child svg (#2298)
• Fixed an issue with the ResourceList component where the plural resource name was not used for totalItemsCount (#2301)
• Fixed Stack Item proportion when shrinking (#2319)
• Fixed animation of Collapsible with children having margins (#1980)
• Added vertical adjustment to OptionList control items (#2313)

Dependency upgrades

• Updated sewing-kit to v0.111.0 and storybook to v5.2.4 (#2326)

Enhancements

• Added CSS custom properties to Portal container (#2306)

Bug fixes

• Fixed a regression with the positioning of the Popover component (#2305)

Enhancements

• Added a totalItemsCount prop to the ResourceList component (#2233)
• Prevented the Header primary action label on the Page component from wrapping when the title is too long (#2262)

Bug fixes

• Fixed an issue with the Stack component where a Stack.Item was not getting a minimum width (#2273)
• Fixed an issue with Filters applying inconsistent border styles to sibling filters when
  there is only one filter in the filter list (#2284)
• Added aria-disabled to the Select component’s content when it is disabled (#2281)

Documentation

• Added accessibility documentation for the DropZone component (#2243)
• Improved accessibility documentation for the Spinner component (#2258)

Development workflow

• Added support for context customization in Storybook using addon-contexts (#2281)

Code quality

• Migrated DateSelector to use hooks instead of withAppProvider (#2193)
• Migrated Toast to use hooks (#2222)
• Removed link, theme and scrollLockManager from the object returned by withAppProvider as nothing consumes them any more (#2277)

Enhancements

• Added showTotalsInFooter prop to DataTable for control over placement of “Totals” row (#2200)
• Added hasFocusableParent to Spinner (#2176)

Bug fixes

• Fixed tabs that don’t wrap correctly on small screens in pre-iOS 13 Safari (#2232)
• Fixed BulkActions checkbox losing on selection focus (#2138)
• Moved rendering of the portal component’s node within the node created by the theme provider component to enable theming through CSS Custom Properties (#2224)
• Fixed a bug which caused the Popover overlay to remain in the DOM if it was updated during exiting (#2246)
• Fixed Breadcrumbs to use accessibilityLabel prop when passed in (#2254)

Documentation

• Added accessibility documentation for the date picker component (#2242)
• Added accessibility documentation for the empty state component (#2244)

Code quality

• Improved code quality for the theme provider component (#2225):

  • updated type for theme prop to ThemeConfig to distinguish from the type Theme which is shared over context. A Theme contains only the logo properties, while ThemeConfig can contain a colors property.
  • converted ThemeProvider to use hooks
  • created symmetry in context between app provider and test provider
  • added better tests for default topBar colors
  • fixed an issue where colorToHsla returned HSLA strings instead of HSLA objects when given HSL or HSLA strings
  • fixed an issue with colorToHsla where RGB colors with no saturation could result in a divide by zero error
  • fixed an issue where colorToHsla inconsistently returned an alpha value
  • fixed an issue where lightenColor and darkenColor would lighten or darken absolute lightness values (0, 100)

Enhancements

• Removed the need for z-indexes in Icon (#2207)
• Added features prop to AppProvider (#2204)

Bug fixes

• Fixed loss of focus on TextField when changing connectedRight/connectedLeft content while user is typing (#2170)
• Fixed type for clearButton (#2060). Thank you chenxsan for the contribution.
• Prevented the onSelect prop of Tabs from changing scroll position (#2196)
• Fixed 200ms visual delay when activating Popover (#2209)
• Removed the ResourceList Item hover state when Item is deselected (#1952)
• Fixed Subheading’s font-weight (#2218)
• Fixed fullWidth CardSections when contained in a page with a Nav (#2227)

Documentation

• Converted SettingToggle, Sheet, and Tabs examples to functional components (#2134)
• Converted Form, Frame, and Loading examples to functional components (#2130)
• Replaced Latin abbreviations with English words in Text field content guidelines (#2192)
• Converted SettingToggle, Sheet, and Tabs examples to functional components (#2134)
• Converted DatePicker, DropZone, and Filters examples to functional components (#2129)

Code quality

• Added MediaQueryProvider to ease the use of media queries and reduce duplication (#2117)
• Migrated Tab to use hooks instead of withAppProvider (#2096)

Development workflow

• Added a GitHub action, discoverability-action, that runs yarn splash on PR diffs and leaves a comment with the output (#2208)

Enhancements

• Added new label prop to Pagination which is used to insert contextual info between navigation buttons (#2098)
• Updated trigger to use act (#2141)
• Changed border color of Drop zone to have better contrast from the background and to be lighter when disabled (#2119)
• Adjusted search results overlay to take up 100% height of the screen on small screens and to match the width of the search bar on large screens. (#2103)
• Added skipToContentTarget prop to Frame component (#2080)

Bug fixes

• Updated Card footer actions to be left aligned instead of right by default (#2075)
• Fixed vertical alignment of Tabs disclosure activator (#2087)
• Fixed Modal setting an invalid id on aria-labelledby when no title is set (#2115)
• Fixed error warnings in Card and RollupActions tests (#2125)
• Fixed modal border not being visible in Windows high contrast mode (#2114)
• Added default accessibility label from ResourceItem (#2097)
• Reverted Page.primaryAction forcing primary to be true (#2137)
• Removed React.Children.only from AppProviderand ThemeProvider (#2121)
• Fixed visual bug where button width changed in Filters component. Thank you to @alexieyizhe for the contribution (#2003).
• Changed text-rendering to auto in Select to prevent Safari 13 from crashing (#2179)

Documentation

• Converted Autocomplete, Banner, and ChoiceList examples to functional components (#2127)
• Converted Collapsible, ColorPicker, and DataTable examples to functional components (#2128)
• Converted Modal, OptionList, and Popover examples to functional components (#2131)
• Converted RadioButton, RangeSlider, and ResourceItem examples to functional components (#2132)
• Converted ResourceList, ResourcePicker, and Select examples to functional components (#2133)
• Converted TextField, Toast, and TopBar examples to functional components (#2135)
• Updated the withContext section in the v3 to v4 migration guide (#2124)
• Clarified when to use the external prop on the Link component (#2153)
• Updated documentation examples to include disclosure on Popover activators (#2171)

Development workflow

• Added yarn splash (beta), a command-line interface to observe the splash zone of a change across the component library (#2113)
• Updated Storybook – v5.2 release notes (#2157)

Code quality

• Added useLazyRef hook to use while building components (#2166)
• Migrated FilterCreator to use hooks instead of withAppProvider (#2156)
• Created a custom error for lack of context providers (#2136)
• Migrated ContextualSaveBar to use hooks instead of withAppProvider. Thank you to @sijad for the contribution (#2091).
• Migrated RangeSlider, ScrollLock and TopBar.SearchField to use hooks instead of withAppProvider (#2083)
• Updated ResourceItem to no longer rely on withAppProvider (#2094)
• Migrated TextField and Resizer to use hooks (#1997)
• Migrated Avatar to use hooks instead of withAppProvider (#2067)
• Updated Day and DatePicker to use hooks (#2089)

Bug fixes

• Fixed TypeScript not generating correct types for functional components that have subcomponents (#2111)

Enhancements

• Added support for min/max dates in TextField by setting a string on min and max props (#1991)
• Made the title prop on Page optional, supporting continued use of Page for structure in apps using the App Bridge React TitleBar (#2082)

Bug fixes

• Fixed inconsistent padding of sections in Modal (#2072)
• Fixed animation for Modal when being rendered asynchronously (#2076)
• Fixed item content from overflowing past the container in Stack (#2071)
• Fixed Dropzone hover, disabled, and focus states (#1994)
• Added name prop to ResourceItem to fix accessibility labels (#2077)
• Fixed misalignment of ResourceItem actions (#2051)

Documentation

• Added Android/iOS images for Plain destructive button (#2081)
• Removed mobile mention from right-aligned text component guidelines (#2081)
• Added mobile example images error state of Single Choice List (#2007)

Dependency upgrades

• Updated Prettier to v1.18.2 (#2070)

Development workflow

• Added a displayName to the function generated by the withAppProvider HoC for a better devtools experience (#2093)

Code quality

• Migrated ActionMenu.RollupAction, Autocomplete, Card, EmptySearchResult, Form, SkeletonPage and TopBar to use hooks instead of withAppProvider (#2065)
• Added useUniqueId hook that can be used to get a unique id that remains consistent between rerenders and updated components to use it where appropriate (#2079)

Enhancements

• Moved ResourceItem to its own component (#1774)
• Updated ResourceList sort to show an inline label (#1774)
• Removed the tap-highlight-color for Buttons (#1545)

Bug fixes

• Removed Tooltip on disabled Pagination buttons (#1963)
• Fixed accessibility labels on ResourceList.Item persistent action disclosure icon (#1973)
• Fixed accessibility issue with Autocomplete where keyboard navigation of options was laggy and skipped options (#1887)
• Fixed bug where Autocomplete was bubbling up the Enter key event unexpectedly (#1887)
• Fixed ContextualSaveBar actions overflowing on small screens (#1967)
• Fixed Tabs rollup automatically opening from keyboard navigation of tab list (#1933)

Documentation

• Updated example section to include new examples and remove old ones (#1979)
• Updated example for the ResourceList.Item persistent actions accessibility labels (#1973)
• Removed FilterControl documentation and case studies from ResourceList documentation (#1774)
• Updated ResourceList examples to use Filters (#1774)
• Added an example to Filters showing the use of children (#1774)
• Added guidance for making animated gifs in PRs and issues more accessibility-friendly #1998
• Added RadioButton guidance to make one option selected by default #2005

Development workflow

• Update subcomponents to use named exports for components and better names props exports (#2058)

Code quality

• Removed mocks in various tests suites that are now redundant (#1978)

Deprecations

• Deprecated FilterControl. Use Filters instead (#1774)

Polaris React v4.0.0 is a major release that introduces breaking changes, primarily due to updates made to component internals. This builds a stronger foundation that ensures readiness for future React performance improvements.

This release doesn’t include any new components, but it does update some components to use React Hooks. It also deletes several deprecated features and removes dependencies on legacy context and unsafe lifecycle methods. Thanks to these improvements, Polaris React is React Strict Mode compliant.

For instructions on updating from v3 to v4, read the migration guide.

Breaking changes

• Removed groups prop on Select. Pass groups to the options prop instead. (#1831)
• Removed Autocomplete.ComboBox.TextField and Autocomplete.ComboBox.OptionList. You should use the Autocomplete.TextField and OptionList components instead. (#1830)
• Removed secondaryFooterAction prop on Card. Pass an array of secondary actions to the secondaryFooterActions prop instead. (#1831)
• Removed iconBody prop on Navigation.Item. Pass a string to the icon prop instead. (#1831)
• Removed the WithContext component, as it was an undocumented part of the public API meant for internal use only (#1641)
• Removed the WithRef component, as it was an undocumented part of the public API meant for internal use only (#1610)
• Removed support for passing a string into <Icon source> to load a bundled icon. You must load the required icon directly from @shopify/polaris-icons instead. (#1604)
• Removed support for passing an SvgSource shaped object into <Icon source> to load an icon imported using Shopify’s legacy icon loader. You must update sewing-kit to at least v0.82.0 which replaced the legacy loader with using SVGR. (#1604)
• Removed support for passing a React Element into <Icon source>. You must pass in a React Component that returns an SVG element instead. (#1604)
• Removed support for <Icon untrusted>. Passing a string into source will now always load an untrusted icon, you don't need that additional property. (#1604).
• Removed Navigation.UserMenu. Use TopBar.UserMenu instead. (#1599)
• Made title a required prop on ChoiceList to improve accessibility. It can be hidden with titleHidden. (#1575)
• Made i18n a required prop on AppProvider. Usage instructions are included in the AppProvider docs. (#1530)
• Upgraded react and react-dom peer-dependencies to 16.8.6 to enable the use of hooks (#1525)
• Changed the import method for React to use default imports. Applications consuming Polaris using TypeScript must enable esModuleInterop in tsconfig.json. (#1523)
• Removed LinkLikeComponent type export. Use AppProviderProps['linkComponent'] instead. (#1864)
• Removed the Modal.Dialog and Tabs.Panel subcomponents as they were undocumented parts of our public API meant for internal use only (#1899).

Enhancements

• Added a new create-react-app example in TypeScript demonstrating use of Polaris with react-testing (#1937)
• Exported AppliedFilterInterface and FilterInterface from Filters (#1924)
• Improved color contrast of links inside Banner (#1651)
• Add underline to Links and Plain button on hover, so it doesn't rely on color alone for accessibility (#1885)
• Add onQueryFocus callback prop to the Filters component (#1948)

Bug fixes

• Fixed types merge of ActionMenu MenuAction and MenuGroup.actions (#1895)
• Fixed the activator buttons of Page actionGroups not toggling the Popover active state on click #1905
• Fixed Windows high contrast support of Badge progress (#1928)
• Fixed BulkActionButton from throwing an error in componentDidMount (#1913)
• Fixed ToastManager from not working correctly in React.StrictMode (#1741)
• Updated translation.yml with the new locales path (#1649)
• Fixed accessibility issue with Tabs list item presentation role (#1958)
• Fixed cross-origin error being thrown in Modal when loading an external app (#1992)
• Fixed regression in PopoverOverlay causing onClose to be fired when Popover is opening and trigger was not the activator (#2000)
• Fixed issue with ContextualSaveBar blocking search when hidden (#2044)

Documentation

• Updated AppProvider app bridge example to use our AppBridgeContext (#1877)

Development workflow

• Added support for React hooks in Storybook (#1665)
• Created toBeDisabled, mountWithContext and added custom testing matchers (#1596)
• Added PolarisTestProvider helper to ease configuration of required Polaris contexts in tests, see polaris examples for usage (#1810)
• Enabled strict mode in TypeScript (#1883)
• Moved to unpkg.com for our CDN CSS assets, instead of using sdks.shopifycdn.com. Existing URLs will continue to work but new versions will only be available at unpkg.com. (#1960)
• Added ChromaUI integration for previewing Storybook builds, to potentially replace our self-hosted Heroku instance (#1975)

Dependency upgrades

• Updated @shopify/polaris in all examples to 4.0.0-rc.2 (#1937)
• Added @material-ui/react-transition-group and removed react-transition-group to support React.StrictMode (#1759)
• Added @shopify/react-testing (#1596)
• Removed@shopify/css-utilities (#1586)
• Removed @types/prop-types and prop-types (#1505)
• Updatedreact to 16.8.6 and enzyme to 3.9.1 (#1392)

Code quality

• Bumped test coverage in Collapsible (#1929)
• Bumped test coverage in DropZone, Frame, Icon, and Loading (#1927)
• Removed unused type definitions (#1862)
• Ignored deprecation warnings related to Shopify App Bridge in tests (#1852)
• Updated withAppProvider to use a functional component rather than a class component (#1813)
• Updated Link to use useI18n rather than withAppProvider (#1806)
• Updated several components to use hooks instead of withAppProvider (#1797)
• Removed CSSTransition from PopoverOverlay (#1756)
• Updated exports in src/utilities and src/test-utilities to named exports (#1717)
• Removed test errors and non-deprecation warnings (#1715)
• Enabled React.StrictMode in test components and Storybook (#1709)
• Removed all uses of ReactDOM.findDOMNode (#1696)
• Enabled react/no-unsafe ESLint rule with checkAliases (#1695)
• Alphabetized component export order and kebab-case files (#1674)
• Updated Collapsible to no longer use componentWillReceiveProps(#1670)
• Restructured context structure to be more modular (#1664)
• Updated PositionedOverlay to no longer use componentWillReceiveProps(#1621)
• Simplified WithinContentContainer context type (#1602)
• Updated OptionList to no longer use componentWillReceiveProps (#1557)
• Refactored RangeSlider DualThumb tests (#1548)
• Converted Sheet to a functional component (#1548)
• Removed withContext from ResourceList.Item (#1503)
• Removed withContext from Navigation.Item (#1502)
• Removed withRef from UnstyledLink (#1501)
• Removed withContext from ResourceList.FilterControl (#1500)
• Removed withContext from Scrollable.ScrollTo and added a test to boost coverage (#1499)
• Removed withContext from Loading (#1497)
• Removed withContext and withAppProvider from ContextualSaveBar (#1498)
• Removed withContext from Toast (#1494)
• Removed withRef and withContext from DropZone.FileUpload (#1491)
• Created useAppBridge hook (#1482)
• Removed testID warning in tests (#1447)
• Updated AppProvider to use the new context API and refactored other instances to follow a new pattern and refactor test utilities (#1424)
• Updated all context files to export react context rather than a provider and consumer (#1424)
• Deleted withSticky (#1424)
• Upgraded the Autocomplete component from legacy context API to use createContext (#1403)
• Upgraded the Navigation component from legacy context API to use createContext (#1402)
• Updated ThemeProvider to use the new context API (#1396)
• Updated AppProvider to no longer use componentWillReceiveProps(#1255)
• Removed unused context from Scrollable (#1253)
• Updated ThemeProvider to no longer use componentWillReceiveProps (#1254)
• Removed context from Collapsible (#1114)
• Refactored Frame and its subcomponents to use the createContext API instead of legacy context (#803)
• Upgraded the Banner, Card, and Modal components from legacy context API to use createContext (#786)

Deprecations

• Renamed singleColumnonPagetonarrowWidth (#1606)

Enhancements

• Added onQueryFocus callback prop to the Filters component (#1948)

Enhancements

• Added a subtitle and thumbnail prop to Page (#1880)

Bug fixes

• Fixed accessibility issue with ChoiceList errors not being correctly connected to the inputs (#1824)
• Fixed Tab aria-controls pointing to a non-existent Panel id (#1869)
• Fixed Toast accessibility issue by moving aria-live prop to ToastManager (#1873)

Code quality

• Use @shopify/typescript-configs as the base of tsconfig.json for the project (#1829)

Enhancements

• Added a verticalAlign prop to DataTable (#1790)
• Improved focus and hover states for Navigation (#1822)

Bug fixes

• Fixed the SearchInput clear button which was overflowing the search bar in Firefox 65+ (#1795)
• Fixed a bug preventing the display of Tooltip when cursor enters from a disabled element (#1783)
• Fixed React imports in the Filters component to use import * as React for projects that don't use esModuleInterop (#1820)
• Fixed tabIndex on main element causing event delegation issues (#1821)
• Fixed icon color for destructive ActionList items (#1836)
• Fixed not being able to explictly set autoComplete prop onAutocomplete.TextField (#1839)

Documentation

• Added links to App Bridge React component documentation in deprecation notices for embedded components (#1765)
• Improved link text for App Bridge deprecation notices #1802

Development workflow

• Use explicit imports for our base sass mixins instead of having them implicitly defined at build-time. This simplifies our build config and other tooling that wants to build us from source [#1680]

New components

• Filters: Use to filter the items of a list or table (#1718)

Enhancements

• Added the rollover and Windows high contrast mode to Disclosure button on Tabs (#1755)
• Added support for disabling all choices in ChoiceList (#1758)
• Components in our sass build (the styles folder) are now precompiled to avoid the chance of accidentally overwriting any of our global variables, mixins and functions (#1764)
• Changed Skip to content to render an anchor instead of a button to meet accessibility level A guidelines (#1785)

Bug fixes

• Fixed a regression introduced in #1247, where icons inside of Link would always be recolored to match the text color (#1729)
• Fixed the DiscardConfirmationModal not closing when the discard button is clicked (#1784)
• Fixed Navigation.Item secondaryAction wrapping when content wraps (#1678)

Documentation

• Added links to App Bridge React component documentation in deprecation notices for embedded components (#1765)

Development workflow

• Renamed yarn run ts to yarn run type-check to match most other Shopify projects (#1745)
• Fixed deprecation notice in build (#1754)
• Simplified our rollup plugin for sass compilation while retaining identical behaviour (#1753)

New components

• ActionMenu: Use for display of actions and action groups within the context of a header (#1653)

Enhancements

• Added the stopAnnouncements prop to Banner, which disables screen reader announcements when content changes (#1719)
• Add selectable prop to ResourceList component (thanks to @vict-shevchenko for the pull request)
• Allow Link and Button interactions when rendered as prefix/suffix within <TextField /> (#1394)
• Improve TextField so that character count is only announced on focus. (#1720)
• ActionList can now pass a unique accessibilityLabel to each Item (#1653)
• Greatly reduced complexity of Page > Header (#1653)
• Long Page > Header breadcrumb labels will now truncate instead of breaking layout (#1653)
• Improves performance of TabMeasure component (#1544)
• Added secondaryFooterActions prop to Card which adds an action list of secondary actions to the footer #1625

Bug fixes

• Fixes monochrome variant of Link and Button components to support multi-line link text (#1686)
• Fixed the first column of DataTable not rendering in iOS Safari (#1605)
• Fixed paint loss on scroll of TextField Spinner (#1740)

Documentation

• Mentioned that the Contextual Save Bar is now available for embedded apps through App Bridge directly #1721
• Mentioned Polaris icons in the Icon component documentation (#1693)
• Added an example to Card for custom action layout with a secondary action and a plain button (thanks to @sharoonthomas for the pull request)

Development workflow

• Updated Storybook to v5.1.9 (#1728)

Code quality

• Updated PositionedOverlay to no longer use componentWillReceiveProps(#1621)

Deprecations

• Card secondaryFooterAction is now deprecated. Set an array of secondary actions on the secondaryFooterActions prop instead #1625