@northguild/gmt 1.14.2

package/dist/internal/cycleFieldValue.js

@@ -0,0 +1,48 @@
+/**
+ * Compute the wrapped (or rounded) target value for one field of a `cycle*` call.
+ *
+ * - `bounds: null` means the field is unbounded (only `year` uses this) — cycling is plain
+ *   addition, and rounding still snaps to a multiple of `amount` with no wrap correction.
+ * - Non-round path is modulo arithmetic relative to `bounds.min`, so it resolves any `amount` —
+ *   including one bigger than the field's own range (e.g. cycling month by +13) — in one step,
+ *   not by repeatedly correcting a single overflow.
+ * - Round path is **not** "round to nearest": it steps by `Math.sign(amount)` first, then snaps to
+ *   the next multiple of `Math.abs(amount)` in the direction of that sign (ceiling for positive
+ *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. This matches
+ *   `@internationalized/date`'s `CycleOptions.round` behavior exactly (verified against its
+ *   `manipulation.ts` source) — e.g. minute `22` cycled by `+15` with `round: true` lands on `30`
+ *   (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ *
+ * @param current the field's current numeric value
+ * @param amount signed amount to cycle by
+ * @param bounds inclusive `{ min, max }` range to wrap within, or `null` for unbounded
+ * @param round whether to snap to the next/previous multiple of `amount` instead of adding it
+ * @example cycleFieldValue(12, 1, { min: 1, max: 12 }, false) // 1 (month December +1 wraps to January)
+ * @example cycleFieldValue(1, 13, { min: 1, max: 12 }, false) // 2 (amount larger than the range)
+ * @example cycleFieldValue(22, 15, { min: 0, max: 59 }, true) // 30 (next multiple of 15 above 22)
+ * @example cycleFieldValue(22, -15, { min: 0, max: 59 }, true) // 15 (previous multiple of 15 below 22)
+ * @example cycleFieldValue(2022, 5, null, true) // 2025 (unbounded field, still rounds)
+ * @returns the new field value
+ */
+export function cycleFieldValue(current, amount, bounds, round) {
+    if (amount === 0)
+        return current;
+    if (round) {
+        let stepped = current + Math.sign(amount);
+        if (bounds && stepped < bounds.min)
+            stepped = bounds.max;
+        const increment = Math.abs(amount);
+        stepped =
+            amount > 0
+                ? Math.ceil(stepped / increment) * increment
+                : Math.floor(stepped / increment) * increment;
+        if (bounds && stepped > bounds.max)
+            stepped = bounds.min;
+        return stepped;
+    }
+    if (!bounds)
+        return current + amount;
+    const size = bounds.max - bounds.min + 1;
+    const wrapped = (((current - bounds.min + amount) % size) + size) % size;
+    return bounds.min + wrapped;
+}

package/dist/internal/dateCycleFieldBounds.d.ts

@@ -0,0 +1,25 @@
+import type { DateCycleField } from "../types/index.js";
+/**
+ * Return the inclusive wrap bounds for a `DateCycleField`, or `null` for `year` (unbounded — see
+ * `cycleFieldValue`'s doc).
+ *
+ * - `month` bounds use `source.monthsInYear` and `day` bounds use `source.daysInMonth` rather than
+ *   hardcoded `12`/`31` — both work identically on `Temporal.PlainDate`, `PlainDateTime`, and
+ *   `ZonedDateTime`, all of which expose these calendar-derived properties. `day`'s bounds are
+ *   always the **current** month's `daysInMonth`, never the target month's — cycling `day` never
+ *   changes `month`.
+ *
+ * @param field the date field being cycled
+ * @param source an object exposing `monthsInYear` and `daysInMonth` (any Temporal date-bearing type)
+ * @example dateCycleFieldBounds("year", { monthsInYear: 12, daysInMonth: 31 }) // null
+ * @example dateCycleFieldBounds("month", { monthsInYear: 12, daysInMonth: 31 }) // { min: 1, max: 12 }
+ * @example dateCycleFieldBounds("day", { monthsInYear: 12, daysInMonth: 29 }) // { min: 1, max: 29 }
+ * @returns `{ min, max }` inclusive bounds, or `null` when the field is unbounded
+ */
+export declare function dateCycleFieldBounds(field: DateCycleField, source: {
+    monthsInYear: number;
+    daysInMonth: number;
+}): {
+    min: number;
+    max: number;
+} | null;

