PlainYearMonth docs

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

@@ -31,7 +31,7 @@ round(options)
     - `roundingMode` {{optional_inline}}
       - : A string representing the rounding mode specifying to round up or down in various scenarios. See [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode). Defaults to `"halfExpand"`.
     - `smallestUnit` {{optional_inline}}
-      - : Any of the temporal units: `"year"`, `"month"`, `"week"`, `"day"`, `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. Defaults to `"nanosecond"`. Fractional parts of the `smallestUnit` will be rounded according to the `roundingIncrement` and `roundingMode` settings. Must be smaller or equal to `largestUnit`. At least one of `smallestUnit` and `largestUnit` must be provided.
+      - : Any of the temporal units: `"year"`, `"month"`, `"week"`, `"day"`, `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. Defaults to `"nanosecond"`. For units larger than `"nanosecond"`, fractional parts of the `smallestUnit` will be rounded according to the `roundingIncrement` and `roundingMode` settings. Must be smaller or equal to `largestUnit`. At least one of `smallestUnit` and `largestUnit` must be provided.
 
 ### Return value
 
@@ -50,6 +50,8 @@ The `round()` method performs two operations: rounding and balancing. It does th
 2. For all components larger than `largestUnit`, they are carried down into `largestUnit`; for example, "2 hours 30 minutes" becomes "150 minutes" if `largestUnit` is `"minute"`.
 3. For all components smaller than `smallestUnit`, they are carried up into `smallestUnit` as a fractional part, and then rounded according to the `roundingIncrement` and `roundingMode` settings. For example, "1 hour 30 minutes" becomes "1.5 hours" if `smallestUnit` is `"hour"`, and then rounded to "2 hours" using the default settings.
 
+[Calendar units](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_units) have uneven lengths. Their lengths are resolved relative to a starting point. For example, a duration of "2 years" in the Gregorian calendar may be 730 days or 731 days long, depending on whether it moves through a leap year or not. When rounding to a calendar unit, we first get the exact date-time represented by `relativeTo + duration`, then round it down and up according to `smallestUnit` and `roundingIncrement` to get two candidates. Then, we choose the candidate according to the `roundingMode` setting, and finally subtract `relativeTo` to get the final duration.
+
 ## Examples
 
 ### Rounding off small units

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

