Skip to content

Latest commit

 

History

History
721 lines (500 loc) · 45.8 KB

MIGRATION.md

File metadata and controls

721 lines (500 loc) · 45.8 KB
Raw

Migration

🤖 Codemods

Some of the changes in this guide can be automated with codemods, small scripts that modify your app's source code automatically. Changes that can be codemodded are marked with a robot emoji (🤖) and the name of the transform (e.g. button-variant-enum). The codemods are built with jscodeshift and can be run through the CLI that ships with Circuit UI. Here is an overview of all available options (you can view this help menu by running yarn circuit-ui migrate --help):

yarn circuit-ui migrate

Automatically transforms your source code to Circuit UI's latest APIs

Options:
  --language, -l   The programming language(s) of the files to be transformed
                [array] [required] [choices: "TypeScript", "JavaScript", "Flow"]
  --path, -p       A path to the folder that contains the files to be
                   transformed                           [string] [default: "."]
  --transform, -t  The transform to be applied to the source code
                       [string] [required] [choices: "button-variant-enum", ...]

You can only run one codemod at a time and we encourage you to apply the transforms incrementally and review the changes before continuing. The codemods don't cover all edge cases, so further manual changes might be necessary. For example, jscodeshift is only able to look at one file at a time, so if a Circuit UI component is wrapped in a styled component in one file and used in another, the codemod won't be able to update its props.

Tip: Provide the --transform/-t argument at the end of the command, so that as you run further codemods you can easily replace the last argument and reuse the command to run the next codemod.

⚠️ If you run into 'node\r': No such file or directory when running the codemods with yarn, run them with node directly instead (this is a known issue).

./node_modules/.bin/circuit-ui migrate -l JavaScript -l TypeScript -t codemod-name

From v4 to v5

Circuit UI v5 is a maintenance release, primarily removing deprecated components and props.

⚠️ In order to make the migration from v4 to v5 easier, we recommend that you address the changes listed below before upgrading the Circuit UI dependencies. Deprecation warnings can also help identify code that needs to be migrated.

Explicit browser support

Starting in v5, Circuit UI is explicit about which browsers it supports. Refer to the browser support documentation for details.

Here's what you need to be mindful of when migrating:

  • You no longer need to transpile Circuit UI when bundling your application (using e.g. next-transpile-module in Next.js). Circuit UI now supports all target browsers out-of-the-box.
  • Previously recommended polyfills for Internet Explorer support are no longer necessary, and can be removed from your application:

New semantic color names

...in design tokens

New semantic color names were introduced in @sumup/design-tokens@3.4.0. The legacy names were deprecated and have been removed in v5.

Legacy name New name
success confirm
warning notify
danger alert

The new naming brings cross-platform consistency, as well as alignment with some existing components such as the notification icons.

🤖 semantic-color-names

...in component variants

Some Body, BodyLarge and Badge component variants were also renamed for consistency with the new design tokens:

Legacy variant New variant
<Body variant="success" /> <Body variant="confirm" />
<Body variant="error" /> <Body variant="alert" />
<Badge variant="success" /> <Badge variant="confirm" />
<Badge variant="warning" /> <Badge variant="notify" />
<Badge variant="danger" /> <Badge variant="alert" />

Note: the Body variants mapping above also apply to the BodyLarge component.

The legacy variant names were deprecated in v4.14.0 and will be removed in v5.

🤖 semantic-variant-names

New notification components

The legacy Circuit UI notification components (Notification, NotificationList, NotificationCard and InlineMessage) were general purpose and lacking clear guidelines on when to use which, leading to inconsistent usage in our apps.

They were deprecated in v4.14.0 and replaced by semantic, accessible components that make it clear when each should be used and are flexible enough to cover all use cases (NotificationBanner, NotificationFullscreen, NotificationModal, NotificationToast and NotificationInline). The legacy components have been removed in v5.

To migrate to the new notifications, you'll need to:

  • Replace the InlineMessage by the NotificationInline in your app
  • Replace uses of the NotificationCard, NotificationList and Notification (often used together) by either the NotificationInline or NotificationBanner, depending on the use cases.