package/dist/internal/dateCycleFieldBounds.js

@@ -0,0 +1,27 @@
+/**
+ * Return the inclusive wrap bounds for a `DateCycleField`, or `null` for `year` (unbounded — see
+ * `cycleFieldValue`'s doc).
+ *
+ * - `month` bounds use `source.monthsInYear` and `day` bounds use `source.daysInMonth` rather than
+ *   hardcoded `12`/`31` — both work identically on `Temporal.PlainDate`, `PlainDateTime`, and
+ *   `ZonedDateTime`, all of which expose these calendar-derived properties. `day`'s bounds are
+ *   always the **current** month's `daysInMonth`, never the target month's — cycling `day` never
+ *   changes `month`.
+ *
+ * @param field the date field being cycled
+ * @param source an object exposing `monthsInYear` and `daysInMonth` (any Temporal date-bearing type)
+ * @example dateCycleFieldBounds("year", { monthsInYear: 12, daysInMonth: 31 }) // null
+ * @example dateCycleFieldBounds("month", { monthsInYear: 12, daysInMonth: 31 }) // { min: 1, max: 12 }
+ * @example dateCycleFieldBounds("day", { monthsInYear: 12, daysInMonth: 29 }) // { min: 1, max: 29 }
+ * @returns `{ min, max }` inclusive bounds, or `null` when the field is unbounded
+ */
+export function dateCycleFieldBounds(field, source) {
+    switch (field) {
+        case "year":
+            return null;
+        case "month":
+            return { min: 1, max: source.monthsInYear };
+        case "day":
+            return { min: 1, max: source.daysInMonth };
+    }
+}

package/dist/internal/dateTimeUnitHelpers.d.ts

@@ -0,0 +1,27 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the start of the specified date-time `unit` for a `Temporal.PlainDateTime`.
+ *
+ * - Always uses Monday as the week start (consistent with roundDateTime semantics).
+ * - Date units (year, month, week) reset the time to midnight.
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param source Temporal.PlainDateTime to round
+ * @param unit DateTimeUnit to specify the unit for the start
+ * @returns Temporal.PlainDateTime at the start of the specified unit
+ */
+export declare function getStartOfDateTimeUnit(source: Temporal.PlainDateTime, unit: string): Temporal.PlainDateTime;
+/**
+ * Add `amount` units of the specified date-time `unit` to a `Temporal.PlainDateTime`.
+ *
+ * - Only year, month, and week are meaningful for the manual rounding path.
+ * - Day and time units return the input unchanged (they are handled by
+ *   `Temporal.PlainDateTime.round()` in the callers).
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param date Temporal.PlainDateTime to advance
+ * @param unit DateTimeUnit to add
+ * @param amount number of units to add
+ * @returns new Temporal.PlainDateTime advanced by the specified amount
+ */
+export declare function addDateTimeUnit(date: Temporal.PlainDateTime, unit: string, amount: number): Temporal.PlainDateTime;

package/dist/internal/dateTimeUnitHelpers.js

