Date time picker

## Summary

Input component to allow users to select times and dates with multiple input methods.

very high complexity.

Match to existing component definition:

Text entry
Date input
Time input
Date picker
Required
Disabled
Interaction states
Large, default and small size variants.
Validation
scrollable and selectable time options
Limits

##💰 User value

Helps developers make clearer, more specific inputs for forms and selections. Helps end users by simplifying interactions when inputting a time and date rather than using a standard text box/input

##📚 User Stories
If relevant, describe the high-level functionality as user stories.

As an date time picker user:
I need to be able to select time down to the millisecond
So that i can choose precise intervals as part of my daily work

As a date time picker user:
I need to freely type a time and date in text format (DD/MM/YYYY HH:MM:SS:MMS)
So that i can input a time and date easily, without needing to interact with a modal/dialogue window or dropdown

As a date time picker user:
I need to have a 'Clear' button
So that i can reset the input to a blank state.

As a designer/developer creating an app that uses date time picker
I need to be able to set specific disabled timeframes
So that i can restrict the options within the picker to 'allowed' timeframes.

As a designer/developer creating an app that uses date time picker
I need to be able to pre-select a default time
So that I can convey a message to my users (i.e. suggested time, current, popular time...)

As a date time picker user:
I need to view a focus indicator for any element that can be interacted with
So that i know where my keyboard actions will target.

As a date time picker user:
I need to be able to navigate through the date time picker dropdown using a keyboard
so that i have equal access to its content.

## 📝 Acceptance Criteria
If relevant, describe in full detail the different interactions and edge cases that the component or patterns needs to fulfil.

**Variants**

L/D/S

-----------------------
**Properties**

- prop for date time input for calendar button + dropdown (see date picker)

- date format prop

- quick time select property
with configurable time intervals

**Calendar time input**

- Display seconds: Toggles the visibility of seconds in the helper text, placeholder text, time picker and input.

- Display milliseconds: Toggles the visibility of milliseconds in the helper text, placeholder text, time picker and input.

- 12hr/24hr clock: Toggles between a 12 hour and 24 hour clock selection and validation in picker and input.

- Default values: Define the default values that autofill on a partial time selection.

- Define placeholder: Allows selection of a specific time, now or 00:00:00 as the placeholder time displayed.

-----------------------
**Date time picker interaction behaviour**

*Input*

Given there is 'calendar' prop
when it is unselected
Then there will be no calendar icon or dropdown available
when it is selected
Then there will be a calendar icon and dropdown available

Given there is a 'date format' prop
when is it selected
Then there should be an option for MM/DD/YYYY, DD/MM/YYYY and YYYY/MM/DD formats

Given that the user types a full date and time into the input field,
When a complete/full date and time is valid and accepted,
Then the calendar dropdown should reflect the selected date and time When opened, but it should stay closed until the user opens it.

Given that the user types a full date and time into the input field,
When a complete/full date and time is invalid,
Then the calendar dropdown should reflect the default date and time when opened, but it should stay closed until the user opens it.

Given that the date time picker component has an input field,
When the user interacts with the input field,
Then it should behave like the date input and time input components.

Given that date time input is displayed
When it is navigated to
Then a focus area should surround the input area and a cursor should be active

Given that date time input is focussed and cursor active
When directional keys or tab are pressed
Then selection will move between individual date and time elements.

Given that the date time input is focussed and the last element selected
When tab is pressed
Then focus will move to the next page element

Given that focus is on date time input and last text element selected
When arrow key 'right' is pressed
Then nothing will happen

Given date time input is focussed and an acceptable input has been entered
When 'enter' is pressed
Or When focus is shifted to another page element
Then input will autocomplete to the specified date format specified by the developer (01/01/01 + 'Enter' = 01/01/2001)

Given that the date time input component is formed of several separate micro-inputs (DD/MM/YYYY HH:MM:SS:MMS)
When a user fills in one field
Then there should be auto-tabbing behaviour (i.e. in a HH:MM:SS format, if a user types '10' in the HH: field, then the field would update to '10:' and focus would move to the MM: input)

Given that input is focussed
When micro-inputs are selected with mouse
or When micro-inputs are moved to with 'tab'
Then cursor focus will move to that element

Given that the date time input is focussed and an input has been entered
When the clear button is selected
Then the date time input will be cleared and reverted to placeholder text

*Calendar*

