Clarify setDate() behavior during timezone changes (fixes mdn#40531) (mdn#40559)

* Clarify setDate() behavior during timezone changes (fixes mdn#40531)

* Fix others

---------

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

Author: Shrinivassab

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

@@ -131,6 +131,21 @@ The {{jsxref("Date/Date", "Date()")}} constructor can be called with two or more
 
 When a segment overflows or underflows its expected range, it usually "carries over to" or "borrows from" the higher segment. For example, if the month is set to 12 (months are zero-based, so December is 11), it becomes the January of the next year. If the day of month is set to 0, it becomes the last day of the previous month. This also applies to dates specified with the [date time string format](#date_time_string_format).
 
+When attempting to set the local time to a time falling within an offset transition (usually daylight saving time), the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
+```js
+// Assume America/New_York local time zone
+// 2024-03-10 02:30 is within the spring-forward transition and does not exist
+// 01:59 (UTC-5) jumps to 03:00 (UTC-4), so 02:30 moves forward by one hour
+console.log(new Date(2024, 2, 10, 2, 30).toString());
+// Sun Mar 10 2024 03:30:00 GMT-0400 (Eastern Daylight Time)
+
+// 2024-11-03 01:30 is within the fall-back transition and exists twice
+// 01:59 (UTC-4) jumps to 01:00 (UTC-5), so the earlier 01:30 (UTC-4) is chosen
+console.log(new Date(2024, 10, 3, 1, 30).toString());
+// Sun Nov 03 2024 01:30:00 GMT-0400 (Eastern Daylight Time)
+```
+
 ### Date time string format
 
 There are many ways to format a date as a string. The JavaScript specification only specifies one format to be universally supported: the [_date time string format_](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-date-time-string-format), a simplification of the ISO 8601 calendar date extended format. The format is as follows:

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

@@ -45,6 +45,10 @@ Changes the {{jsxref("Date")}} object in place, and returns its new [timestamp](
 
 If you specify a number outside the expected range, the date information in the {{jsxref("Date")}} object is updated accordingly. For example, if the `Date` object holds June 1st, a `dateValue` of 40 changes the date to July 10th, while a `dateValue` of 0 changes the date to the last day of the previous month, May 31st.
 
+Because `setDate()` operates on the local time, crossing a Daylight Saving Time (DST) boundary may result in a different elapsed time than expected. For example, if setting the date crosses a spring-forward transition (losing an hour), the difference in timestamps between the new and old date is one hour less than the nominal day difference multiplied by 24 hours. Conversely, crossing a fall-back transition (gaining an hour) result in an extra hour. If you need to adjust the date by a fixed amount of time, consider using {{jsxref("Date/setUTCDate", "setUTCDate()")}} or {{jsxref("Date/setTime", "setTime()")}}.
+
+If the new local time falls within an offset transition, the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
 ## Examples
 
 ### Using setDate()

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

@@ -52,6 +52,10 @@ If you do not specify the `monthValue` and `dateValue` parameters, the same valu
 
 If a parameter you specify is outside of the expected range, other parameters and the date information in the {{jsxref("Date")}} object are updated accordingly. For example, if you specify 15 for `monthValue`, the year is incremented by 1 (`yearValue + 1`), and 3 is used for the month.
 
+Because `setFullYear()` operates on the local time, crossing a Daylight Saving Time (DST) boundary may result in a different elapsed time than expected. For example, if setting the date crosses a spring-forward transition (losing an hour), the difference in timestamps between the new and old date is one hour less than the nominal day difference multiplied by 24 hours. Conversely, crossing a fall-back transition (gaining an hour) result in an extra hour. If you need to adjust the date by a fixed amount of time, consider using {{jsxref("Date/setUTCFullYear", "setUTCFullYear()")}} or {{jsxref("Date/setTime", "setTime()")}}.
+
+If the new local time falls within an offset transition, the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
 ## Examples
 
 ### Using setFullYear()

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

@@ -55,6 +55,10 @@ If you do not specify the `minutesValue`, `secondsValue`, and `msValue` paramete
 
 If a parameter you specify is outside of the expected range, other parameters and the date information in the {{jsxref("Date")}} object are updated accordingly. For example, if you specify 100 for `secondsValue`, the minutes are incremented by 1 (`minutesValue + 1`), and 40 is used for seconds.
 
+Because `setHours()` operates on the local time, crossing a Daylight Saving Time (DST) boundary may result in a different elapsed time than expected. For example, if setting the hours crosses a spring-forward transition (losing an hour), the difference in timestamps between the new and old date is one hour less than the nominal hour difference. Conversely, crossing a fall-back transition (gaining an hour) result in an extra hour. If you need to adjust the date by a fixed amount of time, consider using {{jsxref("Date/setUTCHours", "setUTCHours()")}} or {{jsxref("Date/setTime", "setTime()")}}.
+
+If the new local time falls within an offset transition, the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
 ## Examples
 
 ### Using setHours()

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

@@ -42,6 +42,10 @@ Changes the {{jsxref("Date")}} object in place, and returns its new [timestamp](
 
 If you specify a number outside the expected range, the date information in the {{jsxref("Date")}} object is updated accordingly. For example, if you specify 1005, the number of seconds is incremented by 1, and 5 is used for the milliseconds.
 
+Because `setMilliseconds()` operates on the local time, crossing a Daylight Saving Time (DST) boundary may result in a different elapsed time than expected. For example, if setting the milliseconds crosses a spring-forward transition (losing an hour), the difference in timestamps between the new and old date is one hour less than the nominal time difference. Conversely, crossing a fall-back transition (gaining an hour) result in an extra hour. If you need to adjust the date by a fixed amount of time, consider using {{jsxref("Date/setUTCMilliseconds", "setUTCMilliseconds()")}} or {{jsxref("Date/setTime", "setTime()")}}.
+
+If the new local time falls within an offset transition, the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
 ## Examples
 
 ### Using setMilliseconds()

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

@@ -51,6 +51,10 @@ If you do not specify the `secondsValue` and `msValue` parameters, the same valu
 
 If a parameter you specify is outside of the expected range, other parameters and the date information in the {{jsxref("Date")}} object are updated accordingly. For example, if you specify 100 for `secondsValue`, the minutes is incremented by 1 (`minutesValue + 1`), and 40 is used for seconds.
 
+Because `setMinutes()` operates on the local time, crossing a Daylight Saving Time (DST) boundary may result in a different elapsed time than expected. For example, if setting the minutes crosses a spring-forward transition (losing an hour), the difference in timestamps between the new and old date is one hour less than the nominal time difference. Conversely, crossing a fall-back transition (gaining an hour) result in an extra hour. If you need to adjust the date by a fixed amount of time, consider using {{jsxref("Date/setUTCMinutes", "setUTCMinutes()")}} or {{jsxref("Date/setTime", "setTime()")}}.
+
+If the new local time falls within an offset transition, the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
 ## Examples
 
 ### Using setMinutes()

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

@@ -54,6 +54,10 @@ Conceptually it will add the number of days given by the current day of the mont
 For example, if the current value is 31st January 2016, calling setMonth with a value of 1 will return 2nd March 2016.
 This is because in 2016 February had 29 days.
 
+Because `setMonth()` operates on the local time, crossing a Daylight Saving Time (DST) boundary may result in a different elapsed time than expected. For example, if setting the month crosses a spring-forward transition (losing an hour), the difference in timestamps between the new and old date is one hour less than the nominal day difference multiplied by 24 hours. Conversely, crossing a fall-back transition (gaining an hour) result in an extra hour. If you need to adjust the date by a fixed amount of time, consider using {{jsxref("Date/setUTCMonth", "setUTCMonth()")}} or {{jsxref("Date/setTime", "setTime()")}}.
+
+If the new local time falls within an offset transition, the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
 ## Examples
 
 ### Using setMonth()

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

@@ -54,6 +54,10 @@ For example, if you use 100 for `secondsValue`, the minutes stored
 in the {{jsxref("Date")}} object will be incremented by 1, and 40 will be used for
 seconds.
 
+Because `setSeconds()` operates on the local time, crossing a Daylight Saving Time (DST) boundary may result in a different elapsed time than expected. For example, if setting the seconds crosses a spring-forward transition (losing an hour), the difference in timestamps between the new and old date is one hour less than the nominal time difference. Conversely, crossing a fall-back transition (gaining an hour) result in an extra hour. If you need to adjust the date by a fixed amount of time, consider using {{jsxref("Date/setUTCSeconds", "setUTCSeconds()")}} or {{jsxref("Date/setTime", "setTime()")}}.
+
+If the new local time falls within an offset transition, the exact time is derived using the same behavior as `Temporal`'s [`disambiguation: "compatible"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity_and_gaps_from_local_time_to_utc_time) option. That is, if the local time corresponds to two instants, the earlier one is chosen; if the local time does not exist (there is a gap), we go forward by the gap duration.
+
 ## Examples
 
 ### Using setSeconds()