Merge pull request #1895 from nhsuk/character-count-grapheme

[v10] Add character count `countType: "characters"` option using Intl.Segmenter

Author: colinrotherham

docs/configuration/javascript-api-reference.md

@@ -63,7 +63,7 @@ Default:
 
 Type: string
 
-The count type (`'length'` or `'words'`) used to count the text.
+The count type (`'length'`, `'characters'` or `'words'`) used to count the text.
 
 Default:
 

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

@@ -1,11 +1,14 @@
 import { getByRole } from '@testing-library/dom'
+import { userEvent } from '@testing-library/user-event'
 import { outdent } from 'outdent'
 
 import { components } from '#lib'
 
 import { CharacterCount, initCharacterCounts } from './character-count.mjs'
 import { examples } from './fixtures.mjs'
 
+const user = userEvent.setup()
+
 describe('Character count', () => {
   /** @type {HTMLElement} */
   let $root
@@ -94,6 +97,17 @@ describe('Character count', () => {
   })
 
   describe('Initialisation via class', () => {
+    /** @type {typeof Intl.Segmenter} */
+    let Segmenter
+
+    beforeEach(() => {
+      Segmenter = Intl.Segmenter
+    })
+
+    afterEach(() => {
+      Object.assign(Intl, { Segmenter })
+    })
+
     it('should not throw with $root element', () => {
       expect(() => new CharacterCount($root)).not.toThrow()
     })
@@ -106,6 +120,19 @@ describe('Character count', () => {
       )
     })
 
+    it('should throw without Intl.Segmenter support', () => {
+      // @ts-expect-error The operand of a 'delete' operator cannot be a read-only property
+      delete Intl.Segmenter
+
+      expect(() => {
+        new CharacterCount($root, {
+          countType: 'characters'
+        })
+      }).toThrow(
+        `${CharacterCount.moduleName}: Support for "Intl.Segmenter" required`
+      )
+    })
+
     it('should throw with missing $root element', () => {
       // @ts-expect-error Parameter '$root' not provided
       expect(() => new CharacterCount()).toThrow(
@@ -164,8 +191,9 @@ describe('Character count', () => {
       expect(component.updateIfValueChanged).toHaveBeenCalled()
     })
 
-    it('should handle deprecated params', () => {
-      $textarea.value = 'Existing value'
+    it('should handle deprecated params', async () => {
+      await user.click($textarea)
+      await user.keyboard('Existing value')
 
       const component = new CharacterCount($root)
 
@@ -234,13 +262,25 @@ describe('Character count', () => {
       })
     })
 
+    it('configures `countType: "characters"`', () => {
+      initExample("with count type 'characters'")
+
+      const characterCount = new CharacterCount($root)
+      expect(characterCount.config).toEqual({
+        ...CharacterCount.defaults,
+        maxlength: 200,
+        threshold: 0,
+        countType: 'characters'
+      })
+    })
+
     it('configures `countType: "words"`', () => {
       initExample("with count type 'words'")
 
       const characterCount = new CharacterCount($root)
       expect(characterCount.config).toEqual({
         ...CharacterCount.defaults,
-        maxlength: 150,
+        maxlength: 50,
         threshold: 0,
         countType: 'words'
       })
@@ -327,8 +367,9 @@ describe('Character count', () => {
         expect(component.formatCountMessage(0)).toBe('Different custom text.')
       })
 
-      it('uses existing textarea value for `maxlength` limit when initialised', () => {
-        $textarea.value = 'Existing value'
+      it('uses existing textarea value for `maxlength` limit when initialised', async () => {
+        await user.click($textarea)
+        await user.keyboard('Existing value')
 
         const component = new CharacterCount($root, {
           maxlength: 100
@@ -339,8 +380,9 @@ describe('Character count', () => {
         )
       })
 
-      it('uses existing textarea value for `maxwords` limit when initialised', () => {
-        $textarea.value = 'Existing value'
+      it('uses existing textarea value for `maxwords` limit when initialised', async () => {
+        await user.click($textarea)
+        await user.keyboard('Existing value')
 
         const component = new CharacterCount($root, {
           maxwords: 100
@@ -349,12 +391,13 @@ describe('Character count', () => {
         expect(component.getCountMessage()).toBe('You have 98 words remaining')
       })
 
-      it('uses current textarea value for `maxlength` limit via back/forward navigation', () => {
+      it('uses current textarea value for `maxlength` limit via back/forward navigation', async () => {
         const component = new CharacterCount($root, {
           maxlength: 100
         })
 
-        $textarea.value = 'Newly updated value'
+        await user.click($textarea)
+        await user.keyboard('Newly updated value')
 
         // Trigger back/forward navigation
         window.dispatchEvent(
@@ -368,12 +411,13 @@ describe('Character count', () => {
         )
       })
 
-      it('uses current textarea value for `maxwords` limit via back/forward navigation', () => {
+      it('uses current textarea value for `maxwords` limit via back/forward navigation', async () => {
         const component = new CharacterCount($root, {
           maxwords: 100
         })
 
-        $textarea.value = 'Newly updated value'
+        await user.click($textarea)
+        await user.keyboard('Newly updated value')
 
         // Trigger back/forward navigation
         window.dispatchEvent(

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

@@ -2,7 +2,7 @@ import { closestAttributeValue } from '../../common/closest-attribute-value.mjs'
 import { normaliseOptions } from '../../common/configuration/index.mjs'
 import { formatErrorMessage } from '../../common/index.mjs'
 import { ConfigurableComponent } from '../../configurable-component.mjs'
-import { ElementError } from '../../errors/index.mjs'
+import { ElementError, SupportError } from '../../errors/index.mjs'
 import { I18n } from '../../i18n.mjs'
 
 /**
@@ -20,6 +20,11 @@ import { I18n } from '../../i18n.mjs'
 export class CharacterCount extends ConfigurableComponent {
   length = 0
 
+  /**
+   * @type {Intl.Segmenter | null}
+   */
+  segmenter = null
+
   /**
    * @type {number | null}
    */
@@ -56,6 +61,7 @@ export class CharacterCount extends ConfigurableComponent {
     const {
       i18n,
       maxlength,
+      countType,
       screenReaderCountMessageClass,
       textareaDescriptionClass,
       visibleCountMessageClass
@@ -66,6 +72,21 @@ export class CharacterCount extends ConfigurableComponent {
       locale: closestAttributeValue(this.$root, 'lang')
     })
 
+    if (countType === 'characters') {
+      if (!('Segmenter' in Intl)) {
+        throw new SupportError(
+          formatErrorMessage(
+            CharacterCount,
+            'Support for "Intl.Segmenter" required'
+          )
+        )
+      }
+
+      this.segmenter = new Intl.Segmenter(this.i18n.locale, {
+        granularity: 'grapheme'
+      })
+    }
+
     // Determine the limit attribute (characters or words)
     this.maxLength = maxlength ?? Infinity
 
@@ -204,13 +225,26 @@ export class CharacterCount extends ConfigurableComponent {
 
     text = text ?? $textarea.value
 
-    if (countType === 'words') {
-      const tokens = text.match(/\S+/g) ?? [] // Matches consecutive non-whitespace chars
-      this.length = tokens.length
-      return
-    }
+    switch (countType) {
+      case 'length':
+        // Count code points (string length)
+        this.length = text.length
+        break
+
+      case 'characters': {
+        // Count grapheme clusters (user-perceived characters)
+        this.length = this.segmenter
+          ? Array.from(this.segmenter.segment(text)).length
+          : 0
 
-    this.length = text.length
+        break
+      }
+
+      case 'words':
+        // Count consecutive non-whitespace results
+        this.length = text.match(/\S+/g)?.length ?? 0
+        break
+    }
   }
 
   /**
@@ -538,8 +572,8 @@ export function initCharacterCounts(options) {
  * @property {number} [threshold=0] - The percentage value of the limit at
  *   which point the count message is displayed. If this attribute is set, the
  *   count message will be hidden by default.
- * @property {'length' | 'words'} countType - The count type (`"length"` or
- *   `"words"`) used to count the text.
+ * @property {'characters' | 'length' | 'words'} countType - The count type
+ *   (`"characters"`, `"length"` or `"words"`) used to count the text.
  * @property {string} textareaDescriptionClass - Textarea description class
  * @property {string} visibleCountMessageClass - Visible count message class
  * @property {string} screenReaderCountMessageClass - Screen reader count message class