@@ -0,0 +1,50 @@
+/**
+ * Return the start of the specified date-time `unit` for a `Temporal.PlainDateTime`.
+ *
+ * - Always uses Monday as the week start (consistent with roundDateTime semantics).
+ * - Date units (year, month, week) reset the time to midnight.
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param source Temporal.PlainDateTime to round
+ * @param unit DateTimeUnit to specify the unit for the start
+ * @returns Temporal.PlainDateTime at the start of the specified unit
+ */
+export function getStartOfDateTimeUnit(source, unit) {
+    switch (unit) {
+        case "year":
+            return source.with({ month: 1, day: 1 }).withPlainTime();
+        case "month":
+            return source.with({ day: 1 }).withPlainTime();
+        case "week": {
+            const daysToSubtract = source.dayOfWeek - 1;
+            return source.subtract({ days: daysToSubtract }).withPlainTime();
+        }
+        default:
+            return source.withPlainTime();
+    }
+}
+/**
+ * Add `amount` units of the specified date-time `unit` to a `Temporal.PlainDateTime`.
+ *
+ * - Only year, month, and week are meaningful for the manual rounding path.
+ * - Day and time units return the input unchanged (they are handled by
+ *   `Temporal.PlainDateTime.round()` in the callers).
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param date Temporal.PlainDateTime to advance
+ * @param unit DateTimeUnit to add
+ * @param amount number of units to add
+ * @returns new Temporal.PlainDateTime advanced by the specified amount
+ */
+export function addDateTimeUnit(date, unit, amount) {
+    switch (unit) {
+        case "year":
+            return date.add({ years: amount });
+        case "month":
+            return date.add({ months: amount });
+        case "week":
+            return date.add({ days: amount * 7 });
+        default:
+            return date;
+    }
+}

package/dist/internal/dateUnitHelpers.d.ts

@@ -0,0 +1,23 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the start of the specified date `unit` for a `Temporal.PlainDate`.
+ *
+ * - Always uses Monday as the week start (consistent with roundDate semantics).
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source Temporal.PlainDate to round
+ * @param unit DateUnit to specify the unit for the start
+ * @returns Temporal.PlainDate at the start of the specified unit
+ */
+export declare function getStartOfDateUnit(source: Temporal.PlainDate, unit: string): Temporal.PlainDate;
+/**
+ * Add `amount` units of the specified date `unit` to a `Temporal.PlainDate`.
+ *
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param date Temporal.PlainDate to advance
+ * @param unit DateUnit to add
+ * @param amount number of units to add
+ * @returns new Temporal.PlainDate advanced by the specified amount
+ */
+export declare function addDateUnit(date: Temporal.PlainDate, unit: string, amount: number): Temporal.PlainDate;

package/dist/internal/dateUnitHelpers.js

@@ -0,0 +1,46 @@
+/**
+ * Return the start of the specified date `unit` for a `Temporal.PlainDate`.
+ *
+ * - Always uses Monday as the week start (consistent with roundDate semantics).
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source Temporal.PlainDate to round
+ * @param unit DateUnit to specify the unit for the start
+ * @returns Temporal.PlainDate at the start of the specified unit
+ */
+export function getStartOfDateUnit(source, unit) {
+    switch (unit) {
+        case "year":
+            return source.with({ month: 1, day: 1 });
+        case "month":
+            return source.with({ day: 1 });
+        case "week": {
+            const daysToSubtract = source.dayOfWeek - 1;
+            return source.subtract({ days: daysToSubtract });
+        }
+        default:
+            return source;
+    }
+}
+/**
+ * Add `amount` units of the specified date `unit` to a `Temporal.PlainDate`.
+ *
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param date Temporal.PlainDate to advance
+ * @param unit DateUnit to add
+ * @param amount number of units to add
+ * @returns new Temporal.PlainDate advanced by the specified amount
+ */
+export function addDateUnit(date, unit, amount) {
+    switch (unit) {
+        case "year":
+            return date.add({ years: amount });
+        case "month":
+            return date.add({ months: amount });
+        case "week":
+            return date.add({ days: amount * 7 });
+        default:
+            return date.add({ days: amount });
+    }
+}

package/dist/internal/durationUntilString.d.ts

