Add configuration helpers to the public JavaScript API

[romaricpascal]

Brief

Design and document a public API to enable components outside of GOV.UK Frontend to receive a configuration in the same fashion the components from GOV.UK Frontend do.

This will allow further code sharing between code from GOV.UK Frontend and that of services or other Design Systems, leading less duplication in the compiled bundles sent to users, as well as avoiding to recreate a solution to the problem for services and other Design Systems.

This will also open the door to offering helpers for internationalising components, which we could start looking at as a stretch goal towards the end of the epic if time allows.

Relevant links

• Configure components on the GOV.UK Frontend docs
• mergeConfigs helper that helps merging configuration from different sources (defaults, HTML Element attributes, JavaScript object)
• A spike from Ollie proposing a way to implement the configuration as a class (note that there's been some changes to how the merging of configuration works since).

Epic lead

@romaricpascal

Driving role(s)

@seaemsi , @patrickpatrickpatrick, @Izabela-16

Further detail

Publish new API

• Refactor the check for the type of the root element in GOVUKFrontendComponent #5326
• Refactor existing components to use the new Component class govuk-design-system#4156
• Add new 'Building your own components' page govuk-frontend-docs#467
• Merge public-js-api to main
• Check no further refactoring of $module to $root are necessary (Rename $module to $root across the project #5322)
• Release
• Close Investigate components being initialised more than once #1127
• Fix typos in the new 'Building your own components' page govuk-frontend-docs#472
• Update workaround for TypeScript

Dev

• Spike into Config class if defined by child class of GOVUKFrontendComponent #5427
• Spike into Config class if defined by GOVUKFrontendComponent #5426
• Spike into Config class if defined by GOVUKFrontendComponentConfigurable #5430
• Refactor Accordion to extend from a GOVUKFrontendConfigurableComponent class #5456
• Refactor Button to extend from a GOVUKFrontendConfigurableComponent class #5457
• Refactor CharacterCount to extend from a GOVUKFrontendConfigurableComponent class #5458
• Refactor ErrorSummary to extend from a GOVUKFrontendConfigurableComponent class #5459
• Refactor ExitThisPage to extend from a GOVUKFrontendConfigurableComponent class #5460
• Refactor NotificationBanner to extend from a GOVUKFrontendConfigurableComponent class #5461
• Refactor PasswordInput to extend from a GOVUKFrontendConfigurableComponent class #5462
• Export GOVUKFrontendConfigurableComponent as part of the public API #5463
• Use ConfigurableComponent in the Design System's Cookie Banner govuk-design-system#4275
• Remove GOVUKFrontend prefix from GOVUKFrontendComponent class #5497
• [Stretch] Review the overlap of the different types representing a component class in our code #5469
• [Stretch] Investigate if we can use config instead of defaults in createAll to get the configuration type #5465
• [Stretch] Create a ConfigurableComponent class to further encapsulate receiving a configuration #5466
• [Stretch] Export ConfigurableComponent as part of the public API #5468
• [Stretch] Use the ConfigurableComponent in the Design System's Cookie Banner govuk-design-system#4276

Documentation

• Draft documentation for the configuration features of the public JavaScript API govuk-frontend-docs#482
• Iterate documentation draft until it's ready for review govuk-frontend-docs#483
• Make drafted documentation for 'Building configurable components' go through review process #5502
• Update internal docs on configuration options #5501
• Add 'Building configurable components' section to the Frontend Docs govuk-frontend-docs#486
• Merge the content to the main branch of the Frontend docs

Community

• Talk about the Public JS API at the next dev catch-up #5472
• Plan presentations to various communities (frontend community, monthly chat...) #5506

[romaricpascal]

A couple of thoughts:

• Not all components accept a configuration, so we need the feature to be composable rather than baked into the Component class that all components will inherit, and especially able to be tree-shaken if not used. If some steps in the feature are optional, it'd be neat if they can be tree-shaken when not used, as well. However, there'll be a balance to strike between something monolithic that encapsulates all steps, ensuring they run in the right order, and something more fragmented leaving it to the user to run each step but where unnecessary steps can be left out of the bundled code.
• Some of our components do validations on the configuration they receive. We'll need to check how costly it would be to offer this as part of the public API as it could quickly spin into lots of Kbs that services can already use a 3rd party package to handle themselves (we have to implement ours to remain dependency free for now)
• Most components do a straightforward merge of configuration options from their defaults, HTML dataset and constructor argument. The Character Count needs to do some overriding which we'll need to account for.
  • I think that's the only component with such shenanigans in GOV.UK Frontend, but it's worth a double check
  • Components outside GOV.UK Frontend may need a similar thing where the presence of one or multiple options in the constructor argument may mean some option(s) from the defaults or HTML dataset need clearing up.
• as always, we'll be the first consumer of our feature, so it's good to look at the components in the Design System and see if any can be configured one way or another (the Cookie banner looks like it could)

[romaricpascal]

Closing this as the final non-stretch issue has a PR almost ready to go (only missing a changelog entry) and the stretch issue can be tackled anytime.