Behavior of YearMonth around Japanese era boundaries

[Manishearth]

https://tc39.es/proposal-temporal/#sec-temporal-nonisoresolvefields

This has the following text:

In the Japanese calendar, when fields.[[Era]] is not unset and the date represented by fields is not within the bounds of that era, fields.[[Era]] should be updated to the appropriate containing era for that date (for example, because the transition from Heisei era [[EraYear]] 31 to Reiwa era [[EraYear]] 1 took place on May 1 of [[Year]] 2019, Heisei era [[EraYear]] 32 should be updated to Reiwa era [[EraYear]] 2, Reiwa era [[EraYear]] 1 [[Month]] 1 should be updated to Heisei era [[EraYear]] 31 [[Month]] 1, etc.).

However, in CalendarYearMonthFromFields, it says:

2. Let firstDayIndex be the 1-based index of the first day of the month described by fields (i.e., 1 unless the month's first day is skipped by this calendar.)

This isn't quite clear on what "the first day of the month described by fields" is. January Heisei 1and January 64 Showa are the same month.

In the polyfill, currently, Temporal.PlainYearMonth.from({calendar: "japanese", era: "heisei", eraYear: 1, month: 1}).era produces "showa", because it constrains down to a reference day of Janaury 1, which is in Showa, even though January 8 is in Heisei.

Personally I think it makes sense for (Heisei 1, January) and (Showa 64, January) to be considered distinct YearMonths, but perhaps we wish to talk about the abstract month here and in that case the current behavior makes sense. Either way, this should probably be explicitly considered and noted.

As an aside, I'm noticing that CalendarResolveFields handles most of the "figure out the rest of the fields" behavior, but reference year / reference day calculation is in callers. It might be cleaner to have it all in one place under CalendarResolveFields/NonISOResolveFields.

cc @sffc

[Manishearth]

The underlying question is: are (Heisei 1, January) and (Showa 64, January) the same or different YearMonths? There are arguments for both: they are the same abstract month, but from a formatting perspective there is still a distinction.

[ptomato]

The two YearMonths are the same, as per Note 2 in NonISOResolveFields.

The "1-based index of the first day of the month described by fields" text is leftover from before days were defined to be ordinal and needs to be replaced with just "1".

[ptomato]

(see tc39/proposal-intl-era-monthcode#74 (comment))

[Manishearth]

Thanks!

[sffc]

The spec is clear when constructing a date, but it is not clear when filling in the day in CalendarYearMonthFromFields. The code in question is

Temporal.PlainYearMonth.from({
    calendar: "japanese",
    era: "heisei",
    eraYear: 1,
    month: 1,
})

Should it return 1989-01-08[u-ca=japanese] (the first day in Heisei) or 1989-01-01[u-ca=japanese] (the first day in that month despite it not being in Heisei)?

The definition of day starting from 1 is about months with missing days, but this isn't a month with a missing day; it is an era that starts in the middle of a month.

[ptomato]

Note 2 in NonISOResolveFields should make that clear. It is the first day in the month despite it not being in Heisei.

[sffc]

Note 2 is in CalendarResolveFields, which takes place before we set the day to "the first day of the month". It can't know whether to set the era to the one at the beginning of the month or the end of the month.

[justingrant]

Personally I think it makes sense for (Heisei 1, January) and (Showa 64, January) to be considered distinct YearMonths, but perhaps we wish to talk about the abstract month here and in that case the current behavior makes sense. Either way, this should probably be explicitly considered and noted.

IIRC, the original intent was that era/eraYear pair should always be converted into year, and then the latter would be used for all subsequent calculations.

If we're sticking with that approach then I'm not sure how "(Heisei 1, January) and (Showa 64, January) to be considered distinct YearMonths" would be possible, because year doesn't know its era. Here's an example of code that would get pretty weird:

ym1 =  Temporal.PlainYearMonth.from({calendar: "japanese", era: "heisei", eraYear: 1, month: 1});
// => era is "heisei"

const {month, year} = ym1;
// => { 1, 1989 }

ym2 = Temporal.PlainYearMonth.from({calendar: "japanese", year: 1989, month: 1});
// => era is "showa"

ym1.equals(ym2); 
// => false ???!!!!????

Changing the current behavior could also have a ripple effect beyond just PlainYearMonth. For example, calling pym.toPlainDate() would start to return different dates depending on the era used to create the PYM instance. Iteration of months (e.g. to display a calendar) would also get weirder. I'm sure there are other oddities and broken invariants that I'm not thinking of.

TL;DR - This seems like it'd be a very impactful change so close to Stage 4.

I think the core problem is that in Japanese, dates belong to only one era but months can belong to one or more. (Heaven forbid an emperor pass away soon after coronation... then there could be three eras in a month!) This necessarily introduces complexity in code using this calendar.

For example, If I were building, for example, a Japanese calendar UI, then I'd need to account for the multi-era possibility and would need to create UI that accommodated showing two eras and two years in the header of the month, unlike the simple Gregorian case below:

I don't think that making PlainYearMonth more complex will make use cases like this any easier.

There's also a more general question: do "months" really belong to an era at all? Years certainly do, e.g. "Heisei 1" means something. But does "Heisei January" have an inherent meaning?

Anyway, unless there's some easier solution I'm not seeing, then I'd be in favor of leaving the current behavior because I can't see any path to a practical solution.

[fabon-f]

I feel very weird if "January of Heisei 1st" and "January of Showa 64th" are distinct. Rather my mental model is like "January 1989 belongs to both Showa and Heisei", in other words "January of Heisei 1st" and "January of Showa 64th" are identical. Perhaps developers may want to treat "January of Heisei 1st" and "January of Showa 64th" differently in a very unusual case, but in general treating these months differently is confusing for the most API users.

Of course I'm not in a position of representing all developers in Japan, but I guess my opinion would be pretty common all across Japan.

[Manishearth]

This all makes sense. In that case the spec text needs to be updated, currently it fixes up the era first in NonISOResolveFields and then fixes up the Day to be 1 in CalendarYearMonthFromFields, which is the wrong order of operations here, depending on the precise behavior of NonISOCalendarDateToISO.