@@ -63,5 +63,6 @@ const obj = JSON.parse(jsonStr, (key, value) => {
 ## See also
 
 - {{jsxref("Temporal.Duration")}}
+- {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}
 - {{jsxref("Temporal/Duration/toString", "Temporal.Duration.prototype.toString()")}}
 - {{jsxref("Temporal/Duration/toLocaleString", "Temporal.Duration.prototype.toLocaleString()")}}

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

@@ -338,7 +338,7 @@ The concept of a "week" is not connected with any astronomical event, but is a c
 - {{jsxref("Temporal.PlainTime")}}
   - : Represents a time without a date or time zone; for example, a recurring event that happens at the same time every day. It is fundamentally represented as a combination of hour, minute, second, millisecond, microsecond, and nanosecond values.
 - {{jsxref("Temporal.PlainYearMonth")}}
-  - : Represents the year and month of a calendar date, without a day or time zone; for example, an event on a calendar that happens during the whole month. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The day is used to disambiguate the year-month in some calendar systems.
+  - : Represents the year and month of a calendar date, without a day or time zone; for example, an event on a calendar that happens during the whole month. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The day is used to disambiguate the year-month in non-ISO calendar systems.
 - {{jsxref("Temporal.ZonedDateTime")}}
   - : Represents a date and time with a time zone. It is fundamentally represented as a combination of an [instant](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant), a time zone, and a calendar system.
 - `Temporal[Symbol.toStringTag]`

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

@@ -27,7 +27,7 @@ round(options)
     - `roundingMode` {{optional_inline}}
       - : A string specifying how to round off the fractional part of `smallestUnit`. See [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode). Defaults to `"halfExpand"`.
     - `smallestUnit`
-      - : A string representing the smallest unit to include in the output. The value must be one of the following: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. Fractional parts of the `smallestUnit` will be rounded according to the `roundingIncrement` and `roundingMode` settings.
+      - : A string representing the smallest unit to include in the output. The value must be one of the following: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. For units larger than `"nanosecond"`, fractional parts of the `smallestUnit` will be rounded according to the `roundingIncrement` and `roundingMode` settings.
 
 ### Return value
 

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

@@ -31,7 +31,7 @@ since(other, options)
     - `roundingMode` {{optional_inline}}
       - : A string specifying how to round off the fractional part of `smallestUnit`. See [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode). Defaults to `"trunc"`.
     - `smallestUnit` {{optional_inline}}
-      - : A string representing the smallest unit to include in the output. The value must be one of the following: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. Defaults to `"nanosecond"`. Fractional parts of the `smallestUnit` will be rounded according to the `roundingIncrement` and `roundingMode` settings. Must be smaller or equal to `largestUnit`.
+      - : A string representing the smallest unit to include in the output. The value must be one of the following: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. Defaults to `"nanosecond"`. For units larger than `"nanosecond"`, fractional parts of the `smallestUnit` will be [rounded](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/round) according to the `roundingIncrement` and `roundingMode` settings. Must be smaller or equal to `largestUnit`.
 
 ### Return value
 

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

@@ -63,5 +63,6 @@ const obj = JSON.parse(jsonStr, (key, value) => {
 ## See also
 
 - {{jsxref("Temporal.Instant")}}
+- {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}
 - {{jsxref("Temporal/Instant/toString", "Temporal.Instant.prototype.toString()")}}
 - {{jsxref("Temporal/Instant/toLocaleString", "Temporal.Instant.prototype.toLocaleString()")}}

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

@@ -31,7 +31,7 @@ add(duration, options)
 
 ### Return value
 
-A new `Temporal.PlainDate` object representing the date specified by the original date, plus the duration.
+A new `Temporal.PlainDate` object representing the date specified by the original `PlainDate`, plus the duration.
 
 ## Description
 
@@ -83,7 +83,7 @@ console.log(end.toString()); // 2021-02-28
 const end2 = start.add({ months: 1, days: 31 });
 console.log(end2.toString()); // 2021-03-31
 
-// Compare:
+// Compare with the same addition in a different order that results in no overflow:
 const end3 = start.add({ days: 31 }).add({ months: 1 });
 console.log(end3.toString()); // 2021-04-03
 ```

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

@@ -33,7 +33,6 @@ Returns `-1` if `date1` comes before `date2`, `0` if they are the same, and `1`
 ```js
 const date1 = Temporal.PlainDate.from("2021-08-01");
 const date2 = Temporal.PlainDate.from("2021-08-02");
-
 console.log(Temporal.PlainDate.compare(date1, date2)); // -1
 
 const date3 = Temporal.PlainDate.from("2021-07-31");

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

@@ -36,7 +36,7 @@ Temporal.PlainDate.from(info, options)
       - `month`
         - : Corresponds to the {{jsxref("Temporal/PlainDate/month", "month")}} property. Must be positive regardless of the `overflow` option.
       - `monthCode`
-        - : Corresponds to the {{jsxref("Temporal/PlainDate/monthCode", "monthCode")}} property. If both `month` and `monthCode` are provided, they must be consistent.
+        - : Corresponds to the {{jsxref("Temporal/PlainDate/monthCode", "monthCode")}} property. If it is not provided, then `month` must be provided. If both `month` and `monthCode` are provided, they must be consistent.
       - `year`
         - : Corresponds to the {{jsxref("Temporal/PlainDate/year", "year")}} property.
 
@@ -65,7 +65,7 @@ A new `Temporal.PlainDate` object, representing the date specified by `info` in
 - {{jsxref("RangeError")}}
   - : Thrown in one of the following cases:
     - The provided properties that specify the same component are inconsistent.
-    - The provided non-numerical properties are not valid, for example, `monthCode` is not a valid month code.
+    - The provided non-numerical properties are not valid, for example, if `monthCode` is never a valid month code in this calendar.
     - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`.
 
 ## Examples

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

@@ -31,7 +31,7 @@ since(other, options)
     - `roundingMode` {{optional_inline}}
       - : A string specifying how to round off the fractional part of `smallestUnit`. See [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode). Defaults to `"trunc"`.
     - `smallestUnit` {{optional_inline}}
-      - : A string representing the smallest unit to include in the output. The value must be one of the following: `"year"`, `"month"`, `"week"`, `"day"`, or their plural forms. Defaults to `"day"`. Fractional parts of the `smallestUnit` will be rounded according to the `roundingIncrement` and `roundingMode` settings. Must be smaller or equal to `largestUnit`.
+      - : A string representing the smallest unit to include in the output. The value must be one of the following: `"year"`, `"month"`, `"week"`, `"day"`, or their plural forms. Defaults to `"day"`. For units larger than `"day"`, fractional parts of the `smallestUnit` will be [rounded](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/round) according to the `roundingIncrement` and `roundingMode` settings. Must be smaller or equal to `largestUnit`.
 
 ### Return value
 

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

@@ -18,6 +18,8 @@ subtract(duration)
 subtract(duration, options)
 ```
 
+### Parameters
+
 - `duration`
   - : A string, an object, or a {{jsxref("Temporal.Duration")}} instance representing a duration to subtract from this date. It is converted to a `Temporal.Duration` object using the same algorithm as {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}.
 - `options` {{optional_inline}}

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

@@ -43,7 +43,7 @@ This example shows how `Temporal.PlainDate` can be serialized as JSON without ex
 
 ```js
 const date = Temporal.PlainDate.from({ year: 2021, month: 8, day: 1 });
-const dateStr = JSON.stringify({ date }); // '{"date":"2021-08-01"}'
+const jsonStr = JSON.stringify({ date }); // '{"date":"2021-08-01"}'
 const obj = JSON.parse(jsonStr, (key, value) => {
   if (key === "date") {
     return Temporal.PlainDate.from(value);
@@ -63,5 +63,6 @@ const obj = JSON.parse(jsonStr, (key, value) => {
 ## See also
 
 - {{jsxref("Temporal.PlainDate")}}
+- {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}
 - {{jsxref("Temporal/PlainDate/toString", "Temporal.PlainDate.prototype.toString()")}}
 - {{jsxref("Temporal/PlainDate/toLocaleString", "Temporal.PlainDate.prototype.toLocaleString()")}}

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

@@ -54,7 +54,7 @@ A new `Temporal.PlainDate` object, where the fields specified in `info` that are
 - {{jsxref("RangeError")}}
   - : Thrown in one of the following cases:
     - The provided properties that specify the same component are inconsistent.
-    - The provided non-numerical properties are not valid, for example, `monthCode` is not a valid month code.
+    - The provided non-numerical properties are not valid, for example, if `monthCode` is never a valid month code in this calendar.
     - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`.
 
 ## Examples

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

@@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.daysInYear
 
 The **`daysInYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the number of days in the year of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 
-The set accessor of `daysInWeek` is `undefined`. You cannot change this property directly.
+The set accessor of `daysInYear` is `undefined`. You cannot change this property directly.
 
 For general information and more examples, see {{jsxref("Temporal/PlainDate/daysInYear", "Temporal.PlainDate.prototype.daysInYear")}}.
 

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

@@ -32,4 +32,4 @@ For general information and more examples, see {{jsxref("Temporal/PlainDate/year
 - {{jsxref("Temporal/PlainDateTime/dayOfWeek", "Temporal.PlainDateTime.prototype.dayOfWeek")}}
 - {{jsxref("Temporal/PlainDateTime/daysInWeek", "Temporal.PlainDateTime.prototype.daysInWeek")}}
 - {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}}
-- {{jsxref("Temporal.PlainDate/yearOfWeek", "Temporal.PlainDate.prototype.yearOfWeek")}}
+- {{jsxref("Temporal/PlainDate/yearOfWeek", "Temporal.PlainDate.prototype.yearOfWeek")}}

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

@@ -21,7 +21,7 @@ The set accessor of `calendarId` is `undefined`. You cannot change this property
 const md = Temporal.PlainMonthDay.from("07-01");
 console.log(md.calendarId); // "iso8601"; default
 
-const md2 = Temporal.PlainMonthDay.from("07-01[u-ca=chinese]");
+const md2 = Temporal.PlainMonthDay.from("2021-07-01[u-ca=chinese]");
 console.log(md2.calendarId); // "chinese"
 ```
 
@@ -33,13 +33,13 @@ const newMD = md
   .toPlainDate({ year: 2021 })
   .withCalendar("chinese")
   .toPlainMonthDay();
-console.log(newMD.monthCode, newMD.day); // "M05", 22
+console.log(newMD.monthCode, newMD.day); // "M05" 22
 
 const newMD2 = md
   .toPlainDate({ year: 2022 })
   .withCalendar("chinese")
   .toPlainMonthDay();
-console.log(newMD2.monthCode, newMD2.day); // "M06", 3
+console.log(newMD2.monthCode, newMD2.day); // "M06" 3
 ```
 
 ## Specifications

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

@@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.equals
 
 {{JSRef}}
 
-The **`equals()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns `true` if this month-day is equivalent in value to another month-day (in a form convertible by {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}}), and `false` otherwise. They are compared both by their date values and their calendars.
+The **`equals()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns `true` if this month-day is equivalent in value to another month-day (in a form convertible by {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}}), and `false` otherwise. They are compared both by their underlying ISO date values and their calendars.
+
+> **Note:** `PlainMonthDay` objects keep track of a reference ISO year, which is also used in the comparison. This year is automatically set when using the {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} method, but can be set manually using the {{jsxref("Temporal/PlainMonthDay/PlainMonthDay", "Temporal.PlainMonthDay()")}} constructor, causing two equivalent month-days to be considered different if they have different reference years. For this reason, you should avoid using the constructor directly and prefer the `from()` method.
 
 ## Syntax
 

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

@@ -40,7 +40,7 @@ Temporal.PlainMonthDay.from(info, options)
 
       Other `Temporal` objects, such as {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainDateTime")}} and {{jsxref("Temporal.ZonedDateTime")}}, conform to this shape and can be used as well.
 
-    - An [ISO 8601](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#iso_8601_format) string containing a date and optionally a calendar. If the calendar is not `iso8601`, a year is required.
+    - An [ISO 8601](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay#iso_8601_format) string containing a date and optionally a calendar. If the calendar is not `iso8601`, a year is required.
 
 - `options` {{optional_inline}}
   - : An object containing the following property:
@@ -59,6 +59,8 @@ Each `PlainMonthDay` stores a whole ISO 8601 date internally, which has the same
 
 For example, for Gregorian-derived calendars, the reference year is 1972. For the Hebrew calendar, the reference year is 1972 in the Gregorian calendar, but if the month is Adar I (`M05L`), which is a leap month, the reference year is 1970 (5730 in Hebrew calendar) instead, because the next leap year is 1973 (5733 in Hebrew calendar), which is after 1972.
 
+This reference year canonicalization ensures that {{jsxref("Temporal/PlainMonthDay/equals", "equals()")}} can directly compare the underlying ISO dates without extra computation.
+
 ### Exceptions
 
 - {{jsxref("TypeError")}}
@@ -69,7 +71,7 @@ For example, for Gregorian-derived calendars, the reference year is 1972. For th
 - {{jsxref("RangeError")}}
   - : Thrown in one of the following cases:
     - The provided properties that specify the same component are inconsistent.
-    - The provided non-numerical properties are not valid, for example, `monthCode` is not a valid month code.
+    - The provided non-numerical properties are not valid, for example, if `monthCode` is never a valid month code in this calendar.
     - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`.
 
 ## Examples

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

@@ -109,3 +109,4 @@ console.log(
 
 - {{jsxref("Temporal")}}
 - {{jsxref("Temporal.PlainDate")}}
+- {{jsxref("Temporal.PlainYearMonth")}}

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

@@ -21,6 +21,9 @@ new Temporal.PlainMonthDay(month, day, calendar, referenceYear)
 
 > **Note:** `Temporal.PlainMonthDay()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}.
 
+> [!WARNING]
+> Avoid using the `calendar` and `referenceYear` parameters, because {{jsxref("Temporal/PlainMonthDay/equals", "equals()")}} will consider the reference year for equality, causing two equivalent month-days to be considered different if they have different reference years. To create a `Temporal.PlainMonthDay` object with a non-ISO calendar, use the {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} static method.
+
 ### Parameters
 
 - `month`
@@ -44,7 +47,7 @@ The same ISO month-day can represent different dates in different years with non
   - : Thrown if `calendar` is not a string or `undefined`.
 - {{jsxref("RangeError")}}
   - : Thrown in one of the following cases:
-    - `month` or `day` is not a finite number, or do not represent a valid date in the ISO calendar system.
+    - `referenceYear`, `month`, or `day` is not a finite number, or do not represent a valid date in the ISO calendar system.
     - `calendar` is not a valid calendar identifier.
 
 ## Examples
@@ -62,6 +65,18 @@ const md3 = new Temporal.PlainMonthDay(7, 1, "chinese", 2021);
 console.log(md3.toString()); // 2021-07-01[u-ca=chinese]
 ```
 
+### Improper usage
+
+You should avoid using the `calendar` and `referenceYear` parameters, unless you know that the `referenceYear` is the canonical reference year that would be selected by `Temporal.PlainMonthDay.from()` for the same month-day.
+
+```js
+const md = new Temporal.PlainMonthDay(7, 1, "chinese", 2021);
+const md2 = Temporal.PlainMonthDay.from("2021-07-01[u-ca=chinese]");
+console.log(md.equals(md2)); // false
+console.log(md.toString()); // 2021-07-01[u-ca=chinese]
+console.log(md2.toString()); // 1972-07-02[u-ca=chinese]
+```
+
 ## Specifications
 
 {{Specifications}}