Merge pull request #1893 from nhsuk/character-count-function

[v10] Deprecate character count `maxwords` and add `countType` option

Author: colinrotherham

docs/configuration/javascript-api-reference.md

@@ -39,13 +39,13 @@ false
 
 Type: number
 
-The maximum number of characters. If `maxwords` is provided, the `maxlength` option will be ignored.
+The maximum number of characters (or words if `countType` is set to `'words'`).
 
-### maxwords
+### maxwords (deprecated)
 
 Type: number
 
-The maximum number of words. If `maxwords` is provided, the `maxlength` option will be ignored.
+The maximum number of words. Replaced by the `maxlength` and `countType: 'words'` options.
 
 ### threshold
 
@@ -59,6 +59,18 @@ Default:
 0
 ```
 
+### countType
+
+Type: string
+
+The count type (`'length'` or `'words'`) used to count the text.
+
+Default:
+
+```json5
+'length'
+```
+
 ### textareaDescriptionClass
 
 Type: string
@@ -215,7 +227,7 @@ Default:
 
 Type: object
 
-Message made available to assistive technologies, if none is already present in the HTML, to describe that the component accepts only a limited amount of content. The component will replace the `%{count}` placeholder with the value of the `maxlength` or `maxwords` option.
+Message made available to assistive technologies, if none is already present in the HTML, to describe that the component accepts only a limited amount of content. The component will replace the `%{count}` placeholder with the value of the `maxlength` option.
 
 Default:
 

packages/nhsuk-frontend-review/src/examples/translated.njk

@@ -74,7 +74,8 @@
           text: "Peidiwch â chynnwys gwybodaeth bersonol, fel eich enw, dyddiad geni na rhif y GIG"
         },
         name: "with-translations-maxwords",
-        maxwords: 10,
+        maxlength: 10,
+        countType: "words",
         textareaDescriptionText: "Gallwch ddefnyddio hyd at %{count} nod",
         wordsUnderLimitText: {
           one: "Mae gennych %{count} gair ar ôl",

packages/nhsuk-frontend/src/nhsuk/components/character-count/character-count.jsdom.test.mjs

@@ -34,6 +34,7 @@ describe('Character count', () => {
 
     jest.spyOn($textarea, 'addEventListener')
     jest.spyOn(window, 'addEventListener')
+    jest.spyOn(console, 'warn').mockImplementation()
   }
 
   beforeEach(() => {
@@ -162,6 +163,35 @@ describe('Character count', () => {
       expect(component.updateCount).toHaveBeenCalled()
       expect(component.updateIfValueChanged).toHaveBeenCalled()
     })
+
+    it('should handle deprecated params', () => {
+      $textarea.value = 'Existing value'
+
+      const component = new CharacterCount($root)
+
+      expect(component.getCountMessage()).toBe(
+        'You have 186 characters remaining'
+      )
+
+      // Temporarily allow deprecated `text` parameter to update count
+      // even though the textarea value has not been updated
+      component.updateCount('')
+
+      // Temporarily allow deprecated `countType = 'characters'` parameter
+      expect(component.formatCountMessage(200, 'characters')).toBe(
+        'You have 200 characters remaining'
+      )
+
+      // Temporarily allow deprecated `countType = 'length'` parameter
+      expect(component.formatCountMessage(200, 'length')).toBe(
+        'You have 200 characters remaining'
+      )
+
+      // Temporarily allow deprecated `countType = 'words'` parameter
+      expect(component.formatCountMessage(200, 'words')).toBe(
+        'You have 200 words remaining'
+      )
+    })
   })
 
   describe('Nunjucks configuration', () => {
@@ -170,18 +200,49 @@ describe('Character count', () => {
       expect(characterCount.config).toEqual({
         ...CharacterCount.defaults,
         maxlength: 200,
-        threshold: 0
+        threshold: 0,
+        countType: 'length'
       })
     })
 
-    it('configures `maxwords`', () => {
-      initExample('with word count')
+    it('configures `maxwords` (deprecated)', () => {
+      initExample('with maxwords')
 
       const characterCount = new CharacterCount($root)
       expect(characterCount.config).toEqual({
         ...CharacterCount.defaults,
+        maxlength: 150,
         maxwords: 150,
-        threshold: 0
+        threshold: 0,
+        countType: 'words'
+      })
+
+      expect(console.warn).toHaveBeenCalledWith(
+        `${CharacterCount.moduleName}: Option \`maxwords\` is deprecated. Use \`maxlength\` with \`countType: "words"\` instead.`
+      )
+    })
+
+    it('configures `countType: "length"`', () => {
+      initExample("with count type 'length'")
+
+      const characterCount = new CharacterCount($root)
+      expect(characterCount.config).toEqual({
+        ...CharacterCount.defaults,
+        maxlength: 200,
+        threshold: 0,
+        countType: 'length'
+      })
+    })
+
+    it('configures `countType: "words"`', () => {
+      initExample("with count type 'words'")
+
+      const characterCount = new CharacterCount($root)
+      expect(characterCount.config).toEqual({
+        ...CharacterCount.defaults,
+        maxlength: 150,
+        threshold: 0,
+        countType: 'words'
       })
     })
 