@@ -0,0 +1,17 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { DurationStringOptions, RoundingOptions } from "../types/index.js";
+/**
+ * Compute the ISO 8601 duration string between two Temporal objects via `.until()` + `.toString()`.
+ *
+ * Shared by the `diff*AsDuration` functions, which otherwise differ only in how their inputs are
+ * validated and constructed.
+ *
+ * @param start Temporal object supporting `.until()` (PlainDate, PlainDateTime, or ZonedDateTime)
+ * @param end the Temporal object to diff against
+ * @param largestUnit the duration's largestUnit
+ * @param options .until() rounding options and .toString() precision options
+ * @returns ISO 8601 duration string
+ */
+export declare function durationUntilString(start: Temporal.PlainDate, end: Temporal.PlainDate, largestUnit: string, options?: RoundingOptions<Temporal.DateUnit> & DurationStringOptions): string;
+export declare function durationUntilString(start: Temporal.PlainDateTime, end: Temporal.PlainDateTime, largestUnit: string, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;
+export declare function durationUntilString(start: Temporal.ZonedDateTime, end: Temporal.ZonedDateTime, largestUnit: string, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/internal/durationUntilString.js

@@ -0,0 +1,13 @@
+export function durationUntilString(start, end, largestUnit, options) {
+    const duration = start.until(end, {
+        largestUnit,
+        smallestUnit: options?.smallestUnit,
+        roundingIncrement: options?.roundingIncrement,
+        roundingMode: options?.roundingMode,
+    });
+    return duration.toString({
+        smallestUnit: options?.toStringSmallestUnit,
+        fractionalSecondDigits: options?.fractionalSecondDigits,
+        roundingMode: options?.toStringRoundingMode,
+    });
+}

package/dist/internal/englishCalendarNames.d.ts

@@ -0,0 +1,2 @@
+export declare const ENGLISH_WEEKDAY_NAMES: readonly ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+export declare const ENGLISH_MONTH_NAMES: readonly ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];

package/dist/internal/englishCalendarNames.js

@@ -0,0 +1,30 @@
+// RFC 2822 (§3.3) and RFC 7231 (§7.1.1.1) mandate English weekday/month
+// abbreviations regardless of the caller's locale — these are fixed,
+// non-locale-adaptive grammars, not a display format, so hardcoding the
+// English names here is not the i18n bug it would be in a formatter (see
+// roadmap Decision 1 / J13's "Why this survives Decision 1").
+// Index 0 = Monday, aligned with Temporal's 1-7 `dayOfWeek` via `[dayOfWeek - 1]`.
+export const ENGLISH_WEEKDAY_NAMES = [
+    "Mon",
+    "Tue",
+    "Wed",
+    "Thu",
+    "Fri",
+    "Sat",
+    "Sun",
+];
+// Index 0 = January, aligned with Temporal's 1-12 `month` via `[month - 1]`.
+export const ENGLISH_MONTH_NAMES = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];

