diff --git a/docs/plaindate.md b/docs/plaindate.md index b66dbc45a0..8208b77a4a 100644 --- a/docs/plaindate.md +++ b/docs/plaindate.md @@ -621,7 +621,7 @@ date.equals(date); // => true - `options` (optional object): An object with properties influencing the formatting. The following options are recognized: - `calendarName` (string): Whether to show the calendar annotation in the return value. - Valid values are `'auto'`, `'always'`, and `'never'`. + Valid values are `'auto'`, `'always'`, `'never'`, and `'critical'`. The default is `'auto'`. **Returns:** a string in the ISO 8601 date format representing `date`. @@ -631,6 +631,7 @@ The string can be passed to `Temporal.PlainDate.from()` to create a new `Tempora Normally, a calendar annotation is shown when `date`'s calendar is not the ISO 8601 calendar. By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively. +Normally not necessary, a value of `'critical'` is equivalent to `'always'` but the annotation will contain an additional `!` for certain interoperation use cases. For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems). Example usage: diff --git a/docs/plaindatetime.md b/docs/plaindatetime.md index d5deea83ef..28855a34aa 100644 --- a/docs/plaindatetime.md +++ b/docs/plaindatetime.md @@ -850,7 +850,7 @@ dt1.equals(dt1); // => true - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - `calendarName` (string): Whether to show the calendar annotation in the return value. - Valid values are `'auto'`, `'always'`, and `'never'`. + Valid values are `'auto'`, `'always'`, `'never'`, and `'critical'`. The default is `'auto'`. - `fractionalSecondDigits` (number or string): How many digits to print after the decimal point in the output string. Valid values are `'auto'`, 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9. @@ -875,6 +875,7 @@ Note that rounding may change the value of other units as well. Normally, a calendar annotation is shown when `datetime`'s calendar is not the ISO 8601 calendar. By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively. +Normally not necessary, a value of `'critical'` is equivalent to `'always'` but the annotation will contain an additional `!` for certain interoperation use cases. For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems). Example usage: diff --git a/docs/plainmonthday.md b/docs/plainmonthday.md index 238e8fff85..f5992b22fc 100644 --- a/docs/plainmonthday.md +++ b/docs/plainmonthday.md @@ -247,7 +247,7 @@ md2.equals({ monthCode: 'M02', day: 29 }); // => true - `options` (optional object): An object with properties influencing the formatting. The following options are recognized: - `calendarName` (string): Whether to show the calendar annotation in the return value. - Valid values are `'auto'`, `'always'`, and `'never'`. + Valid values are `'auto'`, `'always'`, `'never'`, and `'critical'`. The default is `'auto'`. **Returns:** a string in the ISO 8601 date format representing `monthDay`. @@ -257,6 +257,7 @@ The string can be passed to `Temporal.PlainMonthDay.from()` to create a new `Tem Normally, a calendar annotation is shown when `monthDay`'s calendar is not the ISO 8601 calendar. By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively. +Normally not necessary, a value of `'critical'` is equivalent to `'always'` but the annotation will contain an additional `!` for certain interoperation use cases. For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems). Example usage: diff --git a/docs/plainyearmonth.md b/docs/plainyearmonth.md index 29a5b7dd8f..10b34d11c1 100644 --- a/docs/plainyearmonth.md +++ b/docs/plainyearmonth.md @@ -509,7 +509,7 @@ ym.equals(ym); // => true - `options` (optional object): An object with properties influencing the formatting. The following options are recognized: - `calendarName` (string): Whether to show the calendar annotation in the return value. - Valid values are `'auto'`, `'always'`, and `'never'`. + Valid values are `'auto'`, `'always'`, `'never'`, and `'critical'`. The default is `'auto'`. **Returns:** a string in the ISO 8601 date format representing `yearMonth`. @@ -519,6 +519,7 @@ The string can be passed to `Temporal.PlainYearMonth.from()` to create a new `Te Normally, a calendar annotation is shown when `yearMonth`'s calendar is not the ISO 8601 calendar. By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively. +Normally not necessary, a value of `'critical'` is equivalent to `'always'` but the annotation will contain an additional `!` for certain interoperation use cases. For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems). Example usage: diff --git a/docs/zoneddatetime.md b/docs/zoneddatetime.md index d94f250549..5744c02499 100644 --- a/docs/zoneddatetime.md +++ b/docs/zoneddatetime.md @@ -1248,7 +1248,7 @@ zdt1.equals(zdt1); // => true Valid values are `'auto'` and `'never'`. The default is `'auto'`. - `calendarName` (string): Whether to show the calendar annotation in the return value. - Valid values are `'auto'`, `'always'`, and `'never'`. + Valid values are `'auto'`, `'always'`, `'never'`, and `'critical'`. The default is `'auto'`. - `fractionalSecondDigits` (number or string): How many digits to print after the decimal point in the output string. Valid values are `'auto'`, 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9. @@ -1279,6 +1279,7 @@ Note that rounding may change the value of other units as well. Normally, a calendar annotation is shown when `zonedDateTime`'s calendar is not the ISO 8601 calendar. By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively. +Normally not necessary, a value of `'critical'` is equivalent to `'always'` but the annotation will contain an additional `!` for certain interoperation use cases. For more information on the calendar annotation, see [ISO string extensions](./strings.md#calendar-systems). Likewise, passing `'never'` to the `timeZoneName` or `offset` options controls whether the time zone offset (`+01:00`) or name annotation (`[Europe/Paris]`) are shown. diff --git a/polyfill/lib/ecmascript.mjs b/polyfill/lib/ecmascript.mjs index 248f841d7e..eba28fac11 100644 --- a/polyfill/lib/ecmascript.mjs +++ b/polyfill/lib/ecmascript.mjs @@ -286,7 +286,8 @@ export const ES = ObjectAssign({}, ES2020, { FormatCalendarAnnotation: (id, showCalendar) => { if (showCalendar === 'never') return ''; if (showCalendar === 'auto' && id === 'iso8601') return ''; - return `[u-ca=${id}]`; + const flag = showCalendar === 'critical' ? '!' : ''; + return `[${flag}u-ca=${id}]`; }, ParseISODateTime: (isoString) => { // ZDT is the superset of fields for every other Temporal type @@ -718,7 +719,7 @@ export const ES = ObjectAssign({}, ES2020, { return ES.GetOption(options, 'offset', ['prefer', 'use', 'ignore', 'reject'], fallback); }, ToShowCalendarOption: (options) => { - return ES.GetOption(options, 'calendarName', ['auto', 'always', 'never'], 'auto'); + return ES.GetOption(options, 'calendarName', ['auto', 'always', 'never', 'critical'], 'auto'); }, ToShowTimeZoneNameOption: (options) => { return ES.GetOption(options, 'timeZoneName', ['auto', 'never'], 'auto'); @@ -2085,7 +2086,7 @@ export const ES = ObjectAssign({}, ES2020, { let resultString = `${month}-${day}`; const calendar = GetSlot(monthDay, CALENDAR); const calendarID = ES.ToString(calendar); - if (showCalendar === 'always' || calendarID !== 'iso8601') { + if (showCalendar === 'always' || showCalendar === 'critical' || calendarID !== 'iso8601') { const year = ES.ISOYearString(GetSlot(monthDay, ISO_YEAR)); resultString = `${year}-${resultString}`; } @@ -2099,7 +2100,7 @@ export const ES = ObjectAssign({}, ES2020, { let resultString = `${year}-${month}`; const calendar = GetSlot(yearMonth, CALENDAR); const calendarID = ES.ToString(calendar); - if (showCalendar === 'always' || calendarID !== 'iso8601') { + if (showCalendar === 'always' || showCalendar === 'critical' || calendarID !== 'iso8601') { const day = ES.ISODateTimePartString(GetSlot(yearMonth, ISO_DAY)); resultString += `-${day}`; } diff --git a/spec/abstractops.html b/spec/abstractops.html index 3e8e5c771b..5d8fc37593 100644 --- a/spec/abstractops.html +++ b/spec/abstractops.html @@ -148,7 +148,7 @@