@@ -192,7 +253,8 @@ describe('Character count', () => {
       expect(characterCount.config).toEqual({
         ...CharacterCount.defaults,
         maxlength: 112,
-        threshold: 75
+        threshold: 75,
+        countType: 'length'
       })
     })
 
@@ -215,7 +277,8 @@ describe('Character count', () => {
       expect(characterCount.config).toEqual({
         ...CharacterCount.defaults,
         maxlength: 200,
-        threshold: 0
+        threshold: 0,
+        countType: 'length'
       })
     })
   })
@@ -234,12 +297,10 @@ describe('Character count', () => {
           }
         })
 
-        expect(component.formatCountMessage(1, 'characters')).toBe(
-          'Custom text. Count: 1'
-        )
+        expect(component.formatCountMessage(1)).toBe('Custom text. Count: 1')
 
         // Other keys remain untouched
-        expect(component.formatCountMessage(10, 'characters')).toBe(
+        expect(component.formatCountMessage(10)).toBe(
           'You have 10 characters remaining'
         )
       })
@@ -252,9 +313,7 @@ describe('Character count', () => {
           }
         })
 
-        expect(component.formatCountMessage(0, 'characters')).toBe(
-          'Custom text.'
-        )
+        expect(component.formatCountMessage(0)).toBe('Custom text.')
       })
 
       it('uses specific translation keys when `maxwords` limit is reached', () => {
@@ -265,9 +324,7 @@ describe('Character count', () => {
           }
         })
 
-        expect(component.formatCountMessage(0, 'words')).toBe(
-          'Different custom text.'
-        )
+        expect(component.formatCountMessage(0)).toBe('Different custom text.')
       })
 
       it('uses existing textarea value for `maxlength` limit when initialised', () => {
@@ -337,7 +394,7 @@ describe('Character count', () => {
           maxwords: 20000
         })
 
-        expect(component.formatCountMessage(10000, 'words')).toBe(
+        expect(component.formatCountMessage(10000)).toBe(
           'You have 10.000 words remaining'
         )
       })
@@ -349,7 +406,7 @@ describe('Character count', () => {
           maxwords: 20000
         })
 
-        expect(component.formatCountMessage(10000, 'words')).toBe(
+        expect(component.formatCountMessage(10000)).toBe(
           'You have 10.000 words remaining'
         )
       })
@@ -366,12 +423,10 @@ describe('Character count', () => {
           maxlength: 100
         })
 
-        expect(component.formatCountMessage(1, 'characters')).toBe(
-          'Custom text. Count: 1'
-        )
+        expect(component.formatCountMessage(1)).toBe('Custom text. Count: 1')
 
         // Other keys remain untouched
-        expect(component.formatCountMessage(10, 'characters')).toBe(
+        expect(component.formatCountMessage(10)).toBe(
           'You have 10 characters remaining'
         )
       })
@@ -391,16 +446,14 @@ describe('Character count', () => {
           }
         })
 
-        expect(component.formatCountMessage(1, 'characters')).toBe(
-          'Custom text. Count: 1'
-        )
+        expect(component.formatCountMessage(1)).toBe('Custom text. Count: 1')
 
         // Other keys remain untouched
