Stepper component for use on the additional image details form

[MatMoore]

Description

This brings in a version of the stepper component as app-stepper-input, and wires it up to the customised IntegerField in the nhsforms app.

Example usage:

            stepper_field = IntegerField(
                label="Stepper",
                initial=1,
                min_value=0,
                max_value=10,
                widget=StepperInput,  # this is new
            )

At the time of writing, the additional image details form is not merged yet, but I can update that to use this component when it is.

Note: I've added a little debug page at /debug/components in order to preview components like this that are not coming from the design system. This is not enabled in the review environments as I don't intend to be visible except for developers running in DEBUG mode. If you prefer, I can remove this page, but I found useful for manual testing.

Jira link

https://nhsd-jira.digital.nhs.uk/browse/DTOSS-12115

Review notes

• I've based the javascript, html and scss on @colinrotherham's proposal from [WIP] Add stepper input component nhsuk/nhsuk-frontend#1719
• I've kept the aria attributes, and hiding the buttons when javascript is not available
• I've removed some of the extra params we won't be using straight away, to simplify things
• I tweaked one of the polyfills slightly to match the behaviour I saw in chrome, and tested it again on safari for iOS

Post merge tasks

• contribute unit tests back to @colinrotherham's PR against nhsuk-frontend
• raise a separate PR for propagating label.id from input to label in nhsuk-frontend

Review checklist

• Check database queries are correctly scoped to current_provider

[github-actions]

The review app at this URL has been deleted:
https://pr-955.manage-breast-screening.non-live.screening.nhs.uk

[MatMoore]

this is the polyfill I changed. If the input is blank and min is 0, step up sets it to 1, not 0.

[MatMoore]

it's awkward having to specify all this HTML here... for the nhsuk-frontend version, we can just render the nunjucks macro. I considered bringing in nunjucks as a dependency and rendering the jinja component as if it was nunjucks, but I thought this would complicate things too much.

[colinrotherham]

There's a PR open here to make the components.render() JavaScript API we use (internally) on NHS.UK frontend available for use via the npm package:

• [v10] Expose NHS.UK frontend Node.js render API nhsuk/nhsuk-frontend#1702

I've not had another JavaScript developer available to review it

But would be useful here!

[MatMoore]

Note: these two tests are technically testing jsdom, as this behaviour is normally provided by a browser, but I thought it was worth including as it helps to document the intended behaviour.

[MatMoore]

This scss is all unchanged from the nhsuk-frontend PR, excpept I've renamed the class prefixes to app-

[MatMoore]

This might become obsolete soon if the icons are accepted into the design system, but I copied the macro structure as I thought it would be handy to have. If we need another custom SVG at any point we can just add it here.

[MatMoore]

I figured out I could render the underlying component like this to simplify the test. This means the test is not sensitive to the implementation of the jinja component, only that we pass through the right params from the field to the component.

We should do this for the other fields too but I didn't want to overload this PR.

[colinrotherham]

We wouldn't typically use type="number" except with the stepper input where we've taken steps to control the unexpected mousewheel behaviour (see guidance).

Perhaps this highlights the need for a plain (non-stepper) number input?

Otherwise the default should be type="text" with inputmode="numeric" here

---

Related guidance from the GOV.UK Design System:

Avoid using inputs with a type of number

Do not use <input type="number"> unless your user research shows that there’s a need for it. With <input type="number"> there’s a risk of users accidentally incrementing a number when they’re trying to do something else - for example, scroll up or down the page. And if the user tries to enter something that’s not a number, there’s no explicit feedback about what they’re doing wrong.

[MatMoore]

I think the simplest thing then is to change the default case of IntegerField to output a text field. We are using this in a few forms already for entering years.

This behaviour comes from the NumberInput widget which is the django default for IntegerField, but we can override it to use text instead.

[colinrotherham]

If you can add a <form> element we tend to follow this pattern in the JSDOM tests:

    $root = /** @type {HTMLElement} */ (
      document.querySelector(`[data-module="${StepperInput.moduleName}"]`)
    )

Then the $root can be used to locate the $input via accessible name:

Suggested change

	input = getByLabelText(document.body, 'Number of giraffes')
	$input = getByRole($root, 'textbox', {
	name: 'Number of giraffes'
	})

It's a holdover from jQuery, but prefer input → $input

[MatMoore]

the role was spinbutton rather than textbox but have made the change now

[colinrotherham]

Hmm that means it was type="number" already

For when we contribute these tests into NHS.UK frontend, we'll want to start with the basic server-side rendered HTML using type="text" and let the component JavaScript do the enhancement for us

[colinrotherham]

Don't think we have any awaits inside

Suggested change

	beforeEach(async () => {
	beforeEach(() => {

[colinrotherham]

Just to align with the JSDOM tests in NHS.UK frontend

1. Move user outside the describe block
2. Use the $ prefix for DOM elements
3. Add type comments

You'll see how to locate $root using moduleName in this comment

Suggested change

	describe('stepper-input', () => {
	const user = userEvent.setup()
	let stepUpButton
	let stepDownButton
	let input
	const user = userEvent.setup()
	describe('Stepper input', () => {
	/** @type {HTMLElement} */
	let $root
	/** @type {HTMLInputElement} */
	let $input
	/** @type {HTMLElement} */
	let $stepUpButton
	/** @type {HTMLElement} */
	let $stepDownButton

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud