PlainMonthDay docs, copy date-related fields to PlainDateTime

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

@@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.Duration.Duration
 
 The **`Temporal.Duration()`** constructor creates {{jsxref("Temporal.Duration")}} objects.
 
-Like all other `Temporal` classes, you should usually construct `Temporal.Duration` objects using the {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}} static method, which can handle a variety of input types.
+This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.Duration` objects using the {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}} static method, which can handle a variety of input types.
 
 ## Syntax
 

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

@@ -83,7 +83,7 @@ Because a duration is a difference between two time points, it can be positive,
 ## Constructor
 
 - {{jsxref("Temporal/Duration/Duration", "Temporal.Duration()")}}
-  - : Creates a new `Temporal.Duration` object.
+  - : Creates a new `Temporal.Duration` object by directly supplying the underlying data.
 
 ## Static methods
 

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

@@ -23,20 +23,13 @@ toLocaleString(locales, options)
 
 The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used.
 
-In implementations that support the [`Intl.DurationFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat), these parameters correspond exactly to the [`Intl.DurationFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat) constructor's parameters. Implementations without `Intl.DurationFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent.
+In implementations that support the [`Intl.DurationFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat), these parameters correspond exactly to the [`Intl.DurationFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat) constructor's parameters. Implementations without `Intl.DurationFormat` support return the exact same string as {{jsxref("Temporal/Duration/toString", "toString()")}}, ignoring both parameters.
 
 - `locales` {{optional_inline}}
-
   - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat#locales) parameter of the `Intl.DurationFormat()` constructor.
-
-    In implementations without `Intl.DurationFormat` support, this parameter is ignored and the host's locale is usually used.
-
 - `options` {{optional_inline}}
-
   - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat#options) parameter of the `Intl.DurationFormat()` constructor.
 
-    In implementations without `Intl.DurationFormat` support, this parameter is ignored.
-
 See the [`Intl.DurationFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat) for details on these parameters and how to use them.
 
 ### Return value

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

@@ -334,7 +334,7 @@ The concept of a "week" is not connected with any astronomical event, but is a c
 - {{jsxref("Temporal.PlainDateTime")}}
   - : Represents a date (calendar date) and time (wall-clock time) without a time zone. It is fundamentally represented as a combination of a [date](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate) (with an associated calendar system) and a [time](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime).
 - {{jsxref("Temporal.PlainMonthDay")}}
-  - : Represents the month and day of a calendar date, without a year or time zone; for example, an event on a calendar that recurs every year and happens during the whole day. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The year is used to disambiguate the month-day in some calendar systems.
+  - : Represents the month and day of a calendar date, without a year or time zone; for example, an event on a calendar that recurs every year and happens during the whole day. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The year is used to disambiguate the month-day in non-ISO calendar systems.
 - {{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")}}

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

@@ -47,7 +47,7 @@ When serializing, you can configure the fractional second digits and offset.
 ## Constructor
 
 - {{jsxref("Temporal/Instant/Instant", "Temporal.Instant()")}}
-  - : Creates a new `Temporal.Instant` object.
+  - : Creates a new `Temporal.Instant` object by directly supplying the underlying data.
 
 ## Static methods
 

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

@@ -23,20 +23,13 @@ toLocaleString(locales, options)
 
 The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used.
 
-In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent.
+In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support return the exact same string as {{jsxref("Temporal/Instant/toString", "toString()")}}, ignoring both parameters.
 
 - `locales` {{optional_inline}}
-
   - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) parameter of the `Intl.DateTimeFormat()` constructor.
-
-    In implementations without `Intl.DateTimeFormat` support, this parameter is ignored and the host's locale is usually used.
-
 - `options` {{optional_inline}}
-
   - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) parameter of the `Intl.DateTimeFormat()` constructor.
 
-    In implementations without `Intl.DateTimeFormat` support, this parameter is ignored.
-
 See the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) for details on these parameters and how to use them.
 
 ### Return value

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

@@ -25,7 +25,7 @@ add(duration, options)
     - `overflow` {{optional_inline}}
       - : A string specifying the behavior when a date component is out of range. Possible values are:
         - `"constrain"` (default)
-          - : The date component is clamped to the valid range.
+          - : The date component is [clamped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping) to the valid range.
         - `"reject"`
           - : A {{jsxref("RangeError")}} is thrown if the date component is out of range.
 
@@ -37,7 +37,7 @@ A new `Temporal.PlainDate` object representing the date specified by the origina
 
 The `duration` is handled in this way:
 
-- Move forward by the number of years, keeping the `monthCode` and `day` the same. If the `monthCode` is invalid in the resulting year (impossible for Gregorian and ISO 8601, but possible for calendars with leap months), we adjust based on the `overflow` option: for `constrain`, we pick another month according to the cultural conventions of that calendar's users. For example, because the leap month is usually thought of as a duplicate of the previous month, we might choose the month before the leap month.
+- Move forward by the number of years, keeping the `monthCode` and `day` the same. If the `monthCode` is invalid in the resulting year (impossible for Gregorian and ISO 8601, but possible for calendars with leap months), we adjust based on the `overflow` option: for `constrain`, we pick another month according to the cultural conventions of that calendar's users. For example, because the leap month is usually thought of as a duplicate of another month, we may pick the month that it is a duplicate of.
 - Move forward by the number of months, adjusting the year if necessary, keeping the `day` the same. If the `day` is invalid in the resulting month (e.g., February 30), we adjust based on the `overflow` option: for `constrain`, we pick the closest valid day (e.g., February 28 or 29).
 - All commonly supported calendars use fixed-length weeks, so the number of weeks is just converted to the number of days. If the rule is more complex, we may take an approach similar to shifting months.
 - For all [non-calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) units (days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds), they are converted to the number of days. Fractional part of a day is ignored. Then, we move forward by that number of days, adjusting the month and year if necessary.

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

@@ -34,10 +34,10 @@ Returns `-1` if `date1` comes before `date2`, `0` if they are the same, and `1`
 const date1 = Temporal.PlainDate.from("2021-08-01");
 const date2 = Temporal.PlainDate.from("2021-08-02");
 
-console.log(Temporal.Instant.compare(instant1, instant2)); // -1
+console.log(Temporal.PlainDate.compare(date1, date2)); // -1
 
-const instant3 = Temporal.Instant.from("2021-07-31");
-console.log(Temporal.Instant.compare(instant1, instant3)); // 1
+const date3 = Temporal.PlainDate.from("2021-07-31");
+console.log(Temporal.PlainDate.compare(date1, date3)); // 1
 ```
 
 ### Comparing dates in different calendars

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

@@ -7,11 +7,14 @@ browser-compat: javascript.builtins.Temporal.PlainDate.day
 
 {{JSRef}}
 
-The **`day`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
+The **`day`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 
 It generally starts at 1 and is continuous, but not always. If you want to loop through all the days in a month, first use {{jsxref("Temporal/PlainDate/with", "with()")}} with `{ day: 1 }` (which sets to the beginning of the month, even if the actual number is not `1`), then repeatedly use {{jsxref("Temporal/PlainDate/add", "add()")}} with `{ days: 1 }`, until the month changes.
 
-The set accessor of `calendarId` 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.
+> [!NOTE]
+> Usually, the day index only changes when transitioning from one calendar system into another, such as [from the Julian to the Gregorian calendar](https://en.wikipedia.org/wiki/Adoption_of_the_Gregorian_calendar). In practice, all currently built-in calendars are [proleptic](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), meaning the calendar system is extended indefinitely into the past and future. Assuming `day` is non-continuous guards against future introductions of non-proleptic calendars.
+
+The set accessor of `day` 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.
 
 ## Examples
 
@@ -54,14 +57,16 @@ const newDate = date.add({ days: 14 });
 console.log(newDate.toString()); // 2021-07-15
 ```
 
-By default, `with()` constrains the day to the range of valid values. So you can use `{ day: 1 }` to set the day to the first day of the month, even if the first day does not have the number `1`. Similarly, both of the following will set the day to the last day of the month:
+By default, `with()` constrains the day to the range of valid values. So you can use `{ day: 1 }` to set the day to the first day of the month, even if the first day does not have the number `1`. Similarly, the following will set the day to the last day of the month:
 
 ```js
 const date = Temporal.PlainDate.from("2021-07-01");
-const lastDay = date.with({ day: date.daysInMonth }); // 2021-07-31
-const lastDay2 = date.with({ day: Number.MAX_VALUE }); // 2021-07-31
+const lastDay = date.with({ day: Number.MAX_VALUE }); // 2021-07-31
 ```
 
+> [!NOTE]
+> Avoid using {{jsxref("Temporal/PlainDate/daysInMonth", "daysInMonth")}} to set the day to the last day of the month. The last day of the month is not always the same as the number of days in the month, in the rare case where a month may have a few days skipped.
+
 ## Specifications
 
 {{Specifications}}

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

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.dayOfWeek
 
 {{JSRef}}
 
-The **`dayOfWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the week of this date. Days in a week are numbered sequentially from `1` to {{jsxref("Temporal/PlainDate/daysInWeek", "daysInWeek")}}, with each number mapping to its name. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. 1 usually represents Monday in the calendar, even when locales using the calendar may consider a different day as the first day of the week (see {{jsxref("Intl/Locale/getWeekInfo", "Intl.Locale.prototype.getWeekInfo()")}}).
+The **`dayOfWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the week of this date. Days in a week are numbered sequentially from `1` to {{jsxref("Temporal/PlainDate/daysInWeek", "daysInWeek")}}, with each number mapping to its name. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. 1 usually represents Monday in the calendar, even when locales using the calendar may consider a different day as the first day of the week (see {{jsxref("Intl/Locale/getWeekInfo", "Intl.Locale.prototype.getWeekInfo()")}}).
 
 All commonly supported calendars use 7-day weeks, and you could generally expect this property to return the same value for the same date across different calendars.
 

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

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.dayOfYear
 
 {{JSRef}}
 
-The **`dayOfYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the year of this date. The first day of this year is `1`, and the last day is the {{jsxref("Temporal/PlainDate/daysInYear", "daysInYear")}}. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
+The **`dayOfYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the year of this date. The first day of this year is `1`, and the last day is the {{jsxref("Temporal/PlainDate/daysInYear", "daysInYear")}}. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 
 The set accessor of `dayOfYear` is `undefined`. You cannot change this property directly. To create a new `Temporal.PlainDate` object with the desired new `dayOfYear` value, use the {{jsxref("Temporal/PlainDate/add", "add()")}} or {{jsxref("Temporal/PlainDate/subtract", "subtract()")}} method with the appropriate number of `days`.
 

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

@@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainDate.daysInMonth
 
 {{JSRef}}
 
-The **`daysInMonth`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the month of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
+The **`daysInMonth`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the month of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
+
+Note that the days in month is not always equal to the {{jsxref("Temporal/PlainDate/day", "day")}} of the last day of the month, in the rare case where a month may have a few days skipped.
 
 The set accessor of `daysInMonth` is `undefined`. You cannot change this property directly.
 
@@ -40,6 +42,16 @@ const secondLastDay = date.with({ day: date.daysInMonth - 1 });
 console.log(secondLastDay.toString()); // 2021-07-30
 ```
 
+This is not totally safe, though, because `daysInMonth` is not guaranteed to have any connection with the day index. Here's a safer way to get the second last day:
+
+```js
+const date = Temporal.PlainDate.from("2021-07-01");
+const secondLastDay = date
+  .with({ day: Number.MAX_SAFE_INTEGER })
+  .subtract({ days: 1 });
+console.log(secondLastDay.toString()); // 2021-07-30
+```
+
 ## Specifications
 
 {{Specifications}}

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

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.daysInWeek
 
 {{JSRef}}
 
-The **`daysInWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the week of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
+The **`daysInWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the week of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 
 For the ISO 8601 calendar, this is always 7, but in other calendar systems it may differ from week to week. All commonly supported calendars use 7-day weeks.
 

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

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.daysInYear
 
 {{JSRef}}
 
-The **`daysInYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances 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.
+The **`daysInYear`** accessor property of {{jsxref("Temporal.PlainDate")}} 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.
 
 For the ISO 8601 calendar, this is 365, or 366 in a leap year. In other calendar systems, it likely differs, especially in non-solar calendars.