-        expect(component.formatCountMessage(-10, 'characters')).toBe(
+        expect(component.formatCountMessage(-10)).toBe(
           'You have 10 characters too many'
         )
 
-        expect(component.formatCountMessage(0, 'characters')).toBe(
+        expect(component.formatCountMessage(0)).toBe(
           'You have 0 characters remaining'
         )
       })
@@ -409,7 +462,11 @@ describe('Character count', () => {
 })
 
 describe('Character count: Format count message', () => {
-  let /** @type {CharacterCount} */ componentWithMaxLength
+  let /** @type {CharacterCount} */ component
+  let /** @type {CharacterCount} */ componentWithCountTypeCharacters
+  let /** @type {CharacterCount} */ componentWithCountTypeWords
+
+  // Deprecated `maxwords` option where `countType` is inferred
   let /** @type {CharacterCount} */ componentWithMaxWords
 
   beforeEach(() => {
@@ -421,18 +478,30 @@ describe('Character count: Format count message', () => {
       <body class="nhsuk-frontend-supported">
         ${components.render('character-count', example)}
         ${components.render('character-count', example)}
+        ${components.render('character-count', example)}
+        ${components.render('character-count', example)}
       </body>
     `
 
     const $roots = document.querySelectorAll(
       `[data-module="${CharacterCount.moduleName}"]`
     )
 
-    componentWithMaxLength = new CharacterCount($roots[0], {
+    component = new CharacterCount($roots[0], {
       maxlength: 100
     })
 
-    componentWithMaxWords = new CharacterCount($roots[1], {
+    componentWithCountTypeCharacters = new CharacterCount($roots[1], {
+      maxlength: 100,
+      countType: 'length'
+    })
+
+    componentWithCountTypeWords = new CharacterCount($roots[2], {
+      maxlength: 100,
+      countType: 'words'
+    })
+
+    componentWithMaxWords = new CharacterCount($roots[3], {
       maxwords: 100
     })
   })
@@ -446,53 +515,38 @@ describe('Character count: Format count message', () => {
   ])(
     'outputs the expected translation for $number characters',
     ({ number, expected }) => {
+      expect(component.formatCountMessage(number)).toEqual(expected)
+
       expect(
-        componentWithMaxLength.formatCountMessage(number, 'characters')
+        componentWithCountTypeCharacters.formatCountMessage(number)
       ).toEqual(expected)
     }
   )
 
   it.each([
-    {
-      number: 1,
-      type: 'words',
-      expected: 'You have 1 word remaining'
-    },
-    {
-      number: 10,
-      type: 'words',
-      expected: 'You have 10 words remaining'
-    },
-    {
-      number: -1,
-      type: 'words',
-      expected: 'You have 1 word too many'
-    },
-    {
-      number: -10,
-      type: 'words',
-      expected: 'You have 10 words too many'
-    },
-    {
-      number: 0,
-      type: 'words',
-      expected: 'You have 0 words remaining'
-    }
+    { number: 1, expected: 'You have 1 word remaining' },
+    { number: 10, expected: 'You have 10 words remaining' },
+    { number: -1, expected: 'You have 1 word too many' },
+    { number: -10, expected: 'You have 10 words too many' },
+    { number: 0, expected: 'You have 0 words remaining' }
   ])(
     'outputs the expected translation for $number words',
     ({ number, expected }) => {
-      expect(componentWithMaxWords.formatCountMessage(number, 'words')).toEqual(
+      expect(componentWithCountTypeWords.formatCountMessage(number)).toEqual(
         expected
       )
+
+      // Deprecated `maxwords` option where `countType` is inferred
+      expect(componentWithMaxWords.formatCountMessage(number)).toEqual(expected)
     }
   )
 
   it('formats the number inserted in the message', () => {
-    expect(componentWithMaxWords.formatCountMessage(10000, 'words')).toBe(
+    expect(componentWithCountTypeWords.formatCountMessage(10000)).toBe(
       'You have 10,000 words remaining'
     )
 
-    expect(componentWithMaxWords.formatCountMessage(-10000, 'words')).toBe(
+    expect(componentWithCountTypeWords.formatCountMessage(-10000)).toBe(
       'You have 10,000 words too many'
     )
   })