Merge pull request #3499 from alphagov/deprecate-js-methods

Deprecate all JavaScript instance properties the except `init` method

CHANGELOG.md

@@ -64,6 +64,14 @@ This was added in [pull request #2230: Add extra letter spacing modifier for inp
 
 ### Deprecated features
 
+#### Stop using JavaScript API properties other than the `init` method
+
+We have deprecated all of the JavaScript properties in the API, except for the `init` method for each component. We will make all of the deprecated JavaScript properties private in v5.0.
+
+Please [let us know if you're using parts of the API other than the `init` method by filling in this form](https://docs.google.com/forms/d/e/1FAIpQLSfmH2AitMeouXqB0FWC5p5e6y1TSiFCjmJ8DrVuwfmpRGCaWw/viewform?usp=sf_link). We'll use this information when prioritising future additions to the public API.
+
+This was added in [pull request #3499: Deprecate all JavaScript instance properties the except `init` method](/~https://github.com/alphagov/govuk-frontend/pull/3499).
+
 #### Stop using the `govuk-button--disabled` class on buttons
 
 The `govuk-button--disabled` class is deprecated and will be removed in the next major release.

src/govuk/common/closest-attribute-value.mjs

@@ -3,6 +3,7 @@ import '../vendor/polyfills/Element/prototype/closest.mjs'
 /**
  * Returns the value of the given attribute closest to the given element (including itself)
  *
+ * @deprecated Will be made private in v5.0
  * @param {Element} $element - The element to start walking the DOM tree up
  * @param {string} attributeName - The name of the attribute
  * @returns {string | null} Attribute value

src/govuk/common/index.mjs

@@ -13,6 +13,7 @@
  * This seems to fail in IE8, requires more investigation.
  * See: /~https://github.com/imagitama/nodelist-foreach-polyfill
  *
+ * @deprecated Will be made private in v5.0
  * @template {Node} ElementType
  * @param {NodeListOf<ElementType>} nodes - NodeList from querySelectorAll()
  * @param {nodeListIterator<ElementType>} callback - Callback function to run for each node
@@ -32,6 +33,7 @@ export function nodeListForEach (nodes, callback) {
  * without them conflicting with each other.
  * https://stackoverflow.com/a/8809472
  *
+ * @deprecated Will be made private in v5.0
  * @returns {string} Unique ID
  */
 export function generateUniqueID () {
@@ -53,6 +55,7 @@ export function generateUniqueID () {
  * (e.g. {'i18n.showSection': 'Show section'}) and combines them together, with
  * greatest priority on the LAST item passed in.
  *
+ * @deprecated Will be made private in v5.0
  * @returns {Object<string, unknown>} A flattened object of key-value pairs.
  */
 export function mergeConfigs (/* configObject1, configObject2, ...configObjects */) {
@@ -126,6 +129,7 @@ export function mergeConfigs (/* configObject1, configObject2, ...configObjects
  * Extracts keys starting with a particular namespace from a flattened config
  * object, removing the namespace in the process.
  *
+ * @deprecated Will be made private in v5.0
  * @param {Object<string, unknown>} configObject - The object to extract key-value pairs from.
  * @param {string} namespace - The namespace to filter keys with.
  * @returns {Object<string, unknown>} Flattened object with dot-separated key namespace removed

src/govuk/common/normalise-dataset.mjs

@@ -14,6 +14,7 @@ import '../vendor/polyfills/String/prototype/trim.mjs'
  * Designed to be used to convert config passed via data attributes (which are
  * always strings) into something sensible.
  *
+ * @deprecated Will be made private in v5.0
  * @param {string} value - The value to normalise
  * @returns {string | boolean | number | undefined} Normalised data
  */
@@ -46,6 +47,7 @@ export function normaliseString (value) {
  *
  * Loop over an object and normalise each value using normaliseData function
  *
+ * @deprecated Will be made private in v5.0
  * @param {DOMStringMap} dataset - HTML element dataset
  * @returns {Object<string, unknown>} Normalised dataset
  */

src/govuk/components/accordion/accordion.mjs

@@ -46,51 +46,93 @@ function Accordion ($module, config) {
     return this
   }
 
+  /** @deprecated Will be made private in v5.0 */
   this.$module = $module
 
   var defaultConfig = {
     i18n: ACCORDION_TRANSLATIONS,
     rememberExpanded: true
   }
 
-  /** @type {AccordionConfig} */
+  /**
+   * @deprecated Will be made private in v5.0
+   * @type {AccordionConfig}
+   */
   this.config = mergeConfigs(
     defaultConfig,
     config || {},
     normaliseDataset($module.dataset)
   )
 
+  /** @deprecated Will be made private in v5.0 */
   this.i18n = new I18n(extractConfigByNamespace(this.config, 'i18n'))
 
+  /** @deprecated Will be made private in v5.0 */
   this.controlsClass = 'govuk-accordion__controls'
+
+  /** @deprecated Will be made private in v5.0 */
   this.showAllClass = 'govuk-accordion__show-all'
+
+  /** @deprecated Will be made private in v5.0 */
   this.showAllTextClass = 'govuk-accordion__show-all-text'
 
+  /** @deprecated Will be made private in v5.0 */
   this.sectionClass = 'govuk-accordion__section'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionExpandedClass = 'govuk-accordion__section--expanded'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionButtonClass = 'govuk-accordion__section-button'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionHeaderClass = 'govuk-accordion__section-header'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionHeadingClass = 'govuk-accordion__section-heading'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionHeadingDividerClass = 'govuk-accordion__section-heading-divider'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionHeadingTextClass = 'govuk-accordion__section-heading-text'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionHeadingTextFocusClass = 'govuk-accordion__section-heading-text-focus'
 
+  /** @deprecated Will be made private in v5.0 */
   this.sectionShowHideToggleClass = 'govuk-accordion__section-toggle'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionShowHideToggleFocusClass = 'govuk-accordion__section-toggle-focus'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionShowHideTextClass = 'govuk-accordion__section-toggle-text'
+
+  /** @deprecated Will be made private in v5.0 */
   this.upChevronIconClass = 'govuk-accordion-nav__chevron'
+
+  /** @deprecated Will be made private in v5.0 */
   this.downChevronIconClass = 'govuk-accordion-nav__chevron--down'
 
+  /** @deprecated Will be made private in v5.0 */
   this.sectionSummaryClass = 'govuk-accordion__section-summary'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionSummaryFocusClass = 'govuk-accordion__section-summary-focus'
+
+  /** @deprecated Will be made private in v5.0 */
   this.sectionContentClass = 'govuk-accordion__section-content'
 
   var $sections = this.$module.querySelectorAll('.' + this.sectionClass)
   if (!$sections.length) {
     return this
   }
 
+  /** @deprecated Will be made private in v5.0 */
   this.$sections = $sections
+
+  /** @deprecated Will be made private in v5.0 */
   this.browserSupportsSessionStorage = helper.checkForSessionStorage()
 }
 
@@ -113,6 +155,8 @@ Accordion.prototype.init = function () {
 
 /**
  * Initialise controls and set attributes
+ *
+ * @deprecated Will be made private in v5.0
  */
 Accordion.prototype.initControls = function () {
   // Create "Show all" button and set attributes
@@ -148,6 +192,8 @@ Accordion.prototype.initControls = function () {
 
 /**
  * Initialise section headers
+ *
+ * @deprecated Will be made private in v5.0
  */
 Accordion.prototype.initSectionHeaders = function () {
   var $component = this
@@ -176,6 +222,7 @@ Accordion.prototype.initSectionHeaders = function () {
 /**
  * Construct section header
  *
+ * @deprecated Will be made private in v5.0
  * @param {Element} $header - Section header
  * @param {number} index - Section index
  */
@@ -282,6 +329,7 @@ Accordion.prototype.constructHeaderMarkup = function ($header, index) {
 /**
  * When a section is opened by the user agent via the 'beforematch' event
  *
+ * @deprecated Will be made private in v5.0
  * @param {Event} event - Generic event
  */
 Accordion.prototype.onBeforeMatch = function (event) {
@@ -302,6 +350,7 @@ Accordion.prototype.onBeforeMatch = function (event) {
 /**
  * When section toggled, set and store state
  *
+ * @deprecated Will be made private in v5.0
  * @param {Element} $section - Section element
  */
 Accordion.prototype.onSectionToggle = function ($section) {
@@ -314,6 +363,8 @@ Accordion.prototype.onSectionToggle = function ($section) {
 
 /**
  * When Open/Close All toggled, set and store state
+ *
+ * @deprecated Will be made private in v5.0
  */
 Accordion.prototype.onShowOrHideAllToggle = function () {
   var $component = this
@@ -334,6 +385,7 @@ Accordion.prototype.onShowOrHideAllToggle = function () {
 /**
  * Set section attributes when opened/closed
  *
+ * @deprecated Will be made private in v5.0
  * @param {boolean} expanded - Section expanded
  * @param {Element} $section - Section element
  */
@@ -401,6 +453,7 @@ Accordion.prototype.setExpanded = function (expanded, $section) {
 /**
  * Get state of section
  *
+ * @deprecated Will be made private in v5.0
  * @param {Element} $section - Section element
  * @returns {boolean} True if expanded
  */
@@ -411,6 +464,7 @@ Accordion.prototype.isExpanded = function ($section) {
 /**
  * Check if all sections are open
  *
+ * @deprecated Will be made private in v5.0
  * @returns {boolean} True if all sections are open
  */
 Accordion.prototype.checkIfAllSectionsOpen = function () {
@@ -426,6 +480,7 @@ Accordion.prototype.checkIfAllSectionsOpen = function () {
 /**
  * Update "Show all sections" button
  *
+ * @deprecated Will be made private in v5.0
  * @param {boolean} expanded - Section expanded
  */
 Accordion.prototype.updateShowAllButton = function (expanded) {
@@ -467,6 +522,7 @@ var helper = {
 /**
  * Set the state of the accordions in sessionStorage
  *
+ * @deprecated Will be made private in v5.0
  * @param {Element} $section - Section element
  */
 Accordion.prototype.storeState = function ($section) {
@@ -491,6 +547,7 @@ Accordion.prototype.storeState = function ($section) {
 /**
  * Read the state of the accordions from sessionStorage
  *
+ * @deprecated Will be made private in v5.0
  * @param {Element} $section - Section element
  */
 Accordion.prototype.setInitialState = function ($section) {
@@ -515,6 +572,7 @@ Accordion.prototype.setInitialState = function ($section) {
  * into thematic chunks.
  * See /~https://github.com/alphagov/govuk-frontend/issues/2327#issuecomment-922957442
  *
+ * @deprecated Will be made private in v5.0
  * @returns {Element} DOM element
  */
 Accordion.prototype.getButtonPunctuationEl = function () {

src/govuk/components/button/button.mjs

@@ -20,14 +20,20 @@ function Button ($module, config) {
     return this
   }
 
+  /** @deprecated Will be made private in v5.0 */
   this.$module = $module
+
+  /** @deprecated Will be made private in v5.0 */
   this.debounceFormSubmitTimer = null
 
   var defaultConfig = {
     preventDoubleClick: false
   }
 
-  /** @type {ButtonConfig} */
+  /**
+   * @deprecated Will be made private in v5.0
+   * @type {ButtonConfig}
+   */
   this.config = mergeConfigs(
     defaultConfig,
     config || {},
@@ -56,6 +62,7 @@ Button.prototype.init = function () {
  *
  * See /~https://github.com/alphagov/govuk_elements/pull/272#issuecomment-233028270
  *
+ * @deprecated Will be made private in v5.0
  * @param {KeyboardEvent} event - Keydown event
  */
 Button.prototype.handleKeyDown = function (event) {
@@ -80,6 +87,7 @@ Button.prototype.handleKeyDown = function (event) {
  * stops people accidentally causing multiple form submissions by double
  * clicking buttons.
  *
+ * @deprecated Will be made private in v5.0
  * @param {MouseEvent} event - Mouse click event
  * @returns {undefined | false} Returns undefined, or false when debounced
  */