@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/convert/convertDateToCalendar.d.ts

@@ -1,44 +1,45 @@
 import type { CalendarSystem } from "../../types/index.js";
 /**
- * Convert a PlainDate to the same date expressed in a different calendar system.
+ * Express a PlainDate in a calendar system: the RFC 9557 string
+ * `Temporal.PlainDate#toString()` writes for that date in that calendar.
  *
- * - Accepts a plain ISO date ("2024-10-03") or a calendar-annotated date previously
- *   produced by this function ("5785-01-01[u-ca=hebrew]"), so conversions can chain
- *   between calendar systems.
- * - The output for "gregorian" is always a bare, unannotated ISO string, matching every
- *   other GMT PlainDate string. Any other calendar returns its own native year/month/day
- *   (e.g. Hebrew year 5785, not the ISO year), tagged with `[u-ca=<identifier>]` — this
- *   diverges from Temporal's own `[u-ca=...]` string convention (which keeps ISO digits
- *   and only annotates the calendar) specifically so the calendar's native fields are
- *   visible in GMT's string contract, not hidden behind calendar-aware accessors.
- * - Uses Temporal's built-in calendar support (`PlainDate.prototype.withCalendar`) for every
- *   calendar except the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic"),
- *   which is computed with GMT-owned arithmetic instead — see
- *   `internal/ethiopicFamilyCalendar.ts` for why. Either way, the underlying date never
- *   changes, only which calendar's fields it resolves through.
+ * - The date never changes, and neither do its digits: they are always the ISO 8601 date.
+ *   The calendar is carried by a `[u-ca=<id>]` annotation (RFC 9557 §3.3), and eras, calendar
+ *   years and month codes are never part of the string.
+ * - `"iso8601"` writes a bare ISO date; every other calendar, `"gregory"` included, is annotated.
+ * - Accepts a bare ISO date or any calendar-annotated date GMT reads (see `isValidCalendarDate`),
+ *   so conversions chain between calendars.
+ * - `calendar` is a canonical calendar id; like Temporal's `withCalendar`, an alias or another
+ *   letter case is canonicalized (`"ethiopic-amete-alem"` writes `[u-ca=ethioaa]`).
+ * - **Only one of CLDR's four legacy calendar aliases works, and that is Temporal's rule, not
+ *   GMT's.** `ethiopic-amete-alem` canonicalizes to `ethioaa`; `gregorian`, `islamic-tabular` and
+ *   `taiwan` return `""`. Chromium 153 and `@js-temporal/polyfill` both throw `RangeError` for
+ *   those three: `gregorian` is nine letters, past the 8-character limit on a Unicode
+ *   locale-extension `type` subtag, and the other two are absent from ECMA-402's
+ *   `AvailableCanonicalCalendars`. Use `gregory`, `islamic-tbla` and `roc`.
  * - Returns "" on invalid input or an unsupported `calendar`.
  *
- * "japanese" and "ethiopic" are the two calendars tagged with an era instead of a plain
- * native year — see the README's calendar-systems section for why.
+ * Compatibility: since 1.16.0 the string is RFC 9557. Earlier releases wrote the calendar's own
+ * year, month and day (`"5785-01-01[u-ca=hebrew]"` for ISO 2024-10-03), a `;era=` suffix for
+ * `japanese` and `ethiopic`, and the ids `gregorian`, `taiwan`, `islamic-tabular` and
+ * `ethiopic-amete-alem`; those strings are not converted.
  *
  * @param value ISO PlainDate string, optionally calendar-annotated
- * @param calendar target calendar system ("gregorian" | "hebrew" | "islamic-civil" |
- *   "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" |
- *   "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic")
- * @returns calendar-native ISO-shaped PlainDate string, or "" on invalid input
+ * @param calendar target calendar id ("iso8601" | "gregory" | "hebrew" | "islamic-civil" |
+ *   "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" |
+ *   "indian" | "ethiopic" | "ethioaa" | "coptic")
+ * @returns RFC 9557 PlainDate string, or "" on invalid input
  *
- * @example convertDateToCalendar("2024-10-03", "hebrew") // "5785-01-01[u-ca=hebrew]"
- * @example convertDateToCalendar("5785-01-01[u-ca=hebrew]", "gregorian") // "2024-10-03"
- * @example convertDateToCalendar("2024-10-03", "gregorian") // "2024-10-03"
- * @example convertDateToCalendar("2024-10-03", "islamic-umalqura") // "1446-03-30[u-ca=islamic-umalqura]"
- * @example convertDateToCalendar("2024-10-03", "japanese") // "0006-10-03[u-ca=japanese;era=reiwa]"
- * @example convertDateToCalendar("2024-10-03", "buddhist") // "2567-10-03[u-ca=buddhist]"
- * @example convertDateToCalendar("2024-10-03", "taiwan") // "0113-10-03[u-ca=taiwan]"
- * @example convertDateToCalendar("2024-10-03", "persian") // "1403-07-12[u-ca=persian]"
- * @example convertDateToCalendar("2024-10-03", "indian") // "1946-07-11[u-ca=indian]"
- * @example convertDateToCalendar("2024-10-03", "ethiopic") // "2017-01-23[u-ca=ethiopic;era=ethiopic]"
- * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem") // "7517-01-23[u-ca=ethiopic-amete-alem]"
- * @example convertDateToCalendar("2024-10-03", "coptic") // "1741-01-23[u-ca=coptic]"
+ * @example convertDateToCalendar("2024-10-03", "hebrew") // "2024-10-03[u-ca=hebrew]"
+ * @example convertDateToCalendar("2024-10-03", "japanese") // "2024-10-03[u-ca=japanese]"
+ * @example convertDateToCalendar("1000-01-01", "roc") // "1000-01-01[u-ca=roc]"
+ * @example convertDateToCalendar("+275760-09-13", "hebrew") // "+275760-09-13[u-ca=hebrew]"
+ * @example convertDateToCalendar("2024-10-03[u-ca=hebrew]", "iso8601") // "2024-10-03"
+ * @example convertDateToCalendar("2024-10-03", "gregory") // "2024-10-03[u-ca=gregory]"
+ * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem" as never) // "2024-10-03[u-ca=ethioaa]"
+ * @example convertDateToCalendar("0006-10-03[u-ca=japanese;era=reiwa]", "iso8601") // "" (not RFC 9557)
+ * @example convertDateToCalendar("2024-10-03", "gregorian" as never) // "" (a CLDR alias Temporal does not accept; use "gregory")
+ * @example convertDateToCalendar("2024-10-03", "taiwan" as never) // "" (a CLDR alias Temporal does not accept; use "roc")
  * @example convertDateToCalendar("invalid", "hebrew") // ""
  */
 export declare function convertDateToCalendar(value: string, calendar: CalendarSystem): string;

