Date Formatting

[gtrufitt]

Is your feature request related to a problem? Please describe.

There are certain formatted dates across platforms used in the context of articles and cards. These date formats can get out of sync across platforms. Date formatting is performed in different ways across platforms (and modules used in platforms).

Describe the solution you'd like

The solution is not to request the date format in the YYY-DD-M type format (a la Moment).

The solution I think makes sense is to leave the Design System to format a timestamp given a context and the current time.

The function should take an argument prescriptive of the context of the date (dateline, card, discussion, liveblog dates etc) and a timestamp.

The decision when to switch from a 'Relative' (x hours ago) date to an 'Absolute' date (4th August 2020) is handled at the design system level (as it is a design decision). The formatter can decide for each context given a timestamp whether it returns relative or absolute dates.

I imagine the API to look something like:

const enum DateContext {
	DateLine,
	Card,
	DiscussionComment,
	LiveblogCard,
	LiveblogKeyEvent,
	LiveblogUpdatedTime
}

type DateString = string; // Means we can type usage

// Maybe timestamp can be a more specific type
const getFormattedDate = (timeStamp: number, Context: DateContext): DateString => ...

Then the platforms can be aligned with display in all situations that timestamps need formatting.

It may be that multiple contexts have the same date format but, like the colour palettes, the formats should be distinct to the usage to allow them to be updated across platforms.

Describe alternatives you've considered

• Manage date formats in the platforms directly, formatting provided timestamps directly
• Creating a separate module outside Source that handles date formats that can be shared across platforms
• Using plain ISO 8601 date formats and letting users parse the date in their head

Additional context

• Timestamps on Dotcom
• Early implementation of date stamps on DCR in which Frontend generates the dateLines and passes to DCR. This is sub-optimal as it means more data passed to DCR.
• Dateline and formatDate functions in Apps Rendering
• Discussion Rendering dateFormatter using timeago.js (rightly or wrongly...)

[JamieB-gu]

This is great! 🕰📆🚀

Here are some questions that occurred to me.

a timestamp given a context and the current time

How do we handle timezones? Dotcom currently switches timezone based on edition and time of year (BST/GMT for the UK, AEST for AU, EDT for US and BST/GMT again for International). I think Apps may use device settings to select a timezone (@SLambrakis @maxspencer should be able to confirm).

as it is a design decision

👍

decide for each context given a timestamp whether it returns relative or absolute dates

So the design system does two things?

1. Maintains several ways of formatting datetimes (e.g. relative time, absolute date, absolute date and time).
2. Provides an abstraction by maintaining a list of contexts that the consumer chooses from, and maps those to the appropriate format under the hood.

type DateString = string; // Means we can type usage

What does typing usage mean?

Using plain ISO 8601 date formats and letting users parse the date in their head

Or we could display UNIX time?

[nicl]

1. I really like the though of date formats in Source
2. I'm not sure about this API - in particular, the DateContext - as it requires too much of Source. It's a complicated API interface, and couples Source too much to specifics, so it seems a bit brittle. I'd prefer the API to simply provide a few 'blessed' date formats, and leave platforms to decide which to use where.

e.g. closer to:

const enum Format = {
    short,
    medium,
    long
}

formatDate(date: Date, format: Format)

[SLambrakis]

On the iOS live app timezones do indeed come from the system. Ideally the date format also would, but we've ended up with a bunch of custom formats all over the place (which I'd love to standardise/lose eventually).

Speaking of enums, iOS actually provides one (useable for formatting dates and times) that looks pretty similar to Nic's suggestion... https://developer.apple.com/documentation/foundation/dateformatter/style

[gtrufitt]

. I'd prefer the API to simply provide a few 'blessed' date formats, and leave platforms to decide which to use where.

+1 this is nicer @nicl

Maybe the API could take the 'hours' to switch between relative and absolute date formats too so that's abstracted away from the platform complexity but I definitely think we'll be able to distill all the date formats into a more defined type.

How do we handle timezones?

Maybe this is an optional param then, I think the 'design' of the time-zoned date is still DS responsibility.

What does typing usage mean?

So you can define that a component takes a DateString that is returned from the formatting function?

Speaking of enums, iOS actually provides one (useable for formatting dates and times) that looks pretty similar to Nic's suggestion... developer.apple.com/documentation/foundation/dateformatter/style

Interesting! Maybe this is worth aligning to then?

[gtrufitt]

Given the above, maybe the API then looks like.

// Aligned to https://developer.apple.com/documentation/foundation/dateformatter/style ?
const enum DateFormat = {
	none,
	short,
	medium,
	long,
	full
}

const enum Timezone = {
		BST,
		GMT, // How do you handle that BST vs GMT?
		AEST,
		EST
}

type DateString = string;

formatDate(
	timestamp: number, 
	dateFormat: DateFormat, 
	timeUntilAbsolute?: seconds, 
	timeZone?: Timezone
): DateString

That feels to me like giving the DS enough info to 'design' the date, without being overly contextually specific?

[JamieB-gu]

How do you handle that BST vs GMT?

We could instead define it as the TZ locations that correspond to the time zones we display:

• London
• Sydney
• New York

then use the current date to figure out whether that should be the Daylight Saving variant or not?

So you can define that a component takes a DateString that is returned from the formatting function?

Fair - I think this makes sense if DateString is a custom type, but worth noting that type DateString = string will act as a type alias rather than a new type, so it's interchangeable with string, e.g.:

type DateString = string;

function foo(s: DateString): string {
    return s;
}

const bar = foo('hello');

We might want to do this for readability even if it doesn't provide us with any additional type safety?

[SiAdcock]

Thanks @gtrufitt for starting this conversation and to everyone else for getting involved. It's started to identify some of the intracacies of this problem.