Given that there is a date time picker component with an input field and a calendar button,
When the user clicks on the calendar button,
Then the calendar dropdown should open.

Given that the calendar can be expanded,
When the calendar is expanded,
Then it should use the same animation token as the Select component. (300ms CSS transition)

Given that the month or year view is navigated to,
When the month or year view is navigated to (and back to calendar view),
Then it should use the same animation token as the popover menu component. (Push in/out 300ms)

Given that the calendar is expanded
When it is presented on screen
Then it should be left-aligned with the Date Input component

Given that the calendar is expanded
When the page is scrolled beyond the calendar view
Then the calendar should appear above the date time input

Given that the user selects a date using the calendar dropdown,
When a date is selected,
Then the calendar dropdown should immediately move focus to the time input, and the input field should be updated with the selected date.

Given that the quick select prop is enabled
When the calendar dropdown is expanded
Then a list of selectable times, defined by the developer, will be available on the right of the date time picker

Given that the quick select prop is enabled
and the calendar time input focussed
When the tab key is pressed
Then focus should to the quick select prop

Given that the quick select prop is enabled
and focussed
When the tab key is pressed
Then focus should move to the 'Done' selection box.

*calendar Input*

see above time input.

Given that the date time picker calendar is open
When a time is input into the calendar
Then that time should be reflected on each micro input of the date & time input (for example 12:MM:SS on calendar = 12:00:00 on date time input)

Given that a date time picker calendar is open
When either month or year are changed prior to day selection
Then the change should not be reflected in date time input

Given that a date time picker calendar is open
When a day has been selected and month or year are changed
Then the change should be reflected in date time input

Given that the date time picker calendar is open
When an invalid time is input
Then an error state should display around the calendar input only

Given that the date time picker calendar is open and calendar time input is focussed
When the user has selected a valid date and successfully inputs an element of every micro-time-input or
When the user hits the 'enter' with partial time selection complete
Then the date time dropdown will close and values reflected in the date time input.

Given that the calendar time is focussed and last micro-input has cursor focus
When the user presses the tab key
Then the focus will move to the 'done' tick box

Given that date time calendar is open and the 'done' tick box focussed
When the user presses the 'enter' key or
When the user clicks with mouse
Then the current input will accepted and the dropdown will close

*Go to today*

Given that Go to today is selectable
When the user navigates to the button
Then the screen reader announces "Navigate to current date"

Given that the user is viewing the current month,
When the "Go to today" button is showing,
Then it should be disabled.

Given that the user is viewing a month which is not the current month,
When the "Go to today" button is showing,
Then it should be enabled, and When clicked, the calendar view should shift to the current month, and the button becomes disabled again.

*Clear*

Given that the "Go to today" prop is switched off,
When the prop is set to false,
Then there should be no button, and the "Clear" button should stay right-aligned.

Given that no date is selected,
When no date is selected,
Then the "Clear" button should remain disabled.

Given that a date is selected,
When the "Clear" button is clicked,
Then the input field should reset, but the calendar dropdown should stay open, and the "Clear" button should become disabled and the selected day in the calendar becomes unselected.

*Calendar numbers*

Given that the developer has specified a specific range of accepted dates,
When a range is set,
Then dates outside this range should be disabled in the calendar and should not be selectable.

Given that the developer has specified a specific range of accepted dates,
When a range is set, and the user is interacting with the input field,
Then the user should be allowed to type in any full date, but validation should specify that the date is not within the accepted range, and the error message should specify what dates are accepted.

Given that there is a prop to display the current day in the calendar,
When it is set to true,
Then the current day should be displayed in the calendar.

Given that there is a prop to display the current day in the calendar,
When it is set to false,
Then the current day should not be displayed in the calendar.

Given that the week start is set to Monday by default,
When the week start is set to Sunday,
Then this should be reflected in the calendar.

*Buttons*

Given that the arrow icon buttons allow users to move back and forth by 1 month,
When the user clicks the Tertiary button for the month,
Then the month view should be shown.

Given that the user clicks the Tertiary button for the year,
When the user clicks the Tertiary button for the year,
Then the year view should be shown, and the year ranges should be shown as XX01-XX10 (i.e. 1991-2000).

Given that the navigational arrows are used to shift between months,
When the navigational arrows are used to shift between months,
Then there should be no animation.

-------------------
**Validation**

*see guidance