Decide and document our JavaScript conventions for components

[hannalaakso]

What

Decide and document our JavaScript conventions for GOV.UK Frontend components. At the moment, our JavaScript has some undocumented conventions (e.g: init methods) which we should document. We should also think about conventions that we don't have in place yet, for example:

• public vs private methods
• conventions for triggering and/or listening to events
• managing state

We need to keep in mind that these conventions should work for future components we build, especially more complex ones like modals. Modals have more unique functionality, e.g: how do you initialise/manage more than one per page; how do users hook into the open/close?

Why

In our component JavaScript at the moment, we don't have a concept of private vs public methods. Doing this will:

• make it possible for users to control some behaviour of components from their application (e.g: Character count message does not update when textarea is updated programmatically #1677)
• make it easier for users to understand which JS methods/variables it is recommended they access in their application script.
• make it easier for us to understand which changes to our JavaScript will affect users and which changes should be considered breaking ones

Having any 'accidental'/unintentional conventions documented will mean we're more likely to follow them in future when building new components or making changes to existing component JavaScript.

Related issues

• Character count message does not update when textarea is updated programmatically #1677
• Programmatically 'unchecking' a checkbox does not hide conditional content #1530

Who needs to know about this

Developers; Tech Writer

Done when

• Research JavaScript APIs in other projects #1719
• Investigate applying JavaScript conventions within GOV.UK Frontend #1720
• Decide if we need to write this up as a proposal and share with the community first
• Document our JavaScript component conventions #1721
• Audit our component JavaScript and ensure it meets our new JavaScript conventions #2560

[36degrees]

Closing, although we should make sure we're including this as part of our 'done when' criteria other JavaScript related work