package/dist/internal/ethiopicFamilyCalendar.d.ts

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+export type EthiopicFamilyCalendar = "ethiopic" | "ethiopic-amete-alem" | "coptic";
+export declare function isEthiopicFamilyCalendar(value: string): value is EthiopicFamilyCalendar;
+export interface EthiopicFamilyFields {
+    year: number;
+    era?: "ethioaa" | "ethiopic";
+    eraYear?: number;
+    month: number;
+    day: number;
+}
+/**
+ * Derive an Ethiopic-family calendar's native year/month/day (+ era, for "ethiopic") from a
+ * Temporal.PlainDate, via Temporal's ICU-independent "ethioaa" calendar rather than the
+ * target's own native calendar id. See the module comment above for why.
+ */
+export declare function ethiopicFamilyFieldsFromDate(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): EthiopicFamilyFields;
+/**
+ * Construct a Temporal.PlainDate from an Ethiopic-family calendar's native fields, backed
+ * by Temporal's "ethioaa" calendar rather than the target's own native calendar id. Throws
+ * on an unrecognized era or a missing required field — callers wrap this in try-catch per
+ * GMT's sentinel-return contract. See the module comment above for why.
+ */
+export declare function dateFromEthiopicFamilyFields(calendar: EthiopicFamilyCalendar, fields: {
+    year?: number;
+    era?: string;
+    eraYear?: number;
+    month: number;
+    day: number;
+}): Temporal.PlainDate;
+/**
+ * Split a Temporal.PlainDate into GMT's calendar-annotated string halves for an Ethiopic-family
+ * calendar, mirroring `calendarDateParts`' shape for the rest of the calendar systems but
+ * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
+ *
+ * Returned as `{ date, annotation }` rather than one string so the zoned grammar can splice its
+ * time/offset between the two halves — see `calendarDateParts`' doc comment for why.
+ */
+export declare function ethiopicFamilyDateParts(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): {
+    date: string;
+    annotation: string;
+};
+/**
+ * Format a Temporal.PlainDate as GMT's calendar-annotated string for an Ethiopic-family
+ * calendar, mirroring `formatCalendarDate`'s shape for the rest of the calendar systems but
+ * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
+ */
+export declare function formatEthiopicFamilyDate(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): string;

package/dist/internal/ethiopicFamilyCalendar.js

