Migrating to v3

This guide will show you how to upgrade your codebase.

1Package upgrade

1yarn upgrade @defencedigital/react-component-library

And:

1yarn upgrade @defencedigital/design-tokens
2yarn upgrade @defencedigital/eslint-config-react
3yarn upgrade @defencedigital/fonts
4yarn upgrade @defencedigital/icon-library

2Breaking changes

Components

Autocomplete

Use Autocomplete instead of Select for behaviour when the user could type and select an item

Avatar

Replace initials by using children

Button

Remove use of color
Use COMPONENT_SIZE for size
Use BUTTON_VARIANT.DANGER for variant instead of color={BUTTON_COLOR.DANGER}

Checkbox

Use checked instead of isChecked
Remove use of isValid

CheckboxEnhanced

Use Checkbox instead of CheckboxEnhanced

ContextMenu

Remove position as component is positioned based on available screen real estate
Update onHide callback parameters
Update onShow callback parameters

DataList

Use the replacement DescriptionList

DatePicker

Use Placement from @popperjs for placement
Use initialIsOpen instead of isOpen
Use startDate and endDate instead of value
If startDate and endDate are used, these should now be set from the current form state instead of the initial form values. Alternatively, you can use initialStartDate and initialEndDate to only set the initial values
onChange is now called when an invalid or disabled date is typed. You should ensure these are correctly handled in your form validation logic
The calendar no longer automatically opens when the input is focused. This may affect automated tests
Check presentation as external margins have been removed
Remove use of isValid

DescriptionList

Use instead of DataList
Use description instead of title on DescriptionList
Use title instead of description on DescriptionListItem
Check presentation as external margins have been removed

DismissibleBanner

Rename to DismissibleBanner from DismissableBanner

Masthead

Update onSearch callback parameters

NumberInput

Remove use of canClear
Use size={COMPONENT_SIZE.SMALL} instead of isCondensed
Update onChange callback parameters
Use icon or prefix instead of startAdornment
Use suffix instead of unit
Use prefix or suffix instead of unitPosition
Check presentation as external margins have been removed
Remove use of isValid

Pagination

Update onChange callback parameters

Radio

Use defaultChecked instead of isChecked
Remove use of isValid

RadioEnhanced

Use Radio instead of RadioEnhanced

RangeSlider

Some of the behaviours associated with this component have fundamentally changed. Refer to the design specification.

Select

Replace instances with Autocomplete where autocomplete/typeahead behaviour is required
Remove use of isClearable as the clear button is always presented when an item is selected
Specify children using SelectOption rather than an array of value and label options
Update onChange callback parameters to use value: string | null rather than event: any
Remove use of isValid

Sidebar

There is the ability to use the Sidebar within a layout by using SidebarWrapper
As the component is more composable nav is no longer a prop.

Refer to Storybook for code examples.

Switch

Specify children using SwitchOption rather than an array of value and label options
Use COMPONENT_SIZE for size
Remove use of isValid

TabSet

Use TabSetItem instead of Tab
Update parameters for use of onChange callback
A ResizeObserver polyfill is required in older browsers and in Jest. The CRA template has been updated to reflect this

TextArea

Remove use of footnote in favour of using the component in conjunction with Field and hintText.
Remove use of isValid

TextInput

Add a label
Remove use of placeholder
Check presentation as external margins have been removed
Remove use of footnote in favour of using the component in conjunction with Field and hintText.
Remove use of isValid

Timeline

Replace render callback with prop bag in TimelineDay, TimelineDays, TimelineEvent, TimelineHour, TimelineHours, TimelineMonth, TimelineMonths, TimelineRow, TimelineRows, TimelineTodayMarker, TimelineWeek, TimelineWeeks
Use the hasSide prop instead of TimelineSide
Rename use of renderColumns to render on TimelineRows
Remove use of dayWidth and daysTotal in render callback of TimelineWeeks
Remove use of isAfterEnd and isBeforeStart in useTimelinePosition in favour of startsAfterEnd and startsAfterStart

Strict null checks

strictNullChecks has been enabled. Interfaces are now more accurate about whether props accept null or undefined. There are no changes required by consumers.

Root font size

Root font-size breakpoints have been removed so any workarounds to fix this can be safely removed.
To fix a problem with the inconsistent position of bold font compared to other weights, fonts are no longer being loaded from Google CDN. It is worth checking text presentation, in particular where different weights are being used.

Forms

Use Field, Fieldset and SectionDivider to replace withFormik and FormikGroup.

Icons (legacy icons are gone)

Replace dependency on legacy icons with @defencedigital/icon-library equivalent

Legacy icons that have been removed:

Bell
Graph
House
Logo
RightArrow
Search
Tools
Visibility
VisibilityOff

Design Tokens

Use ColorGroup instead of ColourGroup

Eslint config

eslint-config-airbnb has been upgraded. The new version includes official compatibility with ESLint 8, drops support for ESLint 6 and older and adds a few new rules.

List of rule changes:

react/function-component-definition has been turned off.

CSS Framework

There is not a 3.x.x of @defencedigital/css-framework and it is strongly recommended to remove any dependencies on this legacy framework. If a dependency is still required then use 2.x.x of @defencedigital/css-framework.

The root of your application should now be wrapped with a single instance of the provided GlobalStyleProvider context provider. (GlobalStyleProvider applies various global styles, and as such, only one instance of it should be mounted at once.)