Clarify our JavaScript components' public API

[romaricpascal]

What

We're drawing a clear line between the properties and methods of our JavaScript components that are meant to be publicly accessed and those that are only for internal use.

Why

Currently, there's no clear distinction about what's for internal us and what's meant to be used by service code. This makes a very wide area for breaking changes, that we don't intentionally control, slowing down our capacity to make changes in places that should be private but are exposed. Also, while accessible to service code, some of these properties and methods are also not designed for outside use in their API.

With the opportunity for breaking changes in v5, this is a chance to clearly separate public and private APIs. This provides to services clarity on what our components are designed to offer, and to us safety when deciding what we can change without it being a breaking change.

Who needs to work on this

Developers, Tech writers

Who needs to review this

Developers, Tech writers

Done when

v4

Preview Give feedback

1. Deprecate properties that will no longer be part of the public API #3473
   3 of 3
   documentation javascript +2
   

v5

Preview Give feedback

1. Define a public API for our components in v5 #3479
   +0
2. Remove init() method from our JavaScript components #4008
   javascript +1
   
3. Throw errors if GOV.UK Frontend is not supported #4009
   javascript +1
   
4. Throw an error if JavaScript components receive the wrong type of $module #4035
   javascript +1
   
5. Throw errors during Skip Link initialisation if key HTML elements are missing #4128
   javascript skip link +2
   
6. Throw errors during Exit This Page initialisation if key HTML elements are missing #4129
   exit this page javascript +2
   
7. Throw errors during Header initialisation if key HTML elements are missing #4130
   header javascript +2
   
8. Throw errors during Radios and Checkboxes initialisation if key HTML elements are missing #4131
   checkboxes javascript radios +3
   
9. Throw errors during Character Count initialisation if key HTML elements are missing #4125
   character count javascript +2
   
10. Throw errors during Accordion initialisation if key HTML elements are missing #4126
    accordion javascript +2
    
11. Throw errors during Tabs initialisation if key HTML elements are missing #4127
    javascript tabs +2
    
12. Update I18n errors to extend GOVUKFrontendError #4144
    +0
13. Review ElementErrors and tie up any loose ends #4036
    javascript +1
14. Throw errors if JavaScript components receive an illegal configuration #4037
    javascript +1
    
15. Define scope of public API for errors #4074
    javascript +1
16. Add CHANGELOG entry describing that components throw errors #4073
    javascript +1
    
17. Prevent initAll from failing when one of the components' instantiation errors #4010
    javascript +1
18. Decide if 'internal' JavaScript files should be exported from the package #3904
    javascript +1
19. Mark internal classes and functions as @internal #4017
    javascript +1
20. Review content of thrown errors #4072
    javascript +1
    
21. Update mangling of our classes names for our minified files #4076
    javascript +1
    
22. Restore ability for tests to fail when component initialisation throws #4103
    javascript +1
23. Replace MissingElementError with ElementError #4209
    javascript skip link +2
24. Error message review: Use plain English and a selector/variable name in backticks as an identifier #4299
    documentation javascript +2
    
25. Refactor ElementError class #4300
    javascript +1
    

Post v5

Preview Give feedback

1. Decide on naming convention for base classes #4071
   javascript +1

[36degrees]

All the tasks in the list are done, so I'm gonna say we can close this! 🎉