@@ -0,0 +1,136 @@
+import { Temporal } from "@js-temporal/polyfill";
+export function isEthiopicFamilyCalendar(value) {
+    return (value === "ethiopic" ||
+        value === "ethiopic-amete-alem" ||
+        value === "coptic");
+}
+// @js-temporal/polyfill@0.5.1's "ethiopic" and "coptic" calendar ids resolve year/era by
+// formatting the date through Intl.DateTimeFormat and matching the resulting era part
+// against a hardcoded era-name table (its HelperBase.isoToCalendarDate — used because,
+// unlike "ethioaa", these two calendars aren't a fixed year-offset from ISO, so the
+// polyfill can't compute them with pure arithmetic the way it does for "ethioaa"). CLDR's
+// era abbreviation for both calendars changed at the ICU 78 boundary, not at any particular
+// Node major version: ICU < 78 emits an era string the polyfill's table matches; ICU >= 78
+// emits "am", which isn't in that table. This is a real trap for "which Node am I on" bug
+// hunting — ICU 78 ships in *both* Node 22 and Node 24 (confirmed directly against a Node 20 /
+// ICU 78.2 environment during E5, issue #78, where the bug reproduces despite being on Node
+// 20 — an earlier draft of this comment wrongly pinned the boundary to "Node 24"). The result
+// is that *every* read or write of Temporal's "ethiopic"/"coptic" calendar ids throws a
+// RangeError under ICU >= 78 (verified directly — this isn't a hypothetical). "ethioaa" (Ethiopic Amete Alem)
+// has no era at all — a single continuous count from a fixed epoch — so the polyfill
+// resolves it with pure arithmetic and never touches Intl, making it stable across Node
+// versions. This module uses "ethioaa" as a computation carrier for the whole Ethiopic
+// family: month/day are identical across all three (they share one annual 13-month cycle),
+// so only the displayed year (+ era, for "ethiopic") needs converting, which this module
+// does with GMT-owned arithmetic instead of ever constructing or reading a Temporal
+// PlainDate calendared as "ethiopic" or "coptic".
+//
+// The two constants below are ported from the same source file
+// (@js-temporal/polyfill/lib/calendar.ts)'s EthiopicHelper/CopticHelper definitions, not
+// independently derived: the Amete Mihret ("ethiopic") era begins at ethioaa proleptic year
+// 5501 (EthiopicHelper's `anchorEpoch: { year: 5501 }`), and Coptic's own epoch
+// (0284-08-29) falls 5776 ethioaa years after ethioaa's epoch (-005492-07-17) — both
+// verified against the polyfill's own output across a spread of dates spanning multiple
+// centuries and both 13th-month lengths before being hardcoded here.
+const ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR = 5501;
+const COPTIC_ETHIOAA_YEAR_OFFSET = 5776;
+/**
+ * Derive an Ethiopic-family calendar's native year/month/day (+ era, for "ethiopic") from a
+ * Temporal.PlainDate, via Temporal's ICU-independent "ethioaa" calendar rather than the
+ * target's own native calendar id. See the module comment above for why.
+ */
+export function ethiopicFamilyFieldsFromDate(date, calendar) {
+    const { year: ethioaaYear, month, day } = date.withCalendar("ethioaa");
+    if (calendar === "ethiopic-amete-alem") {
+        return { year: ethioaaYear, month, day };
+    }
+    if (calendar === "coptic") {
+        return { year: ethioaaYear - COPTIC_ETHIOAA_YEAR_OFFSET, month, day };
+    }
+    if (ethioaaYear >= ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR) {
+        return {
+            year: ethioaaYear,
+            era: "ethiopic",
+            eraYear: ethioaaYear - (ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR - 1),
+            month,
+            day,
+        };
+    }
+    return {
+        year: ethioaaYear,
+        era: "ethioaa",
+        eraYear: ethioaaYear,
+        month,
+        day,
+    };
+}
+/**
+ * Construct a Temporal.PlainDate from an Ethiopic-family calendar's native fields, backed
+ * by Temporal's "ethioaa" calendar rather than the target's own native calendar id. Throws
+ * on an unrecognized era or a missing required field — callers wrap this in try-catch per
+ * GMT's sentinel-return contract. See the module comment above for why.
+ */
+export function dateFromEthiopicFamilyFields(calendar, fields) {
+    let ethioaaYear;
+    if (calendar === "ethiopic-amete-alem" || calendar === "coptic") {
+        if (fields.year === undefined) {
+            throw new RangeError(`${calendar} requires a year`);
+        }
+        ethioaaYear =
+            calendar === "coptic"
+                ? fields.year + COPTIC_ETHIOAA_YEAR_OFFSET
+                : fields.year;
+    }
+    else if (fields.era === "ethioaa" || fields.era === "ethiopic") {
+        if (fields.eraYear === undefined) {
+            throw new RangeError("ethiopic requires an eraYear");
+        }
+        ethioaaYear =
+            fields.era === "ethioaa"
+                ? fields.eraYear
+                : fields.eraYear + (ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR - 1);
+    }
+    else {
+        throw new RangeError(`Unknown ethiopic era: ${fields.era}`);
+    }
+    return Temporal.PlainDate.from({
+        year: ethioaaYear,
+        month: fields.month,
+        day: fields.day,
+        calendar: "ethioaa",
+    }, { overflow: "reject" });
+}
+/**
+ * Split a Temporal.PlainDate into GMT's calendar-annotated string halves for an Ethiopic-family
+ * calendar, mirroring `calendarDateParts`' shape for the rest of the calendar systems but
+ * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
+ *
+ * Returned as `{ date, annotation }` rather than one string so the zoned grammar can splice its
+ * time/offset between the two halves — see `calendarDateParts`' doc comment for why.
+ */
+export function ethiopicFamilyDateParts(date, calendar) {
+    const fields = ethiopicFamilyFieldsFromDate(date, calendar);
+    const month = String(fields.month).padStart(2, "0");
+    const day = String(fields.day).padStart(2, "0");
+    if (calendar === "ethiopic") {
+        const eraYear = String(fields.eraYear).padStart(4, "0");
+        return {
+            date: `${eraYear}-${month}-${day}`,
+            annotation: `[u-ca=ethiopic;era=${fields.era}]`,
+        };
+    }
+    const year = String(fields.year).padStart(4, "0");
+    return {
+        date: `${year}-${month}-${day}`,
+        annotation: `[u-ca=${calendar}]`,
+    };
+}
+/**
+ * Format a Temporal.PlainDate as GMT's calendar-annotated string for an Ethiopic-family
+ * calendar, mirroring `formatCalendarDate`'s shape for the rest of the calendar systems but
+ * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
+ */
+export function formatEthiopicFamilyDate(date, calendar) {
+    const { date: datePart, annotation } = ethiopicFamilyDateParts(date, calendar);
+    return `${datePart}${annotation}`;
+}