There are a lot of angles we'd need to consider.

• I think it's likely that date and time format will become part of Core Source rather than the Editorial Source
• We know that different date and time formats are being used across the existing platforms. We need to take a wide UI inventory and work closely with design to ensure we're capturing a solution that scales and delivers the best user experience
• As @nicl points out, we shouldn't couple this solution to any existing contexts. The solution should provide a generic way to format dates. Platforms can implement their own contextual wrappers around this API if they wish.
• Timezones are a potentially thorny problem. JavaScript allows us to encode the timezone into the date string rather than passing the timestamp as a number
• Alternatively, as @gtrufitt suggests, we could receive a timestamp for the UTC datetime and a timezone to convert it to. We don't want Source to be aware of every timezone in existance, Source can support a (very small) subset of the tz database as @JamieB-gu suggests
• We want the names of date formats to be readable, understandable and memorable. The predefined iOS date formats that @SLambrakis mentioned are a great starting point, and I'd be interested to hear of any others we know about
• I think we display the datetime as daylight savings if the date being displayed occurred within the daylight savings period

It would be really useful if we could continue to pick apart these kind of issues before we nail an API, although thinking in terms of API is a good way to help identify issues 🙂

I've started a doc to try to capture some of these considerations in a structured way.

If anyone can think of any aspects of datetime that are not captured here, please add a comment here, or to the document.

The design side of this conversation might have to wait until Akemi is back from sabbatical in mid-September.

[gtrufitt]

https://github.com/xxczaki/light-date

[JamieB-gu]

I think it's likely that date and time format will become part of Core Source rather than the Editorial Source

JavaScript allows us to encode the timezone into the date string rather than passing the timestamp as a number

This sounds sensible 🚀. So perhaps the Core Source function looks something like this:

const format = (dateTime: string, dateFormat: DateFormat): string;

And if we want, Editorial Source could provide a wrapper that also takes the Edition:

const editorialFormat = (utcTime: string, dateFormat: DateFormat, edition: Edition): string => {
  switch (edition) {
    case Edition.AU:
      return format(`${utcTime}+10:00`, dateFormat);
    case Edition.US:
      return format(`${utcTime}-04:00`, dateFormat);
    case Edition.UK:
    case Edition.INT:
    default:
      return format(utcTime, dateFormat);
  }
}

JavaScript allows us to encode the timezone into the date string rather than passing the timestamp as a number

Coming back to this again, I think it solves the timezone problem in general but pushes the handling of Daylight Saving shifts onto the caller? Because if the caller has to provide the offset (e.g. +09:00) then it will have to change that offset based on whether the date falls within Daylight Saving?

Perhaps we can, again, provide a wrapper function in Core Source that is able to handle Daylight Saving for a pre-defined shortlist of supported areas?

const enum City {
  London,
  NewYork,
  Sydney,
}

const formatWithDaylightSaving = (utcTime: string, dateFormat: DateFormat, city: City): string;

We need to take a wide UI inventory

👍 for this. We could start with dotcom and apps, as I think they contain the most prominent and varied examples?

[maxspencer]

Cool topic and lots of good points raised. In Android we have access to an API provided by the Java standard library called DateFormat. Our current usage of it is inconsistent, but it's a pretty cool API with great features, especially for ensuring dates look "right" in the user's locale/language.

It's not quite this simple, but at a high level the DateFormat class provides this function:

format(style, date, locale) -> String

where

• style is either a precise specification of the output like dd:MM:YYY or one of a predefine set: SHORT, MEDIUM, or LONG,
• date is a Java Date which is roughly interchangeable with a timestamp and can be with or without timezone info.
• locale is the current device locale, e.g. en_GB or fr_CA.

DateFormat does all the hard work of combining those things to make human-readable dates, e.g.:

val now = Date()
val longDateFormat = DateFormat.getDateInstance(DateFormat.LONG, Locale.UK)
println(longDateFormat.format(now))

Prints:

04 September 2020

I wrote a little program to do some different combinations of style and locale to illustrate. This is printing dates with times in three styles for each of four different locales:

val now = Date()
val styles = mapOf(
        "short" to DateFormat.SHORT,
        "medium" to DateFormat.MEDIUM,
        "long" to DateFormat.LONG
)
val locales = listOf(Locale.UK, Locale.US, Locale.FRANCE, Locale.CHINA)

locales.forEach { locale ->
    styles.forEach { (styleName, style) ->
        val dateFormat = DateFormat.getDateTimeInstance(style, style, locale)
        println("$locale, $styleName:\t${dateFormat.format(now)}")
    }
    println()
}

Prints:

en_GB, short:	04/09/20 16:12
en_GB, medium:	04-Sep-2020 16:12:00
en_GB, long:	04 September 2020 16:12:00 BST

en_US, short:	9/4/20 4:12 PM
en_US, medium:	Sep 4, 2020 4:12:00 PM
en_US, long:	September 4, 2020 4:12:00 PM BST

fr_FR, short:	04/09/20 16:12
fr_FR, medium:	4 sept. 2020 16:12:00
fr_FR, long:	4 septembre 2020 16:12:00 BST

zh_CN, short:	20-9-4 下午4:12
zh_CN, medium:	2020-9-4 16:12:00
zh_CN, long:	2020年9月4日 下午04时12分00秒

I think to some extent the philosophy of this class/API challenges the idea of date formats being purely a design decision, instead it asserts: "There are certain ways dates and times should be formatted and I DateFormat know them all!"

[mxdvl]

Having fr_CA as my default locale, I always find it quite weird to have a date formatted in French if the article I’m reading is in English. Same as spelling my UK phone number in French—nearly impossible (even though you could think the underlying format is numerals, and not language-specific)