Skip to content

Commit

Permalink
docs(date picker component): adding guidance for date picker component
Browse files Browse the repository at this point in the history
  • Loading branch information
@robertjmccarthy
robertjmccarthy committed Jul 1, 2024
1 parent c9c648d commit f3bd535
Showing 1 changed file with 94 additions and 28 deletions.
122 changes: 94 additions & 28 deletions docs/components/date-picker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,51 +3,117 @@ 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 allows users to pick a date by entering a date or choosing from a calendar.</span>

## Status of development
{% example "/examples/date-picker", 220 %}

The below criteria all need to be met for a component to be considered as fully developed for use within the MoJ Design System.
## When to use

This page will be updated as the component is developed.
A date picker helps users choose a date by using a calendar view. This may help users to choose:
- a relative date - for example, last Tuesday or next Wednesday
- a date they don’t commonly use
- today’s date
- available dates only

The calendar view is not mandatory - users can still input a date into the text field.

## When not to use

Do not use if users need to enter a memorable date (e.g. their date of birth) or a date they can easily look up (e.g. an appointment date on a letter they have received). Instead, use the [date input component](https://design-system.service.gov.uk/components/date-input/) from the GOV.UK Design System.

## Similar or linked components

The GOV.UK Design System has a [date input component](https://design-system.service.gov.uk/components/date-input/) and a [pattern for asking users for dates](https://design-system.service.gov.uk/patterns/dates/).

## Hint text
INCLUDE SOMETHING HERE === The date picker default hint text is 17/05/2024. Always include a full-stop at the end.

INLUDE SOMETHING HERE === If using hint text that is different from the default date, use a date that is within the context of your service. And, consider using numbers that are visually different to avoid confusion for some users. For example, 08/03/2023 can be confusing for some users.

## Disabled dates

You can set allowed date ranges if you need a user to pick a date within a date range. Individual dates and date ranges can also be disabled in the calendar view.

Users may type unavailable or disabled dates in the input field, so error messages will be necessary.

{% example "/examples/date-picker", 220 %}

INCLUDE SOMETHING HERE === You can disable specific dates (e.g. 17/10/2024, 18/10/2024, 19/10/2024).

INCLUDE SOMETHING HERE === You can disable days of the week (e.g. every Saturday and Sunday).

## From and to dates

Allow users to pick to and from dates by stacking 2 date pickers together.

When stacking 2 date pickers horizontally or vertically, apply padding that is consistent with the rest of your product.

### Vertically stacked

Multiple date picker components can be vertically stacked. This is useful when used in vertical filters or forms.

{% example "/examples/date-picker", 220 %}

### Horizontally stacked

Multiple date picker components can be horizontally displayed. This is useful when used in horizontal filters.

{% example "/examples/date-picker", 220 %}

## Errors

Follow the guidance in the [GOV.UK Design System](https://design-system.service.gov.uk/components/error-message/) for error messages.

{% example "/examples/date-picker", 220 %}

### Error messages in English and Welsh

<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">English error message</th>
<th scope="col" class="govuk-table__header">Welsh 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>
</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">If no date is entered or picked from the calendar</th>
<td class="govuk-table__cell">Enter or pick a date</td>
<td class="govuk-table__cell">Nodwch neu dewiswch ddyddiad</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">If the date entered is in the wrong format</th>
<td class="govuk-table__cell">Enter the date in the correct format, for example, 17/5/2024</td>
<td class="govuk-table__cell">Rhowch y dyddiad yn y fformat cywir, er enghraifft, 17/5/2024</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">If the date entered does not exist</th>
<td class="govuk-table__cell">The date you entered must be a real date</td>
<td class="govuk-table__cell">Rhaid i'r dyddiad a roesoch fod yn ddyddiad go iawn</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">If the date entered is incomplete</th>
<td class="govuk-table__cell">Enter a complete date, for example, 17/5/2024</td>
<td class="govuk-table__cell">Nodwch ddyddiad cyflawn, er enghraifft, 17/5/2024</td>
</tr>
</tbody>
</table>

### If you are using multiple date pickers

Make sure you use error summaries and error messages for each text field. Even if the same errors occur for multiple date pickers.

## Examples

Text

## Considerations

Whilst the date picker is fully navigable using a keyboard, date pickers can be slow and difficult to use for keyboard only users.

Another challenge for users, especially those with poor vision or colour blindness, is seeing the unavailable or disabled dates.

## Contributors

Thanks to **Dom Billington**, **Eddie Shannon**, **David Middleton**, and the **DPS Connect team** for contributing this component.

0 comments on commit f3bd535

Please sign in to comment.