package/dist/internal/formatDateInCalendar.d.ts

@@ -0,0 +1,47 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { CalendarSystem } from "../types/index.js";
+import { type CalendarDateStringParts } from "./calendarDateString.js";
+/**
+ * Split a Temporal.PlainDate into GMT's calendar-annotated string halves (`{ date, annotation }`)
+ * in a known target CalendarSystem — the shared primitive behind both `formatDateInCalendar`
+ * (`plain/`) and `internal/calendarZonedString.ts`'s `formatZonedInCalendar` (`zoned/`).
+ *
+ * The two namespaces need the halves joined differently — `plain/` concatenates them directly,
+ * while GMT's zoned grammar splices `T<time><offset>` between them and appends `[<timeZone>]`
+ * (see `regex/calendar-zoned-date-time.ts` for why `[u-ca=...]` precedes `[timeZone]`). Sharing
+ * the split rather than string-slicing `formatDateInCalendar`'s output on `"["` keeps the era,
+ * Ethiopic-family and zero-padding logic in exactly one place per calendar family.
+ *
+ * The calendar must always be known up front and passed in explicitly, never re-derived from
+ * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
+ * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
+ * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
+ *
+ * @param date Temporal.PlainDate to split, already calendared as `calendar` expects
+ *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
+ * @param calendar the CalendarSystem `date` is known to represent
+ * @returns `{ date, annotation }` — `annotation` is `""` for the "gregorian"/iso8601 case
+ */
+export declare function calendarDateStringParts(date: Temporal.PlainDate, calendar: CalendarSystem): CalendarDateStringParts;
+/**
+ * Format a Temporal.PlainDate as a GMT calendar-annotated (or bare ISO) string in a known
+ * target CalendarSystem — companion to `calendarSystemOfDateValue`.
+ *
+ * The calendar must always be known up front and passed in explicitly, never re-derived from
+ * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
+ * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
+ * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
+ *
+ * Within a known target calendar, though, the *fields* (year, era, month, day) are always
+ * re-derived from the actual resulting `date`, never copied from an input string's tag —
+ * `calendarDateParts`/`ethiopicFamilyDateParts` both already do this per-call, which is
+ * required because calendar-unit arithmetic can cross a leap-month or era boundary (Hebrew
+ * Adar I -> Adar, Japanese Heisei -> Reiwa): a copied tag would describe a date that no longer
+ * exists (E5 decision of record D7).
+ *
+ * @param date Temporal.PlainDate to format, already calendared as `calendar` expects
+ *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
+ * @param calendar the CalendarSystem `date` is known to represent
+ * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") PlainDate string
+ */
+export declare function formatDateInCalendar(date: Temporal.PlainDate, calendar: CalendarSystem): string;

package/dist/internal/formatDateInCalendar.js

