feat: Let Form Error List add the error count to the document title (#…

…1309)

Co-authored-by: Vincent Smedinga <[email protected]>

packages/css/src/components/form-error-list/README.md

@@ -23,6 +23,11 @@ For questions that require a user to select one or more options from a list usin
 
 Put the Form Error List directly above the first question on the page. Place it outside of the `<form>`-tag, [to make sure screen readers do not skip it](https://nldesignsystem.nl/richtlijnen/formulieren/meerdere-stappen/#plaats-de-informatie-over-waar-de-gebruiker-is-in-de-stappen-boven-het-formulier).
 
+## Error count in document title
+
+This component adds the error count to the document title,
+in line with [GOV.UK guidelines for informing users about validation errors](https://design-system.service.gov.uk/patterns/validation/#how-to-tell-the-user-about-validation-errors).
+
 ## Relevant WCAG requirements
 
 Pay extra attention to these parts:

packages/react/src/FormErrorList/FormErrorList.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react'
+import { render, screen, waitFor } from '@testing-library/react'
 import { createRef } from 'react'
 import { FormErrorList } from './FormErrorList'
 import '@testing-library/jest-dom'
@@ -78,6 +78,47 @@ describe('Form error list', () => {
     expect(component).toBeInTheDocument()
   })
 
+  const docTitle = 'Document title'
+  const singleTestError = [{ id: '#', label: 'De geldigheidsdatum van uw paspoort moet in de toekomst liggen.' }]
+
+  describe('prepends the document title with the error count', () => {
+    it('single error', async () => {
+      document.title = docTitle
+
+      render(<FormErrorList errors={singleTestError} />)
+
+      await waitFor(() => expect(document.title).toBe(`(1 invoerfout) ${docTitle}`))
+    })
+
+    it('multiple errors', async () => {
+      document.title = docTitle
+
+      render(<FormErrorList errors={testErrors} />)
+
+      await waitFor(() => expect(document.title).toBe(`(2 invoerfouten) ${docTitle}`))
+    })
+  })
+
+  describe('renders a custom document title label', () => {
+    const label = { plural: 'errors', singular: 'error' }
+
+    it('single error', async () => {
+      document.title = docTitle
+
+      render(<FormErrorList errors={singleTestError} errorCountLabel={label} />)
+
+      await waitFor(() => expect(document.title).toBe(`(1 error) ${docTitle}`))
+    })
+
+    it('multiple errors', async () => {
+      document.title = docTitle
+
+      render(<FormErrorList errors={testErrors} errorCountLabel={label} />)
+
+      await waitFor(() => expect(document.title).toBe(`(2 errors) ${docTitle}`))
+    })
+  })
+
   it('supports ForwardRef in React', () => {
     const ref = createRef<HTMLDivElement>()
 

packages/react/src/FormErrorList/FormErrorList.tsx

@@ -6,6 +6,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes } from 'react'
+import { useAddErrorCountToDocumentTitle } from './useAddErrorCountToDocumentTitle'
 import { Alert } from '../Alert'
 import type { HeadingLevel } from '../Heading'
 import { LinkList } from '../LinkList'
@@ -16,6 +17,11 @@ export type FormError = {
 }
 
 export type FormErrorListProps = {
+  /**
+   * The text following the error count.
+   * This is used to show the error count in the document title.
+   */
+  errorCountLabel?: { plural: string; singular: string }
   /** The list of error messages to display. */
   errors: FormError[]
   /** The text for the Heading. */
@@ -31,13 +37,16 @@ export const FormErrorList = forwardRef(
   (
     {
       className,
+      errorCountLabel,
       errors,
       heading = 'Verbeter de fouten voor u verder gaat',
       headingLevel = 2,
       ...restProps
     }: FormErrorListProps,
     ref: ForwardedRef<HTMLDivElement>,
   ) => {
+    useAddErrorCountToDocumentTitle(errors, errorCountLabel)
+
     if (errors.length === 0) return undefined
 
     return (

packages/react/src/FormErrorList/useAddErrorCountToDocumentTitle.tsx

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react'
+
+export const useAddErrorCountToDocumentTitle = (
+  /** The list of error messages used to calculate the error count. */
+  errors: { id: string; label: string }[],
+  /** The text following the error count. */
+  label = {
+    plural: 'invoerfouten',
+    singular: 'invoerfout',
+  },
+) => {
+  const [documentTitle, setDocumentTitle] = useState<string>()
+
+  useEffect(() => {
+    setDocumentTitle(document.title)
+  }, [])
+
+  if (!documentTitle) return null
+
+  if (errors.length === 1) {
+    document.title = `(${errors.length} ${label.singular}) ${documentTitle}`
+  } else if (errors.length > 1) {
+    document.title = `(${errors.length} ${label.plural}) ${documentTitle}`
+  } else {
+    document.title = documentTitle
+  }
+
+  return null
+}