Furthermore, some patterns that were previously not supported by Circuit UI are now available:

  • The new NotificationToast provider and hook should replace any custom implementation of a toast notifications system for improved accessibility.
  • The new NotificationModal can be used for building notification dialogs that are essential to user flows.
  • The new NotificationFullscreen can replace custom full-screen messages such as error pages or empty states, for more consistency across pages.

Read more about the new notification components in the Notification section in Storybook.

Required accessible labels

In Circuit UI v3, components requiring accessible labels started throwing an error when the labels weren't being passed. This behavior could be worked around for migration purposes by setting the UNSAFE_DISABLE_ACCESSIBILITY_ERRORS environment variable.

In v5, the workaround was removed, meaning that all components that require accessible labels expect to receive them.

Before migrating, make sure that you add appropriate and localized labels for all occurrences flagged by the error mechanism. After that, stop setting the UNSAFE_DISABLE_ACCESSIBILITY_ERRORS environment variable.

Runtime errors for missing noMargin props

Several components used to have built-in bottom margin by default, and a noMargin prop to reset it. This non-atomic behavior was deprecated several major versions ago, but migration has proved difficult.

All components with built-in margin should be passed noMargin, so that we can remove the prop using codemods in a future major while avoiding UI regressions.

Instead of removing the noMargin prop in v5, components that should receive it now throw a runtime error in development if the prop is missing. Production and testing builds are not affected. The noMargin prop was also marked as required in TypeScript types.

While migrating, you can use an escape hatch to continue running your app in development without throwing.

In your app, expose the UNSAFE_DISABLE_NO_MARGIN_ERRORS environment variable. You can use the Webpack DefinePlugin (see the Circuit UI Storybook Webpack config as an example) or, if your app uses Next.js, you can declare the variable in your next.config.js (Next.js documentation).

Once your app is set up to accept the environment variable, set it to true in development to prevent components from throwing:

UNSAFE_DISABLE_NO_MARGIN_ERRORS=true yarn dev # or yarn start

Keep in mind that this escape hatch is not meant as a way to permanently bypass the errors, but as a temporary workaround to help migrate without regressions. The noMargin prop will be entirely removed in v6.

The ListItemGroup replaces the CardList

Two new components, ListItem and ListItemGroup, were added to Circuit UI v4.4.0 to render lists of contextually similar items.

The ListItem component should generally be used implicitly by passing items to the ListItemGroup. The ListItemGroup differs from the List component because while the latter applies light styling to an HTML ul or ol, the former allows for structured data and interactivity. Refer to the component's documentation for usage guidelines and examples.

Circuit UI v5 comes with two related breaking changes:

  • the legacy CardList component has been deprecated in favor of the ListItemGroup. The component APIs are very different and migration can unfortunately not be automated: please migrate manually. The new component also comes with different styles: verify the changes visually with a designer.
  • (If you were already using the ListItem in a Circuit UI v4.x release:) The ListItem component's prefix and suffix props were renamed to leadingComponent and trailingComponent. The suffixLabel and suffixDetails props were renamed to trailingLabel and trailingDetails. The codemod will not transform uses of the ListItem as ListItemGroup items. (🤖 listitem-prop-names)

Combined LoadingButton and Button

The LoadingButton is an extension of the Button component and adds a loading state. This is a common use case, so the loading functionality has been added to the Button component itself. The LoadingButton was deprecated in v4.1 and was removed in v5.

The API hasn't changed: uses of the LoadingButton can be replaced by the Button component

🤖 component-names-v5

