Skip to content

Commit 7ebfc58

Browse files
colinrotherhamcolinrotherham
committed
Document breaking changes
1 parent e829982 commit 7ebfc58

File tree

1 file changed

+277
-0
lines changed

1 file changed

+277
-0
lines changed

‎docs/upgrade-to-6.0.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
# Upgrading to 6.0
2+
3+
There are some breaking changes you'll need to be aware of when upgrading to v6.
4+
5+
[NHS.UK frontend v10.0.0](https://github.com/nhsuk/nhsuk-frontend/releases/tag/v10.0.0) introduces some breaking changes to file paths, full width buttons on mobile, the header component and others. It also stops Internet Explorer 11 and other older browsers from running NHS.UK frontend JavaScript.
6+
7+
You must read and apply these updates carefully to make sure your service does not break.
8+
9+
## Breaking changes
10+
11+
### Update the JavaScript supported script snippet
12+
13+
You must now use the NHS.UK frontend v10.x feature detection snippet to check for `<script type="module">`. This change enables styling for JavaScript only features in [supported browsers]() only:
14+
15+
```patch
16+
- <body class="js-enabled">
17+
+ <body>
18+
+ <script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' nhsuk-frontend-supported' : '');</script>
19+
```
20+
21+
### Restore visually hidden text for accessibility
22+
23+
For accessibility reasons, it's no longer possible to pass `visuallyHiddenText: false` or override other hidden text for the following:
24+
25+
- [**Breadcrumbs** back link prefix](https://service-manual.nhs.uk/design-system/components/breadcrumbs)
26+
- [**Care card** urgency level](https://service-manual.nhs.uk/design-system/patterns/help-users-decide-when-and-where-to-get-care)
27+
- [**Contents list** links heading](https://service-manual.nhs.uk/design-system/components/contents-list)
28+
- [**Inset text** prefix](https://service-manual.nhs.uk/design-system/components/inset-text)
29+
- [**Warning callout** prefix](https://service-manual.nhs.uk/design-system/components/warning-callout)
30+
31+
Read about other [changes to meet WCAG 2.2](https://service-manual.nhs.uk/design-system/changes-to-design-system-wcag-2-2) on the design system in the NHS digital service manual.
32+
33+
### Check components that conditionally reveal content still work
34+
35+
Previously, conditionally revealing content ([radios](https://service-manual.nhs.uk/design-system/components/radios#conditionally-revealing-content), [checkboxes](https://service-manual.nhs.uk/design-system/components/checkboxes#conditionally-revealing-content)) would not be rendered until their related input was checked.
36+
37+
To align with NHS.UK frontend, conditionally revealing content is now always rendered but remains hidden until revealed. Accessibility issues with missing `aria-controls`, `aria-describedby` or `aria-expanded` are now fixed.
38+
39+
You must check all form components, form validation and error handling that may not expect hidden conditionally revealing content in the HTML.
40+
41+
### Remove unsupported icons
42+
43+
To align with NHS.UK frontend, icons unused by components have been removed:
44+
45+
- `ChevronLeftIcon`
46+
- `ChevronRightIcon`
47+
- `ChevronDownIcon`
48+
- `CloseIcon`
49+
- `EmdashIcon` and `SmallEmdashIcon`
50+
- `MinusIcon`
51+
- `PlusIcon`
52+
53+
### Back link
54+
55+
To align with NHS.UK frontend, we've added an underline to the [back link component](https://service-manual.nhs.uk/design-system/components/back-link). We've also changed the default text from "Go back" to "Back" in all examples.
56+
57+
### Button
58+
59+
To align with NHS.UK frontend, we've updated the [button component](https://service-manual.nhs.uk/design-system/components/buttons) to remove any references to the `nhsuk-button--disabled` class.
60+
61+
Use the [`disabled` HTML boolean attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/disabled) to mark `<button>` elements as being disabled instead.
62+
63+
You must also make the following changes:
64+
65+
- replace `<DefaultButton>` with `<Button>` to render HTML `<button>` elements
66+
- replace `<LinkButton>` with `<Button href="/example">` to render HTML `<a>` elements
67+
- remove the `debounceTimeout` prop when preventing double clicks
68+
69+
### Character count
70+
71+
To align with NHS.UK frontend, we have removed `enum CharacterCountType` and you must make the following changes:
72+
73+
- use the `maxLength` prop for maximum characters only
74+
- use the `maxWords` prop for maximum words only
75+
- rename the `thresholdPercent` prop to `threshold`
76+
- remove the `countType` prop
77+
78+
To count maximum characters:
79+
80+
```patch
81+
- <CharacterCountComponent maxLength={350} countType={CharacterCountType.Characters} textAreaId="example">
82+
+ <CharacterCountComponent maxLength={350} textAreaId="example">
83+
```
84+
85+
To count maximum words:
86+
87+
```patch
88+
- <CharacterCountComponent maxLength={20} countType={CharacterCountType.Words} textAreaId="example">
89+
+ <CharacterCountComponent maxWords={20} textAreaId="example">
90+
```
91+
92+
### Contents list
93+
94+
To align with NHS.UK frontend, the contents list component automatically adds ARIA attributes for the current item. You must make the following changes:
95+
96+
- remove the `ContentsList` component `aria-label` attribute
97+
- remove the `ContentsList.Item` component `aria-current` attribute
98+
99+
```patch
100+
- <ContentsList aria-label="Pages in this guide">
101+
+ <ContentsList>
102+
- <ContentsList.Item current aria-current="page">Example page 1</ContentsList.Item>
103+
- <ContentsList.Item current>Example page 1</ContentsList.Item>
104+
<ContentsList.Item>Example page 2</ContentsList.Item>
105+
<ContentsList.Item>Example page 3</ContentsList.Item>
106+
</ContentsList>
107+
```
108+
109+
### Date input
110+
111+
To align with NHS.UK frontend, the date input component automatically renders its own fieldset, legend and associated ARIA attributes. The custom `autoSelectNext` prop is no longer supported:
112+
113+
```patch
114+
<DateInput
115+
- label="What is your date of birth?"
116+
+ legend="What is your date of birth?"
117+
hint="For example, 15 3 1984"
118+
- autoSelectNext={true}
119+
value={value}
120+
/>
121+
```
122+
123+
The custom `autoSelectNext` prop is no longer supported.
124+
125+
### New header component with account section
126+
127+
The updated header component from NHS.UK frontend v10.x has been added. You will need to make the following changes:
128+
129+
- remove the wrapping `Header.Container` component
130+
- remove the wrapping `Header.Content` component
131+
- remove the automatically created `HeaderComponent.ServiceName` component
132+
- remove the automatically created `Header.NavDropdownMenu` component
133+
- rename the `Header.Nav` component to `Header.Navigation`
134+
- rename the `Header.NavItem` component to `Header.NavigationItem`
135+
136+
```patch
137+
<Header>
138+
- <Header.Container>
139+
- <Header.Logo href="/" />
140+
- <Header.Content>
141+
- <Header.Search />
142+
- </Header.Content>
143+
- </Header.Container>
144+
+ <Header.Logo href="/" />
145+
+ <Header.Search />
146+
- <Header.Nav>
147+
- <Header.NavItem href="#">Example 1</Header.NavItem>
148+
- <Header.NavItem href="#">Example 2</Header.NavItem>
149+
- <Header.NavItem href="#">Example 3</Header.NavItem>
150+
- <Header.NavItem href="#">Example 4</Header.NavItem>
151+
- <Header.NavDropdownMenu />
152+
- </Header.Nav>
153+
+ <Header.Navigation>
154+
+ <Header.NavigationItem href="#">Example 1</Header.NavigationItem>
155+
+ <Header.NavigationItem href="#">Example 2</Header.NavigationItem>
156+
+ <Header.NavigationItem href="#">Example 3</Header.NavigationItem>
157+
+ <Header.NavigationItem href="#">Example 4</Header.NavigationItem>
158+
+ </Header.Navigation>
159+
</Header>
160+
```
161+
162+
### Footer
163+
164+
The updated footer component from NHS.UK frontend v10.x has been added. You will need to make the following changes:
165+
166+
- replace `<Footer.List className="nhsuk-footer__meta">` with `<Header.Meta>`
167+
- nest the `Footer.Copyright` component into `Header.Meta` component
168+
169+
```patch
170+
<Footer>
171+
<Footer.List>
172+
<Footer.ListItem href="#">Item 1</Footer.ListItem>
173+
<Footer.ListItem href="#">Item 2</Footer.ListItem>
174+
<Footer.ListItem href="#">Item 3</Footer.ListItem>
175+
</Footer.List>
176+
177+
- <Footer.List className="nhsuk-footer__meta">
178+
+ <Footer.Meta>
179+
<Footer.ListItem href="#">Meta 1</Footer.ListItem>
180+
<Footer.ListItem href="#">Meta 2</Footer.ListItem>
181+
<Footer.ListItem href="#">Meta 3</Footer.ListItem>
182+
+
183+
+ <Footer.Copyright />
184+
- </Footer.List>
185+
+ </Footer.Meta>
186+
- <Footer.Copyright />
187+
</Footer>
188+
```
189+
190+
### Radios
191+
192+
To align with NHS.UK frontend, the radios component automatically renders its own fieldset, legend and associated ARIA attributes. You must also rename the `Radios.Radio` component to `Radios.Item` as shown:
193+
194+
```patch
195+
- <Fieldset>
196+
- <Fieldset.Legend>Have you changed your name?</Fieldset.Legend>
197+
- <Radios>
198+
+ <Radios legend="Have you changed your name?">
199+
- <Radios.Radio value="yes">Yes</Radios.Radio>
200+
- <Radios.Radio value="no">No</Radios.Radio>
201+
+ <Radios.Item value="yes">Yes</Radios.Item>
202+
+ <Radios.Item value="no">No</Radios.Item>
203+
</Radios>
204+
- </Fieldset>
205+
```
206+
207+
### Checkboxes
208+
209+
To align with NHS.UK frontend, the checkboxes component automatically renders its own fieldset, legend and associated ARIA attributes. You must also rename the `Checkboxes.Box` component to `Checkboxes.Item` as shown:
210+
211+
```patch
212+
- <Fieldset>
213+
- <Fieldset.Legend>What is your nationality?</Fieldset.Legend>
214+
- <Checkboxes>
215+
+ <Checkboxes legend="What is your nationality?">
216+
- <Checkboxes.Box value="british">British</Checkboxes.Box>
217+
- <Checkboxes.Box value="irish">Irish</Checkboxes.Box>
218+
- <Checkboxes.Box value="other">Citizen of another country</Checkboxes.Box>
219+
+ <Checkboxes.Item value="british">British</Checkboxes.Item>
220+
+ <Checkboxes.Item value="irish">Irish</Checkboxes.Item>
221+
+ <Checkboxes.Item value="other">Citizen of another country</Checkboxes.Item>
222+
</Checkboxes>
223+
- </Fieldset>
224+
```
225+
226+
### Error summary
227+
228+
To align with NHS.UK frontend, the error summary component is automatically alerted to screen readers by focusing itself on render. You will need to make the following changes:
229+
230+
- remove the nested `ErrorSummary.Body` component wrapper
231+
- rename the `ErrorSummary.Item` component to `ErrorSummary.ListItem`
232+
233+
```patch
234+
- </Fieldset>
235+
<ErrorSummary>
236+
<ErrorSummary.Title>There is a problem</ErrorSummary.Title>
237+
- <ErrorSummary.Body>
238+
<ErrorSummary.List>
239+
- <ErrorSummary.Item href="#example-error-1">
240+
+ <ErrorSummary.ListItem href="#example-error-1">
241+
Date of birth must be in the past
242+
- </ErrorSummary.Item>
243+
+ </ErrorSummary.ListItem>
244+
</ErrorSummary.List>
245+
- </ErrorSummary.Body>
246+
</ErrorSummary>
247+
```
248+
249+
### Skip link
250+
251+
To align with NHS.UK frontend, the skip link component focuses the main content rather than the first heading on the page:
252+
253+
```html
254+
<main class="nhsuk-main-wrapper id="maincontent">
255+
<!-- // ... -->
256+
```
257+
258+
For accessibility reasons, you must make the following changes:
259+
260+
- remove the `disableDefaultBehaviour` prop
261+
- remove the `disableHeadingFocus` prop
262+
- remove custom `onClick` handlers
263+
264+
### Warning callout
265+
266+
To align with NHS.UK frontend, the warning callout `WarningCallout.Label` component has been renamed to `WarningCallout.Heading` as shown:
267+
268+
```patch
269+
<WarningCallout>
270+
- <WarningCallout.Label>School, nursery or work</WarningCallout.Label>
271+
+ <WarningCallout.Heading>School, nursery or work</WarningCallout.Heading>
272+
<p>
273+
Stay away from school, nursery or work until all the spots have crusted over. This is
274+
usually 5 days after the spots first appeared.
275+
</p>
276+
</WarningCallout>
277+
```

0 commit comments

Comments
 (0)