Skip to content

Latest commit

 

History

History
169 lines (122 loc) · 13.7 KB

MIGRATION.md

File metadata and controls

169 lines (122 loc) · 13.7 KB

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.

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.

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 not 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)