Normative: Add timeZoneName: "critical" option to ZonedDateTime.toStr…

…ing()

This adds a new recognized value "critical" to the timeZoneName option of
ZonedDateTime.prototype.toString(). timeZoneName: "critical" behaves like
timeZoneName: "always", but it also outputs a "!" flag in the time zone
annotation. This flag is never used by Temporal, but could be consumed by
other programs.

See: #1450

docs/zoneddatetime.md

@@ -1245,7 +1245,7 @@ zdt1.equals(zdt1); // => true
     Valid values are `'auto'` and `'never'`.
     The default is `'auto'`.
   - `timeZoneName` (string): Whether to show the time zone name annotation in the return value.
-    Valid values are `'auto'` and `'never'`.
+    Valid values are `'auto'`, `'never'`, and `'critical'`.
     The default is `'auto'`.
   - `calendarName` (string): Whether to show the calendar annotation in the return value.
     Valid values are `'auto'`, `'always'`, `'never'`, and `'critical'`.
@@ -1284,8 +1284,9 @@ For more information on the calendar annotation, see [ISO string extensions](./s
 
 Likewise, passing `'never'` to the `timeZoneName` or `offset` options controls whether the time zone offset (`+01:00`) or name annotation (`[Europe/Paris]`) are shown.
 If the time zone offset is shown, it is always shown rounded to the nearest minute.
+The `timeZoneName` option can additionally be `'critical'` which will add an additional `!` to the annotation, similar to `calendarName`.
 
-The string format output by this method can be parsed by [`java.time.ZonedDateTime`](https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html) as long as the calendar annotation is not output.
+The string format output by this method can be parsed by [`java.time.ZonedDateTime`](https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html) as long as the calendar annotation is not output and `'critical'` is not used.
 For more information on `Temporal`'s extensions to the ISO 8601 / RFC 3339 string format and the progress towards becoming a published standard, see [String Parsing, Serialization, and Formatting](./strings.md).
 
 Example usage:

polyfill/lib/ecmascript.mjs

@@ -722,7 +722,7 @@ export const ES = ObjectAssign({}, ES2020, {
     return ES.GetOption(options, 'calendarName', ['auto', 'always', 'never', 'critical'], 'auto');
   },
   ToShowTimeZoneNameOption: (options) => {
-    return ES.GetOption(options, 'timeZoneName', ['auto', 'never'], 'auto');
+    return ES.GetOption(options, 'timeZoneName', ['auto', 'never', 'critical'], 'auto');
   },
   ToShowOffsetOption: (options) => {
     return ES.GetOption(options, 'offset', ['auto', 'never'], 'auto');
@@ -2146,7 +2146,10 @@ export const ES = ObjectAssign({}, ES2020, {
       const offsetNs = ES.GetOffsetNanosecondsFor(tz, instant);
       result += ES.FormatISOTimeZoneOffsetString(offsetNs);
     }
-    if (showTimeZone !== 'never') result += `[${tz}]`;
+    if (showTimeZone !== 'never') {
+      const flag = showTimeZone === 'critical' ? '!' : '';
+      result += `[${flag}${tz}]`;
+    }
     result += ES.MaybeFormatCalendarAnnotation(GetSlot(zdt, CALENDAR), showCalendar);
     return result;
   },

spec/abstractops.html

@@ -162,7 +162,7 @@ <h1>ToShowTimeZoneNameOption ( _normalizedOptions_ )</h1>
       It is different from the `timeZone` property passed to `Temporal.ZonedDateTime.from()` and from the `timeZone` property in the options passed to `Temporal.Instant.prototype.toString()`.
     </emu-note>
     <emu-alg>
-      1. Return ? GetOption(_normalizedOptions_, *"timeZoneName"*, *"string"*, « *"auto"*, *"never"* », *"auto"*).
+      1. Return ? GetOption(_normalizedOptions_, *"timeZoneName"*, *"string"*, « *"auto"*, *"never"*, *"critical"* », *"auto"*).
     </emu-alg>
   </emu-clause>
 

spec/zoneddatetime.html

@@ -1163,7 +1163,7 @@ <h1>
           _zonedDateTime_: a Temporal.ZonedDateTime,
           _precision_: one of *"auto"*, *"minute"*, or an integer between 0 and 9 inclusive,
           _showCalendar_: one of *"auto"*, *"always"*, *"never"*, or *"critical"*,
-          _showTimeZone_: one of *"auto"* or *"never"*,
+          _showTimeZone_: one of *"auto"*, *"never"*, or *"critical"*,
           _showOffset_: one of *"auto"* or *"never"*,
           optional _increment_: an integer,
           optional _unit_: one of *"minute"*, *"second"*, *"millisecond"*, *"microsecond"*, or *"nanosecond"*,
@@ -1195,7 +1195,8 @@ <h1>
           1. Let _timeZoneString_ be the empty String.
         1. Else,
           1. Let _timeZoneID_ be ? ToString(_timeZone_).
-          1. Let _timeZoneString_ be the string-concatenation of the code unit 0x005B (LEFT SQUARE BRACKET), _timeZoneID_, and the code unit 0x005D (RIGHT SQUARE BRACKET).
+          1. If _showTimeZone_ is *"critical"*, let _flag_ be *"!"*; else let _flag_ be the empty String.
+          1. Let _timeZoneString_ be the string-concatenation of the code unit 0x005B (LEFT SQUARE BRACKET), _flag_, _timeZoneID_, and the code unit 0x005D (RIGHT SQUARE BRACKET).
         1. Let _calendarString_ be ? MaybeFormatCalendarAnnotation(_zonedDateTime_.[[Calendar]], _showCalendar_).
         1. Return the string-concatenation of _dateTimeString_, _offsetString_, _timeZoneString_, and _calendarString_.
       </emu-alg>