@northguild/gmt 1.14.2

package/dist/internal/calendarDateString.js

@@ -0,0 +1,103 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarDate, plainDate } from "../regex/index.js";
+import { calendarSystemIdFromTemporal, isCalendarSystem, temporalCalendarIds, } from "./calendarSystemIds.js";
+import { dateFromEthiopicFamilyFields, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+/**
+ * Parse a plain ISO PlainDate string or a GMT calendar-annotated PlainDate string
+ * (`"5785-01-01[u-ca=hebrew]"`, calendar-native fields, not Temporal's own ISO-digit
+ * `[u-ca=...]` annotation convention) into a Temporal.PlainDate. Throws on invalid input —
+ * callers wrap this in try-catch per GMT's sentinel-return contract.
+ *
+ * The regex only proves shape; `Temporal.PlainDate.from` performs the real construction
+ * and validation (rejecting overflowed fields and unknown calendar identifiers), per the
+ * scoped manual-string-parsing exception for fixed, non-caller-supplied grammars. The
+ * Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic") is the one exception —
+ * see ethiopicFamilyCalendar.ts for why they're constructed via GMT-owned arithmetic
+ * instead of Temporal's own calendar ids for those three.
+ *
+ * The non-annotated fallback branch requires the strict PlainDate-only shape (via the
+ * `plainDate` regex) before delegating to `Temporal.PlainDate.from` — bare `.from()` silently
+ * truncates a full datetime/zoned string to its date portion (`Temporal.PlainDate.from("2024-
+ * 03-10T14:30:00")` succeeds), which would make this function (and therefore
+ * `isValidCalendarDate`/`convertDateToCalendar`) wrongly accept datetime input. Found and
+ * fixed as part of E5 (issue #78) — it predates this story but this function is E5's shared
+ * gate, so it must not inherit the hazard.
+ */
+export function parseCalendarDateValue(value) {
+    const match = calendarDate.exec(value);
+    if (!match) {
+        if (!plainDate.test(value)) {
+            throw new RangeError(`Not a valid GMT PlainDate string: ${value}`);
+        }
+        return Temporal.PlainDate.from(value);
+    }
+    const [, year, month, day, calendarId, era] = match;
+    if (isEthiopicFamilyCalendar(calendarId)) {
+        return dateFromEthiopicFamilyFields(calendarId, {
+            year: era ? undefined : Number(year),
+            era,
+            eraYear: era ? Number(year) : undefined,
+            month: Number(month),
+            day: Number(day),
+        });
+    }
+    // The regex captures GMT's own calendar identifier (e.g. "islamic-tabular"), which
+    // doesn't always match Temporal's id for the same calendar (e.g. "islamic-tbla") — an
+    // unrecognized id is passed through as-is so Temporal.PlainDate.from rejects it the
+    // same way it rejects any other unknown calendar identifier.
+    const temporalCalendarId = isCalendarSystem(calendarId)
+        ? temporalCalendarIds[calendarId]
+        : calendarId;
+    // A captured `;era=` suffix (only ever present for "japanese", the one remaining calendar
+    // whose plain `.year` doesn't reset at an era change) means `year` is an era-relative
+    // `eraYear`, not a proleptic year — Temporal needs `era`+`eraYear` together to resolve
+    // it back to the correct date.
+    const fields = era
+        ? { era, eraYear: Number(year), month: Number(month), day: Number(day) }
+        : { year: Number(year), month: Number(month), day: Number(day) };
+    return Temporal.PlainDate.from({ ...fields, calendar: temporalCalendarId }, { overflow: "reject" });
+}
+/**
+ * Split a Temporal.PlainDate into GMT's calendar-annotated string halves: a bare ISO date with
+ * an empty annotation for the "iso8601" calendar (GMT's existing default, unannotated), or the
+ * calendar's own native year/month/day plus a `[u-ca=<identifier>]` annotation for any other.
+ *
+ * "japanese" is the one exception to "native year": Temporal's `.year` for it stays
+ * proleptic across era changes (Meiji 1 and Reiwa 1 don't both read `1`), which would
+ * contradict the era-based numbering the calendar is for — so it's tagged with `.eraYear`
+ * and `;era=<name>` instead, both of which Temporal always populates for this calendar
+ * (including for pre-Meiji dates, under a synthetic "japanese" era — see the README's
+ * calendar-systems section for why GMT doesn't reject those unlike `@internationalized/date`).
+ *
+ * This function is never called with an Ethiopic-family ("ethiopic" /
+ * "ethiopic-amete-alem" / "coptic") calendared date — those three format through
+ * `ethiopicFamilyDateParts` in ethiopicFamilyCalendar.ts instead, which never touches
+ * Temporal's own "ethiopic"/"coptic" calendar ids. See that file for why.
+ */
+export function calendarDateParts(date) {
+    if (date.calendarId === "iso8601") {
+        return { date: date.toString(), annotation: "" };
+    }
+    const calendarId = calendarSystemIdFromTemporal(date.calendarId);
+    const isEraBased = calendarId === "japanese";
+    const year = String(isEraBased ? date.eraYear : date.year).padStart(4, "0");
+    const month = String(date.month).padStart(2, "0");
+    const day = String(date.day).padStart(2, "0");
+    const eraSuffix = isEraBased ? `;era=${date.era}` : "";
+    return {
+        date: `${year}-${month}-${day}`,
+        annotation: `[u-ca=${calendarId}${eraSuffix}]`,
+    };
+}
+/**
+ * Format a Temporal.PlainDate as GMT's calendar-annotated string: a bare ISO string for
+ * the "iso8601" calendar (GMT's existing default, unannotated), or the calendar's own
+ * native year/month/day tagged with `[u-ca=<identifier>]` for any other calendar.
+ *
+ * See `calendarDateParts` (the shared primitive this concatenates) for the era handling and
+ * the Ethiopic-family carve-out.
+ */
+export function formatCalendarDate(date) {
+    const { date: datePart, annotation } = calendarDateParts(date);
+    return `${datePart}${annotation}`;
+}

package/dist/internal/calendarSystemIds.d.ts

@@ -0,0 +1,4 @@
+import type { CalendarSystem } from "../types/index.js";
+export declare const temporalCalendarIds: Record<CalendarSystem, string>;
+export declare function isCalendarSystem(value: string): value is CalendarSystem;
+export declare function calendarSystemIdFromTemporal(temporalId: string): CalendarSystem;

package/dist/internal/calendarSystemIds.js

@@ -0,0 +1,55 @@
+// Maps GMT's public CalendarSystem identifiers to the Temporal/Intl calendar identifiers
+// they wrap. "gregorian" maps to "iso8601" (Temporal's default, era-free calendar) rather
+// than "gregory" (which carries BCE/CE eras) since GMT's existing unannotated ISO strings
+// are already iso8601-calendared — this keeps "gregorian" round-trips a no-op.
+//
+// "islamic-tabular" maps to Temporal's "islamic-tbla" id (its name for the same
+// arithmetic/astronomical-epoch tabular calendar). "islamic-umalqura" resolves through
+// Temporal's built-in Umm al-Qura implementation rather than a table GMT ports itself —
+// per E1's "no ported leap-year tables or arithmetic" precedent, the polyfill already
+// carries the correct tabulated/algorithmic data, so a GMT-owned copy would only add a
+// second, divergence-prone source of truth.
+//
+// "taiwan" maps to Temporal's "roc" id (Republic of China calendar — the same calendar
+// react-aria's TaiwanCalendar wraps under a different name). "japanese", "buddhist", and
+// "persian"/"indian" match Temporal's own ids directly.
+//
+// "ethiopic-amete-alem" maps to Temporal's "ethioaa" id (Ethiopic calendar anchored to the
+// Amete Alem/"Year of the World" epoch, ~5493 BCE — a single continuous era, never resets).
+// "ethiopic" and "coptic" match Temporal's own ids directly; both share the Ethiopic
+// family's 13-month structure (12 x 30 days + a 5/6-day Pagume/Nasie) but differ in epoch —
+// "ethiopic" additionally resets to the Amete Mihret/"Incarnation" era at its own epoch
+// (~AD 8), which is why it needs the same eraYear-based string handling as "japanese" (see
+// calendarDateString.ts's isEraBased).
+export const temporalCalendarIds = {
+    gregorian: "iso8601",
+    hebrew: "hebrew",
+    "islamic-civil": "islamic-civil",
+    "islamic-tabular": "islamic-tbla",
+    "islamic-umalqura": "islamic-umalqura",
+    japanese: "japanese",
+    buddhist: "buddhist",
+    taiwan: "roc",
+    persian: "persian",
+    indian: "indian",
+    ethiopic: "ethiopic",
+    "ethiopic-amete-alem": "ethioaa",
+    coptic: "coptic",
+};
+export function isCalendarSystem(value) {
+    return value in temporalCalendarIds;
+}
+// Reverse of temporalCalendarIds — needed because some GMT calendar identifiers (e.g.
+// "islamic-tabular") don't match Temporal's own id for the same calendar ("islamic-tbla"),
+// so a PlainDate's `calendarId` can't be used directly as GMT's string annotation.
+const gmtCalendarSystemIds = Object.fromEntries(Object.entries(temporalCalendarIds).map(([gmtId, temporalId]) => [
+    temporalId,
+    gmtId,
+]));
+export function calendarSystemIdFromTemporal(temporalId) {
+    const gmtId = gmtCalendarSystemIds[temporalId];
+    if (!gmtId) {
+        throw new Error(`Unsupported Temporal calendar id: ${temporalId}`);
+    }
+    return gmtId;
+}

package/dist/internal/calendarValueOfDate.d.ts

@@ -0,0 +1,22 @@
+import type { CalendarSystem } from "../types/index.js";
+/**
+ * Determine which CalendarSystem a GMT PlainDate string is expressed in: `"gregorian"` for a
+ * bare (non-annotated) string, the tagged CalendarSystem for a calendar-annotated string (as
+ * produced by `convertDateToCalendar`), or `null` when the annotation names an unrecognized
+ * calendar identifier.
+ *
+ * Does not itself validate overall shape or field values — pair with `parseCalendarDateValue`
+ * (which throws on invalid input) for full validation. Callers are expected to have already
+ * confirmed `value` is valid (e.g. via `isValidCalendarDate`) before relying on this.
+ *
+ * Part of E5 (issue #78)'s calendar-aware `plain/` gate — see the E5 decisions of record for
+ * why calendar-system awareness is confined to `plain/` `PlainDate` values (D1).
+ */
+export declare function calendarSystemOfDateValue(value: string): CalendarSystem | null;
+/**
+ * N-ary generalization of `calendarSystemOfDateValue` for list-form functions
+ * (`mergeIntervalsDate`, `intervalXorAllDate`, `intervalSplitAtDate`'s `points`): returns the
+ * shared CalendarSystem when every value carries the same tag, or `null` on any mismatch or
+ * unrecognized identifier. An empty list is treated as `"gregorian"` (the identity/no-op case).
+ */
+export declare function calendarOfAllDateValues(values: readonly string[]): CalendarSystem | null;

package/dist/internal/calendarValueOfDate.js

@@ -0,0 +1,41 @@
+import { calendarDate } from "../regex/index.js";
+import { isCalendarSystem } from "./calendarSystemIds.js";
+/**
+ * Determine which CalendarSystem a GMT PlainDate string is expressed in: `"gregorian"` for a
+ * bare (non-annotated) string, the tagged CalendarSystem for a calendar-annotated string (as
+ * produced by `convertDateToCalendar`), or `null` when the annotation names an unrecognized
+ * calendar identifier.
+ *
+ * Does not itself validate overall shape or field values — pair with `parseCalendarDateValue`
+ * (which throws on invalid input) for full validation. Callers are expected to have already
+ * confirmed `value` is valid (e.g. via `isValidCalendarDate`) before relying on this.
+ *
+ * Part of E5 (issue #78)'s calendar-aware `plain/` gate — see the E5 decisions of record for
+ * why calendar-system awareness is confined to `plain/` `PlainDate` values (D1).
+ */
+export function calendarSystemOfDateValue(value) {
+    const match = calendarDate.exec(value);
+    if (!match) {
+        return "gregorian";
+    }
+    const [, , , , calendarId] = match;
+    return isCalendarSystem(calendarId) ? calendarId : null;
+}
+/**
+ * N-ary generalization of `calendarSystemOfDateValue` for list-form functions
+ * (`mergeIntervalsDate`, `intervalXorAllDate`, `intervalSplitAtDate`'s `points`): returns the
+ * shared CalendarSystem when every value carries the same tag, or `null` on any mismatch or
+ * unrecognized identifier. An empty list is treated as `"gregorian"` (the identity/no-op case).
+ */
+export function calendarOfAllDateValues(values) {
+    if (values.length === 0) {
+        return "gregorian";
+    }
+    const first = calendarSystemOfDateValue(values[0]);
+    if (!first) {
+        return null;
+    }
+    return values.every((value) => calendarSystemOfDateValue(value) === first)
+        ? first
+        : null;
+}

package/dist/internal/calendarValueOfZoned.d.ts

@@ -0,0 +1,38 @@
+import type { CalendarSystem } from "../types/index.js";
+/**
+ * Determine which CalendarSystem a GMT ZonedDateTime string is expressed in: `"gregorian"` for a
+ * bare (non-annotated) ISO zoned string, the tagged CalendarSystem for a GMT calendar-annotated
+ * zoned string (as produced by `convertZonedToCalendar`), or `null` when the annotation names an
+ * unrecognized calendar identifier.
+ *
+ * Kept as its own file rather than an overload of `calendarValueOfDate.ts` because the two differ
+ * on both axes that matter: the regex (zoned carries a time, an offset and a `[timeZone]`
+ * segment) and the non-matching fallback. `calendarSystemOfDateValue` reports `"gregorian"` for
+ * ANY non-match, which is safe there because `plain/`'s only annotated shape is the one its regex
+ * accepts. In `zoned/` a non-matching string may still carry `[u-ca=...]` — Temporal's own
+ * RFC 9557 ordering, or a wrong-ordered GMT string — and calling either of those `"gregorian"`
+ * would hand a caller a Gregorian answer for a string that visibly asked for something else. Those
+ * fail closed with `null` instead.
+ *
+ * Does not itself validate overall shape or field values — pair with `parseCalendarZonedValue`
+ * (which throws on invalid input) for full validation. Callers are expected to have already
+ * confirmed `value` is valid (e.g. via `isValidCalendarZonedDateTime`) before relying on this.
+ *
+ * Part of E7 (issue #152)'s calendar-aware `zoned/` gate.
+ */
+export declare function calendarSystemOfZonedValue(value: string): CalendarSystem | null;
+/**
+ * N-ary generalization of `calendarSystemOfZonedValue` for list-form functions
+ * (`mergeIntervalsZoned`, `intervalXorAllZoned`, `intervalSplitAtZoned`'s `points`, and the
+ * four-endpoint pairwise set operations): returns the shared CalendarSystem when every value
+ * carries the same tag, or `null` on any mismatch or unrecognized identifier. An empty list is
+ * treated as `"gregorian"` (the identity/no-op case).
+ *
+ * This is E7's D4-zoned reject gate for the eight value-returning interval set operations. A
+ * "winning endpoint's tag survives" policy was considered and rejected: four of the eight return
+ * ARRAYS, so a per-element copied tag would produce a result set whose members disagree about
+ * which calendar they are in — unreadable as a set. `intervalUnionZoned`'s existing "winning
+ * endpoint's time zone wins" behavior is not precedent for this; that is about the zone, which is
+ * a property of the surviving point, not about the calendar, which is a property of the answer.
+ */
+export declare function calendarOfAllZonedValues(values: readonly string[]): CalendarSystem | null;

package/dist/internal/calendarValueOfZoned.js

@@ -0,0 +1,58 @@
+import { calendarZonedDateTime } from "../regex/index.js";
+import { isCalendarSystem } from "./calendarSystemIds.js";
+import { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+/**
+ * Determine which CalendarSystem a GMT ZonedDateTime string is expressed in: `"gregorian"` for a
+ * bare (non-annotated) ISO zoned string, the tagged CalendarSystem for a GMT calendar-annotated
+ * zoned string (as produced by `convertZonedToCalendar`), or `null` when the annotation names an
+ * unrecognized calendar identifier.
+ *
+ * Kept as its own file rather than an overload of `calendarValueOfDate.ts` because the two differ
+ * on both axes that matter: the regex (zoned carries a time, an offset and a `[timeZone]`
+ * segment) and the non-matching fallback. `calendarSystemOfDateValue` reports `"gregorian"` for
+ * ANY non-match, which is safe there because `plain/`'s only annotated shape is the one its regex
+ * accepts. In `zoned/` a non-matching string may still carry `[u-ca=...]` — Temporal's own
+ * RFC 9557 ordering, or a wrong-ordered GMT string — and calling either of those `"gregorian"`
+ * would hand a caller a Gregorian answer for a string that visibly asked for something else. Those
+ * fail closed with `null` instead.
+ *
+ * Does not itself validate overall shape or field values — pair with `parseCalendarZonedValue`
+ * (which throws on invalid input) for full validation. Callers are expected to have already
+ * confirmed `value` is valid (e.g. via `isValidCalendarZonedDateTime`) before relying on this.
+ *
+ * Part of E7 (issue #152)'s calendar-aware `zoned/` gate.
+ */
+export function calendarSystemOfZonedValue(value) {
+    const match = calendarZonedDateTime.exec(value);
+    if (!match) {
+        return hasCalendarAnnotation(value) ? null : "gregorian";
+    }
+    const [, , , , , , calendarId] = match;
+    return isCalendarSystem(calendarId) ? calendarId : null;
+}
+/**
+ * N-ary generalization of `calendarSystemOfZonedValue` for list-form functions
+ * (`mergeIntervalsZoned`, `intervalXorAllZoned`, `intervalSplitAtZoned`'s `points`, and the
+ * four-endpoint pairwise set operations): returns the shared CalendarSystem when every value
+ * carries the same tag, or `null` on any mismatch or unrecognized identifier. An empty list is
+ * treated as `"gregorian"` (the identity/no-op case).
+ *
+ * This is E7's D4-zoned reject gate for the eight value-returning interval set operations. A
+ * "winning endpoint's tag survives" policy was considered and rejected: four of the eight return
+ * ARRAYS, so a per-element copied tag would produce a result set whose members disagree about
+ * which calendar they are in — unreadable as a set. `intervalUnionZoned`'s existing "winning
+ * endpoint's time zone wins" behavior is not precedent for this; that is about the zone, which is
+ * a property of the surviving point, not about the calendar, which is a property of the answer.
+ */
+export function calendarOfAllZonedValues(values) {
+    if (values.length === 0) {
+        return "gregorian";
+    }
+    const first = calendarSystemOfZonedValue(values[0]);
+    if (!first) {
+        return null;
+    }
+    return values.every((value) => calendarSystemOfZonedValue(value) === first)
+        ? first
+        : null;
+}

package/dist/internal/calendarZonedPairPolicy.d.ts

@@ -0,0 +1,31 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { CalendarSystem } from "../types/index.js";
+export interface CalendarZonedPair {
+    calendar: CalendarSystem;
+    a: Temporal.ZonedDateTime;
+    b: Temporal.ZonedDateTime;
+}
+/**
+ * Parse two GMT ZonedDateTime values for calendar-unit arithmetic (diff, count, length,
+ * split-by-unit): measure in the endpoints' shared calendar when both match, fall back to
+ * Gregorian/ISO otherwise, rather than rejecting outright. The zoned sibling of
+ * `calendarDatePairPolicy.ts`'s `parseCalendarDatePairForArithmetic` (E5 decision D5).
+ *
+ * The fallback is MORE load-bearing here than in `plain/`, not less.
+ * `Temporal.PlainDate.prototype.until` throws across mismatched calendars only for date units;
+ * `Temporal.ZonedDateTime.prototype.until` throws for EVERY `largestUnit` — verified, including
+ * `"hour"` and `"nanosecond"`. Without this policy, `diffZoned(hebrewValue, islamicValue,
+ * "hours")` would return `null` for a question that has nothing to do with either calendar.
+ *
+ * **Consume the returned `a`/`b`, never the values you parsed them from.** The returned operands
+ * are already normalized to the resolved calendar, and every downstream use — including a
+ * `Temporal.Duration.prototype.total` `relativeTo` anchor — has to be the normalized one. Feeding
+ * a raw calendar-tagged operand to `relativeTo` while measuring in ISO does NOT throw; it returns
+ * a plausible-looking wrong number (verified: 12.586… where the correct ISO answer is 12.5666…
+ * and the correct Hebrew answer is 13), which no sanity check would catch.
+ *
+ * Throws if either value fails to parse as a valid GMT ZonedDateTime string — callers are
+ * expected to have already validated both values (e.g. via `isValidCalendarZonedDateTime`) before
+ * calling this, consistent with GMT's existing gate-then-parse-inside-try structure.
+ */
+export declare function parseCalendarZonedPairForArithmetic(aValue: string, bValue: string): CalendarZonedPair;

package/dist/internal/calendarZonedPairPolicy.js

@@ -0,0 +1,39 @@
+import { calendarSystemOfZonedValue } from "./calendarValueOfZoned.js";
+import { parseCalendarZonedValue } from "./calendarZonedString.js";
+/**
+ * Parse two GMT ZonedDateTime values for calendar-unit arithmetic (diff, count, length,
+ * split-by-unit): measure in the endpoints' shared calendar when both match, fall back to
+ * Gregorian/ISO otherwise, rather than rejecting outright. The zoned sibling of
+ * `calendarDatePairPolicy.ts`'s `parseCalendarDatePairForArithmetic` (E5 decision D5).
+ *
+ * The fallback is MORE load-bearing here than in `plain/`, not less.
+ * `Temporal.PlainDate.prototype.until` throws across mismatched calendars only for date units;
+ * `Temporal.ZonedDateTime.prototype.until` throws for EVERY `largestUnit` — verified, including
+ * `"hour"` and `"nanosecond"`. Without this policy, `diffZoned(hebrewValue, islamicValue,
+ * "hours")` would return `null` for a question that has nothing to do with either calendar.
+ *
+ * **Consume the returned `a`/`b`, never the values you parsed them from.** The returned operands
+ * are already normalized to the resolved calendar, and every downstream use — including a
+ * `Temporal.Duration.prototype.total` `relativeTo` anchor — has to be the normalized one. Feeding
+ * a raw calendar-tagged operand to `relativeTo` while measuring in ISO does NOT throw; it returns
+ * a plausible-looking wrong number (verified: 12.586… where the correct ISO answer is 12.5666…
+ * and the correct Hebrew answer is 13), which no sanity check would catch.
+ *
+ * Throws if either value fails to parse as a valid GMT ZonedDateTime string — callers are
+ * expected to have already validated both values (e.g. via `isValidCalendarZonedDateTime`) before
+ * calling this, consistent with GMT's existing gate-then-parse-inside-try structure.
+ */
+export function parseCalendarZonedPairForArithmetic(aValue, bValue) {
+    const calendarA = calendarSystemOfZonedValue(aValue);
+    const calendarB = calendarSystemOfZonedValue(bValue);
+    const a = parseCalendarZonedValue(aValue);
+    const b = parseCalendarZonedValue(bValue);
+    if (calendarA && calendarB && calendarA === calendarB) {
+        return { calendar: calendarA, a, b };
+    }
+    return {
+        calendar: "gregorian",
+        a: a.withCalendar("iso8601"),
+        b: b.withCalendar("iso8601"),
+    };
+}

package/dist/internal/calendarZonedString.d.ts

@@ -0,0 +1,77 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { CalendarSystem, Disambiguation, Offset } from "../types/index.js";
+/**
+ * Parse a bare ISO ZonedDateTime string or a GMT calendar-annotated ZonedDateTime string
+ * (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`, calendar-native fields, not
+ * Temporal's own ISO-digit `[u-ca=...]` annotation convention) into a Temporal.ZonedDateTime.
+ * Throws on invalid input — callers wrap this in try-catch per GMT's sentinel-return contract.
+ *
+ * The regex only proves shape; the real construction and validation happen in Temporal —
+ * `parseCalendarDateValue` (`Temporal.PlainDate.from(fields, { overflow: "reject" })`) for the
+ * calendar-native date half, and `Temporal.ZonedDateTime.from` for the recomposed ISO string
+ * (which rejects unknown zones, stale offsets, and out-of-range times). See
+ * `context/coding-standards.md`'s scoped manual-string-parsing exception, rule 2.
+ *
+ * ---------------------------------------------------------------------------------------
+ * WHY THE DATE HALF IS FIELD-DECOMPOSED AND HANDED BACK TO TEMPORAL AS ISO DIGITS
+ * ---------------------------------------------------------------------------------------
+ * The `;era=` suffix can NEVER round-trip through Temporal, at any segment ordering, because it
+ * is not valid RFC 9557 at all — `Temporal.PlainDate.from("0006-10-03[u-ca=japanese;era=reiwa]")`
+ * throws `RangeError: invalid RFC 9557 string`, and so does every `Temporal.*.from` entry point
+ * given the same suffix. Era-bearing calendars ("japanese", "ethiopic") therefore have to be
+ * decomposed into `{ era, eraYear, month, day }` and constructed field-wise, which is exactly
+ * what `parseCalendarDateValue` already does for the plain case — this function delegates the
+ * whole date half to it rather than reimplementing era handling, the Ethiopic-family "ethioaa"
+ * carrier routing, or the GMT-to-Temporal calendar-id mapping.
+ *
+ * The date half then travels back through Temporal as plain ISO digits
+ * (`.withCalendar("iso8601").toString()`), so `Temporal.ZonedDateTime.from` resolves the zone,
+ * offset and DST against a string it can actually parse. The calendar is re-attached to the
+ * RESULT via `.withCalendar(...)`, which keeps downstream `.add`/`.until`/`.round` calendar-aware
+ * (verified: `withTimeZone`/`round`/`with`/`startOfDay`/`toPlainDate` all preserve the tag).
+ *
+ * `isLeapSecond` runs before anything else, exactly as `isValidZonedDateTime` does: verified that
+ * `Temporal.ZonedDateTime.from("2024-06-30T23:59:60+00:00[UTC]")` silently CLAMPS to `:59` rather
+ * than throwing, so this guard is load-bearing rather than redundant.
+ *
+ * @param value bare ISO zoned datetime string, or GMT calendar-annotated zoned datetime string
+ * @param options optional Temporal `disambiguation`/`offset`, passed through to
+ *   `Temporal.ZonedDateTime.from` so a caller's own DST/offset policy still applies
+ * @returns Temporal.ZonedDateTime carrying the annotated calendar (or `iso8601` when bare)
+ */
+export declare function parseCalendarZonedValue(value: string, options?: {
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): Temporal.ZonedDateTime;
+/**
+ * Format a Temporal.ZonedDateTime as GMT's calendar-annotated (or bare ISO) zoned string in a
+ * known target CalendarSystem — the zoned companion to `formatDateInCalendar`, and the ONLY
+ * writer of the calendar-annotated zoned grammar anywhere in GMT.
+ *
+ * Never call `zdt.toString()` on a calendared value and never compose
+ * `` `${zdt.toPlainDateTime()}[${zdt.timeZoneId}]` `` on one either: both emit Temporal's
+ * `[timeZone][u-ca=...]` RFC 9557 ordering (verified: a Hebrew-calendared
+ * `.toPlainDateTime().toString()` yields `"2024-03-25T14:30:00[u-ca=hebrew]"`), which is exactly
+ * the ordering GMT rejects because reading it back misparses the digits as ISO. Route every
+ * calendar-annotated zoned output through this function instead.
+ *
+ * Every field is RE-DERIVED from the actual `zdt` result and nothing but the IANA zone id is
+ * copied (E7's D7-zoned, extending E5's D7): a single calendar-unit add can move the era AND the
+ * UTC offset at once — verified, Japanese Heisei 31-04-05 in `Africa/Casablanca` `+1 month` lands
+ * on Reiwa 1-05-05 inside a DST fold — so a tag or offset copied from the input would describe a
+ * moment that no longer exists.
+ *
+ * Unlike `formatDateInCalendar`, this does NOT require `zdt` to already carry `calendar`'s own
+ * Temporal calendar id — it re-calendars the value itself before reading the date fields. That is
+ * deliberate: several `zoned/interval/*` functions synthesize boundary points via
+ * `Temporal.Instant.prototype.toZonedDateTimeISO`, which always returns an `iso8601`-calendared
+ * value. Re-calendaring here means a synthesized boundary can never silently emit a bare ISO
+ * string into an otherwise calendar-tagged result set — one class of bug removed by construction
+ * rather than by remembering to re-attach the tag at every synthesis site. The instant, wall time
+ * and zone are untouched; only which calendar the date fields resolve through changes.
+ *
+ * @param zdt Temporal.ZonedDateTime to format
+ * @param calendar the CalendarSystem to express `zdt`'s date fields in
+ * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") zoned datetime string
+ */
+export declare function formatZonedInCalendar(zdt: Temporal.ZonedDateTime, calendar: CalendarSystem): string;

package/dist/internal/calendarZonedString.js

@@ -0,0 +1,120 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../plain/validate/isLeapSecond.js";
+import { calendarZonedDateTime } from "../regex/index.js";
+import { parseCalendarDateValue } from "./calendarDateString.js";
+import { temporalCalendarIds } from "./calendarSystemIds.js";
+import { isEthiopicFamilyCalendar } from "./ethiopicFamilyCalendar.js";
+import { calendarDateStringParts } from "./formatDateInCalendar.js";
+import { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+/**
+ * Parse a bare ISO ZonedDateTime string or a GMT calendar-annotated ZonedDateTime string
+ * (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`, calendar-native fields, not
+ * Temporal's own ISO-digit `[u-ca=...]` annotation convention) into a Temporal.ZonedDateTime.
+ * Throws on invalid input — callers wrap this in try-catch per GMT's sentinel-return contract.
+ *
+ * The regex only proves shape; the real construction and validation happen in Temporal —
+ * `parseCalendarDateValue` (`Temporal.PlainDate.from(fields, { overflow: "reject" })`) for the
+ * calendar-native date half, and `Temporal.ZonedDateTime.from` for the recomposed ISO string
+ * (which rejects unknown zones, stale offsets, and out-of-range times). See
+ * `context/coding-standards.md`'s scoped manual-string-parsing exception, rule 2.
+ *
+ * ---------------------------------------------------------------------------------------
+ * WHY THE DATE HALF IS FIELD-DECOMPOSED AND HANDED BACK TO TEMPORAL AS ISO DIGITS
+ * ---------------------------------------------------------------------------------------
+ * The `;era=` suffix can NEVER round-trip through Temporal, at any segment ordering, because it
+ * is not valid RFC 9557 at all — `Temporal.PlainDate.from("0006-10-03[u-ca=japanese;era=reiwa]")`
+ * throws `RangeError: invalid RFC 9557 string`, and so does every `Temporal.*.from` entry point
+ * given the same suffix. Era-bearing calendars ("japanese", "ethiopic") therefore have to be
+ * decomposed into `{ era, eraYear, month, day }` and constructed field-wise, which is exactly
+ * what `parseCalendarDateValue` already does for the plain case — this function delegates the
+ * whole date half to it rather than reimplementing era handling, the Ethiopic-family "ethioaa"
+ * carrier routing, or the GMT-to-Temporal calendar-id mapping.
+ *
+ * The date half then travels back through Temporal as plain ISO digits
+ * (`.withCalendar("iso8601").toString()`), so `Temporal.ZonedDateTime.from` resolves the zone,
+ * offset and DST against a string it can actually parse. The calendar is re-attached to the
+ * RESULT via `.withCalendar(...)`, which keeps downstream `.add`/`.until`/`.round` calendar-aware
+ * (verified: `withTimeZone`/`round`/`with`/`startOfDay`/`toPlainDate` all preserve the tag).
+ *
+ * `isLeapSecond` runs before anything else, exactly as `isValidZonedDateTime` does: verified that
+ * `Temporal.ZonedDateTime.from("2024-06-30T23:59:60+00:00[UTC]")` silently CLAMPS to `:59` rather
+ * than throwing, so this guard is load-bearing rather than redundant.
+ *
+ * @param value bare ISO zoned datetime string, or GMT calendar-annotated zoned datetime string
+ * @param options optional Temporal `disambiguation`/`offset`, passed through to
+ *   `Temporal.ZonedDateTime.from` so a caller's own DST/offset policy still applies
+ * @returns Temporal.ZonedDateTime carrying the annotated calendar (or `iso8601` when bare)
+ */
+export function parseCalendarZonedValue(value, options) {
+    if (isLeapSecond(value)) {
+        throw new RangeError(`Leap seconds are not supported: ${value}`);
+    }
+    const match = calendarZonedDateTime.exec(value);
+    if (!match) {
+        // Either Temporal's own `[timeZone][u-ca=...]` ordering or a wrong-ordered GMT string. Both
+        // are rejected rather than re-parsed: the former is not GMT's contract (E5 decision D1), and
+        // the latter is the ~3760-year silent-misparse hazard documented in
+        // `regex/calendar-zoned-date-time.ts`. Only a genuinely un-annotated string falls through.
+        if (hasCalendarAnnotation(value)) {
+            throw new RangeError(`Not a valid GMT ZonedDateTime string: ${value}`);
+        }
+        const bare = Temporal.ZonedDateTime.from(value, options);
+        if (bare.timeZoneId.length === 0) {
+            throw new RangeError(`Missing time zone: ${value}`);
+        }
+        return bare;
+    }
+    const [, year, month, day, time, offset, calendarId, era, timeZone] = match;
+    const eraSuffix = era ? `;era=${era}` : "";
+    const date = parseCalendarDateValue(`${year}-${month}-${day}[u-ca=${calendarId}${eraSuffix}]`);
+    const isoDate = date.withCalendar("iso8601").toString();
+    const zoned = Temporal.ZonedDateTime.from(`${isoDate}T${time}${offset ?? ""}[${timeZone}]`, options);
+    // Re-attach the calendar the date half resolved to — `date.calendarId` rather than the string's
+    // own tag, so the Ethiopic family lands on its "ethioaa" carrier and GMT ids that differ from
+    // Temporal's ("islamic-tabular" -> "islamic-tbla") map through exactly once, in one place.
+    return zoned.withCalendar(date.calendarId);
+}
+/**
+ * Format a Temporal.ZonedDateTime as GMT's calendar-annotated (or bare ISO) zoned string in a
+ * known target CalendarSystem — the zoned companion to `formatDateInCalendar`, and the ONLY
+ * writer of the calendar-annotated zoned grammar anywhere in GMT.
+ *
+ * Never call `zdt.toString()` on a calendared value and never compose
+ * `` `${zdt.toPlainDateTime()}[${zdt.timeZoneId}]` `` on one either: both emit Temporal's
+ * `[timeZone][u-ca=...]` RFC 9557 ordering (verified: a Hebrew-calendared
+ * `.toPlainDateTime().toString()` yields `"2024-03-25T14:30:00[u-ca=hebrew]"`), which is exactly
+ * the ordering GMT rejects because reading it back misparses the digits as ISO. Route every
+ * calendar-annotated zoned output through this function instead.
+ *
+ * Every field is RE-DERIVED from the actual `zdt` result and nothing but the IANA zone id is
+ * copied (E7's D7-zoned, extending E5's D7): a single calendar-unit add can move the era AND the
+ * UTC offset at once — verified, Japanese Heisei 31-04-05 in `Africa/Casablanca` `+1 month` lands
+ * on Reiwa 1-05-05 inside a DST fold — so a tag or offset copied from the input would describe a
+ * moment that no longer exists.
+ *
+ * Unlike `formatDateInCalendar`, this does NOT require `zdt` to already carry `calendar`'s own
+ * Temporal calendar id — it re-calendars the value itself before reading the date fields. That is
+ * deliberate: several `zoned/interval/*` functions synthesize boundary points via
+ * `Temporal.Instant.prototype.toZonedDateTimeISO`, which always returns an `iso8601`-calendared
+ * value. Re-calendaring here means a synthesized boundary can never silently emit a bare ISO
+ * string into an otherwise calendar-tagged result set — one class of bug removed by construction
+ * rather than by remembering to re-attach the tag at every synthesis site. The instant, wall time
+ * and zone are untouched; only which calendar the date fields resolve through changes.
+ *
+ * @param zdt Temporal.ZonedDateTime to format
+ * @param calendar the CalendarSystem to express `zdt`'s date fields in
+ * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") zoned datetime string
+ */
+export function formatZonedInCalendar(zdt, calendar) {
+    if (calendar === "gregorian") {
+        return zdt.withCalendar("iso8601").toString();
+    }
+    // The whole Ethiopic family computes through "ethioaa" rather than Temporal's own
+    // "ethiopic"/"coptic" ids, which throw under ICU >= 78 — see internal/ethiopicFamilyCalendar.ts.
+    const temporalCalendarId = isEthiopicFamilyCalendar(calendar)
+        ? "ethioaa"
+        : temporalCalendarIds[calendar];
+    const { date, annotation } = calendarDateStringParts(zdt.withCalendar(temporalCalendarId).toPlainDate(), calendar);
+    const time = zdt.toPlainTime().toString();
+    return `${date}T${time}${zdt.offset}${annotation}[${zdt.timeZoneId}]`;
+}

package/dist/internal/cycleFieldValue.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function cycleFieldValue(current: number, amount: number, bounds: {
+    min: number;
+    max: number;
+} | null, round: boolean): number;