@@ -0,0 +1,54 @@
+import { calendarDateParts, } from "./calendarDateString.js";
+import { ethiopicFamilyDateParts, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+/**
+ * Split a Temporal.PlainDate into GMT's calendar-annotated string halves (`{ date, annotation }`)
+ * in a known target CalendarSystem — the shared primitive behind both `formatDateInCalendar`
+ * (`plain/`) and `internal/calendarZonedString.ts`'s `formatZonedInCalendar` (`zoned/`).
+ *
+ * The two namespaces need the halves joined differently — `plain/` concatenates them directly,
+ * while GMT's zoned grammar splices `T<time><offset>` between them and appends `[<timeZone>]`
+ * (see `regex/calendar-zoned-date-time.ts` for why `[u-ca=...]` precedes `[timeZone]`). Sharing
+ * the split rather than string-slicing `formatDateInCalendar`'s output on `"["` keeps the era,
+ * Ethiopic-family and zero-padding logic in exactly one place per calendar family.
+ *
+ * The calendar must always be known up front and passed in explicitly, never re-derived from
+ * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
+ * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
+ * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
+ *
+ * @param date Temporal.PlainDate to split, already calendared as `calendar` expects
+ *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
+ * @param calendar the CalendarSystem `date` is known to represent
+ * @returns `{ date, annotation }` — `annotation` is `""` for the "gregorian"/iso8601 case
+ */
+export function calendarDateStringParts(date, calendar) {
+    if (isEthiopicFamilyCalendar(calendar)) {
+        return ethiopicFamilyDateParts(date, calendar);
+    }
+    return calendarDateParts(date);
+}
+/**
+ * Format a Temporal.PlainDate as a GMT calendar-annotated (or bare ISO) string in a known
+ * target CalendarSystem — companion to `calendarSystemOfDateValue`.
+ *
+ * The calendar must always be known up front and passed in explicitly, never re-derived from
+ * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
+ * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
+ * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
+ *
+ * Within a known target calendar, though, the *fields* (year, era, month, day) are always
+ * re-derived from the actual resulting `date`, never copied from an input string's tag —
+ * `calendarDateParts`/`ethiopicFamilyDateParts` both already do this per-call, which is
+ * required because calendar-unit arithmetic can cross a leap-month or era boundary (Hebrew
+ * Adar I -> Adar, Japanese Heisei -> Reiwa): a copied tag would describe a date that no longer
+ * exists (E5 decision of record D7).
+ *
+ * @param date Temporal.PlainDate to format, already calendared as `calendar` expects
+ *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
+ * @param calendar the CalendarSystem `date` is known to represent
+ * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") PlainDate string
+ */
+export function formatDateInCalendar(date, calendar) {
+    const { date: datePart, annotation } = calendarDateStringParts(date, calendar);
+    return `${datePart}${annotation}`;
+}

package/dist/internal/getLocaleFirstDayOfWeek.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve the ISO day-of-week number (1 = Monday .. 7 = Sunday) that a
+ * locale considers the first day of the week, via
+ * `Intl.Locale.prototype.weekInfo`.
+ *
+ * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Falls back to `1` (Monday, matching GMT's existing ISO default in
+ *   `startOfDate`/`startOfZoned`) if `weekInfo` is unavailable on the
+ *   runtime (older engines) or unresolvable for the given locale.
+ */
+export declare function getLocaleFirstDayOfWeek(locale: string): number | null;

package/dist/internal/getLocaleFirstDayOfWeek.js

@@ -0,0 +1,26 @@
+// `Intl.Locale.prototype.weekInfo`'s ambient type augmentation lives in
+// `getLocaleWeekendDays.ts` (TS's lib.d.ts doesn't declare it as of TS 5.9).
+// Declared once there; this file relies on that global augmentation rather
+// than redeclaring it.
+/**
+ * Resolve the ISO day-of-week number (1 = Monday .. 7 = Sunday) that a
+ * locale considers the first day of the week, via
+ * `Intl.Locale.prototype.weekInfo`.
+ *
+ * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Falls back to `1` (Monday, matching GMT's existing ISO default in
+ *   `startOfDate`/`startOfZoned`) if `weekInfo` is unavailable on the
+ *   runtime (older engines) or unresolvable for the given locale.
+ */
+export function getLocaleFirstDayOfWeek(locale) {
+    try {
+        const weekInfo = new Intl.Locale(locale).weekInfo;
+        if (!weekInfo || typeof weekInfo.firstDay !== "number") {
+            return 1;
+        }
+        return weekInfo.firstDay;
+    }
+    catch {
+        return null;
+    }
+}