package/dist/plain/convert/convertDateToCalendar.js

@@ -1,57 +1,58 @@
-import { formatCalendarDate, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, parseCalendarDateValue, temporalCalendarIds, } from "../../internal/index.js";
+import { canonicalCalendarSystem, formatDateInCalendar, parseCalendarDateValue, } from "../../internal/index.js";
 import { isValidCalendarDate } from "../validate/index.js";
 /**
- * Convert a PlainDate to the same date expressed in a different calendar system.
+ * Express a PlainDate in a calendar system: the RFC 9557 string
+ * `Temporal.PlainDate#toString()` writes for that date in that calendar.
  *
- * - Accepts a plain ISO date ("2024-10-03") or a calendar-annotated date previously
- *   produced by this function ("5785-01-01[u-ca=hebrew]"), so conversions can chain
- *   between calendar systems.
- * - The output for "gregorian" is always a bare, unannotated ISO string, matching every
- *   other GMT PlainDate string. Any other calendar returns its own native year/month/day
- *   (e.g. Hebrew year 5785, not the ISO year), tagged with `[u-ca=<identifier>]` — this
- *   diverges from Temporal's own `[u-ca=...]` string convention (which keeps ISO digits
- *   and only annotates the calendar) specifically so the calendar's native fields are
- *   visible in GMT's string contract, not hidden behind calendar-aware accessors.
- * - Uses Temporal's built-in calendar support (`PlainDate.prototype.withCalendar`) for every
- *   calendar except the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic"),
- *   which is computed with GMT-owned arithmetic instead — see
- *   `internal/ethiopicFamilyCalendar.ts` for why. Either way, the underlying date never
- *   changes, only which calendar's fields it resolves through.
+ * - The date never changes, and neither do its digits: they are always the ISO 8601 date.
+ *   The calendar is carried by a `[u-ca=<id>]` annotation (RFC 9557 §3.3), and eras, calendar
+ *   years and month codes are never part of the string.
+ * - `"iso8601"` writes a bare ISO date; every other calendar, `"gregory"` included, is annotated.
+ * - Accepts a bare ISO date or any calendar-annotated date GMT reads (see `isValidCalendarDate`),
+ *   so conversions chain between calendars.
+ * - `calendar` is a canonical calendar id; like Temporal's `withCalendar`, an alias or another
+ *   letter case is canonicalized (`"ethiopic-amete-alem"` writes `[u-ca=ethioaa]`).
+ * - **Only one of CLDR's four legacy calendar aliases works, and that is Temporal's rule, not
+ *   GMT's.** `ethiopic-amete-alem` canonicalizes to `ethioaa`; `gregorian`, `islamic-tabular` and
+ *   `taiwan` return `""`. Chromium 153 and `@js-temporal/polyfill` both throw `RangeError` for
+ *   those three: `gregorian` is nine letters, past the 8-character limit on a Unicode
+ *   locale-extension `type` subtag, and the other two are absent from ECMA-402's
+ *   `AvailableCanonicalCalendars`. Use `gregory`, `islamic-tbla` and `roc`.
  * - Returns "" on invalid input or an unsupported `calendar`.
  *
- * "japanese" and "ethiopic" are the two calendars tagged with an era instead of a plain
- * native year — see the README's calendar-systems section for why.
+ * Compatibility: since 1.16.0 the string is RFC 9557. Earlier releases wrote the calendar's own
+ * year, month and day (`"5785-01-01[u-ca=hebrew]"` for ISO 2024-10-03), a `;era=` suffix for
+ * `japanese` and `ethiopic`, and the ids `gregorian`, `taiwan`, `islamic-tabular` and
+ * `ethiopic-amete-alem`; those strings are not converted.
  *
  * @param value ISO PlainDate string, optionally calendar-annotated
- * @param calendar target calendar system ("gregorian" | "hebrew" | "islamic-civil" |
- *   "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" |
- *   "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic")
- * @returns calendar-native ISO-shaped PlainDate string, or "" on invalid input
+ * @param calendar target calendar id ("iso8601" | "gregory" | "hebrew" | "islamic-civil" |
+ *   "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" |
+ *   "indian" | "ethiopic" | "ethioaa" | "coptic")
+ * @returns RFC 9557 PlainDate string, or "" on invalid input
  *
- * @example convertDateToCalendar("2024-10-03", "hebrew") // "5785-01-01[u-ca=hebrew]"
- * @example convertDateToCalendar("5785-01-01[u-ca=hebrew]", "gregorian") // "2024-10-03"
- * @example convertDateToCalendar("2024-10-03", "gregorian") // "2024-10-03"
- * @example convertDateToCalendar("2024-10-03", "islamic-umalqura") // "1446-03-30[u-ca=islamic-umalqura]"
- * @example convertDateToCalendar("2024-10-03", "japanese") // "0006-10-03[u-ca=japanese;era=reiwa]"
- * @example convertDateToCalendar("2024-10-03", "buddhist") // "2567-10-03[u-ca=buddhist]"
- * @example convertDateToCalendar("2024-10-03", "taiwan") // "0113-10-03[u-ca=taiwan]"
- * @example convertDateToCalendar("2024-10-03", "persian") // "1403-07-12[u-ca=persian]"
- * @example convertDateToCalendar("2024-10-03", "indian") // "1946-07-11[u-ca=indian]"
- * @example convertDateToCalendar("2024-10-03", "ethiopic") // "2017-01-23[u-ca=ethiopic;era=ethiopic]"
- * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem") // "7517-01-23[u-ca=ethiopic-amete-alem]"
- * @example convertDateToCalendar("2024-10-03", "coptic") // "1741-01-23[u-ca=coptic]"
+ * @example convertDateToCalendar("2024-10-03", "hebrew") // "2024-10-03[u-ca=hebrew]"
+ * @example convertDateToCalendar("2024-10-03", "japanese") // "2024-10-03[u-ca=japanese]"
+ * @example convertDateToCalendar("1000-01-01", "roc") // "1000-01-01[u-ca=roc]"
+ * @example convertDateToCalendar("+275760-09-13", "hebrew") // "+275760-09-13[u-ca=hebrew]"
+ * @example convertDateToCalendar("2024-10-03[u-ca=hebrew]", "iso8601") // "2024-10-03"
+ * @example convertDateToCalendar("2024-10-03", "gregory") // "2024-10-03[u-ca=gregory]"
+ * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem" as never) // "2024-10-03[u-ca=ethioaa]"
+ * @example convertDateToCalendar("0006-10-03[u-ca=japanese;era=reiwa]", "iso8601") // "" (not RFC 9557)
+ * @example convertDateToCalendar("2024-10-03", "gregorian" as never) // "" (a CLDR alias Temporal does not accept; use "gregory")
+ * @example convertDateToCalendar("2024-10-03", "taiwan" as never) // "" (a CLDR alias Temporal does not accept; use "roc")
  * @example convertDateToCalendar("invalid", "hebrew") // ""
  */
 export function convertDateToCalendar(value, calendar) {
-    if (!isValidCalendarDate(value) || !(calendar in temporalCalendarIds)) {
+    if (!isValidCalendarDate(value)) {
+        return "";
+    }
+    const target = canonicalCalendarSystem(calendar);
+    if (!target) {
         return "";
     }
     try {
-        const date = parseCalendarDateValue(value);
-        if (isEthiopicFamilyCalendar(calendar)) {
-            return formatEthiopicFamilyDate(date, calendar);
-        }
-        return formatCalendarDate(date.withCalendar(temporalCalendarIds[calendar]));
+        return formatDateInCalendar(parseCalendarDateValue(value), target);
     }
     catch {
         return "";

package/dist/plain/format/formatCalendar.d.ts

@@ -1,11 +1,11 @@
-export interface FormatCalendarOptions {
-    reference?: string;
+import type { CalendarOptions } from "../../types/index.js";
+export interface FormatCalendarOptions extends CalendarOptions {
     /**
      * `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half.
-     * "full" is deliberately not offered here: it appends a `timeZoneName`
-     * (e.g. "Coordinated Universal Time"), and plain values have no real
-     * timezone — the UTC anchor below is an implementation detail, not a
-     * fact about `value`, so surfacing it as a zone name would be a lie.
+     * "long" and "full" are not offered: they differ from "medium" only by a
+     * `timeZoneName`, and a plain value has no zone. Passed anyway (from
+     * untyped code), they format as "medium" — Temporal's PlainDateTime format
+     * drops `timeZoneName` (AdjustDateTimeStyleFormat).
      */
     timeStyle?: "short" | "medium";
 }
@@ -28,16 +28,22 @@ export interface FormatCalendarOptions {
  *   `internal/joinDateTimeConnector.ts`), not hardcoded — this is what lets
  *   `formatCalendar` avoid the i18n objection that excludes a token
  *   formatter (Decision 1 in `context/roadmap/issues/J.md`).
+ * - The time never carries a zone name: a plain value has none. A `timeStyle` of `"long"` or
+ *   `"full"` (outside the type) formats as `"medium"`.
  * - Use `formatCalendar` for user-facing schedules ("Tomorrow at 2:30 PM");
  *   use `formatRelativeDateTime` for elapsed-time displays ("in 1 day").
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO PlainDateTime string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { reference, timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendar("2026-03-16T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "tomorrow at 2:30 PM"
  * @example formatCalendar("2026-03-08T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "March 8, 2026 at 2:30 PM" (7 days out — beyond the threshold, absolute fallback)
  * @example formatCalendar("not-a-date") // ""
+ * @example formatCalendar("2024-03-16T14:30:00", ["fr-FR", "en-US"], { reference: "2024-03-15T09:00:00" }) // "demain à 14:30"
+ * @example formatCalendar("2024-03-12T10:00:00", "en-US", null as never) // "" (null options)
  */
-export declare function formatCalendar(value: string, locale?: string, options?: FormatCalendarOptions): string;
+export declare function formatCalendar(value: string, locale?: string | string[], options?: FormatCalendarOptions): string;

package/dist/plain/format/formatCalendar.js

@@ -1,5 +1,7 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.js";
+import { plainTimeStyle } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
 // Beyond a week either direction, Moment's `.calendar()` falls back to an
 // absolute date rather than "6 days ago" / "in 6 days" wording. GMT follows
@@ -24,47 +26,67 @@ const ABS_DAY_THRESHOLD = 6;
  *   `internal/joinDateTimeConnector.ts`), not hardcoded — this is what lets
  *   `formatCalendar` avoid the i18n objection that excludes a token
  *   formatter (Decision 1 in `context/roadmap/issues/J.md`).
+ * - The time never carries a zone name: a plain value has none. A `timeStyle` of `"long"` or
+ *   `"full"` (outside the type) formats as `"medium"`.
  * - Use `formatCalendar` for user-facing schedules ("Tomorrow at 2:30 PM");
  *   use `formatRelativeDateTime` for elapsed-time displays ("in 1 day").
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO PlainDateTime string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { reference, timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendar("2026-03-16T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "tomorrow at 2:30 PM"
  * @example formatCalendar("2026-03-08T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "March 8, 2026 at 2:30 PM" (7 days out — beyond the threshold, absolute fallback)
  * @example formatCalendar("not-a-date") // ""
+ * @example formatCalendar("2024-03-16T14:30:00", ["fr-FR", "en-US"], { reference: "2024-03-15T09:00:00" }) // "demain à 14:30"
+ * @example formatCalendar("2024-03-12T10:00:00", "en-US", null as never) // "" (null options)
  */
 export function formatCalendar(value, locale, options = {}) {
-    if (!isValidDateTime(value))
-        return "";
-    if (options.reference !== undefined && !isValidDateTime(options.reference))
-        return "";
     try {
-        const target = Temporal.PlainDateTime.from(value);
-        const reference = options.reference
-            ? Temporal.PlainDateTime.from(options.reference)
-            : Temporal.Now.plainDateTimeISO();
-        const diffDays = target.toPlainDate().since(reference.toPlainDate()).days;
-        const timeStyle = options.timeStyle ?? "short";
-        // Plain values carry no timezone. UTC is an arbitrary but stable anchor
-        // for reusing Intl's part-level formatting — any fixed zone reproduces
-        // the same wall-clock fields since there's no real zone to get wrong.
-        const epochMilliseconds = target.toZonedDateTime("UTC").epochMilliseconds;
-        if (Math.abs(diffDays) > ABS_DAY_THRESHOLD) {
-            return normalizeDateTime(new Intl.DateTimeFormat(locale, {
-                dateStyle: "long",
-                timeStyle,
-                timeZone: "UTC",
-            }).format(epochMilliseconds));
+        // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
+        // invalid input.
+        if (options === null || typeof options !== "object")
+            return "";
+        if (!isValidDateTime(value))
+            return "";
+        if (options.reference !== undefined && !isValidDateTime(options.reference))
+            return "";
+        try {
+            const target = Temporal.PlainDateTime.from(value);
+            const reference = options.reference
+                ? Temporal.PlainDateTime.from(options.reference)
+                : Temporal.Now.plainDateTimeISO();
+            const diffDays = target.toPlainDate().since(reference.toPlainDate()).days;
+            // "long"/"full" are outside the type but reachable from JS; their zone
+            // name would describe the UTC anchor, not the value. Temporal's
+            // PlainDateTime format drops timeZoneName (AdjustDateTimeStyleFormat).
+            const timeStyle = plainTimeStyle(options.timeStyle === undefined ? "short" : options.timeStyle);
+            // Plain values carry no timezone. UTC is an arbitrary but stable anchor
+            // for reusing Intl's part-level formatting — any fixed zone reproduces
+            // the same wall-clock fields since there's no real zone to get wrong.
+            const epochMilliseconds = target.toZonedDateTime("UTC").epochMilliseconds;
+            if (Math.abs(diffDays) > ABS_DAY_THRESHOLD) {
+                return normalizeDateTime(new Intl.DateTimeFormat(locale, {
+                    dateStyle: "long",
+                    timeStyle,
+                    timeZone: "UTC",
+                }).format(epochMilliseconds));
+            }
+            const dayLabel = new Intl.RelativeTimeFormat(locale, {
+                numeric: "auto",
+            }).format(diffDays, "day");
+            return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, "UTC", locale, dayLabel, timeStyle));
+        }
+        catch {
+            return "";
         }
-        const dayLabel = new Intl.RelativeTimeFormat(locale, {
-            numeric: "auto",
-        }).format(diffDays, "day");
-        return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, "UTC", locale, dayLabel, timeStyle));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/format/formatDate.d.ts

@@ -1,17 +1,35 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return a localized string for a PlainDate ISO input using Intl options.
  *
- * - Uses Temporal.PlainDate.toLocaleString for formatting.
+ * - Formats as Temporal's ECMA-402 PlainDate format (`PlainDate#toLocaleString`) does, through
+ *   the runtime's `Intl.DateTimeFormat`: the requested fields and widths are kept, and
+ *   `timeZoneName` is ignored (a PlainDate has no zone).
  * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
- * - Returns "" for invalid input.
+ * - Returns "" for invalid input, for a `timeStyle` (with or without `dateStyle`) and for only
+ *   time fields, where `PlainDate#toLocaleString` throws a TypeError.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), `timeZoneName` alone returned `""`,
+ *   and a `timeStyle` beside `dateStyle` was ignored. Pass the numeric fields to keep the numeric
+ *   text, and pass only `dateStyle` to keep the styled text.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it. Any
+ *   other non-object — a string, a number, a boolean — formats with the defaults, as
+ *   `Intl.DateTimeFormat` does: CoerceOptionsToObject calls ToObject on it and the wrapper
+ *   carries no recognised option. Only `null` and `undefined` are special-cased.
  *
  * @param value ISO PlainDate string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized date string or "" on invalid input
  *
  * @example formatDate("2024-03-15", "en-US", { year: "numeric", month: "long", day: "numeric" }) // "March 15, 2024"
  * @example formatDate("2024-03-15", "de-DE", { year: "numeric", month: "long", day: "numeric" }) // "15. März 2024"
+ * @example formatDate("2024-02-03", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatDate("2024-02-03", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatDate("2024-02-03", "en-US", { timeZoneName: "long" }) // "2/3/2024"
+ * @example formatDate("2024-02-03", "en-US", { dateStyle: "short", timeStyle: "short" }) // "" — a PlainDate has no time
+ * @example formatDate("2024-02-03", "en-US", { dateStyle: "short" }) // "2/3/24" — the pre-1.16.0 text
  * @example formatDate("invalid") // ""
+ * @example formatDate("2024-02-03", ["fr-FR", "en-US"], { year: "numeric", month: "2-digit", day: "2-digit" }) // "03/02/2024" (the first listed locale)
  */
-export declare function formatDate(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDate(value: string, locale?: string | string[], options?: DateTimeFormatOptions): string;

package/dist/plain/format/formatDate.js

@@ -1,29 +1,61 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
+import { plainDateFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDate } from "../validate/index.js";
 /**
  * Return a localized string for a PlainDate ISO input using Intl options.
  *
- * - Uses Temporal.PlainDate.toLocaleString for formatting.
+ * - Formats as Temporal's ECMA-402 PlainDate format (`PlainDate#toLocaleString`) does, through
+ *   the runtime's `Intl.DateTimeFormat`: the requested fields and widths are kept, and
+ *   `timeZoneName` is ignored (a PlainDate has no zone).
  * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
- * - Returns "" for invalid input.
+ * - Returns "" for invalid input, for a `timeStyle` (with or without `dateStyle`) and for only
+ *   time fields, where `PlainDate#toLocaleString` throws a TypeError.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), `timeZoneName` alone returned `""`,
+ *   and a `timeStyle` beside `dateStyle` was ignored. Pass the numeric fields to keep the numeric
+ *   text, and pass only `dateStyle` to keep the styled text.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it. Any
+ *   other non-object — a string, a number, a boolean — formats with the defaults, as
+ *   `Intl.DateTimeFormat` does: CoerceOptionsToObject calls ToObject on it and the wrapper
+ *   carries no recognised option. Only `null` and `undefined` are special-cased.
  *
  * @param value ISO PlainDate string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized date string or "" on invalid input
  *
  * @example formatDate("2024-03-15", "en-US", { year: "numeric", month: "long", day: "numeric" }) // "March 15, 2024"
  * @example formatDate("2024-03-15", "de-DE", { year: "numeric", month: "long", day: "numeric" }) // "15. März 2024"
+ * @example formatDate("2024-02-03", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatDate("2024-02-03", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatDate("2024-02-03", "en-US", { timeZoneName: "long" }) // "2/3/2024"
+ * @example formatDate("2024-02-03", "en-US", { dateStyle: "short", timeStyle: "short" }) // "" — a PlainDate has no time
+ * @example formatDate("2024-02-03", "en-US", { dateStyle: "short" }) // "2/3/24" — the pre-1.16.0 text
  * @example formatDate("invalid") // ""
+ * @example formatDate("2024-02-03", ["fr-FR", "en-US"], { year: "numeric", month: "2-digit", day: "2-digit" }) // "03/02/2024" (the first listed locale)
  */
 export function formatDate(value, locale, options) {
     if (!isValidDate(value)) {
         return "";
     }
     try {
-        const out = Temporal.PlainDate.from(value).toLocaleString(locale, options);
-        return normalizeDateTime(out);
+        // The runtime's Intl.DateTimeFormat formats the date's instant at the UTC
+        // anchor with the options Temporal's PlainDate format resolves to
+        // (CreateDateTimeFormat ~date~, ~date~), so the requested fields and
+        // widths are kept. Constructing with the caller's options first surfaces
+        // the TypeError or RangeError Intl.DateTimeFormat raises for invalid ones.
+        new Intl.DateTimeFormat(locale, options);
+        // CreateDateTimeFormat: required ~date~ with a timeStyle is a TypeError.
+        if (options?.timeStyle !== undefined) {
+            return "";
+        }
+        const resolved = plainDateFormatOptions(options ?? {});
+        if (resolved === null) {
+            return "";
+        }
+        const epochMilliseconds = Temporal.PlainDate.from(value).toZonedDateTime("UTC").epochMilliseconds;
+        return normalizeDateTime(new Intl.DateTimeFormat(locale, resolved).format(epochMilliseconds));
     }
     catch {
         return "";

package/dist/plain/format/formatDateRange.d.ts

@@ -1,19 +1,33 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Format a plain date range using the Temporal Intl.DateTimeFormat formatRange API.
  *
  * - Plain counterpart of `formatZonedRange` — same parameter order and option shape.
  * - Uses Temporal.PlainDate.from for both endpoints; no timezone is involved.
+ * - Formats as Temporal's ECMA-402 PlainDate format does, through the runtime's
+ *   `Intl.DateTimeFormat#formatRange`: `timeZoneName` is ignored, and a `timeStyle` without
+ *   `dateStyle`, or only time fields, returns `""`.
+ * - **Compatibility:** before 1.16.0 `timeZoneName` alone returned `""`; only that sentinel
+ *   became a value.
  * - Locale elides shared fields between `start` and `end` (e.g. same month/year).
  * - Returns "" for invalid input on either endpoint.
+ * - Output is normalized: dash separators become ASCII "-" (unspaced between digits, spaced
+ *   otherwise), and no-break, narrow and thin spaces become U+0020.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it. Any
+ *   other non-object — a string, a number, a boolean — formats with the defaults, as
+ *   `Intl.DateTimeFormat` does: CoerceOptionsToObject calls ToObject on it and the wrapper
+ *   carries no recognised option. Only `null` and `undefined` are special-cased.
  *
  * @param start ISO PlainDate string (range start)
  * @param end ISO PlainDate string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *
- * @example formatDateRange("2024-02-03", "2024-02-05", "en-US", { dateStyle: "long" }) // "February 3 – 5, 2024"
- * @example formatDateRange("2024-02-03", "2024-06-10", "en-US", { dateStyle: "long" }) // "February 3 – June 10, 2024"
+ * @example formatDateRange("2024-02-03", "2024-02-05", "en-US", { dateStyle: "long" }) // "February 3 - 5, 2024"
+ * @example formatDateRange("2024-02-03", "2024-06-10", "en-US", { dateStyle: "long" }) // "February 3 - June 10, 2024"
+ * @example formatDateRange("2024-02-03", "2024-02-05", "en-US", { timeZoneName: "short" }) // "2/3/2024 - 2/5/2024"
  * @example formatDateRange("invalid", "2024-02-05", "en-US") // "" (invalid input)
+ * @example formatDateRange("2024-02-03", "2024-02-05", ["fr-FR", "en-US"], { dateStyle: "long" }) // "3-5 février 2024" (GMT writes range dashes as ASCII hyphens)
  */
-export declare function formatDateRange(start: string, end: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDateRange(start: string, end: string, locale?: string | string[], options?: DateTimeFormatOptions): string;

package/dist/plain/format/formatDateRange.js

@@ -1,30 +1,54 @@
-import { Temporal, Intl as TemporalIntl } from "@js-temporal/polyfill";
+import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
+import { plainDateFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDate } from "../validate/index.js";
 /**
  * Format a plain date range using the Temporal Intl.DateTimeFormat formatRange API.
  *
  * - Plain counterpart of `formatZonedRange` — same parameter order and option shape.
  * - Uses Temporal.PlainDate.from for both endpoints; no timezone is involved.
+ * - Formats as Temporal's ECMA-402 PlainDate format does, through the runtime's
+ *   `Intl.DateTimeFormat#formatRange`: `timeZoneName` is ignored, and a `timeStyle` without
+ *   `dateStyle`, or only time fields, returns `""`.
+ * - **Compatibility:** before 1.16.0 `timeZoneName` alone returned `""`; only that sentinel
+ *   became a value.
  * - Locale elides shared fields between `start` and `end` (e.g. same month/year).
  * - Returns "" for invalid input on either endpoint.
+ * - Output is normalized: dash separators become ASCII "-" (unspaced between digits, spaced
+ *   otherwise), and no-break, narrow and thin spaces become U+0020.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it. Any
+ *   other non-object — a string, a number, a boolean — formats with the defaults, as
+ *   `Intl.DateTimeFormat` does: CoerceOptionsToObject calls ToObject on it and the wrapper
+ *   carries no recognised option. Only `null` and `undefined` are special-cased.
  *
  * @param start ISO PlainDate string (range start)
  * @param end ISO PlainDate string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *
- * @example formatDateRange("2024-02-03", "2024-02-05", "en-US", { dateStyle: "long" }) // "February 3 – 5, 2024"
- * @example formatDateRange("2024-02-03", "2024-06-10", "en-US", { dateStyle: "long" }) // "February 3 – June 10, 2024"
+ * @example formatDateRange("2024-02-03", "2024-02-05", "en-US", { dateStyle: "long" }) // "February 3 - 5, 2024"
+ * @example formatDateRange("2024-02-03", "2024-06-10", "en-US", { dateStyle: "long" }) // "February 3 - June 10, 2024"
+ * @example formatDateRange("2024-02-03", "2024-02-05", "en-US", { timeZoneName: "short" }) // "2/3/2024 - 2/5/2024"
  * @example formatDateRange("invalid", "2024-02-05", "en-US") // "" (invalid input)
+ * @example formatDateRange("2024-02-03", "2024-02-05", ["fr-FR", "en-US"], { dateStyle: "long" }) // "3-5 février 2024" (GMT writes range dashes as ASCII hyphens)
  */
 export function formatDateRange(start, end, locale, options) {
     if (!isValidDate(start) || !isValidDate(end)) {
         return "";
     }
     try {
-        const out = new TemporalIntl.DateTimeFormat(locale, options).formatRange(Temporal.PlainDate.from(start), Temporal.PlainDate.from(end));
+        // The runtime's Intl.DateTimeFormat formats both dates' instants at the
+        // UTC anchor with the options Temporal's PlainDate format resolves to
+        // (GetDateTimeFormat ~date~, ~date~, ~relevant~). Constructing with the
+        // caller's options first surfaces the TypeError or RangeError
+        // Intl.DateTimeFormat raises for invalid ones.
+        new Intl.DateTimeFormat(locale, options);
+        const resolved = plainDateFormatOptions(options ?? {});
+        if (resolved === null) {
+            return "";
+        }
+        const out = new Intl.DateTimeFormat(locale, resolved).formatRange(Temporal.PlainDate.from(start).toZonedDateTime("UTC").epochMilliseconds, Temporal.PlainDate.from(end).toZonedDateTime("UTC").epochMilliseconds);
         return normalizeDateTime(out);
     }
     catch {

package/dist/plain/format/formatDateTime.d.ts

@@ -1,17 +1,36 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return a localized string for a PlainDateTime ISO input using Intl options.
  *
- * - Uses Temporal.PlainDateTime.toLocaleString for formatting.
+ * - Formats as Temporal's ECMA-402 PlainDateTime format (`PlainDateTime#toLocaleString`) does,
+ *   through the runtime's `Intl.DateTimeFormat`: the requested fields and style widths are kept,
+ *   `era` alone still gets the date and time defaults, and `timeZoneName` is ignored.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width, a
+ *   `long`/`full` `timeStyle` replaced the `dateStyle` width (`{ dateStyle: "short", timeStyle:
+ *   "full" }` gave `"2/3/2024, 2:30:45 PM"`), `era` alone dropped the time, and `timeZoneName`
+ *   alone returned `""`. Pass the fields the old text showed to keep it.
  * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
  * - Returns "" for invalid input.
+ * - Output is normalized: dash separators become ASCII "-" (unspaced between digits, spaced
+ *   otherwise), and no-break, narrow and thin spaces become U+0020.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it. Any
+ *   other non-object — a string, a number, a boolean — formats with the defaults, as
+ *   `Intl.DateTimeFormat` does: CoerceOptionsToObject calls ToObject on it and the wrapper
+ *   carries no recognised option. Only `null` and `undefined` are special-cased.
  *
  * @param value ISO PlainDateTime string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized date-time string or "" on invalid input
  *
- * @example formatDateTime("2024-03-15T14:30:00", "en-US", { dateStyle: "medium", timeStyle: "short" }) // "Mar 15, 2024 at 2:30 PM"
+ * @example formatDateTime("2024-03-15T14:30:00", "en-US", { dateStyle: "medium", timeStyle: "short" }) // "Mar 15, 2024, 2:30 PM"
+ * @example formatDateTime("2024-03-15T14:30:00", "en-US", { dateStyle: "long", timeStyle: "short" }) // "March 15, 2024 at 2:30 PM"
  * @example formatDateTime("2024-03-15T14:30:00", "de-DE", { dateStyle: "medium", timeStyle: "short" }) // "15.03.2024, 14:30"
+ * @example formatDateTime("2024-02-03T14:30:45", "en-US", { dateStyle: "short", timeStyle: "full" }) // "2/3/24, 2:30:45 PM"
+ * @example formatDateTime("2024-02-03T14:30:45", "en-US", { year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" }) // "2/3/2024, 2:30:45 PM" — the pre-1.16.0 text
+ * @example formatDateTime("2024-02-03T14:30:45", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatDateTime("2024-02-03T14:30:45", "en-US", { era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
  * @example formatDateTime("invalid") // ""
+ * @example formatDateTime("2024-02-03T14:30:45", ["fr-FR", "en-US"], { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit" }) // "03/02/2024 14:30"
  */
-export declare function formatDateTime(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDateTime(value: string, locale?: string | string[], options?: DateTimeFormatOptions): string;