@northguild/gmt 1.14.2 → 1.16.0

package/dist/internal/businessCalendar.js

@@ -0,0 +1,230 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../plain/validate/isValidDate.js";
+import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+const ISO_WEEKDAYS = 7;
+/**
+ * The weekend GMT assumed before calendars existed: Saturday and Sunday, no holidays. It is
+ * what `isBusinessDay`, `addBusinessDays` and `subtractBusinessDays` use when no calendar is
+ * passed, so their shipped behaviour is unchanged.
+ */
+const DEFAULT_WEEKEND = [6, 7];
+/**
+ * Calendar days a single business-day walk may step before giving up — roughly 547 years, far
+ * past any real schedule. A walk that runs out returns the sentinel, never a partial answer.
+ */
+export const MAX_BUSINESS_DAY_STEPS = 200_000;
+export const DEFAULT_BUSINESS_CALENDAR = {
+    weekend: new Set(DEFAULT_WEEKEND),
+    holidays: new Set(),
+};
+function parseWeekend(weekend) {
+    if (!Array.isArray(weekend)) {
+        return null;
+    }
+    const everyDayInRange = weekend.every((day) => Number.isInteger(day) && day >= 1 && day <= ISO_WEEKDAYS);
+    if (!everyDayInRange) {
+        return null;
+    }
+    const days = new Set(weekend);
+    // All seven weekdays closed leaves no business day, so every walk would run to its cap.
+    return days.size < ISO_WEEKDAYS ? days : null;
+}
+function parseHolidays(holidays) {
+    if (!Array.isArray(holidays)) {
+        return null;
+    }
+    const dates = new Set();
+    try {
+        for (const holiday of holidays) {
+            if (typeof holiday !== "string" || !isValidDate(holiday)) {
+                return null;
+            }
+            // Normalise through Temporal so a holiday and a walked date compare as the same string.
+            dates.add(Temporal.PlainDate.from(holiday).toString());
+        }
+    }
+    catch {
+        return null;
+    }
+    return dates;
+}
+/**
+ * Reduce a caller-supplied `BusinessCalendar` to its lookups, or `null` when it is not one.
+ *
+ * `undefined` is rejected here; `resolveBusinessCalendar` is the entry point that treats an
+ * absent calendar as the default Saturday–Sunday week.
+ */
+export function parseBusinessCalendar(calendar) {
+    if (typeof calendar !== "object" ||
+        calendar === null ||
+        Array.isArray(calendar)) {
+        return null;
+    }
+    const { weekend, holidays, timeZone } = calendar;
+    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    const weekendDays = parseWeekend(weekend);
+    const holidayDates = parseHolidays(holidays);
+    if (weekendDays === null || holidayDates === null) {
+        return null;
+    }
+    return { weekend: weekendDays, holidays: holidayDates };
+}
+/**
+ * Resolve an optional calendar: absent means the default Saturday–Sunday week with no
+ * holidays, anything else must be a valid `BusinessCalendar` or this returns `null`.
+ */
+export function resolveBusinessCalendar(calendar) {
+    return calendar === undefined
+        ? DEFAULT_BUSINESS_CALENDAR
+        : parseBusinessCalendar(calendar);
+}
+/** True when `date` is neither a weekend day nor a holiday in `calendar`. */
+export function isBusinessDate(date, calendar) {
+    return (!calendar.weekend.has(date.dayOfWeek) &&
+        !calendar.holidays.has(date.toString()));
+}
+/*
+ * The walks step whole days as integers — days since 1970-01-01 — rather than PlainDates: a walk
+ * to the 200,000-day cap through the polyfill's `add`, `dayOfWeek` and `toString` took seconds.
+ * Only the date a walk returns is built as a Temporal object.
+ */
+/**
+ * TC39 `ISODateWithinLimits`: -271821-04-19 and +275760-09-13, counted in days from 1970-01-01,
+ * are the first and last dates a PlainDate holds.
+ */
+const MIN_EPOCH_DAY = -100_000_001;
+const MAX_EPOCH_DAY = 100_000_000;
+/** 1970-01-01 was a Thursday, ISO weekday 4. */
+const EPOCH_WEEKDAY_OFFSET = 3;
+/** Days in a 400-year cycle of the proleptic Gregorian calendar. */
+const DAYS_PER_400_YEARS = 146_097;
+/** Days from 0000-03-01, the start of a March-based year, to 1970-01-01. */
+const DAYS_FROM_MARCH_0000_TO_EPOCH = 719_468;
+/** TC39 `PadISOYear`: years 0–9999 print with four digits, any other with a sign and six. */
+const MAX_FOUR_DIGIT_YEAR = 9999;
+/**
+ * Days from 1970-01-01 to an ISO date, in the proleptic Gregorian calendar of ECMA-262 §21.4.1
+ * that Temporal's ISO calendar extends. Years run from March so the leap day ends each one.
+ */
+function epochDayOf(year, month, day) {
+    const marchYear = month <= 2 ? year - 1 : year;
+    const cycle = Math.floor(marchYear / 400);
+    const yearOfCycle = marchYear - cycle * 400;
+    const dayOfYear = Math.floor((153 * ((month + 9) % 12) + 2) / 5) + day - 1;
+    const dayOfCycle = yearOfCycle * 365 +
+        Math.floor(yearOfCycle / 4) -
+        Math.floor(yearOfCycle / 100) +
+        dayOfYear;
+    return (cycle * DAYS_PER_400_YEARS + dayOfCycle - DAYS_FROM_MARCH_0000_TO_EPOCH);
+}
+/** The ISO year, month and day `epochDay` days from 1970-01-01 — `epochDayOf` inverted. */
+function isoFieldsOf(epochDay) {
+    const shifted = epochDay + DAYS_FROM_MARCH_0000_TO_EPOCH;
+    const cycle = Math.floor(shifted / DAYS_PER_400_YEARS);
+    const dayOfCycle = shifted - cycle * DAYS_PER_400_YEARS;
+    // Remove the leap days of every 4th, 100th and 400th year before dividing into 365-day years.
+    const yearOfCycle = Math.floor((dayOfCycle -
+        Math.floor(dayOfCycle / 1460) +
+        Math.floor(dayOfCycle / 36_524) -
+        Math.floor(dayOfCycle / (DAYS_PER_400_YEARS - 1))) /
+        365);
+    const dayOfYear = dayOfCycle -
+        (365 * yearOfCycle +
+            Math.floor(yearOfCycle / 4) -
+            Math.floor(yearOfCycle / 100));
+    const monthFromMarch = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthFromMarch + 2) / 5) + 1;
+    const month = monthFromMarch < 10 ? monthFromMarch + 3 : monthFromMarch - 9;
+    const year = yearOfCycle + cycle * 400 + (month <= 2 ? 1 : 0);
+    return [year, month, day];
+}
+/** `Temporal.PlainDate#toString` for an ISO date, which is how `holidays` stores its dates. */
+function isoDateString(epochDay) {
+    const [year, month, day] = isoFieldsOf(epochDay);
+    const yearText = year < 0 || year > MAX_FOUR_DIGIT_YEAR
+        ? `${year < 0 ? "-" : "+"}${String(Math.abs(year)).padStart(6, "0")}`
+        : String(year).padStart(4, "0");
+    return `${yearText}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+/**
+ * Days from 1970-01-01 to `date`, an ISO-calendar date. Any other calendar throws a
+ * `RangeError`, which callers turn into their sentinel: its year, month and day are not ISO
+ * fields, so the arithmetic below would silently walk from the wrong day.
+ */
+function epochDayOfDate(date) {
+    if (date.calendarId !== "iso8601") {
+        throw new RangeError("business-day walks take an ISO-calendar date");
+    }
+    return epochDayOf(date.year, date.month, date.day);
+}
+function isBusinessEpochDay(epochDay, calendar) {
+    // `%` keeps the dividend's sign, so a date before 1970 needs the second `+ ISO_WEEKDAYS`.
+    const weekday = ((((epochDay + EPOCH_WEEKDAY_OFFSET) % ISO_WEEKDAYS) + ISO_WEEKDAYS) %
+        ISO_WEEKDAYS) +
+        1;
+    return (!calendar.weekend.has(weekday) &&
+        (calendar.holidays.size === 0 ||
+            !calendar.holidays.has(isoDateString(epochDay))));
+}
+/** One day on from `epochDay`, throwing the `RangeError` `PlainDate#add` throws past a limit. */
+function nextEpochDay(epochDay, direction) {
+    const next = epochDay + direction;
+    if (next < MIN_EPOCH_DAY || next > MAX_EPOCH_DAY) {
+        throw new RangeError("date/time value is outside of supported range");
+    }
+    return next;
+}
+/** The walked-to date; `date` itself when the walk never moved. */
+function dateAt(date, startEpochDay, epochDay) {
+    if (epochDay === startEpochDay) {
+        return date;
+    }
+    const [year, month, day] = isoFieldsOf(epochDay);
+    return new Temporal.PlainDate(year, month, day);
+}
+/**
+ * The first business day at or beyond `date`, walking in `direction`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. Returns `date` itself when it is
+ * already a business day, and `null` when the walk exceeds `MAX_BUSINESS_DAY_STEPS`. Throws a
+ * `RangeError` when the walk passes a Temporal range limit.
+ */
+export function businessDateFrom(date, direction, calendar) {
+    const start = epochDayOfDate(date);
+    let current = start;
+    // `step` counts calendar days moved, exactly as it does in `stepBusinessDates`, so both
+    // walks give up at the same distance — the 200,000 the public JSDoc quotes.
+    for (let step = 0; step < MAX_BUSINESS_DAY_STEPS; step++) {
+        if (isBusinessEpochDay(current, calendar)) {
+            return dateAt(date, start, current);
+        }
+        current = nextEpochDay(current, direction);
+    }
+    return isBusinessEpochDay(current, calendar)
+        ? dateAt(date, start, current)
+        : null;
+}
+/**
+ * Step `count` business days from `date` in `direction`, counting only days that are business
+ * days in `calendar`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. `count` is a non-negative whole
+ * number of business days. `date` itself is never counted, so a `count` of 0 returns `date`
+ * unchanged even when it is not a business day. Returns `null`
+ * when the walk exceeds `MAX_BUSINESS_DAY_STEPS`, and throws a `RangeError` when it passes a
+ * Temporal range limit.
+ */
+export function stepBusinessDates(date, direction, count, calendar) {
+    const start = epochDayOfDate(date);
+    let current = start;
+    let remaining = count;
+    for (let step = 0; step < MAX_BUSINESS_DAY_STEPS && remaining > 0; step++) {
+        current = nextEpochDay(current, direction);
+        if (isBusinessEpochDay(current, calendar)) {
+            remaining -= 1;
+        }
+    }
+    return remaining === 0 ? dateAt(date, start, current) : null;
+}

package/dist/internal/businessDayValues.d.ts

@@ -0,0 +1,20 @@
+import type { BusinessCalendar } from "../types/index.js";
+/**
+ * The shared body of `addBusinessDays` and `subtractBusinessDays`: validate, resolve the
+ * calendar, and walk `amount` working days from `value`.
+ *
+ * - `sign` is the direction a **positive** `amount` moves — `1` for adding, `-1` for
+ *   subtracting — so a negative `amount` walks the other way in both.
+ * - `calendar` is optional; absent means Saturday–Sunday with no holidays.
+ * - Returns `""` on an invalid date, a non-integer or out-of-range `amount`, an invalid
+ *   calendar, and when the walk runs past `MAX_BUSINESS_DAY_STEPS`.
+ */
+export declare function stepBusinessDaysValue(value: string, amount: number, sign: 1 | -1, calendar: BusinessCalendar | undefined): string;
+/**
+ * The shared body of `nextBusinessDay` and `previousBusinessDay`: the first working day
+ * **strictly** one business day away from `value`, in `direction`.
+ *
+ * Unlike `stepBusinessDaysValue`, `calendar` is required — these two assume no weekend, so an
+ * absent calendar is invalid input rather than the Saturday–Sunday default.
+ */
+export declare function neighbourBusinessDayValue(value: string, direction: 1 | -1, calendar: BusinessCalendar): string;

package/dist/internal/businessDayValues.js

@@ -0,0 +1,54 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseBusinessCalendar, resolveBusinessCalendar, stepBusinessDates, } from "./businessCalendar.js";
+import { isValidAmount } from "./isValidAmount.js";
+import { isValidDate } from "../plain/validate/isValidDate.js";
+/**
+ * The shared body of `addBusinessDays` and `subtractBusinessDays`: validate, resolve the
+ * calendar, and walk `amount` working days from `value`.
+ *
+ * - `sign` is the direction a **positive** `amount` moves — `1` for adding, `-1` for
+ *   subtracting — so a negative `amount` walks the other way in both.
+ * - `calendar` is optional; absent means Saturday–Sunday with no holidays.
+ * - Returns `""` on an invalid date, a non-integer or out-of-range `amount`, an invalid
+ *   calendar, and when the walk runs past `MAX_BUSINESS_DAY_STEPS`.
+ */
+export function stepBusinessDaysValue(value, amount, sign, calendar) {
+    const resolved = resolveBusinessCalendar(calendar);
+    if (!isValidDate(value) ||
+        !isValidAmount(amount) ||
+        !Number.isInteger(amount) ||
+        resolved === null) {
+        return "";
+    }
+    try {
+        if (amount === 0) {
+            return Temporal.PlainDate.from(value).toString();
+        }
+        const direction = amount > 0 ? sign : sign === 1 ? -1 : 1;
+        const result = stepBusinessDates(Temporal.PlainDate.from(value), direction, Math.abs(amount), resolved);
+        return result === null ? "" : result.toString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * The shared body of `nextBusinessDay` and `previousBusinessDay`: the first working day
+ * **strictly** one business day away from `value`, in `direction`.
+ *
+ * Unlike `stepBusinessDaysValue`, `calendar` is required — these two assume no weekend, so an
+ * absent calendar is invalid input rather than the Saturday–Sunday default.
+ */
+export function neighbourBusinessDayValue(value, direction, calendar) {
+    const resolved = parseBusinessCalendar(calendar);
+    if (!isValidDate(value) || resolved === null) {
+        return "";
+    }
+    try {
+        const result = stepBusinessDates(Temporal.PlainDate.from(value), direction, 1, resolved);
+        return result === null ? "" : result.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/internal/calendarDatePairPolicy.d.ts

@@ -7,19 +7,17 @@ export interface CalendarDatePair {
 }
 /**
  * Parse two GMT PlainDate 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.
+ * unit): both must name the same calendar, which the pair is measured in.
  *
- * E5 decision of record D5: unlike D4's value-returning interval set-operations (union,
- * intersection, difference, xor, split, divide, merge — which reject a mismatch via
- * `calendarOfAllDateValues` instead, since there's no principled output calendar to pick for a
- * *value* the caller reads back as a date), ordering and duration math both remain well-defined
- * across mismatched calendars: Temporal's own `compare` is calendar-independent, and falling
- * back to ISO for a genuinely mismatched pair is a reasonable, well-defined answer rather than
- * an arbitrary pick.
+ * Follows TC39 Temporal's `DifferenceTemporalPlainDate`: when `CalendarEquals` is false it throws
+ * a RangeError, for every `largestUnit`. Calendars are compared by their canonical id, so
+ * `ethiopic-amete-alem` and `ethioaa` agree, while `iso8601` and `gregory`, or `ethiopic` and
+ * `ethioaa`, do not. A bare ISO string names `iso8601`. Callers catch the throw and return their
+ * sentinel. (Before 1.16.0 the pair fell back to ISO; ordering-only functions still accept
+ * mixed calendars, because `Temporal.PlainDate.compare` has no calendar check.)
  *
- * Throws if either value fails to parse as a valid GMT PlainDate string — callers are expected
- * to have already validated both values (e.g. via `isValidCalendarDate`) before calling this,
- * consistent with GMT's existing gate-then-parse-inside-try structure.
+ * Throws if either value fails to parse as a valid GMT PlainDate string, or if the calendars
+ * differ — callers validate both values first (e.g. via `isValidCalendarDate`) and wrap this in
+ * try-catch, consistent with GMT's gate-then-parse-inside-try structure.
  */
 export declare function parseCalendarDatePairForArithmetic(aValue: string, bValue: string): CalendarDatePair;

package/dist/internal/calendarDatePairPolicy.js

@@ -2,32 +2,26 @@ import { parseCalendarDateValue } from "./calendarDateString.js";
 import { calendarSystemOfDateValue } from "./calendarValueOfDate.js";
 /**
  * Parse two GMT PlainDate 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.
+ * unit): both must name the same calendar, which the pair is measured in.
  *
- * E5 decision of record D5: unlike D4's value-returning interval set-operations (union,
- * intersection, difference, xor, split, divide, merge — which reject a mismatch via
- * `calendarOfAllDateValues` instead, since there's no principled output calendar to pick for a
- * *value* the caller reads back as a date), ordering and duration math both remain well-defined
- * across mismatched calendars: Temporal's own `compare` is calendar-independent, and falling
- * back to ISO for a genuinely mismatched pair is a reasonable, well-defined answer rather than
- * an arbitrary pick.
+ * Follows TC39 Temporal's `DifferenceTemporalPlainDate`: when `CalendarEquals` is false it throws
+ * a RangeError, for every `largestUnit`. Calendars are compared by their canonical id, so
+ * `ethiopic-amete-alem` and `ethioaa` agree, while `iso8601` and `gregory`, or `ethiopic` and
+ * `ethioaa`, do not. A bare ISO string names `iso8601`. Callers catch the throw and return their
+ * sentinel. (Before 1.16.0 the pair fell back to ISO; ordering-only functions still accept
+ * mixed calendars, because `Temporal.PlainDate.compare` has no calendar check.)
  *
- * Throws if either value fails to parse as a valid GMT PlainDate string — callers are expected
- * to have already validated both values (e.g. via `isValidCalendarDate`) before calling this,
- * consistent with GMT's existing gate-then-parse-inside-try structure.
+ * Throws if either value fails to parse as a valid GMT PlainDate string, or if the calendars
+ * differ — callers validate both values first (e.g. via `isValidCalendarDate`) and wrap this in
+ * try-catch, consistent with GMT's gate-then-parse-inside-try structure.
  */
 export function parseCalendarDatePairForArithmetic(aValue, bValue) {
     const calendarA = calendarSystemOfDateValue(aValue);
     const calendarB = calendarSystemOfDateValue(bValue);
     const a = parseCalendarDateValue(aValue);
     const b = parseCalendarDateValue(bValue);
-    if (calendarA && calendarB && calendarA === calendarB) {
-        return { calendar: calendarA, a, b };
+    if (!calendarA || calendarA !== calendarB) {
+        throw new RangeError(`Mismatched calendars: ${String(calendarA)} and ${String(calendarB)}`);
     }
-    return {
-        calendar: "gregorian",
-        a: a.withCalendar("iso8601"),
-        b: b.withCalendar("iso8601"),
-    };
+    return { calendar: calendarA, a, b };
 }

package/dist/internal/calendarDateString.d.ts

@@ -1,65 +1,39 @@
 import { Temporal } from "@js-temporal/polyfill";
 /**
- * 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 declare function parseCalendarDateValue(value: string): Temporal.PlainDate;
-/**
- * The two halves of GMT's calendar-annotated PlainDate string, kept separate so a zoned string
- * can splice its own time/offset between them: `<date>` is the calendar-native (or bare ISO)
- * `YYYY-MM-DD`, `<annotation>` is the `[u-ca=...]` tail (empty for the "iso8601" calendar).
- *
- * `formatCalendarDate` is `date + annotation`; `internal/calendarZonedString.ts`'s
- * `formatZonedInCalendar` is `date + "T" + time + offset + annotation + "[" + timeZone + "]"`,
- * since GMT's zoned grammar orders `[u-ca=...]` before `[timeZone]` (see
- * `regex/calendar-zoned-date-time.ts` for why). Splitting here rather than string-slicing
- * `formatCalendarDate`'s output on `"["` keeps the era/zero-padding logic in exactly one place.
+ * Second `60` in the time of day, before any `[`: `T`, `t` or space separator, extended or basic
+ * digits. Temporal's ParseISODateTime clamps it to `:59`; GMT's Plain date-time inputs reject it
+ * (`isValidDateTime`, a duration `relativeTo`). Unlike `regex/leap-second.ts`, no designator is
+ * required, because a Plain string has none.
  */
-export interface CalendarDateStringParts {
-    date: string;
-    annotation: string;
-}
+export declare const temporalStringLeapSecond: RegExp;
 /**
- * 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.
+ * Parse a GMT calendar date string into a Temporal.PlainDate, exactly as `Temporal.PlainDate.from`
+ * reads it, restricted to GMT's written shape and GMT's calendars. Throws on invalid input — callers
+ * wrap this in try-catch per GMT's sentinel contract.
  *
- * "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`).
+ * - The part before the first `[` must be GMT's strict extended date (`plainDate`) or date-time
+ *   (`plainDateTime`), as `isValidDate` and `isValidDateTime` require. Basic
+ *   format (`20241003`), a space or lower-case `t` separator and a UTC offset are rejected, although
+ *   `Temporal.PlainDate.from` reads them. Only then does Temporal read the annotations.
+ * - An ISO date, optionally followed by RFC 9557 annotations (`"2024-10-03[u-ca=hebrew]"`, which is
+ *   what `Temporal.PlainDate#toString()` writes). The digits are always the ISO date; the annotation
+ *   names the calendar (RFC 9557 §3.3).
+ * - A date-time is read as its date, as `Temporal.PlainDate.from` reads it
+ *   (`"2024-10-03T14:30[u-ca=hebrew]"` is 2024-10-03 in Hebrew): the time is dropped. A leap
+ *   second (second `60`) is rejected, as every GMT Plain date-time input rejects it.
+ * - The annotations follow Temporal's ISO grammar (`ParseISODateTime`): a time zone annotation
+ *   and elective unknown annotations (`[foo=bar]`) are read and ignored, the first `u-ca`
+ *   annotation names the calendar, and an unknown critical annotation (`[!foo=bar]`) or a second
+ *   `u-ca` annotation when either one is critical is rejected. `Temporal.PlainDate.from` applies
+ *   those rules and canonicalizes the id (`HEBREW` → `hebrew`, `islamicc` → `islamic-civil`,
+ *   `ethiopic-amete-alem` → `ethioaa`).
+ * - The calendar must be a `CalendarSystem`. Temporal also knows `chinese`, `dangi`, `islamic` and
+ *   `islamic-rgsa`, which GMT does not support.
+ * - The result computes in `computationCalendarId(calendar)`: `"ethiopic"` and `"coptic"` are read
+ *   in `"ethioaa"`, so callers that write a string back take the calendar from
+ *   `calendarSystemOfDateValue(value)`, not from `date.calendarId`.
  *
- * 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.
+ * @param value an extended ISO date or date-time, optionally with RFC 9557 annotations
+ * @returns the Temporal.PlainDate, in the computation calendar
  */
-export declare function calendarDateParts(date: Temporal.PlainDate): CalendarDateStringParts;
-/**
- * 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 declare function formatCalendarDate(date: Temporal.PlainDate): string;
+export declare function parseCalendarDateValue(value: string): Temporal.PlainDate;