DateTime Formatting & Guidance

[SOjaHPE]

Summary

There is a need across our platform to establish guidelines around the display of time and date stamps.

ToDos

• [x] #3388
• [x] #3450
• [ ] ...

Background

Storage Time / Date Stamp Requirements-

• RFC 3339 (and ISO 8601) standards in UTC+0 timezone • Storages current standard is that the API returns the Timestamps in conformance to RFC 3339 (and ISO 8601) standards in UTC+0 timezone.

Infosight Use Cases

1. Data is aggregated across time zones according to UTC
2. Showing both time periods in the UI. That way, users can see their local time zone and are told why a day doesn't start when they'd expect it to

Manually Entering Dates

• The user’s input should be recognized no matter which separator format users chose to use when entering the date, e.g. dots, forward/back slashes, dashes, spaces between the month, day, and year component
• Whether a user prepends leading zeros or not, their inputs should be recognized so long as the system has separators to differentiate the month, day and year inputs

• Time formatting

• Default - 12-hour AM/PM formatting in the end user’s time zone e.g. 9:00 AM PT
• 24-hour formatting
• Fixed time
  • UTC
  • Local time zone
• Relative time
  • based on UTC
    • UTC+8, UTC-1
  • Showing local time zone
• Friendly ‘TimeSince’ format - abbreviate minute, hour, month?
  • 1 min ago
  • 1 hr ago
  • 3 days ago
  • 1 month ago
• Absolute date and time
  • YYYY/MMM/DD 4:00 AM PT

Notes from Edgar and Misc. Sources

Can appear in many contexts:

• Table column
• Attribute/Value Lists
• Notification
• Log files
• Emails (paragraph)   Can be rendered by the back-end for output to log files. Can be transmitted by API to UI for display. Can be stored in a database.   May be presented as:
• Date
• Date and time
• Including seconds (and fractional seconds)
• Including timezone   Might apply to:
• When something happened (e.g. a task completed or a user approved an order)
• An expiration date (e.g. license expires)
• When something is scheduled   Considerations
• When multiple timestamps are in close proximity (column, list), use a numeric format for ease of sorting/comparison.  E.G.: 11/11/2020, 02:54 AM
• Always output timestamps in the browser locale.
• APIs should store and transmit timestamps numerically in UTC for conversion by the UI.
• If/when a timestamp must be stored in a file in a readable format (e.g. textual log file), it must include the timezone.
• It is best practice to emit a time with a timestamp and not just a date.  For example, if a license expires at 10PM on November 11th, 2021 MST, Simply showing the date portion may confuse a user.  For example, this timestamp converts to 10:30AM November 12th, 2021 IST.  An Indian user seeing a date stamp of Nov 12, 2021 could reasonably expect that the expiration is at midnight -- and would be wrong.
• Show seconds/fractional for items of a logging nature.  If the user needs to replay history, they need to know exactly when things happened (started/ended)
• When shown alone, a more human readable format may be preferable (notification, paragraph). E.G.: Monday, November 11th, 2021
• When to use something like "3 minutes ago"? Use it as an annotation on a timestamp to ease understanding. Use for timestamps indicating historical events, not future events.
  • Use minutes (e.g. N minutes ago) for…
  • Use days (e.g. N days ago) for timestamps at least 24 hours old, but < 1 week.
  • Use weeks (e.g. 1 week ago) for timestamps > 1 week, but < 1 month.
  • Use months (e.g. 5 months ago) for timestamps >1 month, but < 1 year.
  • Don't annotate for older timestamps.   Use cases
• Individual dates: e.g. "Set appointment for 1/2/2022".  When dates are used in a context like this, zero-padding is not needed.
• Columns of dates.  When comparing columnar data, dates and times should be zero-padded (e.g. 01/02/2022 or 05:06:27) to aid in comparing dates.
• Granularity depends on context.  In a casual context, things like seconds or tenths/hundreths of seconds can be dropped.  In fact, it may be ok to say "1 minute ago", "2 days ago", etc in a casual context.  But, drilling in to details should provide additional detail.
• Data entry of date: use the DS date picker.
• Data entry of time: TBD
• Data entry of date and time: TBD   Durations
• Don't force the user to do the math.  We should know when things started and ended and should include duration information for the user.
• Consider that a submission time does not always equal a start time.  Often, a job/task might be waiting for resources before it starts executing.  Depending on context, the wait time may or may not be included in a duration/elapsed time.       https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat // APIs should always store timestamps in UTC and then they get converted to local time by the UI for display. // For log files, there are two options: // 1) always output timestamps in UTC, indicating UTC in the output. // 2) allow the user to specify a default timezone and always output timestamps //    in that timezone, specifying the timezone in the output.   const date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738)); // Results below assume UTC timezone - your results may vary   // Specify default date formatting for language (locale) console.log(new Intl.DateTimeFormat('en-US').format(date)); // expected output: "12/20/2020"   // Specify default date formatting for language with a fallback language (in this case Indonesian) console.log(new Intl.DateTimeFormat(['ban', 'id']).format(date)); // expected output: "20/12/2020"   // Specify date and time format using "style" options (i.e. full, long, medium, short) console.log(new Intl.DateTimeFormat('en-GB', { dateStyle: 'short', timeStyle: 'full' }).format(date)); // Expected output "Sunday, 20 December 2020 at 14:23:16 GMT+11"   options = {   year: 'numeric', month: 'numeric', day: 'numeric',   hour: 'numeric', minute: 'numeric', second: 'numeric' }; var dateFormat = new Intl.DateTimeFormat('default', options); // to specify options but use the browser's default locale, use 'default' console.log(dateFormat.format(date)); // → "12/19/2012, 19:00:00" var usedOptions = dateFormat.resolvedOptions();   console.log(usedOptions.timeZone);         Document here: https://design-system.hpe.design/foundation     Other localization issues: I18N: Is your app internationalized?
• Does it uses message catalogs for messaging?
• Does it pay attention to browser locale?
• Does it may optionally include a language preference (possibly for crafting internal/async messages)?
• Does it handle time/date/timezone/currency display appropriately? L10N: Is you app localized in more than just English?  What languages?
• Just the app?
• What about documentation/user guides? Accessibility
• Does your app support light/dark mode?
• Does your app pass WCAG AA? Responsiveness:
• What browsers does your app support?
• Does your app have any resolution requirements (does it work on a cell phone?)     Also need to consider other locale-specific formatting:
• Phone numbers
• Integers
• Decimals
• Currency
• Lists
• Plurals
• Relative time
• Etc
• See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl

[vavalos5]

Including link to Edgar's notes for any future reference.

[vavalos5]

Relevant to #2039 which i'm closing because it's an older and similar ticket as this one. Moving to the "Next Active" column per Eric's request.

[SOjaHPE]

Adding some more context here, DSCC tech pubs recommended their UX team to follow Microsoft UI abbreviations.

It appears that their guidance works well for them, Judy W. reach out to see if HPE Design System has further guidance.

There only reservations in particular, using just a “d” or an “h” looks a little lonely in the UI, but it could technically be fine too:

https://www.figma.com/file/2cuoao4i28opFMSNrFDx9a/Time-Zone-%26-Timestamps?type=design&node-id=1368%3A14721&t=9sElRDP4ZWhFW2W0-1

Microsoft UI abbreviations:

Second, Seconds: sec Minute, Minutes: min Hour, Hours: h Day, Days: d Week, Weeks: wk Month, Months: mo Years, Years: yr

[KennyAtHPE]

DateTime abbreviation recommendation

[taysea]

Closing, page has been published: https://design-system.hpe.design/foundation/date-and-time?q=date