Editorial: Recommend "remapping" for dates exceeding era year bounds

docs/plaindate.md

@@ -81,8 +81,8 @@ If the string isn't valid according to ISO 8601, then a `RangeError` will be thr
 
 The `overflow` option works as follows, if `item` is an object:
 
-- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value.
-- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
+- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`).
+- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`.
 
 The `overflow` option is ignored if `item` is a string.
 

docs/plaindatetime.md

@@ -112,8 +112,8 @@ If the string isn't valid according to ISO 8601, then a `RangeError` will be thr
 
 The `overflow` option works as follows, if `item` is an object:
 
-- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value.
-- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
+- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`).
+- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`.
 
 The `overflow` option is ignored if `item` is a string.
 

docs/plainyearmonth.md

@@ -83,8 +83,8 @@ A `RangeError` will also be thrown for strings that contain a `Z` in place of a
 
 The `overflow` option works as follows, if `item` is an object:
 
-- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value.
-- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
+- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`).
+- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`.
 
 The `overflow` option is ignored if `item` is a string.
 

docs/zoneddatetime.md

@@ -175,8 +175,8 @@ Instead of using `Temporal.ZonedDateTime` with an offset time zone, it may be ea
 
 The `overflow` option works as follows, if `item` is an object:
 
-- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value.
-- In `'reject'` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
+- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`).
+- In `'reject'` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`.
 
 The `overflow` option is ignored if `item` is a string.
 

polyfill/lib/calendar.mjs

@@ -1461,9 +1461,6 @@ const makeHelperGregorian = (id, originalEras) => {
           ({ code, names = [] }) => code === era || ES.Call(ArrayPrototypeIncludes, names, [era])
         ]);
         if (!matchingEra) throw new RangeErrorCtor(`Era ${era} (ISO year ${eraYear}) was not matched by any era`);
-        if (eraYear < 1 && matchingEra.reverseOf) {
-          throw new RangeErrorCtor(`Years in ${era} era must be positive, not ${year}`);
-        }
         if (matchingEra.reverseOf) {
           year = matchingEra.anchorEpoch.year - eraYear;
         } else {

spec/calendar.html

@@ -1348,6 +1348,13 @@ <h1>
       <emu-note>
         In some cases, verifying the internal consistency of fields requires accessing the data from other fields, such checking _fields_.[[MonthCode]] *"M06"* against _fields_.[[Month]] 7 in the Hebrew calendar (which are consistent if and only if _fields_ identifies a year that includes leap month Adar I).
       </emu-note>
+      <emu-note>
+        <p>When the fields of _fields_ are inconsistent with respect to a non-~unset~ _fields_.[[Era]], it is recommended that _fields_.[[Era]] and _fields_.[[EraYear]] be updated to resolve the inconsistency by appropriate interpretation of out-of-bounds values (rather than throwing a *RangeError*), which is particularly useful for consistent interpretation of dates in calendars with regnal eras.</p>
+        <ul>
+          <li>In the Gregorian calendar, a non-positive [[EraYear]] should be replaced with a positive [[EraYear]] corresponding with extension of the era into its complement and [[Era]] should be updating accordingly (such that Common Era [[EraYear]] 0 is updated to Before Common Era [[EraYear]] 1, Before Common Era [[EraYear]] -1 is updated to Common Era [[EraYear]] 2, etc.).</li>
+          <li>In the Japanese calendar, when _fields_.[[Era]] is not ~unset~ and the date represented by _fields_ is not within the bounds of that era, _fields_.[[Era]] should be updated to the appropriate containing era for that date (for example, because the transition from Heisei era [[EraYear]] 31 to Reiwa era [[EraYear]] 1 took place on May 1 of [[Year]] 2019, Heisei era [[EraYear]] 32 should be updated to Reiwa era [[EraYear]] 2, Reiwa era [[EraYear]] 1 [[Month]] 1 should be updated to Heisei era [[EraYear]] 31 [[Month]] 1, etc.).</li>
+        </ul>
+      </emu-note>
       <emu-note>
         When _type_ is ~month-day~ and _fields_.[[Month]] is not ~unset~, it is recommended that all built-in calendars other than the ISO 8601 calendar require a disambiguating year (e.g., either _fields_.[[Year]] or _fields_.[[Era]] and _fields_.[[EraYear]]), regardless of whether or not _fields_.[[MonthCode]] is also ~unset~. The ISO 8601 calendar allows _fields_.[[Year]] to be ~unset~ in this case because it is a special default calendar that is permanently stable for automated processing.
       </emu-note>