feat(date picker): add date picker component

.eleventy.js

@@ -98,6 +98,8 @@ module.exports = function (eleventyConfig) {
     });
   });
 
+  eleventyConfig.addShortcode("dateInCurrentMonth", (day) => `${day}/${new Date().getMonth()+1}/${new Date().getFullYear()}`);
+
   eleventyConfig.addShortcode("lastUpdated", function (component) {
     if (process.env.STAGING) return '';
 

Dockerfile

@@ -7,7 +7,6 @@ COPY package.json package.json
 COPY package-lock.json package-lock.json
 RUN npm ci
 
-COPY assets assets
 COPY docs docs
 COPY src src
 COPY package package

docs/_includes/arguments/date-picker.md

@@ -0,0 +1,16 @@
+| Name         | Type   | Required | Description                                                                                                                      |
+| ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| id           | string | Yes      | The ID of the input.                |
+| name         | string | Yes      | The name of the input, which is submitted with the form data. |
+| value        | string | No       | Optional initial value of the input. |
+| formGroup    | object | No       | Additional options for the form group containing the text input component. See [formGroup](#options-date-picker-form-group). |
+| label        | object | Yes      | The label used by the text input component. See [GOV.UK text input documentation](https://design-system.service.gov.uk/components/text-input/) for label options. |
+| hint         | object | No       | Can be used to add a hint to a text input component. See [GOV.UK text input documentation](https://design-system.service.gov.uk/components/text-input/) for hint options. |
+| errorMessage | object | No       | Can be used to add an error message to the text input component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`. See [GOV.UK text input documentation](https://design-system.service.gov.uk/components/text-input/) for errorMessage options. |
+| minDate      | string | No       | Earliest date that can be selected (format dd/mm/yyyy) |
+| maxDate      | string | No       | Latest date that can be selected (format dd/mm/yyyy) |
+| exludedDates | string | No       | String of space separated dates that cannot be selected |
+| excludedDays | string | No       | String of space separated days of the week that cannot be selected |
+| weekStartDay | string | No       | Day of the week the calendar starts on. Either 'monday' or 'sunday'. Defaults to 'monday' |
+
+

docs/_includes/example.njk

@@ -6,10 +6,22 @@
 </div>
 <div class="app-tabs" data-module="app-tabs">
   <ul class="app-tabs__list" role="tablist">
-    <li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#html-default-{{ id }}" role="tab" id="tab_html-default-{{ id }}" aria-controls="html-default-{{ id }}">HTML</a></li>
-    <li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#nunjucks-default-{{ id }}" role="tab" id="tab_nunjucks-default-{{ id }}" aria-controls="nunjucks-default-{{ id }}">Nunjucks</a></li>
-    {%- if jsCode %}<li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#js-default-{{ id }}" role="tab" id="tab_js-default-{{ id }}" aria-controls="js-default-{{ id }}">JavaScript</a></li>{% endif -%}
-    {%- if figmaLink %}<li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#figma-default-{{ id }}" role="tab" id="tab_figma-default-{{ id }}" aria-controls="figma-default-{{ id }}">Figma</a></li>{% endif -%}
+    <li class="app-tabs__list-item" role="presentation">
+      <a class="app-tabs__tab" href="#html-default-{{ id }}" role="tab" id="tab_html-default-{{ id }}" aria-controls="html-default-{{ id }}">HTML <span class="govuk-visually-hidden">({{ title }})</span></a>
+    </li>
+    <li class="app-tabs__list-item" role="presentation">
+      <a class="app-tabs__tab" href="#nunjucks-default-{{ id }}" role="tab" id="tab_nunjucks-default-{{ id }}" aria-controls="nunjucks-default-{{ id }}">Nunjucks <span class="govuk-visually-hidden">({{ title }})</span></a>
+    </li>
+    {%- if jsCode %}
+    <li class="app-tabs__list-item" role="presentation">
+      <a class="app-tabs__tab" href="#js-default-{{ id }}" role="tab" id="tab_js-default-{{ id }}" aria-controls="js-default-{{ id }}">JavaScript <span class="govuk-visually-hidden">({{ title }})</span></a>
+    </li>
+    {% endif -%}
+    {%- if figmaLink %}
+    <li class="app-tabs__list-item" role="presentation">
+      <a class="app-tabs__tab" href="#figma-default-{{ id }}" role="tab" id="tab_figma-default-{{ id }}" aria-controls="figma-default-{{ id }}">Figma</a>
+    </li>
+    {% endif -%}
   </ul>
 
   <div class="app-tabs__panel app-tabs__panel--hidden" id="html-default-{{ id }}" data-module="app-copy" role="tabpanel" aria-labelledby="tab_html-default-{{ id }}">

docs/_includes/layouts/home.njk

@@ -24,6 +24,17 @@
     </div>
   </div>
 
+  <div class="govuk-width-container">
+    <div class="govuk-grid-row">
+      <div class="govuk-grid-column-full">
+        <h2 class="govuk-heading-l">What’s new</h2>
+        <p class="govuk-body">29 July 2024: We’ve released a new <a href="/components/date-picker">date picker component</a> to help users select a date quickly and easily.</p>
+        <p class="govuk-body"><a href="https://docs.google.com/forms/d/1i7rinQINSjdQ6w_SChXqxQFTttPMgfcSfPamq8YRnP8/edit" class="govuk-link">Sign up to get emails</a> about the MoJ Design System.</p>
+        <hr class="govuk-section-break govuk-section-break--l govuk-section-break--visible">
+      </div>
+    </div>
+  </div>
+
   <div class="govuk-width-container">
     <div class="govuk-grid-row">
       <div class="govuk-grid-column-one-half">
@@ -32,7 +43,7 @@
             <h2 class="govuk-heading-l govuk-!-margin-bottom-3">Components</h2>
             <p class="govuk-body">Save time with reusable, accessible components for forms, navigation, panels, tables and more.</p>
             <p class="govuk-body">
-              <a href="/components" class="govuk-link"><strong>Find a component</strong></a>
+              <a href="/components" class="govuk-link">Find a component</a>
             </p>
           </section>
         </article>
@@ -44,13 +55,15 @@
             <h2 class="govuk-heading-l govuk-!-margin-bottom-3">Patterns</h2>
             <p class="govuk-body">Help users complete common tasks like uploading files, filtering lists, and getting help.</p>
             <p class="govuk-body">
-              <a href="/patterns" class="govuk-link"><strong>Find a pattern</strong></a>
+              <a href="/patterns" class="govuk-link">Find a pattern</a>
             </p>
           </section>
         </article>
       </div>
     </div>
 
+    <hr class="govuk-section-break govuk-section-break--l govuk-section-break--visible">
+
     {{ content | safe }}
   </div>
 

docs/_includes/layouts/partials/suggest-a-change-and-help.njk

@@ -3,25 +3,25 @@
 
 <div class="govuk-!-padding-bottom-3"></div>
 
-<div class="govuk-notification-banner" role="region" aria-labelledby="govuk-notification-banner-title" data-module="govuk-notification-banner">
+<div class="govuk-notification-banner" role="region" data-module="govuk-notification-banner">
   <div class="govuk-notification-banner__content">
-  <p class="govuk-notification-banner__heading">
-    Suggest a change
-  </p>
-    <p class="govuk-notification-banner__body">
-      To help improve the MoJ Design System, you can suggest changes.
-    </p>
+  <h2 id="govuk-notification-banner-title" class="govuk-notification-banner__heading">
+  Suggest a change
+</h2>
     <p class="govuk-notification-banner__body">
-      Tell us about the change you're proposing by using the <a href="https://forms.gle/FpDpbgttwmfmcz8o7" class="govuk-link">suggest a change form</a>. The MoJ Design System Group will be notified of your suggestion and will review it.
+     You can <a href="https://forms.gle/FpDpbgttwmfmcz8o7" class="govuk-link">suggest a change to improve the MoJ Design System</a>.
+  </p>
+  <p>
+     The MoJ Design System team will review it.
     </p>
 
     <hr class="govuk-section-break govuk-section-break--l govuk-section-break--visible">
 
-    <p class="govuk-notification-banner__heading">
-      Need help?
-    </p>
+    <h2 class="govuk-notification-banner__heading">
+      Get help  
+    </h2>
       <p class="govuk-notification-banner__body">
-        The MoJ Design System Group provides support for users of the MoJ Design System. <a href="/community/help-and-feedback" class="govuk-link">Contact us</a> to ask for help.
+      <a href="/community/help-and-feedback" class="govuk-link">Contact the MoJ Design System team</a> for support.
       </p>
 
   </div>

docs/assets/stylesheets/components/_example.scss

@@ -24,7 +24,7 @@
   }
 
   .app-example__new-window {
-    @include govuk-font($size: 14);
+    @include govuk-font($size: 16);
     border: 1px solid $govuk-border-colour;
     position: absolute; top: -1px; left: -1px;
 
@@ -34,18 +34,18 @@
       background-color: white;
       color: govuk-colour("blue");
       display: block;
-      padding: 5px 10px;
+      margin: 8px;
       text-decoration: none;
     }
 
     a:hover {
-      color: govuk-colour("light-blue");
+      color: $govuk-link-hover-colour;
     }
 
     a:focus {
-      // color: $govuk-focus-text-colour;
+      color: $govuk-focus-text-colour;
       background-color: $govuk-focus-colour;
-      // box-shadow: 0 -2px $govuk-focus-colour, 0 4px $govuk-focus-text-colour;
+      box-shadow: 0 -2px $govuk-focus-colour, 0 4px $govuk-focus-text-colour;
       // border-color: $govuk-focus-text-colour;
     }
 

docs/community/suggest-a-change.md

@@ -1,6 +1,6 @@
 ---
+title: Suggest a Change
 layout: layouts/community.njk
-title: Suggest a change
 ---
 
 To help improve the MoJ Design System, you can suggest changes to components and patterns.

docs/components/date-picker.md

@@ -3,51 +3,115 @@ layout: layouts/component.njk
 title: Date picker
 ---
 
-<span class="govuk-caption-xl">This component has recently been contributed to the MoJ Design System and is being developed.</span>
+<span class="govuk-caption-xl">The date picker component enables users to select a date from a calendar.  </span>
 
-## Status of development
+{% example "/examples/date-picker", 590 %}
 
-The below criteria all need to be met for a component to be considered as fully developed for use within the MoJ Design System.
 
-This page will be updated as the component is developed.
+## Overview
+
+When users first open the date picker's calendar it'll show today's date. Users do not have to use this calendar view to select a date - they can also enter one directly into the text field.
+
+### When to use
+
+Users might want to use the calendar view:
+
+- for a relative date or one they need to look up, for example last Thursday or next Wednesday
+- to enter today's date more quickly
+- for available dates only, such as for prison visits
+
+### When not to use
+
+Do not use the date picker:
+
+- for a memorable date, such as a user's date of birth
+- for a date that users know or can easily look up, like an appointment date on a letter
+- when only a rough date is needed, for example just a month and year
+
+Use the [GOV.UK Design System's date input component](https://design-system.service.gov.uk/components/date-input/) instead.
+
+### Things to consider
+
+Date pickers are fully navigable using a keyboard, but can be slow for keyboard-only and screen reader users.
+
+### Similar or linked components
+
+There's also the ['Ask users for dates' pattern in the GOV.UK Design System](https://design-system.service.gov.uk/patterns/dates/).
+
+
+## How to use
+
+### Hint text
+
+The date picker hint text is set to 17/5/2024. This can be changed to a more helpful date, for example the start of a scheme. Add a full stop at the end.
+
+### Excluding dates
+
+You can exclude (or disable) specific dates and days of the week from the date picker, for example bank holidays or every weekend.
+
+{% example "/examples/date-picker-excluded-dates", 590 %}
+
+You need to add server-side validation for when users enter an unavailable date directly into the text field (rather than in the calendar). This will show them an error message.
+
+Excluded dates have the correct colour contrast ratio with the date text and calendar background. This is WCAG 2.2 compliant. However, these dates may be harder to view for users with low vision or colour blindness, so there’s also a strikethrough. Numbers with a strikethrough can be harder for people with dyscalculia to read.  
+
+If there are not many available dates, users will have to navigate a lot to find one. Consider listing these dates with radio buttons instead.  
+
+### Error messages
+
+Follow the [GOV.UK Design System guidance on error messages](https://design-system.service.gov.uk/components/error-message/).
+
+{% example "/examples/date-picker-error", 590 %}
 
 <table class="govuk-table">
   <thead class="govuk-table__head">
     <tr class="govuk-table__row">
-      <th scope="col" class="govuk-table__header">Development criteria</th>
-      <th scope="col" class="govuk-table__header">Status</th>
+      <th scope="col" class="govuk-table__header">Error state</th>
+      <th scope="col" class="govuk-table__header">Error message</th>
     </tr>
   </thead>
   <tbody class="govuk-table__body">
     <tr class="govuk-table__row">
-      <th scope="row" class="govuk-table__header">WCAG 2.2 compliant</th>
-      <td class="govuk-table__cell"><strong class="govuk-tag govuk-tag--grey">
-          Being reviewed
-        </strong></td>
+      <th scope="row" class="govuk-table__header">No date is entered or selected from the calendar</th>
+      <td class="govuk-table__cell">Enter or select a date</td>
     </tr>
     <tr class="govuk-table__row">
-      <th scope="row" class="govuk-table__header">HTML / Nunjucks version</th>
-      <td class="govuk-table__cell"><strong class="govuk-tag govuk-tag--orange">
-          In progress
-        </strong></td>
+      <th scope="row" class="govuk-table__header">The date is in the wrong format</th>
+      <td class="govuk-table__cell">Enter the date in the correct format, for example, 17/5/2024</td>
     </tr>
     <tr class="govuk-table__row">
-      <th scope="row" class="govuk-table__header">Figma version</th>
-      <td class="govuk-table__cell"><strong class="govuk-tag govuk-tag--orange">
-          In progress
-        </strong></td>
+      <th scope="row" class="govuk-table__header">The date does not exist</th>
+      <td class="govuk-table__cell">Enter a real date</td>
     </tr>
     <tr class="govuk-table__row">
-      <th scope="row" class="govuk-table__header">Documentation</th>
-      <td class="govuk-table__cell"><strong class="govuk-tag govuk-tag--grey">
-          Being reviewed
-        </strong></td>
+      <th scope="row" class="govuk-table__header">The date is incomplete</th>
+      <td class="govuk-table__cell">Enter a full date, for example 17/5/2024</td>
     </tr>
     <tr class="govuk-table__row">
-      <th scope="row" class="govuk-table__header">Researched and tested</th>
-      <td class="govuk-table__cell"><strong class="govuk-tag govuk-tag--red">
-          Not started
-        </strong></td>
+      <th scope="row" class="govuk-table__header">The date is excluded</th>
+      <td class="govuk-table__cell">Select an available date from the calendar</td>
     </tr>
   </tbody>
 </table>
+
+###  Using multiple date pickers
+
+If you're using more than one date picker, give each text field its own error summary and message (even if the error is the same).
+
+
+## Examples
+
+### Filtering information with a date picker
+
+<p><img src="/assets/images/date-picker-filter-example.svg" alt="A screenshot with the title 'Attended appointments'. In a grey box is the title Filter, underneath is the title Date and then a text input field. The calendar icon and a green 'Apply filter' button is on the right. Below this element is the text '7 appointments'. Details of these appointments are shown."></p>
+
+### Asking a question with a date picker
+
+<p><img src="/assets/images/date-picker-question-example.svg" alt="A screenshot with the title 'What date do you want to view appointments for?' Underneath is the title 'Date' and then a text input field with the calendar icon. Underneath that is a green 'Continue' button."></p>
+
+
+## Contributors
+
+Thanks to Dom Billington, Eddie Shannon, David Middleton, and the DPS Connect team for contributing this component.
+
+This component was based on the [Scottish Government Design System date picker](https://designsystem.gov.scot/components/date-picker).

docs/examples/date-picker-error/index.njk

@@ -0,0 +1,22 @@
+---
+layout: layouts/example.njk
+title: Date Picker (example)
+arguments: date-picker
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=792-861&t=6DfPOX7RAnjrVE0j-0
+---
+
+{%- from "moj/components/date-picker/macro.njk" import mojDatePicker -%}
+
+{{ mojDatePicker({
+  id: "date",
+  name: "date",
+  label: {
+      text: "Date"
+  },
+  hint: {
+    text: "For example, 17/5/2024."
+  },
+  errorMessage: {
+    text: 'Enter or select a date'
+  }
+}) }}

docs/examples/date-picker-excluded-dates/index.njk

@@ -0,0 +1,23 @@
+---
+layout: layouts/example.njk
+title: Date Picker Excluded Dates (example)
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=792-861&t=6DfPOX7RAnjrVE0j-0
+---
+
+{%- from "moj/components/date-picker/macro.njk" import mojDatePicker -%}
+
+{{ mojDatePicker({
+  id: "date",
+  name: "date",
+  label: {
+      text: "Date"
+  },
+  hint: {
+    text: "For example, 17/5/2024."
+  },
+  value: "10/04/2025",
+  minDate: "01/04/2025",
+  maxDate: "30/04/2025",
+  excludedDates: "02/04/2025 18/04/2025 21/04/2025",
+  excludedDays: "saturday sunday"
+}) }}

docs/examples/date-picker-excluded-days/index.njk

@@ -0,0 +1,19 @@
+---
+layout: layouts/example.njk
+title: Date Picker Excluded Days (example)
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=792-861&t=6DfPOX7RAnjrVE0j-0
+---
+
+{%- from "moj/components/date-picker/macro.njk" import mojDatePicker -%}
+
+{{ mojDatePicker({
+  id: "date",
+  name: "date",
+  label: {
+      text: "Date"
+  },
+  hint: {
+    text: "For example, 17/5/2024."
+  },
+  disabledDays: "saturday sunday"
+}) }}