diff --git a/.vscode/dictionaries/code-entities.txt b/.vscode/dictionaries/code-entities.txt index 9bd7bf65ff54c00..556238dd0afa8d8 100644 --- a/.vscode/dictionaries/code-entities.txt +++ b/.vscode/dictionaries/code-entities.txt @@ -84,6 +84,7 @@ BPPV1 Brai braillelabel brailleroledescription +broc browser-bottombox browser.safebrowsing browser.sessionhistory diff --git a/.vscode/dictionaries/cultural-words.txt b/.vscode/dictionaries/cultural-words.txt index 4d49e4baf730f91..a7bc43ae73b8a19 100644 --- a/.vscode/dictionaries/cultural-words.txt +++ b/.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 diff --git a/.vscode/dictionaries/proper-names.txt b/.vscode/dictionaries/proper-names.txt index ab805e32b52c7a0..8526808759d7df4 100644 --- a/.vscode/dictionaries/proper-names.txt +++ b/.vscode/dictionaries/proper-names.txt @@ -305,6 +305,7 @@ Kaku Kang Kaply Karmadrome +KASI Kaspersky Katari Kazam diff --git a/files/en-us/web/javascript/reference/global_objects/intl/supportedvaluesof/index.md b/files/en-us/web/javascript/reference/global_objects/intl/supportedvaluesof/index.md index 6dbba072087224f..a65c4db9b39fd25 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/supportedvaluesof/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/supportedvaluesof/index.md @@ -58,36 +58,38 @@ A sorted array of unique string values indicating the values supported by the im #### Supported calendar types -Below are all values that are commonly supported by browsers for the `calendar` key. These values can be used for the `calendar` option or the `ca` [Unicode extension key](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) when creating objects such as {{jsxref("Intl.DateTimeFormat")}}, as well as for creating {{jsxref("Temporal")}} date objects. - -| Value | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `buddhist` | Thai Buddhist calendar | -| `chinese` | Traditional Chinese calendar | -| `coptic` | Coptic calendar | -| `dangi` | Traditional Korean calendar | -| `ethioaa` | Ethiopic calendar, Amete Alem, single-era variant (epoch approx. 5493 B.C.E) | -| `ethiopic` | Ethiopic calendar, Amete Mihret, two-era variant (epoch approx, 8 C.E., Amete Alem for years before Amete Mihret) | -| `gregory` | Gregorian calendar (proleptic, _not_ Julian hybrid) | -| `hebrew` | Traditional Hebrew calendar | -| `indian` | Indian calendar | -| `islamic` | Hijri calendar, unspecified algorithm. **Note:** As of April 2025, this is an astronomical simulation whose parameters are undocumented and that is not known to match a specific Hijri calendar variant from non-software contexts. For well-specified results, use one of the three specific variants: `islamic-umalqura`, `islamic-tbla`, or `islamic-civil`. | -| `islamic-umalqura` | Hijri calendar, Umm al-Qura (uses KACST-calculated months from the start of 1300 AH (1882-11-12 ISO) to the end of 1600 AH (2174-11-25 ISO) and falls back to `islamic-civil` outside that range) | -| `islamic-tbla` | Hijri calendar, tabular/rule-based with leap year rule II (leap years 2,5,7,10,13,16,18,21,24,26,29 in the 30-year cycle (1-based numbering)) and Thursday/astronomical epoch (July 15, 622 Julian / 0622-07-18 ISO) | -| `islamic-civil` | Hijri calendar, tabular/rule-based with leap year rule II (leap years 2,5,7,10,13,16,18,21,24,26,29 in the 30-year cycle (1-based numbering)) and Friday/civil epoch (July 16, 622 Julian / 0622-07-19 ISO) | -| `iso8601` | ISO calendar (variant of the Gregorian calendar with week rules and formatting parameters made region-independent) | -| `japanese` | Japanese Imperial calendar (this 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. **Note:** See the remarks below this table about dates prior to 1868-10-23 ISO.) | -| `persian` | Persian calendar | -| `roc` | Republic of China calendar | - -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 the Meiji era 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. +Below are all values that are commonly supported by browsers for the `calendar` key. These values can be used for the `calendar` option or the `ca` [Unicode extension key](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) when creating objects such as {{jsxref("Intl.DateTimeFormat")}}, as well as for creating {{jsxref("Temporal")}} date objects. This list is explicitly sanctioned by the ECMA-402 specification, so all implementations should be consistent. + +| Value | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `buddhist` | Thai Buddhist calendar, proleptic. Month numbers, month codes, and days are the same as in the ISO 8601 calendar, but the epoch year is different. There is one era. | +| `chinese` | Traditional Chinese calendar, proleptic. Lunisolar calendar used in China based on data published by the Purple Mountain Observatory between 1900 and 2100 (which compiles with GB/T 33661-2017 between 1912 and 2100), falling back to an implementation-defined approximation outside that range. The arithmetic year is identical to `gregory`, and there are no eras. | +| `coptic` | Coptic calendar, proleptic. Similar solar algorithm to `ethioaa` and `ethiopic`, with one era and a different epoch year. | +| `dangi` | Traditional Korean calendar, proleptic. Lunisolar calendar using months published by the Korea Astronomy and Space Science Institute (KASI) between 1900 and 2050, falling back to an implementation-defined approximation outside that range. The arithmetic year is identical to `gregory`, and there are no eras. | +| `ethioaa` | Ethiopic calendar, Amete Alem, proleptic. Similar solar algorithm to `coptic` and `ethiopic`, with one era and a different epoch year. | +| `ethiopic` | Ethiopic calendar, Amete Mihret, proleptic. Similar solar algorithm to `coptic` and `ethioaa`, with two eras and a different epoch year. | +| `gregory` | Gregorian calendar, proleptic. Solar calendar almost identical to the ISO 8601 calendar, except that it does not define week numbering and it contains two eras, one before the epoch year. | +| `hebrew` | Hebrew calendar, proleptic. Civil calendar with Tishrei as the first month of the year. Lunisolar calendar with one leap month inserted after month 5. There is one era. | +| `indian` | Indian national (or Śaka) calendar, proleptic. Solar calendar with one era. | +| `islamic-civil` | Hijri calendar, proleptic, tabular/rule-based with leap year rule II (leap years 2,5,7,10,13,16,18,21,24,26,29 in the 30-year cycle (1-based numbering)) and civil epoch (Friday July 16, 622 Julian / 0622-07-19 ISO) | +| `islamic-tbla` | Hijri calendar, proleptic, tabular/rule-based with leap year rule II (leap years 2,5,7,10,13,16,18,21,24,26,29 in the 30-year cycle (1-based numbering)) and astronomical epoch (Thursday July 15, 622 Julian / 0622-07-18 ISO) | +| `islamic-umalqura` | Hijri calendar, proleptic, Umm al-Qura. Lunar calendar using KACST-calculated months from the start of 1300 AH (1882-11-12 ISO) to the end of 1600 AH (2174-11-25 ISO), falling back to `islamic-civil` outside that range. | +| `iso8601` | ISO calendar (variant of the Gregorian calendar with week rules and formatting parameters made region-independent) | +| `japanese` | Japanese Imperial calendar (this 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. **Note:** See the remarks below this table about dates prior to 1868-10-23 ISO.) | +| `persian` | Persian (or Solar Hijri) calendar, proleptic. There is one era. | +| `roc` | Republic of China (or Minguo) calendar, proleptic. Month numbers, month codes, and days are the same as in the ISO 8601 calendar, but the epoch year is different. There are two eras, one before the epoch year and one after. | + +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. The types below are specified in CLDR but do not have implementations distinct from the above calendars in browsers. -| Value | Description | Notes | -| -------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `islamicc` {{deprecated_inline}} | Civil (algorithmic) Arabic calendar. | This is an alias for `islamic-civil` and therefore is not returned by `supportedValuesOf()`. Use `islamic-civil` instead. | -| `islamic-rgsa` | Hijri calendar, Saudi Arabia sighting | Browsers do not have historical sighting data and future sightings have not occurred yet. As of April 2025, this calendar results in the same behavior as `islamic`. Use `islamic-umalqura` for a Mecca-based astronomical calculation. | +| Value | Description | Notes | +| -------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ethiopic-amete-alem` | Ethiopic calendar, Amete Alem, proleptic. | This is an alias for `ethioaa` and therefore is not returned by `supportedValuesOf()`. Use `ethioaa` instead. | +| `islamic` | Hijri calendar, unspecified algorithm. | As of April 2025, this is an astronomical simulation whose parameters are undocumented and that is not known to match a specific Hijri calendar variant from non-software contexts. It is specified to be canonicalized to a different calendar, usually one of `islamic-umalqura`, `islamic-tbla`, or `islamic-civil`, and raise a warning. | +| `islamicc` {{deprecated_inline}} | Civil (algorithmic) Arabic calendar. | This is an alias for `islamic-civil` and therefore is not returned by `supportedValuesOf()`. Use `islamic-civil` instead. | + +The {{jsxref("Temporal/PlainDate/era", "Temporal.PlainDate.prototype.era")}} and {{jsxref("Temporal/PlainDate/monthCode", "Temporal.PlainDate.prototype.monthCode")}} docs provide more information about different calendars. References: diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md index 759996641fdfa91..9939957a65c95ea 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/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 diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md index 30289f80e88fff3..c3cfb6b91f67ab6 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/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. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md index 989f3f022dc42d7..ebc8aaab650df20 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/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({ diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md index 2ae8caaf704cfd1..c91f22e9fbfa15e 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/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")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md index 4b7cec9705b893f..d8dbc1ff37bd8c4 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/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"); diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md index 05bb1a6efd097f9..0f6dc37b05ccfb3 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/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 diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md index 43272dc0d95fcb4..bf87a10b9346e6f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md @@ -7,9 +7,26 @@ browser-compat: javascript.builtins.Temporal.PlainDate.year sidebar: jsref --- -The **`year`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns an integer representing the number of years of this date relative to the start of a calendar-specific epoch year. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`year`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns an integer representing the number of years of this date relative to the start of a calendar-specific epoch year. This property has the same function as the {{jsxref("Temporal/PlainDate/era", "era")}}/{{jsxref("Temporal/PlainDate/eraYear", "eraYear")}} pair as a unique identifier of a year in a calendar. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -This property has the same function as the {{jsxref("Temporal/PlainDate/era", "era")}}/{{jsxref("Temporal/PlainDate/eraYear", "eraYear")}} pair as a unique identifier of a year in a calendar. Usually year 1 is either the first year of the latest era or the ISO 8601 year `0001`. Because `year` is relative to the start of the epoch year, not the epoch date, if the epoch is in the middle of the year, that year will have the same value before and after the start date of the era. +## Value + +Usually year 1 is either the first year of the latest era or the ISO 8601 year `0001`. Because `year` is relative to the start of the epoch year, not the epoch date, if the epoch is in the middle of the year (only known to happen for the `japanese` calendar), that year will have the same `year` value before and after the start date of the era (for the `japanese` calendar, `year` is the same as the ISO 8601 year). + +All [specified calendars](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types) have arithmetic years fully defined by the spec. + +- The following calendars have the same epoch year as ISO 8601: `chinese`, `dangi`, `gregory`, `japanese`, in which `year: 1` corresponds to the ISO year `1`. +- The `buddhist` calendar uses the Buddhist epoch of 543 BCE, so `year: 1` corresponds to the ISO year `-542`. +- The `coptic` calendar uses the Coptic epoch of 284 CE, so `year: 1` corresponds to the ISO year `284`. +- The `ethioaa` calendar uses the Anno Mundi epoch of 5493 BCE, so `year: 1` corresponds to the ISO year `-5492`. +- The `ethiopic` calendar uses the Ethiopic epoch of 8 CE, so `year: 1` corresponds to the ISO year `8`. +- The `hebrew` calendar uses the Anno Mundi epoch of 3761 BCE, so `year: 1` corresponds to the ISO year `-3760`. +- The `indian` calendar uses the Śaka epoch of 79 CE, so `year: 1` corresponds to the ISO year `79`. +- The following calendars use the Hijri epoch of 622 CE: `islamic-civil`, `islamic-tbla`, `islamic-umalqura`, `persian`, in which `year: 1` corresponds to the ISO year `622`. +- The `roc` calendar uses the Minguo epoch of 1912 CE, so `year: 1` corresponds to the ISO year `1912`. + +> [!NOTE] +> For the `chinese` and `dangi` calendars, the CLDR data uses the Huangdi epoch of 2637 BCE by default, but Temporal defined it to use the ISO 8601 epoch for simplicity. The set accessor of `year` 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. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md index 8598a93ad83b38c..728049303478ed2 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md @@ -22,7 +22,7 @@ const dt = Temporal.PlainDateTime.from("2021-07-01"); // ISO 8601 calendar console.log(dt.era); // undefined const dt2 = Temporal.PlainDateTime.from("2021-07-01[u-ca=gregory]"); -console.log(dt2.era); // gregory +console.log(dt2.era); // ce ``` ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md index 4f3528214b1a4fe..17a5bfba290577d 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md @@ -76,7 +76,7 @@ These properties are defined on `Temporal.PlainDateTime.prototype` and shared by - {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.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/PlainDateTime/era", "Temporal.PlainDateTime.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/PlainDateTime/eraYear", "Temporal.PlainDateTime.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/PlainDateTime/hour", "Temporal.PlainDateTime.prototype.hour")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/add/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/add/index.md index fb78638db82accd..fb39c0feb5f0a54 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/add/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/add/index.md @@ -71,15 +71,15 @@ console.log(end3.toString()); // 2022-01 ```js const start = Temporal.PlainYearMonth.from("2021-02-01[u-ca=chinese]"); -console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 11/2020 +console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 12/2020 console.log(start.toString()); // 2021-01-13[u-ca=chinese] const end = start.add({ months: 1 }); -console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 12/2020 +console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 1/2021 console.log(end.toString()); // 2021-02-12[u-ca=chinese] // Adding an extra day has no effect at all const end2 = start.add({ months: 1, days: 1 }); -console.log(end2.toLocaleString("en-US", { calendar: "chinese" })); // 12/2020 +console.log(end2.toLocaleString("en-US", { calendar: "chinese" })); // 1/2021 // The reference day doesn't change, because it's always the first day of the Chinese month console.log(end2.toString()); // 2021-02-12[u-ca=chinese] diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/era/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/era/index.md index 2255ab7c5ad7c3a..87fdf673f3fef23 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/era/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/era/index.md @@ -22,7 +22,7 @@ const ym = Temporal.PlainYearMonth.from("2021-07"); // ISO 8601 calendar console.log(ym.era); // undefined const ym2 = Temporal.PlainYearMonth.from("2021-07-01[u-ca=gregory]"); -console.log(ym2.era); // gregory +console.log(ym2.era); // ce ``` ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md index 63a30d878125290..2cb92c23de11d77 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md @@ -58,7 +58,7 @@ These properties are defined on `Temporal.PlainYearMonth.prototype` and shared b - {{jsxref("Temporal/PlainYearMonth/daysInYear", "Temporal.PlainYearMonth.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/PlainYearMonth/era", "Temporal.PlainYearMonth.prototype.era")}} - - : Returns a calendar-specific lowercase string representing the era of this year-month, 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 year-month, 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/PlainYearMonth/eraYear", "Temporal.PlainYearMonth.prototype.eraYear")}} - : Returns a non-negative integer representing the year of this year-month 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/PlainYearMonth/inLeapYear", "Temporal.PlainYearMonth.prototype.inLeapYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/tostring/index.md index 7d2e0ab445981f2..632a3a452f0829d 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/tostring/index.md @@ -51,11 +51,11 @@ const ym = Temporal.PlainYearMonth.from({ year: 2021, month: 8 }); console.log(ym.toString()); // '2021-08' const ym2 = Temporal.PlainYearMonth.from({ - year: 4658, + year: 5781, monthCode: "M08", - calendar: "chinese", + calendar: "hebrew", }); -console.log(ym2.toString()); // '2021-09-07[u-ca=chinese]' +console.log(ym2.toString()); // '2021-04-13[u-ca=hebrew]' ``` ### Using options @@ -63,18 +63,18 @@ console.log(ym2.toString()); // '2021-09-07[u-ca=chinese]' ```js const isoYM = Temporal.PlainYearMonth.from({ year: 2021, month: 8 }); const ym = Temporal.PlainYearMonth.from({ - year: 4658, + year: 5781, monthCode: "M08", - calendar: "chinese", + calendar: "hebrew", }); console.log(isoYM.toString({ calendarName: "auto" })); // '2021-08' -console.log(ym.toString({ calendarName: "auto" })); // '2021-09-07[u-ca=chinese]' +console.log(ym.toString({ calendarName: "auto" })); // '2021-04-13[u-ca=hebrew]' console.log(isoYM.toString({ calendarName: "always" })); // '2021-08-01[u-ca=iso8601]' -console.log(ym.toString({ calendarName: "always" })); // '2021-09-07[u-ca=chinese]' +console.log(ym.toString({ calendarName: "always" })); // '2021-04-13[u-ca=hebrew]' console.log(isoYM.toString({ calendarName: "never" })); // '2021-08' -console.log(ym.toString({ calendarName: "never" })); // '2021-09-07' +console.log(ym.toString({ calendarName: "never" })); // '2021-04-13' console.log(isoYM.toString({ calendarName: "critical" })); // '2021-08-01[!u-ca=iso8601]' -console.log(ym.toString({ calendarName: "critical" })); // '2021-09-07[!u-ca=chinese]' +console.log(ym.toString({ calendarName: "critical" })); // '2021-04-13[!u-ca=hebrew]' ``` ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/era/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/era/index.md index 796981d38b73a45..9e56f8502c36534 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/era/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/era/index.md @@ -24,7 +24,7 @@ console.log(dt.era); // undefined const dt2 = Temporal.ZonedDateTime.from( "2021-07-01[America/New_York][u-ca=gregory]", ); -console.log(dt2.era); // gregory +console.log(dt2.era); // ce ``` ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md index 49dfcefc0d71b19..5fd1be3330eb6e2 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md @@ -199,7 +199,7 @@ These properties are defined on `Temporal.ZonedDateTime.prototype` and shared by - {{jsxref("Temporal/ZonedDateTime/epochNanoseconds", "Temporal.ZonedDateTime.prototype.epochNanoseconds")}} - : Returns a {{jsxref("BigInt")}} representing the number of nanoseconds elapsed since the Unix epoch (midnight at the beginning of January 1, 1970, UTC) to this instant. - {{jsxref("Temporal/ZonedDateTime/era", "Temporal.ZonedDateTime.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/ZonedDateTime/eraYear", "Temporal.ZonedDateTime.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/ZonedDateTime/hour", "Temporal.ZonedDateTime.prototype.hour")}}