github-actions[bot]
commented
10 months ago Welcome 👋
Welcome to the ic-ui-kit repo, thank you for raising an issue!
How to contribute
Please read our CONTRIBUTING.md, which explains our ways of working and guidelines for contributions.
Code of Conduct
We'd appreciate it if you could read and abide by our Code of Conduct, as we wish to foster an inclusive and respectful community.
GCHQ-Developer-094
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