@defra/lis-infra-ui-services 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/lis-infra-ui-services",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "UI-Services shared definitions for the livestock taxonomy topology.",
   "main": "src/index.js",
   "repository": {

package/src/components/sortable-paginated-table.scss

@@ -25,3 +25,34 @@
 .lis-sortable-table__icon {
   flex-shrink: 0;
 }
+
+// A focusable region so keyboard users can scroll a table that's wider than
+// the viewport.
+.lis-sortable-table__wrapper {
+  // Contains the table's absolutely positioned visually-hidden text, which
+  // would otherwise escape the overflow and make the whole page scroll.
+  position: relative;
+  overflow-x: auto;
+
+  // The GOV.UK non-text focus state - yellow alone has too little contrast
+  // against a white page. Both rings sit outside the box, clear of the text.
+  &:focus {
+    outline: $govuk-focus-width solid govuk-functional-colour("focus");
+    outline-offset: $govuk-focus-width;
+    box-shadow: 0 0 0 $govuk-focus-width govuk-functional-colour("focus-text");
+  }
+
+  // A header never wraps - on a narrow screen the table scrolls inside the
+  // wrapper instead.
+  .govuk-table__header {
+    white-space: nowrap;
+  }
+}
+
+// Also keeps every cell on one line. Opt-in, since it suits tables of short
+// values but not ones with free text. Pass as `classes`.
+.lis-sortable-table--no-wrap {
+  .govuk-table__cell {
+    white-space: nowrap;
+  }
+}

package/src/nunjucks/components/date/date.test.js

@@ -0,0 +1,72 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import nunjucks from 'nunjucks'
+import { describe, expect, test } from 'vitest'
+
+import { formatDate } from '../../format-date.js'
+
+const componentRoot = path.dirname(fileURLToPath(import.meta.url))
+const environment = new nunjucks.Environment(
+  new nunjucks.FileSystemLoader([path.dirname(componentRoot)]),
+  { autoescape: true, trimBlocks: true, lstripBlocks: true }
+)
+environment.addFilter('formatDate', formatDate)
+
+describe('lisDate()', () => {
+  test('it formats an ISO date string as day, short month and year', () => {
+    // Arrange
+    const params = { value: '2024-11-29' }
+
+    // Act
+    const html = environment.render('date/template.njk', { params })
+
+    // Assert
+    expect(html.trim()).toEqual('29 Nov 2024')
+  })
+
+  test('it does not zero-pad a single-digit day', () => {
+    // Arrange
+    const params = { value: '2023-02-01' }
+
+    // Act
+    const html = environment.render('date/template.njk', { params })
+
+    // Assert
+    expect(html.trim()).toEqual('1 Feb 2023')
+  })
+
+  test('it formats a Date value', () => {
+    // Arrange
+    const params = { value: new Date(2024, 10, 29) }
+
+    // Act
+    const html = environment.render('date/template.njk', { params })
+
+    // Assert
+    expect(html.trim()).toEqual('29 Nov 2024')
+  })
+
+  test('it renders nothing when there is no value', () => {
+    // Arrange
+    const params = { value: null }
+
+    // Act
+    const html = environment.render('date/template.njk', { params })
+
+    // Assert
+    expect(html.trim()).toEqual('')
+  })
+
+  test('it renders with no surrounding whitespace when called inline', () => {
+    // Arrange
+    const template =
+      '{% from "date/macro.njk" import lisDate %}<td>{{ lisDate(value) }}</td>'
+
+    // Act
+    const html = environment.renderString(template, { value: '2024-11-29' })
+
+    // Assert
+    expect(html).toEqual('<td>29 Nov 2024</td>')
+  })
+})

package/src/nunjucks/components/date/macro.njk

@@ -0,0 +1,3 @@
+{% macro lisDate(value) -%}
+  {%- if value %}{{ value | formatDate("d MMM yyyy") }}{% endif -%}
+{%- endmacro %}

package/src/nunjucks/components/date/template.njk

@@ -0,0 +1,3 @@
+{% from "date/macro.njk" import lisDate %}
+
+{{ lisDate(params.value) }}

package/src/nunjucks/components/search-form/search-form.test.js

@@ -36,6 +36,25 @@ describe('searchForm()', () => {
     expect(html).toContain('name="search"')
   })
 
+  test('links the hint to the input so it is read out with the label', () => {
+    // Act
+    const html = render({ label: 'Search', hint: 'Search by ear tag' })
+
+    // Assert
+    expect(html).toContain(
+      '<p class="govuk-body" id="search-hint">Search by ear tag</p>'
+    )
+    expect(html).toContain('aria-describedby="search-hint"')
+  })
+
+  test('does not describe the input by a hint when none is given', () => {
+    // Act
+    const html = render({ label: 'Search' })
+
+    // Assert
+    expect(html).not.toContain('aria-describedby')
+  })
+
   test('defaults the input name and id to "search"', () => {
     // Act
     const html = render({ label: 'Search' })

package/src/nunjucks/components/search-form/template.njk

@@ -8,7 +8,7 @@
   </h2>
 
   {%- if params.hint -%}
-    <p class="govuk-body">{{ params.hint }}</p>
+    <p class="govuk-body" id="{{ id }}-hint">{{ params.hint }}</p>
   {%- endif -%}
 
   <form method="GET" class="lis-search-form">
@@ -19,6 +19,7 @@
         id="{{ id }}"
         name="{{ params.name or 'search' }}"
         value="{{ params.value }}"
+        {% if params.hint %}aria-describedby="{{ id }}-hint"{% endif %}
       >
       <div class="lis-search-form__submit-wrapper">
         <button class="lis-search-form__submit" type="submit">

package/src/nunjucks/components/sortable-paginated-table/sortable-paginated-table.test.js

@@ -123,6 +123,56 @@ test('passes rows straight through to the table', () => {
   assert.match(html, /<td class="govuk-table__cell">UK 324537 113234<\/td>/)
 })
 
+test('tells screen reader users that the column headers are sortable', () => {
+  const html = render({
+    caption: 'Animals',
+    columns,
+    rows,
+    baseHref: '/animals'
+  })
+
+  assert.match(
+    html,
+    /<caption class="govuk-table__caption govuk-visually-hidden">\s*Animals<span class="govuk-visually-hidden"> \(column headers with links are sortable\)\.<\/span>\s*<\/caption>/
+  )
+})
+
+test('omits the sortable hint when no column has a sortKey', () => {
+  const html = render({
+    caption: 'Animals',
+    columns: [{ text: 'Ear tag number' }, { text: 'Age' }, { text: 'Breed' }],
+    rows,
+    baseHref: '/animals'
+  })
+
+  assert.doesNotMatch(html, /are sortable/)
+})
+
+test('renders no caption, and a generic region label, when no caption is given', () => {
+  const html = render({
+    columns,
+    rows,
+    baseHref: '/animals'
+  })
+
+  assert.doesNotMatch(html, /<caption/)
+  assert.match(html, /role="region" aria-label="Table">/)
+})
+
+test('wraps the table in a focusable, labelled region so it can be scrolled by keyboard', () => {
+  const html = render({
+    caption: 'Animals',
+    columns,
+    rows,
+    baseHref: '/animals'
+  })
+
+  assert.match(
+    html,
+    /<div class="lis-sortable-table__wrapper" tabindex="0" role="region" aria-label="Animals table">\s*<table/
+  )
+})
+
 test('renders the results summary but no pagination nav when there is only one page', () => {
   const html = render({
     caption: 'Animals',

package/src/nunjucks/components/sortable-paginated-table/template.njk

@@ -4,27 +4,30 @@
 {%- set query = params.query or {} -%}
 
 {%- set upArrow -%}
-  <svg width="22" height="22" focusable="false" aria-hidden="true" role="img" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" class="lis-sortable-table__icon">
+  <svg width="22" height="22" focusable="false" aria-hidden="true" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" class="lis-sortable-table__icon">
     <path d="M6.5625 15.5L11 6.63125L15.4375 15.5H6.5625Z" fill="currentColor"></path>
   </svg>
 {%- endset -%}
 
 {%- set downArrow -%}
-  <svg width="22" height="22" focusable="false" aria-hidden="true" role="img" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" class="lis-sortable-table__icon">
+  <svg width="22" height="22" focusable="false" aria-hidden="true" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" class="lis-sortable-table__icon">
     <path d="M15.4375 7L11 15.8687L6.5625 7L15.4375 7Z" fill="currentColor"></path>
   </svg>
 {%- endset -%}
 
 {%- set upDownArrow -%}
-  <svg width="22" height="22" focusable="false" aria-hidden="true" role="img" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" class="lis-sortable-table__icon">
+  <svg width="22" height="22" focusable="false" aria-hidden="true" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg" class="lis-sortable-table__icon">
     <path d="M8.1875 9.5L10.9609 3.95703L13.7344 9.5H8.1875Z" fill="currentColor"></path>
     <path d="M13.7344 12.0781L10.9609 17.6211L8.1875 12.0781H13.7344Z" fill="currentColor"></path>
   </svg>
 {%- endset -%}
 
 {%- set head = [] -%}
+{#- a list, since a set inside the loop wouldn't be visible outside it -#}
+{%- set sortableColumns = [] -%}
 {%- for column in params.columns -%}
   {%- if column.sortKey -%}
+    {%- set _ = sortableColumns.push(column.sortKey) -%}
     {%- set isActive = params.sort == column.sortKey -%}
     {%- set ariaSort = "ascending" if (isActive and params.direction == "asc") else ("descending" if (isActive and params.direction == "desc") else "none") -%}
     {%- set nextDirection = "desc" if ariaSort == "ascending" else "asc" -%}
@@ -39,14 +42,20 @@
   {%- endif -%}
 {%- endfor -%}
 
-{{ govukTable({
-  caption: params.caption,
-  captionClasses: params.captionClasses or "govuk-visually-hidden",
-  classes: params.classes,
-  firstCellIsHeader: params.firstCellIsHeader,
-  head: head,
-  rows: params.rows
-}) }}
+{%- set captionHtml -%}
+  {{ params.caption }}{% if sortableColumns | length %}<span class="govuk-visually-hidden"> (column headers with links are sortable).</span>{% endif %}
+{%- endset -%}
+
+<div class="lis-sortable-table__wrapper" tabindex="0" role="region" aria-label="{{ (params.caption ~ ' table') if params.caption else 'Table' }}">
+  {{ govukTable({
+    caption: (captionHtml | safe) if params.caption else undefined,
+    captionClasses: params.captionClasses or "govuk-visually-hidden",
+    classes: params.classes,
+    firstCellIsHeader: params.firstCellIsHeader,
+    head: head,
+    rows: params.rows
+  }) }}
+</div>
 
 {%- if params.pagination -%}
   {%- set currentPage = params.pagination.currentPage -%}

package/src/nunjucks/filters.js

@@ -1,6 +1,8 @@
 import assign from 'lodash/assign.js'
 
+export { formatAge } from './format-age.js'
 export { formatDate } from './format-date.js'
+export { formatEarTag } from './format-ear-tag.js'
 export { formatCurrency } from './format-currency.js'
 export { queryString } from './query-string.js'
 

package/src/nunjucks/format-age.js

@@ -0,0 +1,38 @@
+import { intervalToDuration, isDate, isValid, parseISO } from 'date-fns'
+
+/**
+ * @param {Date | string} dateOfBirth
+ * @param {Date} [now]
+ * @returns {string} e.g. "3 years, 6 months", "3 years" for a whole number
+ *   of years, or "6 months" for an animal under a year old. Empty when there
+ *   is no usable date of birth - missing, unparseable or in the future - so
+ *   a page never shows a made-up age.
+ */
+export function formatAge(dateOfBirth, now = new Date()) {
+  if (!dateOfBirth) {
+    return ''
+  }
+
+  const start = isDate(dateOfBirth) ? dateOfBirth : parseISO(dateOfBirth)
+
+  if (!isValid(start) || start > now) {
+    return ''
+  }
+
+  // intervalToDuration omits a unit entirely (rather than returning 0) when
+  // its value is zero, so years/months need a default.
+  const { years = 0, months = 0 } = intervalToDuration({ start, end: now })
+
+  const yearsText = `${years} year${years === 1 ? '' : 's'}`
+  const monthsText = `${months} month${months === 1 ? '' : 's'}`
+
+  if (years === 0) {
+    return months === 0 ? 'Less than 1 month' : monthsText
+  }
+
+  if (months === 0) {
+    return yearsText
+  }
+
+  return `${yearsText}, ${monthsText}`
+}

package/src/nunjucks/format-age.test.js

@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'vitest'
+
+import { formatAge } from './format-age.js'
+
+describe('formatAge()', () => {
+  test('it computes whole years and months', () => {
+    // Arrange
+    const dateOfBirth = '2023-03-10'
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('3 years, 6 months')
+  })
+
+  test('it uses singular units for exactly 1 year and 1 month', () => {
+    // Arrange
+    const dateOfBirth = '2025-08-10'
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('1 year, 1 month')
+  })
+
+  test('it omits the months when the age is a whole number of years', () => {
+    // Arrange
+    const dateOfBirth = '2023-08-19'
+    const now = new Date('2026-09-11')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('3 years')
+  })
+
+  test('it uses the singular "year" for a whole number of exactly 1 year', () => {
+    // Arrange
+    const dateOfBirth = '2025-08-19'
+    const now = new Date('2026-09-11')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('1 year')
+  })
+
+  test('it shows only the months for an animal under a year old', () => {
+    // Arrange
+    const dateOfBirth = '2026-03-10'
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('6 months')
+  })
+
+  test('it uses the singular "month" for an animal exactly 1 month old', () => {
+    // Arrange
+    const dateOfBirth = '2026-08-10'
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('1 month')
+  })
+
+  test('it shows "Less than 1 month" for an animal under a month old', () => {
+    // Arrange
+    const dateOfBirth = '2026-09-01'
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('Less than 1 month')
+  })
+
+  test('it accepts a Date value', () => {
+    // Arrange
+    const dateOfBirth = new Date('2023-03-10')
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('3 years, 6 months')
+  })
+
+  test('it returns an empty string when there is no date of birth', () => {
+    // Arrange
+    const dateOfBirth = null
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('')
+  })
+
+  test('it returns an empty string for an unparseable date of birth', () => {
+    // Arrange
+    const dateOfBirth = 'not-a-date'
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('')
+  })
+
+  test('it returns an empty string for a date of birth in the future', () => {
+    // Arrange
+    const dateOfBirth = '2028-01-01'
+    const now = new Date('2026-09-10')
+
+    // Act
+    const age = formatAge(dateOfBirth, now)
+
+    // Assert
+    expect(age).toBe('')
+  })
+})

package/src/nunjucks/format-ear-tag.js

@@ -0,0 +1,26 @@
+// The UK country code, then a six-digit herd mark and a six-digit animal
+// number - e.g. "UK324537113236".
+const earTagPattern = /^(UK)(\d{6})(\d{6})$/
+
+/**
+ * @param {string} earTag
+ * @returns {string[] | undefined} the country code, herd mark and animal
+ *   number, or undefined if the ear tag isn't in that format
+ */
+function earTagGroups(earTag) {
+  return earTag.replace(/\s+/g, '').toUpperCase().match(earTagPattern)?.slice(1)
+}
+
+/**
+ * @param {string} earTag e.g. "UK324537113236"
+ * @returns {string} e.g. "UK 324537 113236" - the country code, herd mark
+ *   and animal number. Anything else - an ear tag in another format, or a
+ *   value that isn't a string - is returned as-is.
+ */
+export function formatEarTag(earTag) {
+  if (typeof earTag !== 'string') {
+    return earTag
+  }
+
+  return earTagGroups(earTag)?.join(' ') ?? earTag
+}

package/src/nunjucks/format-ear-tag.test.js

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'vitest'
+
+import { formatEarTag } from './format-ear-tag.js'
+
+describe('formatEarTag()', () => {
+  test('it splits an ear tag into country code, herd mark and animal number', () => {
+    // Arrange
+    const earTag = 'UK324537113236'
+
+    // Act
+    const formatted = formatEarTag(earTag)
+
+    // Assert
+    expect(formatted).toBe('UK 324537 113236')
+  })
+
+  test('it leaves an already formatted ear tag unchanged', () => {
+    // Arrange
+    const earTag = 'UK 324537 113236'
+
+    // Act
+    const formatted = formatEarTag(earTag)
+
+    // Assert
+    expect(formatted).toBe('UK 324537 113236')
+  })
+
+  test('it upper-cases the country code', () => {
+    // Arrange
+    const earTag = 'uk324537113236'
+
+    // Act
+    const formatted = formatEarTag(earTag)
+
+    // Assert
+    expect(formatted).toBe('UK 324537 113236')
+  })
+
+  test('it returns an ear tag with another country code as-is', () => {
+    // Arrange
+    const earTag = 'IE151234567890'
+
+    // Act
+    const formatted = formatEarTag(earTag)
+
+    // Assert
+    expect(formatted).toBe('IE151234567890')
+  })
+
+  test('it returns an ear tag of the wrong length as-is', () => {
+    // Arrange
+    const earTag = 'UK32453711323'
+
+    // Act
+    const formatted = formatEarTag(earTag)
+
+    // Assert
+    expect(formatted).toBe('UK32453711323')
+  })
+
+  test('it returns an ear tag in another format exactly as given', () => {
+    // Arrange
+    const earTag = 'ab 1234/x'
+
+    // Act
+    const formatted = formatEarTag(earTag)
+
+    // Assert
+    expect(formatted).toBe('ab 1234/x')
+  })
+
+  test('it returns a missing ear tag as-is', () => {
+    // Arrange
+    const earTag = null
+
+    // Act
+    const formatted = formatEarTag(earTag)
+
+    // Assert
+    expect(formatted).toBeNull()
+  })
+})