Reference for stage 2.7 intl-era-monthcode (mdn#42660)

* Fix incorrect Chinese calendar example in Temporal.PlainDate.from docs

The Chinese calendar example incorrectly stated that year 2021 in the
Chinese calendar corresponds to 616 BC in the ISO calendar. According
to the TC39 Intl era and monthCode proposal, the Chinese calendar's
epoch year is now ISO year 0, so year 2021 aligns with ISO year 2021.

This commit:
- Updates the Chinese calendar example comment to reflect the correct
  epoch year alignment
- Corrects the expected output from "-000616-08-12[u-ca=chinese]" to
  "2021-08-08[u-ca=chinese]"
- Adds a new Hebrew calendar example to demonstrate a calendar with a
  significantly different epoch year (5781 Hebrew = 2021 ISO)

Fixes mdn#42565

* Fully document eras and monthCodes

* Fixes

---------

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

Author: codersjj

.vscode/dictionaries/code-entities.txt

@@ -85,6 +85,7 @@ BPPV1
 Brai
 braillelabel
 brailleroledescription
+broc
 browser-bottombox
 browser.safebrowsing
 browser.sessionhistory

.vscode/dictionaries/cultural-words.txt

@@ -32,7 +32,7 @@ Henkan
 Hijri
 Hinckley
 Hiroko
-háček
+Huangdi
 Jeonja
 Kayah
 Khema
@@ -80,9 +80,11 @@ Tangsa
 Thaana
 Tham
 Tirhuta
+Tishrei
 Tlayolotl
 Totnes
 Wancho
 Warang
 Zenkaku
 zhuyin
+Śaka

.vscode/dictionaries/proper-names.txt

@@ -306,6 +306,7 @@ Kaku
 Kang
 Kaply
 Karmadrome
+KASI
 Kaspersky
 Katari
 Kazam

files/en-us/web/javascript/reference/global_objects/intl/supportedvaluesof/index.md

@@ -7,9 +7,33 @@ browser-compat: javascript.builtins.Temporal.PlainDate.era
 sidebar: jsref
 ---
 
-The **`era`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g., ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way that `year` does. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For Gregorian, it is either `"gregory"` or `"gregory-inverse"`.
+The **`era`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g., ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way that `year` does. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For Gregorian, it is either `"ce"` or `"bce"`.
 
-The set accessor of `era` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDate/with", "with()")}} method to create a new `Temporal.PlainDate` object with the desired new value. When setting eras, each code may have some aliases; for example, `"ce"` and `"ad"` are equivalent to `"gregory"`, and `"bce"` and `"bc"` are equivalent to `"gregory-inverse"`.
+## Value
+
+All [specified calendars](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types) have eras fully defined by the spec.
+
+- The following calendars have a single era:
+  - `buddhist`: `"be"`
+  - `coptic`: `"am"`
+  - `ethioaa`: `"aa"`
+  - `hebrew`: `"am"`
+  - `indian`: `"shaka"`
+  - `persian`: `"ap"`
+- The following calendars have two eras. One is the _epoch era_, in which `eraYear` starts at 1 and is the same as {{jsxref("Temporal/PlainDate/year", "year")}}. The other is the inverse era, in which `eraYear` also starts at 1 and is equal to `1 - year` (so `eraYear: 1` corresponds to year `0`, `eraYear: 2` to year `-1`, etc.):
+  - `gregory`: epoch era `"ce"`, inverse era `"bce"`
+  - `islamic-civil`, `islamic-tbla`, `islamic-umalqura`: epoch era `"ah"`, inverse era `"bh"`
+  - `roc`: epoch era `"roc"`, inverse era `"broc"`
+- The `ethiopic` calendar has an `"am"` era which is the epoch era. Years before `1` belong to the `"aa"` era, whose `eraYear` is equal to `year - 5500` (so `eraYear: -1000` corresponds to year `-6500`, `eraYear: 1` corresponds to year `-5499`, up to `eraYear: 5500` as year `0`).
+- The `japanese` calendar adds an era for each new emperor, so the output year and era for a future date may not match the input year and era when your code runs on a future engine version, and we won't enumerate them here. Each era's year starts at 1. It is also the only calendar known to have eras starting in the middle of a year, which means that the same `year` may correspond to different `(era, eraYear)` pairs depending on the month and day.
+  `
+
+  > [!WARNING]
+  > As of October 2025, in the `japanese` calendar, dates prior to 1868-10-23 ISO (the start date of the year 1 Meiji) don't work as expected in browsers in two ways. First, [CLDR had the wrong start date for the Meiji era](https://unicode-org.atlassian.net/browse/CLDR-11375), which causes calendar implementations to extend the Meiji era further to the past than it actually did. Second, the upcoming [Intl era and monthCode Proposal](https://tc39.es/proposal-intl-era-monthcode/) specifies that dates prior to 1873-01-01 ISO should use Gregorian eras, but browsers have traditionally used approximations of prior Japanese eras instead. The `japanese` calendar was taken into use on January 1, 6 Meiji / 1873-01-01 ISO, so these problems only affect proleptic dates.
+
+- Other [specified calendars](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types): `chinese`, `dangi`, `iso8601`, don't use eras and return `undefined`.
+
+The set accessor of `era` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDate/with", "with()")}} method to create a new `Temporal.PlainDate` object with the desired new value. When setting eras, the `"ad"` and `"bc"` aliases are also accepted for the `"ce"` and `"bce"` eras of the `gregory` or `japanese` calendars.
 
 > [!NOTE]
 > This string is not intended for display to users. Use {{jsxref("Temporal/PlainDate/toLocaleString", "toLocaleString()")}} with the appropriate options to get a localized string.
@@ -23,10 +47,10 @@ const date = Temporal.PlainDate.from("2021-07-01"); // ISO 8601 calendar
 console.log(date.era); // undefined
 
 const date2 = Temporal.PlainDate.from("2021-07-01[u-ca=gregory]");
-console.log(date2.era); // gregory
+console.log(date2.era); // ce
 
 const date3 = Temporal.PlainDate.from("-002021-07-01[u-ca=gregory]");
-console.log(date3.era); // gregory-inverse
+console.log(date3.era); // bce
 
 const date4 = Temporal.PlainDate.from("2021-07-01[u-ca=japanese]");
 console.log(date4.era); // reiwa

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md

@@ -9,7 +9,9 @@ sidebar: jsref
 
 The **`eraYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a non-negative integer representing the year of this date within the era, or `undefined` if the calendar does not use eras (e.g., ISO 8601). The year index usually starts from 1 (more common) or 0, and years in an era can decrease with time (e.g., Gregorian BCE). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way that `year` does. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 
-Unlike `year`, `era` and `eraYear` may change in the middle of a calendar year. For example, Japan started the Reiwa era on May 1, 2019, so dates from 2019-01-01 to 2019-04-30 have `{ era: "heisei", eraYear: 31 }`, and dates from 2019-05-01 onwards have `{ era: "reiwa", eraYear: 1 }`, but the `year` is always 2019 (because the Japanese calendar uses the ISO 8601 year as the default year).
+Unlike `year`, `era` and `eraYear` may change in the middle of a calendar year. For example, Japan started the Reiwa era on May 1, 2019, so dates from 2019-01-01 to 2019-04-30 have `{ era: "heisei", eraYear: 31 }`, and dates from 2019-05-01 onwards have `{ era: "reiwa", eraYear: 1 }`, but the `year` is always 2019 (because the Japanese calendar uses the ISO 8601 year as the arithmetic year).
+
+For more information about the values of `era` and `eraYear` for different calendars, see the {{jsxref("Temporal/PlainDate/era", "era")}} property.
 
 The set accessor of `eraYear` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDate/with", "with()")}} method to create a new `Temporal.PlainDate` object with the desired new value.
 

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md

@@ -85,13 +85,13 @@ const d3 = Temporal.PlainDate.from({
   year: 2021,
   month: 7,
   day: 1,
-  calendar: "chinese",
+  calendar: "hebrew",
 });
 // Note: when you construct a date with an object, the date components
 // are in *that* calendar, not the ISO calendar. However, toString() always
 // outputs the date in the ISO calendar. For example, the year "2021" in
-// the Chinese calendar is actually 616 BC in the ISO calendar.
-console.log(d3.toString()); // "-000616-08-12[u-ca=chinese]"
+// the Hebrew calendar is actually 1740 BCE in the ISO calendar.
+console.log(d3.toString()); // "-001739-03-07[u-ca=hebrew]"
 
 // Era, eraYear, month, and day
 const d4 = Temporal.PlainDate.from({

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md

@@ -75,7 +75,7 @@ These properties are defined on `Temporal.PlainDate.prototype` and shared by all
 - {{jsxref("Temporal/PlainDate/daysInYear", "Temporal.PlainDate.prototype.daysInYear")}}
   - : Returns a positive integer representing the number of days in the year of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For the ISO 8601 calendar, this is 365, or 366 in a leap year.
 - {{jsxref("Temporal/PlainDate/era", "Temporal.PlainDate.prototype.era")}}
-  - : Returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g., ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way that `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For Gregorian, it is either `"gregory"` or `"gregory-inverse"`.
+  - : Returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g., ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way that `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For Gregorian, it is either `"ce"` or `"bce"`.
 - {{jsxref("Temporal/PlainDate/eraYear", "Temporal.PlainDate.prototype.eraYear")}}
   - : Returns a non-negative integer representing the year of this date within the era, or `undefined` if the calendar does not use eras (e.g., ISO 8601). The year index usually starts from 1 (more common) or 0, and years in an era can decrease with time (e.g., Gregorian BCE). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way that `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 - {{jsxref("Temporal/PlainDate/inLeapYear", "Temporal.PlainDate.prototype.inLeapYear")}}

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md

@@ -9,13 +9,21 @@ sidebar: jsref
 
 The **`monthCode`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a calendar-specific string representing the month of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 
-Usually it is `M` plus a two-digit month number. For leap months, it is the previous month's code followed by `L` (even if it's conceptually a derivative of the following month; for example, in the Hebrew calendar, Adar I has code `M05L` but Adar II has code `M06`). If the leap month is the first month of the year, the code is `M00L`.
+## Value
+
+The basic format of `monthCode` is `M` plus a two-digit month number. For leap months, it is the previous month's code followed by `L` (even if it's conceptually a derivative of the following month; for example, in the Hebrew calendar, Adar I has code `M05L` but Adar II has code `M06`).
+
+All calendars have at least 12 months, with codes from `"M01"` to `"M12"`.
+
+All [specified calendars](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types) have month codes fully defined by the spec. Most don't have month rules distinct from `iso8601`. The `coptic`, `ethioaa`, and `ethiopic` calendars have an additional `M13` month. The `chinese` and `dangi` calendars have 12 additional leap months possible, with codes from `"M01L"` to `"M12L"`. The `hebrew` calendar has one leap month, `"M05L"` (Adar I).
 
 > [!NOTE]
 > Don't assume that `monthCode` is a user-friendly string; use `toLocaleString()` to format your date instead. Generally, don't cache the name of months in an array or object. Even though `monthCode` usually maps to the month's name within one calendar, we recommend always computing the month's name using, for example, `date.toLocaleString("en-US", { calendar: date.calendarId, month: "long" })`.
 
 The set accessor of `monthCode` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDate/with", "with()")}} method to create a new `Temporal.PlainDate` object with the desired new value.
 
+When setting the date to a different year, the `monthCode` remains the same, but the `month` may change if the target year has a different leap month structure. If the current `monthCode` does not exist in the target year and the method is not configured to reject, then for the `chinese` and `dangi` calendars, the previous month is used instead (e.g., from `"M03L"` to `"M03"`, which is from 闰三月 to 三月). For `hebrew`, the _next_ month is used instead (from `"M05L"` to `"M06"`, which is from Adar I to Adar II).
+
 ## Examples
 
 ### Using monthCode
@@ -70,7 +78,7 @@ Don't do this:
 ```js example-bad
 const names = [
   "January", "February", "March", "April", "May", "June",
-  "July", "August", "September", "October", "November", "December"
+  "July", "August", "September", "October", "November", "December",
 ];
 
 const date = Temporal.PlainDate.from("2021-07-01");
@@ -84,7 +92,7 @@ Also don't do this:
 const names = {
   "M01": "January", "M02": "February", "M03": "March", "M04": "April",
   "M05": "May", "M06": "June", "M07": "July", "M08": "August",
-  "M09": "September", "M10": "October", "M11": "November", "M12": "December"
+  "M09": "September", "M10": "October", "M11": "November", "M12": "December",
 };
 
 const date = Temporal.PlainDate.from("2021-07-01");

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md

@@ -59,13 +59,13 @@ console.log(plainDate.toString()); // 2021-07-01
 
 // Note that the date is stored internally as ISO 8601, even when it's
 // interpreted in a different calendar system. For example, even though
-// 2021-07-01 is 4658-05-22 in the Chinese calendar, you still pass the
+// 2021-07-01 ISO is 5781-10-21 in the Hebrew calendar, you still pass the
 // ISO date to the constructor.
-const plainDate2 = new Temporal.PlainDate(2021, 7, 1, "chinese");
-console.log(plainDate2.toString()); // 2021-07-01[u-ca=chinese]
-console.log(plainDate2.year); // 4658
-console.log(plainDate2.month); // 5
-console.log(plainDate2.day); // 22
+const plainDate2 = new Temporal.PlainDate(2021, 7, 1, "hebrew");
+console.log(plainDate2.toString()); // 2021-07-01[u-ca=hebrew]
+console.log(plainDate2.year); // 5781
+console.log(plainDate2.month); // 10
+console.log(plainDate2.day); // 21
 ```
 
 ## Specifications