Other changes

  • The deprecated zIndex.sidebar design token was removed from @sumup/design-tokens. Use sIndex.navigation instead. There is no codemod for this change: search and replace the old value for the new one in your codebase.
  • The deprecated shadowSingle, shadowDouble and shadowTriple style mixins were removed. Use the shadow() style mixin instead. There is no codemod for this change: migrate manually by searching for the deprecated style mixins in your codebase, and verify the changes visually.
  • The RadioButton component's deprecated children prop was removed. Use the label prop, now typed as required, instead. There is no codemod for this change: search your codebase for uses of the RadioButton or RadioButtonGroup component and migrate them manually.
  • The ButtonGroup component's deprecated children prop was removed. Use the actions prop instead. If the new ButtonGroup component API doesn't fit your use case, consider aligning your use case with the design system, or writing a custom layout wrapper for your buttons.
  • The deprecated showValid option was removed from the inputOutline style mixin.

From v3.x to v4

Circuit v4 is a small maintenance release, featuring the upgrade to Emotion 11 and new brand icons.

To get started, upgrade @sumup/circuit-ui and its peer dependencies:

yarn upgrade @sumup/circuit-ui @sumup/design-tokens @sumup/icons --latest

For a complete list of changes, refer to the changelog.

Emotion 11

Circuit was upgraded to Emotion 11, so apps using Circuit will also have to upgrade. The main changes are Emotion's new package names and better TypeScript support.

New package names

The main change in Emotion 11 is a renaming of most packages under the @emotion organization.

It can be automated by using an ESLint plugin provided by Emotion: refer to the migration guide for upgrade instructions.

Then, after running the codemod:

  • Remove the legacy dependencies and add the new ones: 
    # example with yarn
yarn remove @emotion/core jest-emotion babel-plugin-emotion # remove legacy dependencies
yarn add @emotion/react # add new dependencies
yarn add -D @emotion/babel-plugin @emotion/jest # add new dev dependencies
yarn upgrade @emotion/styled --latest # upgrade existing packages
  • Fix any duplicate imports of @emotion/react in cases where multiple modules (e.g. css from v10's @emotion/core and ThemeProvider from v10's emotion-theming) are all under @emotion/react in v11.

Better TypeScript support

Emotion's TypeScript types have been improved in v11. Refer to the migration guide for details of the changes.

Typing the theme

One of the most useful changes is support for typing the theme.

Previously, many apps would use CreateStyled:

// utils/styled.ts
import styled, { CreateStyled } from '@emotion/styled';
import { Theme } from '@sumup/design-tokens';

// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
export default styled as CreateStyled<Theme>;

...and import the custom styled in their components:

// components/RedCard.tsx
import { css } from '@emotion/core';

import styled from 'util/styled';

const RedCard = styled(Card)(
  ({ theme }) => css`
    background-color: red;
  `,
);

Now, you can type the theme by adding it to @emotion/react's declaration:

// types/emotion.d.ts (don't forget to include this file in tsconfig.json under `typeRoots`)
import { Theme as CircuitTheme } from '@sumup/design-tokens';
import {} from '@emotion/react/types/css-prop'; // See https://github.com/emotion-js/emotion/pull/1941

declare module '@emotion/react' {
  // eslint-disable-next-line @typescript-eslint/no-empty-interface
  export interface Theme extends CircuitTheme {}
}

...and use styled from @emotion/styled directly:

// components/RedCard.tsx
import { css } from '@emotion/core';
import styled from '@emotion/styled';

const RedCard = styled(Card)(
  ({ theme }) => css`
    background-color: red;
  `,
);

Compatibility with Storybook

In case you're using Storybook in your application, you'll need to tweak the Storybook Webpack config to make it compatible with Emotion 11 (Storybook is still on Emotion 10).

Make sure that references to Emotion packages inside Storybook are pointing to the v11 packages:

// .storybook/main.js

const path = require('path');
const toPath = (_path) => path.join(process.cwd(), _path);

module.exports = {
  webpackFinal: async (config) => {
    // Add compatibility with Emotion 11
    config.resolve.alias = {
      ...config.resolve.alias,
      '@emotion/core': toPath('node_modules/@emotion/react'),
      '@emotion/styled': toPath('node_modules/@emotion/styled'),
      'emotion-theming': toPath('node_modules/@emotion/react'),
    };
    return config;
  },
};

New brand icons

