Reconsider year-week support in light of implementation feedback

[ptomato]

In the discussion about specifying ISOWeekOfYear (#2378) it came up that our limited support for year-week numbers can lead to bugs.

For example, Temporal.PlainDate.from('2022-01-01').weekOfYear is 52; January 1 2022 is day 6 of week 52 of the week-year 2021, and in ISO year-week notation (which we decided was out of scope for Temporal) would be notated 2021-W52-6, and referred to as being in "ISO week 52 of 2021". The current way to obtain the week-year is to rewind the date to the previous Monday and get the year of that date, which is not obvious.

Several options:

1. Do nothing. Week numbers are often used in business contexts in Europe, but in the vast majority of use cases you don't need the week-year, you just need the week number, which Temporal correctly provides. Save full year-week-day support for a following proposal. Caution in the documentation against building ISO year-week notation strings using date.year and include an example of how to calculate the week-year in the cookbook.
2. Decide that the likelihood of bugs arising from using date.year as the week-year is too high, and remove the weekOfYear API from Temporal, saving it for a following proposal. In the meantime, week numbers (and week-years in the few use cases where they are needed) can be calculated in userland. Include an example of how to do that in the cookbook.
3. Decide that the likelihood of bugs arising from using date.year as the week-year is too high, and add a weekYear accessor property to PlainDate, PlainDateTime, and ZonedDateTime, or even replace the weekOfYear API with an API that returns both the week-year and the week number since even with weekYear people could still mistakenly use date.year as the week-year. Save full year-week-day support for a following proposal.
4. Bring in full year-week-day support. I mention this for completeness, but I consider this thoroughly off the table.

[ptomato]

cc @sffc

[ljharb]

I prefer, in order, 4, 3, and 1, and don't consider 2 worth doing.

[sffc]

I prefer option 3. We should grow into option 4 but I'm not interested in holding up the proposal on this. We can do 3 now and 4 later.

In ICU4X, we return a single struct with the week number and the "RelativeYear" (which is either current, previous, or next).

https://unicode-org.github.io/icu4x-docs/doc/icu_calendar/week/struct.WeekOf.html

Note that for era and eraYear, we also combine those into a single struct in ICU4X.

https://unicode-org.github.io/icu4x-docs/doc/icu_calendar/types/struct.FormattableYear.html

My preference would be for weekOfYear to return a Tuple or Record with the info, but if that's not possible, then weekYear seems fine. Or, we just return an object, since I think it's safe to say that you seldom want one without the other.

[sffc]

@pipobscure suggested weekOfYear and yearOfWeek.

I would just note that yearOfWeek in this case should be an arithmetic year, not an era year.

[ptomato]

In the Temporal champions meeting of 2022-10-13 we agreed that we want to present option 3 for consensus in November, with (as Shane said) the name yearOfWeek. For example, Temporal.PlainDate.from('2022-01-01').yearOfWeek would be 2021.

This would add a yearOfWeek getter on Temporal.PlainDate.prototype, Temporal.PlainDateTime.prototype, and Temporal.ZonedDateTime.prototype, and a new Temporal.Calendar.prototype.yearOfWeek() method. The algorithm for determining when year and yearOfWeek are different is basically already part of the ToISOWeekOfYear operation, so needs to be adapted slightly for the new API.