@northguild/gmt 1.14.2

package/dist/plain/format/formatCalendar.js

@@ -0,0 +1,70 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.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
+// the same threshold (documented, not a byte-for-byte Moment port — see J15).
+const ABS_DAY_THRESHOLD = 6;
+/**
+ * Format a plain date-time as a relative day label plus time-of-day, e.g.
+ * "Tomorrow at 2:30 PM" — Moment's `.calendar()`, which the existing
+ * `formatRelativeDateTime` family does not cover (that family renders
+ * "in 1 day", an elapsed-time phrase, not a day label + clock time).
+ *
+ * - Within `±6` days of `reference` (default: now), renders `<day label>`
+ *   joined to the localized time using the locale's own connector — never a
+ *   hardcoded "at". The day label comes from `Intl.RelativeTimeFormat`
+ *   (`numeric: "auto"`), so it reads "Today"/"Tomorrow"/"Yesterday" near
+ *   the boundary and "in N days"/"N days ago" further out, all locale-native.
+ * - Beyond `±6` days, falls back to an absolute `dateStyle: "long"` +
+ *   `timeStyle` string with no relative wording, matching Moment's
+ *   `sameElse` behavior.
+ * - The connector between the day label and the time is read from CLDR's
+ *   own combined date+time pattern for the locale (see
+ *   `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`).
+ * - Use `formatCalendar` for user-facing schedules ("Tomorrow at 2:30 PM");
+ *   use `formatRelativeDateTime` for elapsed-time displays ("in 1 day").
+ *
+ * @param value ISO PlainDateTime string to format
+ * @param locale optional: BCP 47 locale tag
+ * @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") // ""
+ */
+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));
+        }
+        const dayLabel = new Intl.RelativeTimeFormat(locale, {
+            numeric: "auto",
+        }).format(diffDays, "day");
+        return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, "UTC", locale, dayLabel, timeStyle));
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Return a localized string for a PlainDate ISO input using Intl options.
+ *
+ * - Uses Temporal.PlainDate.toLocaleString for formatting.
+ * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param locale optional BCP 47 locale identifier
+ * @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("invalid") // ""
+ */
+export declare function formatDate(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;

package/dist/plain/format/formatDate.js

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { normalizeDateTime } from "../../internal/index.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.
+ * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param locale optional BCP 47 locale identifier
+ * @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("invalid") // ""
+ */
+export function formatDate(value, locale, options) {
+    if (!isValidDate(value)) {
+        return "";
+    }
+    try {
+        const out = Temporal.PlainDate.from(value).toLocaleString(locale, options);
+        return normalizeDateTime(out);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ * - Locale elides shared fields between `start` and `end` (e.g. same month/year).
+ * - Returns "" for invalid input on either endpoint.
+ *
+ * @param start ISO PlainDate string (range start)
+ * @param end ISO PlainDate string (range end)
+ * @param locale optional locale tag
+ * @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("invalid", "2024-02-05", "en-US") // "" (invalid input)
+ */
+export declare function formatDateRange(start: string, end: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;

package/dist/plain/format/formatDateRange.js

@@ -0,0 +1,33 @@
+import { Temporal, Intl as TemporalIntl } from "@js-temporal/polyfill";
+import { normalizeDateTime } from "../../internal/index.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.
+ * - Locale elides shared fields between `start` and `end` (e.g. same month/year).
+ * - Returns "" for invalid input on either endpoint.
+ *
+ * @param start ISO PlainDate string (range start)
+ * @param end ISO PlainDate string (range end)
+ * @param locale optional locale tag
+ * @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("invalid", "2024-02-05", "en-US") // "" (invalid input)
+ */
+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));
+        return normalizeDateTime(out);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Return a localized string for a PlainDateTime ISO input using Intl options.
+ *
+ * - Uses Temporal.PlainDateTime.toLocaleString for formatting.
+ * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @param locale optional BCP 47 locale identifier
+ * @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", "de-DE", { dateStyle: "medium", timeStyle: "short" }) // "15.03.2024, 14:30"
+ * @example formatDateTime("invalid") // ""
+ */
+export declare function formatDateTime(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;

package/dist/plain/format/formatDateTime.js

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { normalizeDateTime } from "../../internal/index.js";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return a localized string for a PlainDateTime ISO input using Intl options.
+ *
+ * - Uses Temporal.PlainDateTime.toLocaleString for formatting.
+ * - Accepts optional BCP 47 locale and Intl.DateTimeFormatOptions.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @param locale optional BCP 47 locale identifier
+ * @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", "de-DE", { dateStyle: "medium", timeStyle: "short" }) // "15.03.2024, 14:30"
+ * @example formatDateTime("invalid") // ""
+ */
+export function formatDateTime(value, locale, options) {
+    if (!isValidDateTime(value)) {
+        return "";
+    }
+    try {
+        const out = Temporal.PlainDateTime.from(value).toLocaleString(locale, options);
+        return normalizeDateTime(out);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ * - Locale elides shared fields between `start` and `end` (e.g. same day/month/year).
+ * - Returns "" for invalid input on either endpoint.
+ *
+ * @param start ISO PlainDateTime string (range start)
+ * @param end ISO PlainDateTime string (range end)
+ * @param locale optional locale tag
+ * @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("invalid", "2024-02-03T17:00:00", "en-US") // "" (invalid input)
+ */
+export declare function formatDateTimeRange(start: string, end: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;

package/dist/plain/format/formatDateTimeRange.js

@@ -0,0 +1,33 @@
+import { Temporal, Intl as TemporalIntl } from "@js-temporal/polyfill";
+import { normalizeDateTime } from "../../internal/index.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.
+ * - Locale elides shared fields between `start` and `end` (e.g. same day/month/year).
+ * - Returns "" for invalid input on either endpoint.
+ *
+ * @param start ISO PlainDateTime string (range start)
+ * @param end ISO PlainDateTime string (range end)
+ * @param locale optional locale tag
+ * @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("invalid", "2024-02-03T17:00:00", "en-US") // "" (invalid input)
+ */
+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));
+        return normalizeDateTime(out);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Return the locale-formatted parts of a PlainDateTime.
+ *
+ * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
+ *   `format`). A token pattern hard-codes field order and ships US ordering to
+ *   every locale; `formatToParts` gives the caller full control over presentation
+ *   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"`.
+ * - The caller should iterate the array as returned; reassembling in a fixed
+ *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - Returns `[]` for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @param locale optional BCP 47 locale identifier
+ * @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("invalid") // []
+ */
+export declare function formatDateTimeToParts(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): Array<{
+    type: string;
+    value: string;
+}>;

package/dist/plain/format/formatDateTimeToParts.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the locale-formatted parts of a PlainDateTime.
+ *
+ * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
+ *   `format`). A token pattern hard-codes field order and ships US ordering to
+ *   every locale; `formatToParts` gives the caller full control over presentation
+ *   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"`.
+ * - The caller should iterate the array as returned; reassembling in a fixed
+ *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - Returns `[]` for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @param locale optional BCP 47 locale identifier
+ * @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("invalid") // []
+ */
+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.
+        const epochMilliseconds = Temporal.PlainDateTime.from(value).toZonedDateTime("UTC").epochMilliseconds;
+        const formatter = new Intl.DateTimeFormat(locale, {
+            ...options,
+            timeZone: "UTC",
+        });
+        return formatter
+            .formatToParts(epochMilliseconds)
+            .map((p) => ({ type: p.type, value: p.value }));
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Return the locale-formatted parts of a PlainDate.
+ *
+ * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
+ *   `format`). A token pattern hard-codes field order and ships US ordering to
+ *   every locale; `formatToParts` gives the caller full control over presentation
+ *   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"`.
+ * - The caller should iterate the array as returned; reassembling in a fixed
+ *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - Returns `[]` for invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param locale optional BCP 47 locale identifier
+ * @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("invalid") // []
+ */
+export declare function formatDateToParts(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): Array<{
+    type: string;
+    value: string;
+}>;

package/dist/plain/format/formatDateToParts.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the locale-formatted parts of a PlainDate.
+ *
+ * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
+ *   `format`). A token pattern hard-codes field order and ships US ordering to
+ *   every locale; `formatToParts` gives the caller full control over presentation
+ *   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"`.
+ * - The caller should iterate the array as returned; reassembling in a fixed
+ *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - Returns `[]` for invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param locale optional BCP 47 locale identifier
+ * @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("invalid") // []
+ */
+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.
+        const epochMilliseconds = Temporal.PlainDate.from(value).toZonedDateTime("UTC").epochMilliseconds;
+        const formatter = new Intl.DateTimeFormat(locale, {
+            ...options,
+            timeZone: "UTC",
+        });
+        return formatter
+            .formatToParts(epochMilliseconds)
+            .map((p) => ({ type: p.type, value: p.value }));
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { RelativeRoundingMethod } from "../../types/index.js";
+type RelativeUnit = "year" | "month" | "week" | "day";
+export interface FormatRelativeDateOptions {
+    style?: "long" | "short" | "narrow";
+    numeric?: "always" | "auto";
+    largestUnit?: RelativeUnit;
+    /**
+     * How the computed distance rounds to the display unit: "floor" rounds toward the
+     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
+     * matches current behavior when omitted.
+     */
+    roundingMethod?: RelativeRoundingMethod;
+    reference?: string;
+}
+/**
+ * Format the relative time between a plain date and a reference date.
+ *
+ * - 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.
+ *
+ * @param value ISO date string to format
+ * @param locale optional: BCP 47 locale tag
+ * @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("not-a-date") // ""
+ */
+export declare function formatRelativeDate(value: string, locale?: string, options?: FormatRelativeDateOptions): string;
+export {};