Circuit v4 ships with the new brand icons from @sumup/icons v2.

Overview of @sumup/icons v2

  • There used to be "filled" and "empty" versions of some of the v1 icons. The distinction has been removed and all icons are now using a "filled" design. The icon versions were primarily used in the legacy Sidebar component, which is being replaced by the new SideNavgation.
  • The icons' size names changed from small and large to 16 and 24 (their size in pixels).
  • The default icon size was small in v1 but is now 24 in v2 (this change follows Circuit v3's new component heights).
  • Many icons were renamed.
  • Some icons or icon sizes were removed.

Migrating to @sumup/icons v2

Most of the changes can be automated using the 🤖 icons-v2 codemod.

The codemod will print warnings and errors to your console when a manual migration is required:

  • Some icons were renamed to match the names of SumUp products. They should not be used outside of the product's context. If you have doubts about your use of the icon, file an issue or contact the Design System team.
  • If an icon you were using was removed in v2 and can't be replaced by another icon, file an issue or contact the Design System team.
  • If you were using a small (16px) icon that is only available in v2 in 24 (24px), see if the 24px size works for your use case. If it doesn't, file an issue or contact the Design System team.

Finally, remember to visually verify your application after the upgrade!

From v2.x to v3

Circuit v3 is a large major release, including long-awaited changes from the full year that passed since v2. This guide will help you upgrade your application. Don't hesitate to contact the maintainers if you have any further questions.

Dependencies

Start by upgrading @sumup/circuit-ui and its peer dependencies:

yarn upgrade @sumup/circuit-ui @sumup/design-tokens @sumup/icons --latest

Accessibility

Any accessible label props that were previously optional are now required and enforced in all components.

To help identify places where accessible labels are missing, components throw runtime errors in development at missing labels. Production and testing builds are not affected.

During the migration and while the missing labels are still being added, you can use an escape hatch to continue running the app in development without throwing accessibility errors.

In your app, expose the UNSAFE_DISABLE_ACCESSIBILITY_ERRORS environment variable. You can use the Webpack DefinePlugin (here's an example in the Circuit UI Storybook config) or, if your app uses Next.js, you can declare the variable in your next.config.js (Next.js documentation).

Now, if you want to turn off the accessibility errors temporarily, run the development app with the environment variable set to true:

UNSAFE_DISABLE_ACCESSIBILITY_ERRORS=true yarn dev # or yarn start

Keep in mind that this escape hatch is not meant as a way to permanently avoid the errors, but as a temporary workaround while the missing labels are being written, localized and added to the relevant components.

Reminder: For the Input and Select components, use the built-in label prop instead of using the Label component separately.

Other accessibility improvements include:

New JSX transform

Circuit v3 improves compatibility with the new JSX transforms (introduced in React v17).

We recommend the following Babel config for applications on Next.js and Emotion 10 (Emotion 11 is not yet supported by Circuit UI). It also includes support for Emotion's css prop.

{
  "presets": [
    [
      "next/babel",
      {
        "preset-react": {
          "runtime": "automatic",
          "importSource": "@emotion/core"
        }
      }
    ]
  ],
  "plugins": [["babel-plugin-emotion", { "cssPropOptimization": true }]]
}

Typography

Before v3, typography components were general purpose and flexible. There were no guidelines on when to use a certain typography style. This has led to inconsistent usage in our apps.

The new version introduces new, semantic typography components that make it clear when each should be used, are flexible enough to cover all use cases, and for the first time include semantic colors as well.

Typography component names

The core typography components were renamed:

v2 v3
Text Body
Heading Headline
SubHeading SubHeadline
Blockquote See the next section

(🤖 component-names-v3.)

Note that the codemod will also transform other renamed components (see Other Changes.

Typography component variants

The Body (formerly Text) component's variants were changed:

v2 v3
<Text bold> <Body variant="highlight">
<Text italic> Use custom styles
<Text strike> Use custom styles
<Blockquote> <Body variant="quote">

⚠️ These changes also apply to the Anchor component, which extends Body.

Use 🤖 body-variant-highlight to migrate bold to variant="highlight". Note that this will transform your <p> elements into inline <strong> elements: you might also need to pass as="p" if you need a block-level element.

Bonus: the new Body component also supports the success, error and subtle semantic variants. Have a look at the story to get started.

New sizes

The number of available sizes was reduced, and size names were changed from the metric prefix scale (kilo, mega etc.) to numbers (one, two etc.).

Typography components size prop

The number of sizes was reduced in v3, here's the desired mapping from v2:

v2 v3
<Heading size="kilo"> <Headline size="four">
<Heading size="mega"> <Headline size="four">
<Heading size="giga"> <Headline size="three">
<Heading size="tera"> <Headline size="two">
<Heading size="peta"> <Headline size="one">
<Heading size="exa"> <Headline size="one">
<Heading size="zetta"> Migrate manually to size="one" or use custom styles (2.625rem)
<SubHeading size="kilo"> <SubHeadline> (the sizes were removed)
<SubHeading size="mega"> <SubHeadline> (the sizes were removed)
<Text size="kilo"> <Body size="two">
<Text size="mega"> <Body size="one">
<Text size="giga"> Migrate manually to size="one" or use custom styles (1.125rem)

⚠️ The Body size changes also apply to the Anchor and List components.

Most of these changes can be automated using the 🤖 typography-sizes codemod.

The codemod will also warn about occurrences of <Heading size="zetta"> and <Text size="giga">. These should be manually migrated to size="one" if possible, or alternatively to custom size styles (recommendation from design: 2.625rem for the Headline and 1.125rem for the Body).

Typography sizes mixins

The deprecated text[Kilo|Mega|Giga] style mixins were replaced by a single typography mixin, and the deprecated heading[Kilo|Mega|Giga|Tera|Peta|Exa|Zetta] and subHeading[Kilo|Mega] style mixins were removed.

Generally, avoid using typography style mixins. Instead, use typography components directly.

Heading as props

The as prop is now required in both the Headline and the SubHeadline components. Intentionally setting the heading level ensures a consistent and accessible page structure. The as prop values were also restricted to HTML heading elements to ensure that heading components render semantic heading elements.

Component Allowed as prop values
Headline h1, h2, h3, h4, h5, h6
SubHeadline h2, h3, h4, h5, h6

Note that the Headline and SubHeadline will still fall back to h2 and h3, respectively, but omitting the as prop will start throwing errors in the next major version.

Typography design tokens

The typography size values in @sumup/design-tokens were also updated to reflect the changes in @sumup/circuit-ui.

There is no codemod for these changes, migrate manually through search and replace (e.g. typography.text.mega 👉 typography.body.one). Refer to the tables in Typography component names and Typography components size prop for the correct mappings.

Generally, avoid using typography size tokens. Instead, use typography components directly.

New modal and popover APIs

The Modal and Popover components were refactored to consolidate their APIs and to improve their accessibility.

Modal

The Modal, ModalWrapper, ModalHeader, ModalFooter, ModalContext, and ModalConsumer components are no longer exported. Instead, use the useModal hook to render modals instead.

Modals in Circuit v3 are accessible by default, have a streamlined UI and behavior (dimensions, click outside, etc.) and handle edge cases like modal and popover stacking.

Refer to the Modal stories for usage examples.

⚠️ You might notice browser UI obscuring parts of your application on mobile viewports. Your application needs to ensure its content stays within CSS safe areas using CSS env. See Getting started for help with configuring the viewport.

Popover

The Popover component was rebuilt in Circuit v3. It now uses Popper v2 under the hood and comes with a refreshed component API.

More importantly, the Circuit v3 Popover is opinionated when it comes to its usage pattern. It no longer accepts custom children, unlike v2, but rather a list of actions (links and/or buttons).

To migrate, separate the popovers in your application into two types.

Start by migrating any popover resembling a dropdown menu to the new Circuit v3 Popover. Refer to the Popover story for a usage example.

Most of the remaining popovers with custom children should gradually be migrated to use different UI patterns (for example modals). In the meantime, we recommend creating a local copy of the Circuit v3 Popover in your application that accepts custom children instead of an array of actions. You'll find an example in the SumUp merchant dashboard (private repository).

Component heights

The heights of all form components were aligned for consistency. The new size values are:

Size name Value Usage
giga 48px Default for web + mobile
kilo 32px Dense layout for web + mobile
byte 24px Extreme dense layout for web + mobile

Here's an overview of how the component heights have changed:

Component Old default height New default height
Button and derived components 40px 48px
Input and derived components 40px 48px
Select 40px 48px
Tabs 80px 48px
Tag 34px 32px

We recommend verifying these changes visually at the end of the migration.

In addition to its increased height, the Button's default size was renamed from mega to giga to align it with the new size values (see the table above). (🤖 button-default-size)

Other changes

  • The design tokens borderRadius scale was changed. (🤖 theme-border-radius)
    value v2 name v3 name
    1px kilo — (remove the radius or hardcode)
    4px mega bit
    6px giga — (migrate to byte)
    8px tera byte
    12px peta kilo
    16px — mega (new value)
  • The NotificationBanner component has been renamed to NotificationCard. (🤖 component-names-v3)
  • Label prop names across components were harmonized to follow the Label pattern. (🤖 label-prop-names)
    • CardHeader: labelCloseButton 👉 closeButtonLabel
    • Hamburger: labelActive 👉 activeLabel, labelInActive 👉 inactiveLabel
    • Tag: labelRemoveButton 👉 removeButtonLabel
    • Toggle: labelChecked 👉 checkedLabel, labelUnchecked 👉 uncheckedLabel
  • The TableRow, TableHeader and TableCell components are no longer exported. Use the Table component instead.
  • The Table's custom onSortBy method signature has been changed. The nextDirection argument moved to the third position ((index, nextDirection, rows) 👉 (index, rows, nextDirection)) and is now optional (i.e. it can be undefined instead of null in the previous implementation).
  • The SelectorGroup's label is now visible by default, pass hideLabel to hide it visually. Its children are now rendered horizontally by default.
  • Default data-testids are no longer built into the Table and CardHeader components. We recommend querying by role in tests instead to imitate how users interact with our applications.

Cleaning up

Finally, Circuit v3 removes previously deprecated and/or unused features and props. These breaking changes may not affect your application if you've already addressed the deprecation warnings in Circuit v2 minors, but we still recommend going through the list of changes below.

  • The deprecated Spacing component has been removed. Use the spacing style mixin instead.
  • The ProgressBar's deprecated children prop has been removed. Use the label prop instead.
  • The Card's deprecated shadow prop has been removed. Shadows have been replaced by a single outline in an earlier minor version.
  • The deprecated styleHelpers aggregate is no longer exported. Import each style mixin directly instead.
  • The themePropType is no longer exported from @sumup/circuit-ui. Import it from @sumup/design-tokens instead.
  • The deprecated withComponents HOC has been removed. Use the useComponents hook instead.
  • The Badge's deprecated onClick prop has been removed. Badges are not meant to be interactive and should only communicate the status of an element. Use the Tag component for interactive elements instead.
  • The Badge's deprecated primary variant has been removed. Use the neutral variant instead.
  • The experimental static styles extraction feature has been removed.

From v1.x to v2

Library format

Circuit UI is now compiled with TypeScript instead of Babel (#563, #597). ES and CJS versions are available as before, though this is not something you need to worry about since most bundlers pick the best format that they support automatically based on the main and module entries in package.json.

Note, however, that some modern JavaScript syntax and language features are no longer pretranspiled. Tools such as react-scripts v2+ and Next.js include node_modules in their transpilation process so Circuit UI works with them out of the box. If you have a custom build process, you should make sure that Circuit UI is transpiled like the rest of your source code.

We recommend testing your application in your oldest supported browsers to verify that it still works.

Peer dependencies

Circuit UI v1 included React and Emotion dependencies as direct dependencies. This could cause these dependencies to be bundled twice if your application specified a different version of React or Emotion.

Circuit UI v2 moves these dependencies to peer dependencies, so Circuit UI will use whatever version your application specifies (#485). The minimum version of React has been bumped to v16.8+ to support hooks.

If you haven't installed them already, you can do so by running the following command in your terminal:

# With yarn
yarn add react react-dom @emotion/core @emotion/styled emotion-theming
# With npm
npm install --save react-dom @emotion/core @emotion/styled emotion-theming

In Circuit UI v2 some functionality has been extracted into separate packages for easier maintenance. The themes have been moved to @sumup/design-tokens, the icons are available from @sumup/icons, and the number & currency utils have been completely rewritten in @sumup/intl. The new @sumup/collector package is used for event tracking. These packages are marked as required peer dependencies. To install them, run the following command in your terminal:

# With yarn
yarn add @sumup/collector @sumup/design-tokens @sumup/icons @sumup/intl
# With npm
npm install --save @sumup/collector @sumup/design-tokens @sumup/icons @sumup/intl

Refer to the individual packages for documentation on how to use them.

Font loading

Circuit UI now downloads the Aktiv Grotesk font family in the 400 (regular) and 700 (bold) weights. It uses @font-face with the font-display set to swap, which means a fallback font is shown until the custom fonts have loaded.

You should remove any code in your application that was previously used to load these fonts.

Forward custom props and refs

A big theme of this release is consistency.

Any additional props that are passed to a component are now spread on their outermost child element (#553). This is useful for test ids, data attributes, and custom styles using Emotion's styled function or css prop.

React refs allow you to access the underlying DOM node of a component. All Circuit UI components now forward refs to the underlying DOM node (for single node components such as a Button) or to the main interactive DOM node (for composite components such as an Input) (#592).

⚠️ The ability to pass custom styles and refs is meant as an escape hatch. We strongly recommend avoiding using them as we cannot guarantee that they will be compatible with future changes. Please consider opening an issue or PR to suggest the improvement in Circuit UI instead.

Component static properties

Many components expose their configuration values as static properties. The Text component, for example, exposes its size options as Text.KILO, Text.MEGA, and Text.GIGA. The purpose of these static properties was to autocomplete the options and prevent typos.

Since Circuit UI is being migrated to TypeScript, the static properties are no longer necessary. VS Code can suggest and autocomplete the options based on the TypeScript types. TypeScript will warn you at build time if you use an unsupported or mistyped value. Furthermore, removing the static properties reduces the bundle size slightly.

Thus, the static properties have been removed from all components. Here's how you can pass a value to a component now:

import { Text } from '@sumup/circuit-ui';

const Hello = () => (
-  <Text size={Text.KILO}>Hello</Text>
+  <Text size="kilo">Hello</Text>
);

The affected components are: Badge, Blockquote, Button, ButtonGroup, Card, CardFooter, CardList.Item, Heading, InlineMessage, Input, List, MessageIcon, ModalFooter, NotificationIcon, Popover, ProgressBar, SubHeading, TableHeader, TableCell, Text, TextArea, and Tooltip.

(🤖 component-static-properties)

Removed components

  • The SideNav component has been removed. Use the Sidebar component instead.
  • The CreditCardDetails, CardNumberInput, NameOnCardInput, SecurityCodeInput, ExpiryDateInput, and the credit card utils have been removed. Use SumUp's card widget instead.
  • The CardSchemes and PaymentMethodIcon components have been removed. Use @sumup/icons instead.
  • The AutoCompleteInput and AutoCompleteTags components have been removed. You can build them yourself using the SearchInput, Card, and Tag components.
  • The MaskedInput and RestrictedInput components have been removed. Use react-text-mask or a similar package directly instead.
  • The MessageIcon and MessageButton components have been removed. Use the Notification component's icon and children props instead.
  • The Markdown component has been removed. Use markdown-to-jsx or a similar package instead.
  • The State component has been removed. Use React's useState hook instead.
  • The Picture component has been removed. Use the native HTML picture element instead.

Renamed components

  • The ListView component has been renamed to CardList (🤖 component-names-v2)
  • The SvgButton component has been renamed to IconButton (🤖 component-names-v2)
  • The Message component has been renamed to Notification (🤖 component-names-v2)
  • The InlineNotification component has been renamed to InlineMessage (🤖 component-names-v2)
  • The GlobalStyles component has been renamed to BaseStyles (🤖 component-names-v2)

Changed components

  • The GlobalStyles component no longer accepts a custom prop. Use Emotion's Global component instead.
  • The Heading, SubHeading, Text, and Input components no longer accept the element prop. Emotion 10 introduced the ability to change the HTML element. Use the as prop instead (🤖 as-prop)
  • The List component's ordered prop has been replaced by the variant enum prop (🤖 list-variant-enum)
  • The List component's default size is now mega to match the Text component.
  • The Badge component's color prop has been renamed to variant (🤖 badge-variant-enum)
  • The primary and secondary Button boolean props have been removed. Use the variant enum prop instead (🤖 button-variant-enum)
  • The plain Button prop has been removed. Use the new Anchor component or the tertiary Button variant instead.
  • The flat Button variant has been removed (🤖 button-variant-enum)
  • The giga Button size has been removed. Use the mega size (default) instead (🤖 button-size-giga)
  • The LoadingButton's exit animations have been removed. An action's success or error result should be communicated outside the button (🤖 exit-animations)
  • The Input, TextArea, and Select components have the label built in now. Use the label prop to pass in the label content and remove the Label component from your code. The label prop will become required in the next major version of Circuit UI.
  • The Input and Textarea components no longer accept *ClassName props. Emotion 10 uses style objects instead of class names. Use the *Styles props instead. The wrapperStyles prop has been renamed to labelStyles (🤖 input-styles-prop).
  • The Input and Textarea components' deepRef prop has been renamed to ref (🤖 input-deepref-prop)
  • The Input and Textarea components no longer have an optional state. Add "(optional)" to the label text instead.
  • The Selector component's onClick and selected props have been renamed to onChange and checked (🤖 selector-props). The value and name have been added as required props.
  • The RadioButton, Toggle, and Switch component's onToggle prop has been renamed to onChange (🤖 onchange-prop)
  • The Toggle component's on, labelOn, and labelOff props have been renamed to checked, labelChecked, and labelUnchecked (🤖 toggle-checked-prop).
  • The IconButton component's dimensions and style have changed. It is now consistent with the Button component.
  • The Hamburger component's default size has been increased to match the IconButton component.
  • The Hamburger component's light prop has been removed. Set the color through CSS instead.
  • The Spinner component's dark prop has been removed. Set the color through CSS instead.
  • The InlineMessage component's type prop has been renamed to variant (🤖 inline-message-variant-enum)
  • The Pagination component's footer, justify, align, perPage, and pagesToShow props have been removed. The page prop has been renamed to currentPage. The total prop has been replaced by the totalPages prop which represents the total number of pages as opposed to the total number of items (totalPages = Math.ceil(total / perPage)).

Utilities

  • The currencyAmountUtils have been removed. There is no replacement, we suggest you copy the old implementation to your application.
  • The currencyUtils have been removed. Use @sumup/intl instead (🤖 currency-utils)
  • The textTera style helper has been removed. Use the textGiga style helper instead.
  • The shadowGround and shadowBorder style helpers have been removed. Use the box-shadow CSS property instead.
  • The unit style helpers (addUnit, subtractUnit, multiplyUnit, divideUnit ) have been removed. Use the CSS calc function instead.

Theme changes

  • The themes have been moved to @sumup/design-tokens. Import them from there instead (🤖 theme-to-design-tokens)
  • The iconSizes.byte theme value has been removed. Use iconSizes.kilo instead (🤖 theme-icon-sizes)
  • The grid.afterTera theme value has been renamed to grid.tera (🤖 theme-grid-tera)