-
Notifications
You must be signed in to change notification settings - Fork 4
Date Time Input
Ivaylo Barakov edited this page Jul 22, 2022
·
7 revisions
- Date time input specification
Team: Codex
Radoslav Karaivanov
- | Date:
- Product Owner: Radoslav Mirchev | Date:
- Platform Architect: Damyan Petev | Date:
| Version | Author | Date | Notes |
|---|---|---|---|
| 1 | Ivaylo Barakov | 20-Mar-2022 | First draft |
| 1.01 | Ivaylo Barakov | 22-Jul-2022 | Edit "Custom display format" section |
A date time input is an input field that lets you set and edit the date and time in a chosen input element. The display and input formats are customizable, as well as min and max values.
- Should provide a mask, specifying the date/time
inputFormatanddisplayFormat - Should provide a prompt symbol for customizing the unfilled parts of the mask
- Should support static symbols (literals) in the mask
- Should support all the properties/API of the igc-input element where applicable
- Should correctly manage and report its validation state, if any validation constraints or required positions are applied
- Should be supported as a component which participates in an igc-form submission
- Should support the following custom input formats
Developer stories:
As a developer I expect to be able to:
- define a mask specifying the date/time
inputFormatanddisplayFormat - use the mask as a placeholder if the property is not set
- specify the prompt character
- set predefined
displayFormatin a simple manner -short,long,medium,full - configure the editor as editable, read-only and disabled
- set a default date/time value
- specify if incrementing continues past the maximum and wraps around (by default it does) e.g. for minutes from 59 to 00 or just stays at it.
- set
minValueandmaxValueproperties which control the validity of the input - expect the editor to complete partially entered dates
- expect that the editor will clear invalid input on blur
- enable/disable the zero prefixes for dates/months/hours e.g. 9:03 or 09:03
- specify the step -
spinDelta, at which the selected time part will be incremented/decremented
End user stories:
As an end user, I want:
- To be able to display date/time values based on a defined mask
- To be able to edit the date/time value in the editor
- To be able to paste or drag-and-drop dates from elsewhere into the input
- The fields that need to be filled, to be clearly indicated with prompt characters
- To see a placeholder text when the input is empty, suggesting me what to type in
- The editor to handle partial dates
- The editor to have buttons for incrementing/decrementing the currently selected date/time portion
- To be able to use the mouse wheel to spin date/time portions. The spinning should occur for the date/time portion where the caret currently is in the editor
A date time input is a text field that allows the user to set and edit the date and time in a chosen input element, controlled and filtered by a predefined mask. Helper text, placeholders, and visual states can be updated accordingly upon string input/interaction and data can be submitted.
| Format | Description |
|---|---|
d |
Date, will be coerced with a leading zero while editing. |
dd |
Date with an explicitly set leading zero. |
M |
Month, will be coerced with a leading zero while editing. |
MM |
Month with an explicitly set leading zero. |
yy |
Short year format. |
yyyy |
Full year format. |
h |
Hours in 12-hour format, will be coerced with a leading zero while editing. |
hh |
Hours in 12-hour format with an explicitly set leading zero. |
H |
Hours in 24-hour format, will be coerced with a leading zero while editing. |
HH |
Hours in 24-hour format, with an explicitly set leading zero. |
m |
Minutes, will be coerced with a leading zero while editing. |
mm |
Minutes with an explicitly set leading zero. |
tt |
AM/PM section for 12-hour format. |
The date time input exposes predefined formats for displaying date/time in various manners. All of the examples below are given in en-US locale.
| Option | Example |
|---|---|
short |
7/17/22, 12:00 AM |
medium |
Jul 17, 2022, 12:00:00 AM |
long |
July 17, 2022 at 12:00:00 AM GMT+3 |
full |
Sunday, July 17, 2022 at 12:00:00 AM Eastern European Summer Time |
shortDate |
7/17/22 |
mediumDate |
Jul 17, 2022 |
longDate |
July 17, 2022 |
fullDate |
Sunday, July 17, 2022 |
shortTime |
12:00 AM |
mediumTime |
12:00:00 AM |
longTime |
12:00:00 AM GMT+3 |
fullTime |
12:00:00 AM Eastern European Summer Time |
Furthermore, users can construct a displayFormat string using the supported symbols described in the following table.
| Type | Format | Description | Example |
|---|---|---|---|
| Day of month | d |
Minimum digits. | 7, 17 |
dd |
Zero padded. | 07, 17 | |
| Month | M |
Minimum digits. | 3, 10 |
MM |
Zero padded. | 03, 10 | |
MMM |
Abbreviated | Oct | |
MMMM |
Wide | October | |
MMMMM |
Narrow | O | |
| Year | y |
Numeric | 2022 |
yy |
Two digit | 22 | |
yyy |
Numeric | 2022 | |
yyyy |
Numeric | 2022 | |
| Hour 1-12 | h |
Minimum digits | 1, 12 |
hh |
Zero padded | 01, 12 | |
| Hour 1-24 | H |
Minimum digits | 1, 23 |
HH |
Zero padded | 01, 23 | |
| Minute | m |
Minimum digits | 1, 59 |
mm |
Zero padded | 01, 59 | |
| Second | s |
Minimum digits | 1, 59 |
ss |
Zero padded | 01, 59 | |
| Time Period | t |
Abbreviated | AM, PM |
tt |
Abbreviated | AM, PM | |
ttt |
Short | noon | |
tttt |
Long | noon | |
ttttt |
Narrow | n |
Note: Many locales use the same time period string, irrespective of the format specified. Also, it has an effect only if a 12-hour clock is used.
| Keys | Description |
|---|---|
| ← | Move one character to the left |
| → | Move one character to the right |
| Home | Move to the beginning |
| End | Move to the end |
| Ctrl / Command + ← | Move to the beginning of the date/time section - current one or left one |
| Ctrl / Command + → | Move to the end of the date/time section - current on or right one |
| Focus on a date/time part + ↓ | Decrements a date/time part |
| Focus on a date/time part + ↑ | Increments a date/time part |
| Ctrl / Command + ; | Sets the current date/time as the value of the editor |
TODO
TODO
Mixins: SizableMixin, EventEmitterMixin
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
dir |
dir |
"ltr" | "rtl" | "auto" |
"auto" | The direction attribute of the control. |
label |
label |
string |
The label for the control. | |
inputFormat |
input-format |
string |
The date pattern to apply on the input. | |
placeholder |
placeholder |
string |
Placeholder for the input. | |
prompt |
prompt |
string |
The prompt symbol to use for unfilled parts of the mask. | |
locale |
locale |
string |
"en" | The locale settings used in displayFormat. |
displayFormat |
display-format |
string |
The display date pattern of the editor. | |
size |
size |
"small" | "medium" | "large" |
"medium" | Determines the size of the component. |
value |
value |
Date |
The value of the input. | |
minValue |
min-value |
Date |
Sets the minimum value required for the editor to remain valid. | |
maxValue |
max-value |
Date |
Sets the maximum value required for the editor to remain valid. | |
spinLoop |
spin-loop |
boolean |
true | Loop over the currently spun segment. |
| Name | Type | Description |
|---|---|---|
clear |
(): void |
Clears the input element of user input. |
blur |
(): void |
Removes focus from the control. |
focus |
(options?: FocusOptions | undefined): void |
Sets focus on the control. |
stepUp |
(datePart?: DatePart, delta?: number): void |
Increments the current date/time portion. |
stepDown |
(datePart?: DatePart, delta?: number): void |
Decrements the current date/time portion. |
setCustomValidity |
(message: string): void |
Sets a custom validation message for the control. As long as message is not empty, the control is considered invalid. |
setRangeText |
(replacement: string, start: number, end: number, _selectMode?: "select" | "start" | "end" | "preserve"): void |
Replaces the selected text in the control and re-applies the mask |
setSelectionRange |
(start: number, end: number, direction?: "none" | "backward" | "forward" | undefined): void |
Sets the text selection range of the control |
| Event | Description |
|---|---|
igcBlur |
Emitted when the control loses focus |
igcChange |
Emitted when an alteration of the control's value is committed by the user |
igcFocus |
Emitted when the control gains focus |
igcInput |
Emitted when the control receives user input |
| Name | Description |
|---|---|
helper-text |
Renders content below the input |
prefix |
Renders content before the input |
suffix |
Renders content after the input |
| Part | Description |
|---|---|
container |
The main wrapper that holds all main input elements |
helper-text |
The helper text wrapper |
input |
The native input element |
label |
The native label element |
prefix |
The prefix wrapper |
suffix |
The suffix wrapper |
- The igc-date-input does not expose a type attribute since it is always an input of type text
- Undo/redo behavior is currently not supported.
- Should correctly set default prompt, mask and placeholder values
- Should correctly update mask according to the input format
- Should correctly update mask according to the locale
- Should correctly use display format when defined
- Should correctly switch between pre-defined display formats
- Should correctly clear value on clear
- Should correctly increment/decrement
- Should initialize new date on stepUp/stepDown if value is empty
- Should correctly set value by providing an ISO string
- Should correctly increment/decrement different date/time parts based on spinDelta
- Should correctly increment/decrement different date/time parts based on spinLoop
- Should correctly increment/decrement with mouse wheel and the arrow buttons
- Should correctly fill the missing parts on blur if input is incomplete
- Should clear input on blur if value is an invalid date
- Should respect min/maxValue
- Should correctly set min/maxValue by providing an ISO string
- Should correctly switch between valid/invalid state when required