package/dist/plain/format/formatRelativeDate.js

@@ -0,0 +1,57 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+const AUTO_UNITS = [
+    { unit: "day", maxDays: 7 },
+    { unit: "week", maxDays: 28 },
+    { unit: "month", maxDays: 365 },
+    { unit: "year", maxDays: Infinity },
+];
+/**
+ * Format the relative time between a plain date and a reference date.
+ *
+ * - 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.
+ *
+ * @param value ISO date string to format
+ * @param locale optional: BCP 47 locale tag
+ * @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("not-a-date") // ""
+ */
+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;
+        try {
+            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+        }
+        catch {
+            // month/year are calendrical and need a relativeTo anchor
+            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: reference }), options.roundingMethod);
+        }
+        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
+            numeric: options.numeric ?? "auto",
+            style: options.style ?? "long",
+        }).format(amount, unit));
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { RelativeRoundingMethod } from "../../types/index.js";
+type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
+export interface FormatRelativeDateTimeOptions {
+    style?: "long" | "short" | "narrow";
+    numeric?: "always" | "auto";
+    largestUnit?: RelativeUnit;
+    /**
+     * How the computed distance rounds to the display unit: "floor" rounds toward the
+     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
+     * matches current behavior when omitted.
+     */
+    roundingMethod?: RelativeRoundingMethod;
+    reference?: string;
+}
+/**
+ * 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.
+ * - `roundingMethod` controls how the distance rounds to the display unit.
+ *
+ * @param value ISO date-time string to format
+ * @param locale optional: BCP 47 locale tag
+ * @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("not-a-date") // ""
+ */
+export declare function formatRelativeDateTime(value: string, locale?: string, options?: FormatRelativeDateTimeOptions): string;
+export {};

package/dist/plain/format/formatRelativeDateTime.js

@@ -0,0 +1,57 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.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.
+ * - `roundingMethod` controls how the distance rounds to the display unit.
+ *
+ * @param value ISO date-time string to format
+ * @param locale optional: BCP 47 locale tag
+ * @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("not-a-date") // ""
+ */
+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;
+        try {
+            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+        }
+        catch {
+            // month/year are calendrical — relativeTo needs a PlainDate
+            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: reference.toPlainDate() }), options.roundingMethod);
+        }
+        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
+            numeric: options.numeric ?? "auto",
+            style: options.style ?? "long",
+        }).format(amount, unit));
+    }
+    catch {
+        return "";
+    }
+}