@northguild/gmt 1.15.0 → 1.16.0

package/dist/plain/format/formatDateTimeRange.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 { plainDateTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
 /**
  * Format a plain datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
  * - Plain counterpart of `formatZonedRange` — same parameter order and option shape.
  * - Uses Temporal.PlainDateTime.from for both endpoints; no timezone is involved.
+ * - Formats as Temporal's ECMA-402 PlainDateTime format does, through the runtime's
+ *   `Intl.DateTimeFormat#formatRange`: 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 lost a requested width (zh-CN with
+ *   `{ year: "numeric", month: "long" }` gave `"2024/2"`), `era` alone dropped the time, and
+ *   `timeZoneName` alone returned `""`. Pass the fields the old text showed to keep it.
  * - Locale elides shared fields between `start` and `end` (e.g. same day/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 PlainDateTime string (range start)
  * @param end ISO PlainDateTime string (range end)
- * @param locale optional locale tag (default: runtime default)
+ * @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 formatDateTimeRange("2024-02-03T09:00:00", "2024-02-03T17:00:00", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 3, 2024, 9:00 AM – 5:00 PM"
- * @example formatDateTimeRange("2024-02-03T09:00:00", "2024-02-10T17:00:00", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 3, 2024 at 9:00 AM – February 10, 2024 at 5:00 PM"
+ * @example formatDateTimeRange("2024-02-03T09:00:00", "2024-02-03T17:00:00", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 3, 2024, 9:00 AM - 5:00 PM"
+ * @example formatDateTimeRange("2024-02-03T09:00:00", "2024-02-10T17:00:00", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 3, 2024 at 9:00 AM - February 10, 2024 at 5:00 PM"
+ * @example formatDateTimeRange("2024-02-03T09:00:00", "2024-02-03T17:00:00", "zh-CN", { year: "numeric", month: "long" }) // "2024年2月"
+ * @example formatDateTimeRange("2024-02-03T09:00:00", "2024-02-03T17:00:00", "zh-CN", { year: "numeric", month: "numeric" }) // "2024/2" — the pre-1.16.0 text
+ * @example formatDateTimeRange("2024-02-03T09:00:00", "2024-02-03T17:00:00", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 9:00:00 AM - 5:00:00 PM"
  * @example formatDateTimeRange("invalid", "2024-02-03T17:00:00", "en-US") // "" (invalid input)
+ * @example formatDateTimeRange("2024-02-03T14:30:45", "2024-02-03T16:46:15", ["fr-FR", "en-US"], { hour: "numeric", minute: "numeric" }) // "14:30 - 16:46"
  */
 export function formatDateTimeRange(start, end, locale, options) {
     if (!isValidDateTime(start) || !isValidDateTime(end)) {
         return "";
     }
     try {
-        const out = new TemporalIntl.DateTimeFormat(locale, options).formatRange(Temporal.PlainDateTime.from(start), Temporal.PlainDateTime.from(end));
+        // The runtime's Intl.DateTimeFormat formats both values' instants at the
+        // UTC anchor with the options Temporal's PlainDateTime format resolves to
+        // (GetDateTimeFormat ~any~, ~all~, ~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 out = new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options ?? {})).formatRange(Temporal.PlainDateTime.from(start).toZonedDateTime("UTC")
+            .epochMilliseconds, Temporal.PlainDateTime.from(end).toZonedDateTime("UTC").epochMilliseconds);
         return normalizeDateTime(out);
     }
     catch {

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

@@ -8,22 +8,48 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   while the *locale* keeps control of order. See Decision 1 in
  *   `context/roadmap/issues/J.md`.
  * - Each part is `{ type, value }` where `type` can be:
- *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"hour"`,
- *   `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`, `"literal"`.
+ *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
+ *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`, `"literal"`.
+ * - A lunisolar calendar adds two more: `zh-u-ca-chinese` and `ko-u-ca-dangi` emit
+ *   `"relatedYear"` (the Gregorian year the cycle falls in) and `"yearName"` (the sexagenary
+ *   cycle name) in place of, or beside, `"year"`. Code that looks up a `"year"` part must handle
+ *   their absence.
  * - The caller should iterate the array as returned; reassembling in a fixed
  *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - With no date/time field and no `dateStyle`/`timeStyle`, year, month, day,
+ *   hour, minute and second default to `"numeric"` (ECMA-402 as amended by
+ *   Temporal), so the parts rebuild exactly what
+ *   `Temporal.PlainDateTime#toLocaleString` returns for the same value.
+ * - A zoneless value never yields a `"timeZoneName"` part (Temporal's PlainDateTime format has no
+ *   zone field): a `timeZoneName` option is ignored, and a `"long"`/`"full"` `timeStyle` keeps its
+ *   hour, minute and second and drops the zone, formatting as the locale's `"medium"` time. As in
+ *   `Intl.DateTimeFormat`, `timeZoneName` together with `dateStyle`/`timeStyle` yields `[]`.
+ * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
+ *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
  * - Returns `[]` for invalid input.
+ * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts.
+ *   Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
+ * - **Compatibility:** before 1.16.0 a `"long"`/`"full"` `timeStyle` added the internal UTC anchor
+ *   as a `timeZoneName` part. `formatZonedToParts` on the value at UTC returns those parts.
+ * - `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 (default: runtime default)
+ * @param locale optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
- * @example formatDateTimeToParts("2024-03-15T14:30:00", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: " " }, { type: "dayPeriod", value: "PM" }]
- * @example formatDateTimeToParts("2024-03-15T14:30:00", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "14" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }]
+ * @example formatDateTimeToParts("2024-03-15T14:30:00", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }]
+ * @example formatDateTimeToParts("2024-03-15T14:30:00", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "14" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }]
+ * @example formatDateTimeToParts("2024-03-15T14:30:00", "en-US", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
+ * @example formatDateTimeToParts("2024-02-29T12:00:00", "en-US", { timeStyle: "long" }) // [{ type: "hour", value: "12" }, { type: "literal", value: ":" }, { type: "minute", value: "00" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }]
+ * @example formatZonedToParts("2024-02-29T12:00:00+00:00[UTC]", "en-US", { timeStyle: "long" }) // [{ type: "hour", value: "12" }, { type: "literal", value: ":" }, { type: "minute", value: "00" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "UTC" }] — the pre-1.16.0 parts
  * @example formatDateTimeToParts("invalid") // []
+ * @example formatDateTimeToParts("2024-02-03T14:30:45", ["fr-FR", "en-US"], { dateStyle: "medium", timeStyle: "short" }) // parts of "3 févr. 2024, 14:30"
  */
-export declare function formatDateTimeToParts(value: string, locale?: string, options?: DateTimeFormatOptions): Array<{
+export declare function formatDateTimeToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
     type: string;
     value: string;
 }>;

package/dist/plain/format/formatDateTimeToParts.js

@@ -1,4 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { plainDateTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
 /**
  * Return the locale-formatted parts of a PlainDateTime.
@@ -9,36 +10,61 @@ import { isValidDateTime } from "../validate/index.js";
  *   while the *locale* keeps control of order. See Decision 1 in
  *   `context/roadmap/issues/J.md`.
  * - Each part is `{ type, value }` where `type` can be:
- *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"hour"`,
- *   `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`, `"literal"`.
+ *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
+ *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`, `"literal"`.
+ * - A lunisolar calendar adds two more: `zh-u-ca-chinese` and `ko-u-ca-dangi` emit
+ *   `"relatedYear"` (the Gregorian year the cycle falls in) and `"yearName"` (the sexagenary
+ *   cycle name) in place of, or beside, `"year"`. Code that looks up a `"year"` part must handle
+ *   their absence.
  * - The caller should iterate the array as returned; reassembling in a fixed
  *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - With no date/time field and no `dateStyle`/`timeStyle`, year, month, day,
+ *   hour, minute and second default to `"numeric"` (ECMA-402 as amended by
+ *   Temporal), so the parts rebuild exactly what
+ *   `Temporal.PlainDateTime#toLocaleString` returns for the same value.
+ * - A zoneless value never yields a `"timeZoneName"` part (Temporal's PlainDateTime format has no
+ *   zone field): a `timeZoneName` option is ignored, and a `"long"`/`"full"` `timeStyle` keeps its
+ *   hour, minute and second and drops the zone, formatting as the locale's `"medium"` time. As in
+ *   `Intl.DateTimeFormat`, `timeZoneName` together with `dateStyle`/`timeStyle` yields `[]`.
+ * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
+ *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
  * - Returns `[]` for invalid input.
+ * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts.
+ *   Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
+ * - **Compatibility:** before 1.16.0 a `"long"`/`"full"` `timeStyle` added the internal UTC anchor
+ *   as a `timeZoneName` part. `formatZonedToParts` on the value at UTC returns those parts.
+ * - `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 (default: runtime default)
+ * @param locale optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
- * @example formatDateTimeToParts("2024-03-15T14:30:00", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: " " }, { type: "dayPeriod", value: "PM" }]
- * @example formatDateTimeToParts("2024-03-15T14:30:00", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "14" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }]
+ * @example formatDateTimeToParts("2024-03-15T14:30:00", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }]
+ * @example formatDateTimeToParts("2024-03-15T14:30:00", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "14" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }]
+ * @example formatDateTimeToParts("2024-03-15T14:30:00", "en-US", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
+ * @example formatDateTimeToParts("2024-02-29T12:00:00", "en-US", { timeStyle: "long" }) // [{ type: "hour", value: "12" }, { type: "literal", value: ":" }, { type: "minute", value: "00" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }]
+ * @example formatZonedToParts("2024-02-29T12:00:00+00:00[UTC]", "en-US", { timeStyle: "long" }) // [{ type: "hour", value: "12" }, { type: "literal", value: ":" }, { type: "minute", value: "00" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "UTC" }] — the pre-1.16.0 parts
  * @example formatDateTimeToParts("invalid") // []
+ * @example formatDateTimeToParts("2024-02-03T14:30:45", ["fr-FR", "en-US"], { dateStyle: "medium", timeStyle: "short" }) // parts of "3 févr. 2024, 14:30"
  */
 export function formatDateTimeToParts(value, locale, options) {
     if (!isValidDateTime(value)) {
         return [];
     }
     try {
-        // Temporal.PlainDateTime has no formatToParts of its own — anchor it to
-        // an instant in UTC and hand that to Intl.DateTimeFormat, which does the
-        // part-level locale work. UTC is arbitrary but stable: a plain date-time
-        // has no zone, so any fixed zone reproduces the same clock fields.
+        // Temporal.PlainDateTime has no formatToParts of its own. The runtime's
+        // Intl.DateTimeFormat does the part-level locale work on the value's
+        // instant at the UTC anchor; the options are first narrowed to what a
+        // PlainDateTime format may contain, so no zone field can appear.
+        // Constructing with the caller's options first surfaces the TypeError or
+        // RangeError Intl.DateTimeFormat raises for invalid ones.
+        new Intl.DateTimeFormat(locale, options);
         const epochMilliseconds = Temporal.PlainDateTime.from(value).toZonedDateTime("UTC").epochMilliseconds;
-        const formatter = new Intl.DateTimeFormat(locale, {
-            ...options,
-            timeZone: "UTC",
-        });
-        return formatter
+        return new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options ?? {}))
             .formatToParts(epochMilliseconds)
             .map((p) => ({ type: p.type, value: p.value }));
     }

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

@@ -8,21 +8,42 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   while the *locale* keeps control of order. See Decision 1 in
  *   `context/roadmap/issues/J.md`.
  * - Each part is `{ type, value }` where `type` is one of:
- *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"literal"`.
+ *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
+ *   `"literal"`.
+ * - A lunisolar calendar adds two more: `zh-u-ca-chinese` and `ko-u-ca-dangi` emit
+ *   `"relatedYear"` (the Gregorian year the cycle falls in) and `"yearName"` (the sexagenary
+ *   cycle name) in place of, or beside, `"year"`. Code that looks up a `"year"` part must handle
+ *   their absence.
  * - The caller should iterate the array as returned; reassembling in a fixed
  *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - A PlainDate has no time or zone, so no `hour`/`minute`/`second`/`dayPeriod`/`timeZoneName`
+ *   part is ever returned, following Temporal's ECMA-402 PlainDate format: `timeStyle` without
+ *   `dateStyle`, or only time fields, yields `[]` (as `formatDate` yields `""`); `timeZoneName` is
+ *   ignored. With both `dateStyle` and `timeStyle` the parts keep the date style and drop the
+ *   `timeStyle` (the `Intl.DateTimeFormat` entry point, required ~any~), whereas the text sibling
+ *   `formatDate` returns `""` (`PlainDate#toLocaleString`, required ~date~, is a TypeError).
  * - Returns `[]` for invalid input.
+ * - **Compatibility:** before 1.16.0 time options leaked a UTC midnight and a `"UTC"` zone name
+ *   into the parts. `formatZonedToParts` on the date at midnight UTC returns those parts.
+ * - `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 (default: runtime default)
+ * @param locale optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
  * @example formatDateToParts("2024-03-15", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }]
  * @example formatDateToParts("2024-03-15", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }]
+ * @example formatDateToParts("2024-02-29", "en-US", { dateStyle: "full", timeStyle: "full" }) // [{ type: "weekday", value: "Thursday" }, { type: "literal", value: ", " }, { type: "month", value: "February" }, { type: "literal", value: " " }, { type: "day", value: "29" }, { type: "literal", value: ", " }, { type: "year", value: "2024" }]
+ * @example formatDateToParts("2024-02-29", "en-US", { timeStyle: "long" }) // [] — a PlainDate has no time
+ * @example formatZonedToParts("2024-02-29T00:00:00+00:00[UTC]", "en-US", { timeStyle: "long" }) // [{ type: "hour", value: "12" }, { type: "literal", value: ":" }, { type: "minute", value: "00" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "AM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "UTC" }] — the pre-1.16.0 parts
  * @example formatDateToParts("invalid") // []
+ * @example formatDateToParts("2024-02-03", ["fr-FR", "en-US"]) // [{ type: "day", value: "03" }, { type: "literal", value: "/" }, …]
  */
-export declare function formatDateToParts(value: string, locale?: string, options?: DateTimeFormatOptions): Array<{
+export declare function formatDateToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
     type: string;
     value: string;
 }>;

package/dist/plain/format/formatDateToParts.js

@@ -1,4 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { plainDateFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDate } from "../validate/index.js";
 /**
  * Return the locale-formatted parts of a PlainDate.
@@ -9,35 +10,59 @@ import { isValidDate } from "../validate/index.js";
  *   while the *locale* keeps control of order. See Decision 1 in
  *   `context/roadmap/issues/J.md`.
  * - Each part is `{ type, value }` where `type` is one of:
- *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"literal"`.
+ *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
+ *   `"literal"`.
+ * - A lunisolar calendar adds two more: `zh-u-ca-chinese` and `ko-u-ca-dangi` emit
+ *   `"relatedYear"` (the Gregorian year the cycle falls in) and `"yearName"` (the sexagenary
+ *   cycle name) in place of, or beside, `"year"`. Code that looks up a `"year"` part must handle
+ *   their absence.
  * - The caller should iterate the array as returned; reassembling in a fixed
  *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - A PlainDate has no time or zone, so no `hour`/`minute`/`second`/`dayPeriod`/`timeZoneName`
+ *   part is ever returned, following Temporal's ECMA-402 PlainDate format: `timeStyle` without
+ *   `dateStyle`, or only time fields, yields `[]` (as `formatDate` yields `""`); `timeZoneName` is
+ *   ignored. With both `dateStyle` and `timeStyle` the parts keep the date style and drop the
+ *   `timeStyle` (the `Intl.DateTimeFormat` entry point, required ~any~), whereas the text sibling
+ *   `formatDate` returns `""` (`PlainDate#toLocaleString`, required ~date~, is a TypeError).
  * - Returns `[]` for invalid input.
+ * - **Compatibility:** before 1.16.0 time options leaked a UTC midnight and a `"UTC"` zone name
+ *   into the parts. `formatZonedToParts` on the date at midnight UTC returns those parts.
+ * - `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 (default: runtime default)
+ * @param locale optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
  * @example formatDateToParts("2024-03-15", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }]
  * @example formatDateToParts("2024-03-15", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }]
+ * @example formatDateToParts("2024-02-29", "en-US", { dateStyle: "full", timeStyle: "full" }) // [{ type: "weekday", value: "Thursday" }, { type: "literal", value: ", " }, { type: "month", value: "February" }, { type: "literal", value: " " }, { type: "day", value: "29" }, { type: "literal", value: ", " }, { type: "year", value: "2024" }]
+ * @example formatDateToParts("2024-02-29", "en-US", { timeStyle: "long" }) // [] — a PlainDate has no time
+ * @example formatZonedToParts("2024-02-29T00:00:00+00:00[UTC]", "en-US", { timeStyle: "long" }) // [{ type: "hour", value: "12" }, { type: "literal", value: ":" }, { type: "minute", value: "00" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "AM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "UTC" }] — the pre-1.16.0 parts
  * @example formatDateToParts("invalid") // []
+ * @example formatDateToParts("2024-02-03", ["fr-FR", "en-US"]) // [{ type: "day", value: "03" }, { type: "literal", value: "/" }, …]
  */
 export function formatDateToParts(value, locale, options) {
     if (!isValidDate(value)) {
         return [];
     }
     try {
-        // Temporal.PlainDate has no formatToParts of its own — anchor it to an
-        // instant in UTC (midnight) and hand that to Intl.DateTimeFormat, which
-        // does the part-level locale work. UTC is arbitrary but stable: a plain
-        // date has no zone, so any fixed zone reproduces the same date fields.
+        // Temporal.PlainDate has no formatToParts of its own. The runtime's
+        // Intl.DateTimeFormat does the part-level locale work on the date's
+        // instant at the UTC anchor; the options are first narrowed to what a
+        // PlainDate format may contain, so no time or zone field can appear.
+        // 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 epochMilliseconds = Temporal.PlainDate.from(value).toZonedDateTime("UTC").epochMilliseconds;
-        const formatter = new Intl.DateTimeFormat(locale, {
-            ...options,
-            timeZone: "UTC",
-        });
-        return formatter
+        return new Intl.DateTimeFormat(locale, resolved)
             .formatToParts(epochMilliseconds)
             .map((p) => ({ type: p.type, value: p.value }));
     }

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

@@ -8,14 +8,18 @@ export interface FormatRelativeDateOptions extends RelativeTimeFormatOptions {
  * - Auto-picks the display unit (day/week/month/year) based on the distance, unless
  *   `largestUnit` forces one.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date 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: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"
- * @example formatRelativeDate(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeDate("2026-03-01", "en-US", { reference: "2026-03-11", largestUnit: "week", roundingMethod: "floor" }) // "2 weeks ago" (−1.43 weeks floors to −2; the default rounds to "last week")
  * @example formatRelativeDate("not-a-date") // ""
+ * @example formatRelativeDate("2024-01-15", ["fr-FR", "en-US"], { reference: "2024-03-15" }) // "il y a 2 mois"
+ * @example formatRelativeDate("2024-03-12", "en-US", null as never) // "" (null options)
  */
-export declare function formatRelativeDate(value: string, locale?: string, options?: FormatRelativeDateOptions): string;
+export declare function formatRelativeDate(value: string, locale?: string | string[], options?: FormatRelativeDateOptions): string;

package/dist/plain/format/formatRelativeDate.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { durationTotal, normalizeDateTime, resolveRelativeRounding, } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
 const AUTO_UNITS = [
     { unit: "day", maxDays: 7 },
@@ -13,45 +13,60 @@ const AUTO_UNITS = [
  * - Auto-picks the display unit (day/week/month/year) based on the distance, unless
  *   `largestUnit` forces one.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date 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: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"
- * @example formatRelativeDate(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeDate("2026-03-01", "en-US", { reference: "2026-03-11", largestUnit: "week", roundingMethod: "floor" }) // "2 weeks ago" (−1.43 weeks floors to −2; the default rounds to "last week")
  * @example formatRelativeDate("not-a-date") // ""
+ * @example formatRelativeDate("2024-01-15", ["fr-FR", "en-US"], { reference: "2024-03-15" }) // "il y a 2 mois"
+ * @example formatRelativeDate("2024-03-12", "en-US", null as never) // "" (null options)
  */
 export function formatRelativeDate(value, locale, options = {}) {
-    if (!isValidDate(value))
-        return "";
-    if (options.reference !== undefined && !isValidDate(options.reference))
-        return "";
     try {
-        const target = Temporal.PlainDate.from(value);
-        const reference = options.reference
-            ? Temporal.PlainDate.from(options.reference)
-            : Temporal.Now.plainDateISO();
-        const diff = target.since(reference);
-        const absDays = Math.abs(diff.total("day"));
-        const unit = options.largestUnit ??
-            AUTO_UNITS.find((t) => absDays < t.maxDays)?.unit ??
-            "year";
-        let amount;
+        // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
+        // invalid input.
+        if (options === null || typeof options !== "object")
+            return "";
+        if (!isValidDate(value))
+            return "";
+        if (options.reference !== undefined && !isValidDate(options.reference))
+            return "";
         try {
-            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            const target = Temporal.PlainDate.from(value);
+            const reference = options.reference
+                ? Temporal.PlainDate.from(options.reference)
+                : Temporal.Now.plainDateISO();
+            const diff = target.since(reference);
+            const absDays = Math.abs(diff.total("day"));
+            const unit = options.largestUnit === undefined
+                ? (AUTO_UNITS.find((t) => absDays < t.maxDays)?.unit ?? "year")
+                : options.largestUnit;
+            let amount;
+            try {
+                amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            }
+            catch {
+                // month/year are calendrical and need a relativeTo anchor
+                amount = resolveRelativeRounding(durationTotal(diff, unit, reference), options.roundingMethod);
+            }
+            return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
+                numeric: options.numeric === undefined ? "auto" : options.numeric,
+                style: options.style === undefined ? "long" : options.style,
+            }).format(amount, unit));
         }
         catch {
-            // month/year are calendrical and need a relativeTo anchor
-            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: reference }), options.roundingMethod);
+            return "";
         }
-        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-            numeric: options.numeric ?? "auto",
-            style: options.style ?? "long",
-        }).format(amount, unit));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -5,17 +5,26 @@ export interface FormatRelativeDateTimeOptions extends RelativeTimeFormatOptions
 /**
  * Format the relative time between a plain date-time and a reference date-time.
  *
- * - Auto-picks the display unit (second through year) based on the distance, unless
- *   `largestUnit` forces one.
+ * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
+ *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
+ *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
+ *   "3 years ago".
+ * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
+ *   Pass `largestUnit: "day"` to keep a day count.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date-time 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: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long" }) // "in 3 hours"
- * @example formatRelativeDateTime(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"
+ * @example formatRelativeDateTime("2026-01-15T00:00:00", "en-US", { reference: "2026-01-15T10:30:00", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeDateTime("2021-03-15T12:00:00", "en-US", { reference: "2024-03-15T12:00:00" }) // "3 years ago"
  * @example formatRelativeDateTime("not-a-date") // ""
+ * @example formatRelativeDateTime("2024-03-15T09:00:00", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00" }) // "il y a 3 heures"
+ * @example formatRelativeDateTime("2024-03-12T10:00:00", "en-US", null as never) // "" (null options)
  */
-export declare function formatRelativeDateTime(value: string, locale?: string, options?: FormatRelativeDateTimeOptions): string;
+export declare function formatRelativeDateTime(value: string, locale?: string | string[], options?: FormatRelativeDateTimeOptions): string;

package/dist/plain/format/formatRelativeDateTime.js

@@ -1,57 +1,59 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { durationTotal } from "../../internal/index.js";
+import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { isValidDateTime } from "../validate/index.js";
-const AUTO_UNITS = [
-    { unit: "second", maxSeconds: 60 },
-    { unit: "minute", maxSeconds: 3_600 },
-    { unit: "hour", maxSeconds: 86_400 },
-    { unit: "day", maxSeconds: Infinity },
-];
 /**
  * Format the relative time between a plain date-time and a reference date-time.
  *
- * - Auto-picks the display unit (second through year) based on the distance, unless
- *   `largestUnit` forces one.
+ * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
+ *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
+ *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
+ *   "3 years ago".
+ * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
+ *   Pass `largestUnit: "day"` to keep a day count.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
+ *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date-time 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: { style, numeric, largestUnit, roundingMethod, reference }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long" }) // "in 3 hours"
- * @example formatRelativeDateTime(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"
+ * @example formatRelativeDateTime("2026-01-15T00:00:00", "en-US", { reference: "2026-01-15T10:30:00", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeDateTime("2021-03-15T12:00:00", "en-US", { reference: "2024-03-15T12:00:00" }) // "3 years ago"
  * @example formatRelativeDateTime("not-a-date") // ""
+ * @example formatRelativeDateTime("2024-03-15T09:00:00", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00" }) // "il y a 3 heures"
+ * @example formatRelativeDateTime("2024-03-12T10:00:00", "en-US", null as never) // "" (null options)
  */
 export function formatRelativeDateTime(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 diff = target.since(reference);
-        const absSeconds = Math.abs(diff.total("second"));
-        const unit = options.largestUnit ??
-            AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ??
-            "day";
-        let amount;
+        // 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 {
-            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            const target = Temporal.PlainDateTime.from(value);
+            const reference = options.reference
+                ? Temporal.PlainDateTime.from(options.reference)
+                : Temporal.Now.plainDateTimeISO();
+            const diff = target.since(reference);
+            // month/year are calendrical — relativeTo needs a PlainDate
+            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, reference.toPlainDate()));
         }
         catch {
-            // month/year are calendrical — relativeTo needs a PlainDate
-            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: reference.toPlainDate() }), options.roundingMethod);
+            return "";
         }
-        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-            numeric: options.numeric ?? "auto",
-            style: options.style ?? "long",
-        }).format(amount, unit));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }