Skip to content

Date Time Input

Jump to bottom
Ivaylo Barakov edited this page May 19, 2022 · 7 revisions

Date time input specification

Owned by

Team: Codex

Radoslav Karaivanov

Requires approval from

  • | Date:

Signed off by

  • Product Owner: Radoslav Mirchev | Date:
  • Platform Architect: Damyan Petev | Date:

Revision history

Version Author Date Notes
1 Ivaylo Barakov 20-Mar-2022 First draft

Overview

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.

Acceptance criteria

  1. Should provide a mask, specifying the date/time inputFormat and displayFormat
  2. Should provide a prompt symbol for customizing the unfilled parts of the mask
  3. Should support static symbols (literals) in the mask
  4. Should support all the properties/API of the igc-input element where applicable
  5. Should correctly manage and report its validation state, if any validation constraints or required positions are applied
  6. Should be supported as a component which participates in an igc-form submission
  7. Should support the following custom input formats

User stories

Developer stories:

As a developer I expect to be able to:

  • define a mask specifying the date/time inputFormat and displayFormat
  • use the mask as a placeholder if the property is not set
  • specify the prompt character
  • set predefined displayFormat in 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 minValue and maxValue properties 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

Functionality

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.

Custom input format

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.

Custom display 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
Date 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 Zero padded 01, 23
HH Zero padded 01, 23
Minute m Minimum digits 1, 60
mm Zero padded 01, 60
Second s Minimum digits 1, 60
ss Zero padded 01, 60
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.

Keyboard Navigation

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

End-user experience

TODO

Developer experience

TODO

API

igc-date-time-input

Mixins: SizableMixin, EventEmitterMixin

Properties

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 mask 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 value 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.

Methods

Name Description Return type
clear Clears the input element of user input. (): void
stepUp Increments the current date/time portion. (): void
stepDown Decrements the current date/time portion. (): void
blur Removes focus from the component. (): void
focus Focuses the component. (options?: FocusOptions | undefined): void

Events

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

Slots

Name Description
helper-text Renders content below the input
prefix Renders content before the input
suffix Renders content after the input

CSS Shadow Parts

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

Assumptions and limitations

  • 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.

Test scenarios

  • 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/Down 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.
Clone this wiki locally