@northguild/gmt 1.14.2

package/dist/internal/getLocaleMinimalDaysInFirstWeek.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve the minimum number of days a week must have in January for that
+ * week to count as a locale's week 1, via `Intl.Locale.prototype.weekInfo`.
+ *
+ * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Falls back to `4` (matching ISO 8601's rule — week 1 is the first
+ *   week with at least 4 days in January, equivalently the week
+ *   containing Jan 4) if `weekInfo` is unavailable on the runtime (older
+ *   engines) or unresolvable for the given locale. This mirrors
+ *   `getLocaleFirstDayOfWeek`'s fallback-to-ISO-default pattern.
+ * - Observed on Node 24 (V8/ICU 78): `weekInfo` omits `minimalDays`
+ *   entirely, for every locale, even though Node 20/22 (ICU 77) populate
+ *   it — so this fallback engages universally on that runtime rather
+ *   than only for locales missing data. `getLocaleWeekYear` and
+ *   `getWeeksInLocaleWeekYear` therefore lose locale-specific
+ *   minimal-days behavior (silently degrading to the ISO value) on
+ *   runtimes where the engine doesn't expose it, which is worth knowing
+ *   before treating a Node-version-only test failure as a real bug.
+ */
+export declare function getLocaleMinimalDaysInFirstWeek(locale: string): number | null;

package/dist/internal/getLocaleMinimalDaysInFirstWeek.js

@@ -0,0 +1,31 @@
+/**
+ * Resolve the minimum number of days a week must have in January for that
+ * week to count as a locale's week 1, via `Intl.Locale.prototype.weekInfo`.
+ *
+ * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Falls back to `4` (matching ISO 8601's rule — week 1 is the first
+ *   week with at least 4 days in January, equivalently the week
+ *   containing Jan 4) if `weekInfo` is unavailable on the runtime (older
+ *   engines) or unresolvable for the given locale. This mirrors
+ *   `getLocaleFirstDayOfWeek`'s fallback-to-ISO-default pattern.
+ * - Observed on Node 24 (V8/ICU 78): `weekInfo` omits `minimalDays`
+ *   entirely, for every locale, even though Node 20/22 (ICU 77) populate
+ *   it — so this fallback engages universally on that runtime rather
+ *   than only for locales missing data. `getLocaleWeekYear` and
+ *   `getWeeksInLocaleWeekYear` therefore lose locale-specific
+ *   minimal-days behavior (silently degrading to the ISO value) on
+ *   runtimes where the engine doesn't expose it, which is worth knowing
+ *   before treating a Node-version-only test failure as a real bug.
+ */
+export function getLocaleMinimalDaysInFirstWeek(locale) {
+    try {
+        const weekInfo = new Intl.Locale(locale).weekInfo;
+        if (!weekInfo || typeof weekInfo.minimalDays !== "number") {
+            return 4;
+        }
+        return weekInfo.minimalDays;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/getLocaleWeekYearBounds.d.ts

@@ -0,0 +1,19 @@
+import { Temporal } from "@js-temporal/polyfill";
+export interface LocaleWeekYearBounds {
+    weekYear: number;
+    /** First day of `weekYear`'s week 1. */
+    start: Temporal.PlainDate;
+    /** First day of `weekYear + 1`'s week 1 — an exclusive upper bound. */
+    end: Temporal.PlainDate;
+}
+/**
+ * Resolve the locale week-numbering year `date` belongs to, and the
+ * `[start, end)` bounds (in calendar days) of that week-year, given a
+ * locale's `firstDay` (1 = Monday .. 7 = Sunday) and `minimalDays` (the
+ * minimum January days a week must have to count as week 1) — both from
+ * `Intl.Locale.prototype.weekInfo`.
+ *
+ * Shared by `getLocaleWeekYear` (the year itself) and
+ * `getWeeksInLocaleWeekYear` (the week count, derived from `start`/`end`).
+ */
+export declare function getLocaleWeekYearBounds(date: Temporal.PlainDate, firstDay: number, minimalDays: number): LocaleWeekYearBounds;

package/dist/internal/getLocaleWeekYearBounds.js

@@ -0,0 +1,44 @@
+import { Temporal } from "@js-temporal/polyfill";
+// Week 1 of a locale week-year always contains January's `minimalDays`-th
+// day: the week starting on/before Jan 1 has k days in January, where k
+// ranges from `minimalDays` (the threshold to still count as week 1) up
+// to 7 (a full week starting exactly on Jan 1) — so day `minimalDays` of
+// January falls within that range no matter which end it lands on. This
+// generalizes ISO 8601's own rule (minimalDays = 4, so week 1 always
+// contains Jan 4).
+function startOfWeek1(year, firstDay, minimalDays) {
+    const anchor = Temporal.PlainDate.from({
+        year,
+        month: 1,
+        day: minimalDays,
+    });
+    const daysSinceFirstDay = (anchor.dayOfWeek - firstDay + 7) % 7;
+    return anchor.subtract({ days: daysSinceFirstDay });
+}
+/**
+ * Resolve the locale week-numbering year `date` belongs to, and the
+ * `[start, end)` bounds (in calendar days) of that week-year, given a
+ * locale's `firstDay` (1 = Monday .. 7 = Sunday) and `minimalDays` (the
+ * minimum January days a week must have to count as week 1) — both from
+ * `Intl.Locale.prototype.weekInfo`.
+ *
+ * Shared by `getLocaleWeekYear` (the year itself) and
+ * `getWeeksInLocaleWeekYear` (the week count, derived from `start`/`end`).
+ */
+export function getLocaleWeekYearBounds(date, firstDay, minimalDays) {
+    let weekYear = date.year;
+    let start = startOfWeek1(weekYear, firstDay, minimalDays);
+    if (Temporal.PlainDate.compare(date, start) < 0) {
+        weekYear -= 1;
+        start = startOfWeek1(weekYear, firstDay, minimalDays);
+    }
+    else {
+        const nextStart = startOfWeek1(weekYear + 1, firstDay, minimalDays);
+        if (Temporal.PlainDate.compare(date, nextStart) >= 0) {
+            weekYear += 1;
+            start = nextStart;
+        }
+    }
+    const end = startOfWeek1(weekYear + 1, firstDay, minimalDays);
+    return { weekYear, start, end };
+}

package/dist/internal/getLocaleWeekendDays.d.ts

@@ -0,0 +1,22 @@
+interface LocaleWeekInfo {
+    firstDay: number;
+    weekend: number[];
+    minimalDays: number;
+}
+declare global {
+    namespace Intl {
+        interface Locale {
+            readonly weekInfo: LocaleWeekInfo;
+        }
+    }
+}
+/**
+ * Resolve the set of ISO day-of-week numbers (1 = Monday .. 7 = Sunday)
+ * that count as "weekend" for a locale, via `Intl.Locale.prototype.weekInfo`.
+ *
+ * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Falls back to Saturday/Sunday (`[6, 7]`) if `weekInfo` is unavailable
+ *   on the runtime (older engines) or unresolvable for the given locale.
+ */
+export declare function getLocaleWeekendDays(locale: string): Set<number> | null;
+export {};

package/dist/internal/getLocaleWeekendDays.js

@@ -0,0 +1,20 @@
+/**
+ * Resolve the set of ISO day-of-week numbers (1 = Monday .. 7 = Sunday)
+ * that count as "weekend" for a locale, via `Intl.Locale.prototype.weekInfo`.
+ *
+ * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Falls back to Saturday/Sunday (`[6, 7]`) if `weekInfo` is unavailable
+ *   on the runtime (older engines) or unresolvable for the given locale.
+ */
+export function getLocaleWeekendDays(locale) {
+    try {
+        const weekInfo = new Intl.Locale(locale).weekInfo;
+        if (!weekInfo || !Array.isArray(weekInfo.weekend)) {
+            return new Set([6, 7]);
+        }
+        return new Set(weekInfo.weekend);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/hasCalendarAnnotation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Return true when `value` carries a `[u-ca=...]` calendar annotation — either GMT's own
+ * native-digit shape or Temporal's own ISO-digit RFC 9557 shape.
+ *
+ * The implementation has not changed since E5; its *meaning* has, because `zoned/` is no longer
+ * uniform. Current usage, after E7 (issue #152):
+ *
+ * - **`utc/`** (already regex-gated to a strict `<date>T<time>Z` shape) and **`unix/`** (numeric
+ *   input, structurally immune) reject every annotation, exactly as they always have.
+ * - **`isValidZonedDateTime`** still rejects every annotation, and the ~72 `zoned/` functions
+ *   gated on it therefore still do too. That gate is deliberately left alone: loosening it would
+ *   make `isValidZonedDateTime(x) === true` while e.g. `getZonedYear(x) === null`, i.e. a
+ *   validator certifying strings its own namespace refuses.
+ * - **The ~18 calendar-aware `zoned/` functions** added by E7 gate on the parallel
+ *   `isValidCalendarZonedDateTime`/`isValidCalendarZonedInterval` instead, which ACCEPT GMT's
+ *   `<date>T<time><offset>[u-ca=...][timeZone]` grammar and reject only Temporal's own segment
+ *   ordering. Those paths use `internal/calendarValueOfZoned.ts` and
+ *   `internal/calendarZonedString.ts`, not this predicate.
+ * - **`plain/`** `PlainDate` functions accept GMT's annotated shape via `isValidCalendarDate`
+ *   (E5's D1); `plain/` `PlainDateTime`/`PlainTime` functions have no annotated grammar of their
+ *   own and treat one as invalid input.
+ *
+ * So this predicate answers exactly one question — "does this string carry an annotation at all?"
+ * — and says nothing about whether the caller should accept it. Reach for it only where the
+ * answer is "reject unconditionally".
+ */
+export declare function hasCalendarAnnotation(value: string): boolean;

package/dist/internal/hasCalendarAnnotation.js

@@ -0,0 +1,29 @@
+/**
+ * Return true when `value` carries a `[u-ca=...]` calendar annotation — either GMT's own
+ * native-digit shape or Temporal's own ISO-digit RFC 9557 shape.
+ *
+ * The implementation has not changed since E5; its *meaning* has, because `zoned/` is no longer
+ * uniform. Current usage, after E7 (issue #152):
+ *
+ * - **`utc/`** (already regex-gated to a strict `<date>T<time>Z` shape) and **`unix/`** (numeric
+ *   input, structurally immune) reject every annotation, exactly as they always have.
+ * - **`isValidZonedDateTime`** still rejects every annotation, and the ~72 `zoned/` functions
+ *   gated on it therefore still do too. That gate is deliberately left alone: loosening it would
+ *   make `isValidZonedDateTime(x) === true` while e.g. `getZonedYear(x) === null`, i.e. a
+ *   validator certifying strings its own namespace refuses.
+ * - **The ~18 calendar-aware `zoned/` functions** added by E7 gate on the parallel
+ *   `isValidCalendarZonedDateTime`/`isValidCalendarZonedInterval` instead, which ACCEPT GMT's
+ *   `<date>T<time><offset>[u-ca=...][timeZone]` grammar and reject only Temporal's own segment
+ *   ordering. Those paths use `internal/calendarValueOfZoned.ts` and
+ *   `internal/calendarZonedString.ts`, not this predicate.
+ * - **`plain/`** `PlainDate` functions accept GMT's annotated shape via `isValidCalendarDate`
+ *   (E5's D1); `plain/` `PlainDateTime`/`PlainTime` functions have no annotated grammar of their
+ *   own and treat one as invalid input.
+ *
+ * So this predicate answers exactly one question — "does this string carry an annotation at all?"
+ * — and says nothing about whether the caller should accept it. Reach for it only where the
+ * answer is "reject unconditionally".
+ */
+export function hasCalendarAnnotation(value) {
+    return typeof value === "string" && value.includes("[u-ca=");
+}

package/dist/internal/index.d.ts

@@ -0,0 +1,34 @@
+export { advanceBusinessDays } from "./advanceBusinessDays.js";
+export { adjustZonedBusinessDays } from "./adjustZonedBusinessDays.js";
+export { advanceToWeekday } from "./advanceToWeekday.js";
+export { calendarDateParts, type CalendarDateStringParts, formatCalendarDate, parseCalendarDateValue, } from "./calendarDateString.js";
+export { isCalendarSystem, temporalCalendarIds } from "./calendarSystemIds.js";
+export { parseCalendarDatePairForArithmetic } from "./calendarDatePairPolicy.js";
+export { parseCalendarZonedPairForArithmetic } from "./calendarZonedPairPolicy.js";
+export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarValueOfDate.js";
+export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
+export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
+export { cycleFieldValue } from "./cycleFieldValue.js";
+export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
+export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
+export { durationUntilString } from "./durationUntilString.js";
+export { calendarDateStringParts, formatDateInCalendar, } from "./formatDateInCalendar.js";
+export { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
+export { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
+export { dateFromEthiopicFamilyFields, ethiopicFamilyDateParts, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+export { getLocaleFirstDayOfWeek } from "./getLocaleFirstDayOfWeek.js";
+export { getLocaleMinimalDaysInFirstWeek } from "./getLocaleMinimalDaysInFirstWeek.js";
+export { getLocaleWeekYearBounds } from "./getLocaleWeekYearBounds.js";
+export { getLocaleWeekendDays } from "./getLocaleWeekendDays.js";
+export { getStartOfZonedUnit, getUnitSpan } from "./intervalCountHelpers.js";
+export { isValidAmount } from "./isValidAmount.js";
+export { joinDateTimeConnector } from "./joinDateTimeConnector.js";
+export { isValidDayOfWeek } from "./isValidDayOfWeek.js";
+export { monthGridWeekRow } from "./monthGridWeekRow.js";
+export { normalizeDateTime } from "./normalizeDateTime.js";
+export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
+export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
+export { resolveDurationUnit } from "./resolveDurationUnit.js";
+export { resolveOverflow } from "./resolveOverflow.js";
+export { resolveRelativeRounding } from "./resolveRelativeRounding.js";

package/dist/internal/index.js

@@ -0,0 +1,34 @@
+export { advanceBusinessDays } from "./advanceBusinessDays.js";
+export { adjustZonedBusinessDays } from "./adjustZonedBusinessDays.js";
+export { advanceToWeekday } from "./advanceToWeekday.js";
+export { calendarDateParts, formatCalendarDate, parseCalendarDateValue, } from "./calendarDateString.js";
+export { isCalendarSystem, temporalCalendarIds } from "./calendarSystemIds.js";
+export { parseCalendarDatePairForArithmetic } from "./calendarDatePairPolicy.js";
+export { parseCalendarZonedPairForArithmetic } from "./calendarZonedPairPolicy.js";
+export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarValueOfDate.js";
+export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
+export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
+export { cycleFieldValue } from "./cycleFieldValue.js";
+export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
+export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
+export { durationUntilString } from "./durationUntilString.js";
+export { calendarDateStringParts, formatDateInCalendar, } from "./formatDateInCalendar.js";
+export { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
+export { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
+export { dateFromEthiopicFamilyFields, ethiopicFamilyDateParts, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+export { getLocaleFirstDayOfWeek } from "./getLocaleFirstDayOfWeek.js";
+export { getLocaleMinimalDaysInFirstWeek } from "./getLocaleMinimalDaysInFirstWeek.js";
+export { getLocaleWeekYearBounds } from "./getLocaleWeekYearBounds.js";
+export { getLocaleWeekendDays } from "./getLocaleWeekendDays.js";
+export { getStartOfZonedUnit, getUnitSpan } from "./intervalCountHelpers.js";
+export { isValidAmount } from "./isValidAmount.js";
+export { joinDateTimeConnector } from "./joinDateTimeConnector.js";
+export { isValidDayOfWeek } from "./isValidDayOfWeek.js";
+export { monthGridWeekRow } from "./monthGridWeekRow.js";
+export { normalizeDateTime } from "./normalizeDateTime.js";
+export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
+export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
+export { resolveDurationUnit } from "./resolveDurationUnit.js";
+export { resolveOverflow } from "./resolveOverflow.js";
+export { resolveRelativeRounding } from "./resolveRelativeRounding.js";

package/dist/internal/intervalCountHelpers.d.ts

@@ -0,0 +1,26 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeUnit } from "../types/index.js";
+/**
+ * Return the start of the specified date-time `unit` for a `Temporal.ZonedDateTime`.
+ *
+ * - Always uses Monday as the week start (consistent with `startOfZoned` semantics).
+ * - Day-and-below units truncate by instant via `round({ roundingMode: "trunc" })`, which
+ *   resolves DST correctly — a local day whose midnight is skipped starts at 01:00.
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param source Temporal.ZonedDateTime to truncate
+ * @param unit DateTimeUnit to truncate to
+ * @returns Temporal.ZonedDateTime at the start of the specified unit
+ */
+export declare function getStartOfZonedUnit(source: Temporal.ZonedDateTime, unit: DateTimeUnit): Temporal.ZonedDateTime;
+/**
+ * Extract the whole-unit span from a `Temporal.Duration` measured with `largestUnit: unit`.
+ *
+ * - Floors the field so a partial trailing amount never inflates a boundary count.
+ * - Does NOT validate the unit — caller ensures the duration was measured in it.
+ *
+ * @param duration Temporal.Duration produced by `until({ largestUnit: unit })`
+ * @param unit DateTimeUnit the duration was measured in
+ * @returns whole number of units spanned
+ */
+export declare function getUnitSpan(duration: Temporal.Duration, unit: DateTimeUnit): number;

package/dist/internal/intervalCountHelpers.js

@@ -0,0 +1,62 @@
+/**
+ * Singular DateTimeUnit to its `Temporal.Duration` field name.
+ *
+ * Example lookups:
+ * - DURATION_FIELD_BY_UNIT.day => "days"
+ * - DURATION_FIELD_BY_UNIT.nanosecond => "nanoseconds"
+ */
+const DURATION_FIELD_BY_UNIT = {
+    year: "years",
+    month: "months",
+    week: "weeks",
+    day: "days",
+    hour: "hours",
+    minute: "minutes",
+    second: "seconds",
+    millisecond: "milliseconds",
+    microsecond: "microseconds",
+    nanosecond: "nanoseconds",
+};
+/**
+ * Return the start of the specified date-time `unit` for a `Temporal.ZonedDateTime`.
+ *
+ * - Always uses Monday as the week start (consistent with `startOfZoned` semantics).
+ * - Day-and-below units truncate by instant via `round({ roundingMode: "trunc" })`, which
+ *   resolves DST correctly — a local day whose midnight is skipped starts at 01:00.
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param source Temporal.ZonedDateTime to truncate
+ * @param unit DateTimeUnit to truncate to
+ * @returns Temporal.ZonedDateTime at the start of the specified unit
+ */
+export function getStartOfZonedUnit(source, unit) {
+    switch (unit) {
+        case "year":
+            return source
+                .with({ month: 1, day: 1 })
+                .round({ smallestUnit: "day", roundingMode: "trunc" });
+        case "month":
+            return source
+                .with({ day: 1 })
+                .round({ smallestUnit: "day", roundingMode: "trunc" });
+        case "week":
+            return source
+                .subtract({ days: source.dayOfWeek - 1 })
+                .round({ smallestUnit: "day", roundingMode: "trunc" });
+        default:
+            return source.round({ smallestUnit: unit, roundingMode: "trunc" });
+    }
+}
+/**
+ * Extract the whole-unit span from a `Temporal.Duration` measured with `largestUnit: unit`.
+ *
+ * - Floors the field so a partial trailing amount never inflates a boundary count.
+ * - Does NOT validate the unit — caller ensures the duration was measured in it.
+ *
+ * @param duration Temporal.Duration produced by `until({ largestUnit: unit })`
+ * @param unit DateTimeUnit the duration was measured in
+ * @returns whole number of units spanned
+ */
+export function getUnitSpan(duration, unit) {
+    return Math.floor(duration[DURATION_FIELD_BY_UNIT[unit]]);
+}

package/dist/internal/isValidAmount.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Type guard to check if a value is a valid amount (finite number).
+ *
+ * @param value number candidate
+ * @example isValidAmount(10) // true
+ * @example isValidAmount(-5) // true
+ * @returns boolean indicating whether the value is a valid amount
+ */
+export declare function isValidAmount(value: number): value is number;

package/dist/internal/isValidAmount.js

@@ -0,0 +1,11 @@
+/**
+ * Type guard to check if a value is a valid amount (finite number).
+ *
+ * @param value number candidate
+ * @example isValidAmount(10) // true
+ * @example isValidAmount(-5) // true
+ * @returns boolean indicating whether the value is a valid amount
+ */
+export function isValidAmount(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}

package/dist/internal/isValidDayOfWeek.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Type guard to check if a value is a valid ISO day-of-week number (1 = Monday … 7 = Sunday).
+ *
+ * @param value day-of-week candidate
+ * @example isValidDayOfWeek(1) // true
+ * @example isValidDayOfWeek(7) // true
+ * @example isValidDayOfWeek(0) // false
+ * @example isValidDayOfWeek(8) // false
+ * @returns boolean indicating whether the value is a valid ISO day-of-week number
+ */
+export declare function isValidDayOfWeek(value: number): value is number;

package/dist/internal/isValidDayOfWeek.js

@@ -0,0 +1,13 @@
+/**
+ * Type guard to check if a value is a valid ISO day-of-week number (1 = Monday … 7 = Sunday).
+ *
+ * @param value day-of-week candidate
+ * @example isValidDayOfWeek(1) // true
+ * @example isValidDayOfWeek(7) // true
+ * @example isValidDayOfWeek(0) // false
+ * @example isValidDayOfWeek(8) // false
+ * @returns boolean indicating whether the value is a valid ISO day-of-week number
+ */
+export function isValidDayOfWeek(value) {
+    return Number.isInteger(value) && value >= 1 && value <= 7;
+}

package/dist/internal/joinDateTimeConnector.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Join a relative day label (e.g. "Tomorrow") with the localized time-of-day
+ * for the same instant, using the locale's *own* connector word/punctuation
+ * instead of a hardcoded one (e.g. English "at").
+ *
+ * - Formats `epochMilliseconds` with `dateStyle: "full"` + `timeStyle` to get
+ *   CLDR's locale-correct date/time part sequence and its connector, then
+ *   discards every date-labeled part (weekday/era/year/month/day) in favor of
+ *   `dayLabel` — keeping only the connector and the time-side parts.
+ * - The connector is whatever literal part immediately follows the last
+ *   date-labeled part — a space for locales with none (e.g. tr-TR), a word
+ *   for others (" at " / " um " / " à " / "في " / …). This works for every
+ *   locale because it reads CLDR's own combined-pattern output rather than
+ *   assuming a fixed word or position.
+ * - This is why the day/time split cannot be done by formatting the date and
+ *   time halves separately and concatenating with a hardcoded joiner: the
+ *   joiner itself, and even the ordering of the day-period relative to the
+ *   hour (see ko-KR/zh-TW, where "PM" precedes the hour), are locale-specific
+ *   and only `Intl` knows them.
+ * - One further wrinkle: some locales' date pattern has its own trailing
+ *   literal glued onto the last date field, unrelated to the date/time
+ *   connector — ru-RU renders a bare date as "15 марта 2024 г." (a genitive
+ *   "year" marker suffixed to the year number with no separating space), so
+ *   the combined format's literal after "2024" is " г. в " (suffix + real
+ *   connector, fused into one part). A second `dateStyle`-only format call
+ *   below detects and strips that date-side suffix before treating the rest
+ *   of the literal as the connector — otherwise "г." would leak into
+ *   "tomorrow г. at 2:30", nonsensical since it isn't attached to a year here.
+ *
+ * @param epochMilliseconds instant to format, in milliseconds since the Unix epoch
+ * @param timeZone IANA timezone identifier (or "UTC" for plain values with no real zone)
+ * @param locale optional BCP 47 locale tag
+ * @param dayLabel the word/phrase replacing the date half (e.g. "Tomorrow", "Friday")
+ * @param timeStyle Intl.DateTimeFormatOptions `timeStyle` for the time half
+ * @returns `dayLabel` joined to the localized time with the locale's own connector
+ */
+export declare function joinDateTimeConnector(epochMilliseconds: number, timeZone: string, locale: string | undefined, dayLabel: string, timeStyle: "short" | "medium" | "full"): string;

package/dist/internal/joinDateTimeConnector.js

@@ -0,0 +1,85 @@
+// `Intl.DateTimeFormat`'s part types that belong to the *date* half of a
+// combined `dateStyle` + `timeStyle` format. Everything else (`hour`,
+// `minute`, `second`, `fractionalSecond`, `dayPeriod`, `timeZoneName`, and
+// `literal`) belongs to the time half or is punctuation between fields.
+const DATE_PART_TYPES = new Set([
+    "era",
+    "year",
+    "relatedYear",
+    "yearName",
+    "month",
+    "day",
+    "weekday",
+]);
+/**
+ * Join a relative day label (e.g. "Tomorrow") with the localized time-of-day
+ * for the same instant, using the locale's *own* connector word/punctuation
+ * instead of a hardcoded one (e.g. English "at").
+ *
+ * - Formats `epochMilliseconds` with `dateStyle: "full"` + `timeStyle` to get
+ *   CLDR's locale-correct date/time part sequence and its connector, then
+ *   discards every date-labeled part (weekday/era/year/month/day) in favor of
+ *   `dayLabel` — keeping only the connector and the time-side parts.
+ * - The connector is whatever literal part immediately follows the last
+ *   date-labeled part — a space for locales with none (e.g. tr-TR), a word
+ *   for others (" at " / " um " / " à " / "في " / …). This works for every
+ *   locale because it reads CLDR's own combined-pattern output rather than
+ *   assuming a fixed word or position.
+ * - This is why the day/time split cannot be done by formatting the date and
+ *   time halves separately and concatenating with a hardcoded joiner: the
+ *   joiner itself, and even the ordering of the day-period relative to the
+ *   hour (see ko-KR/zh-TW, where "PM" precedes the hour), are locale-specific
+ *   and only `Intl` knows them.
+ * - One further wrinkle: some locales' date pattern has its own trailing
+ *   literal glued onto the last date field, unrelated to the date/time
+ *   connector — ru-RU renders a bare date as "15 марта 2024 г." (a genitive
+ *   "year" marker suffixed to the year number with no separating space), so
+ *   the combined format's literal after "2024" is " г. в " (suffix + real
+ *   connector, fused into one part). A second `dateStyle`-only format call
+ *   below detects and strips that date-side suffix before treating the rest
+ *   of the literal as the connector — otherwise "г." would leak into
+ *   "tomorrow г. at 2:30", nonsensical since it isn't attached to a year here.
+ *
+ * @param epochMilliseconds instant to format, in milliseconds since the Unix epoch
+ * @param timeZone IANA timezone identifier (or "UTC" for plain values with no real zone)
+ * @param locale optional BCP 47 locale tag
+ * @param dayLabel the word/phrase replacing the date half (e.g. "Tomorrow", "Friday")
+ * @param timeStyle Intl.DateTimeFormatOptions `timeStyle` for the time half
+ * @returns `dayLabel` joined to the localized time with the locale's own connector
+ */
+export function joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle) {
+    const parts = new Intl.DateTimeFormat(locale, {
+        dateStyle: "full",
+        timeStyle,
+        timeZone,
+    }).formatToParts(epochMilliseconds);
+    let lastDateIdx = -1;
+    parts.forEach((part, i) => {
+        if (DATE_PART_TYPES.has(part.type))
+            lastDateIdx = i;
+    });
+    // Detect a date-side trailing literal (e.g. ru-RU's " г.") that a
+    // dateStyle-only format would still produce with no time present — it
+    // belongs to the date field, not the connector, even though the combined
+    // format fuses it into the same literal token as the real connector.
+    const dateOnlyParts = new Intl.DateTimeFormat(locale, {
+        dateStyle: "full",
+        timeZone,
+    }).formatToParts(epochMilliseconds);
+    const dateOnlyLast = dateOnlyParts[dateOnlyParts.length - 1];
+    const dateSuffix = dateOnlyLast?.type === "literal" ? dateOnlyLast.value : "";
+    let cursor = lastDateIdx + 1;
+    let connector = " ";
+    if (parts[cursor]?.type === "literal") {
+        connector = parts[cursor].value;
+        if (dateSuffix.length > 0 && connector.startsWith(dateSuffix)) {
+            connector = connector.slice(dateSuffix.length);
+        }
+        cursor += 1;
+    }
+    const timePortion = parts
+        .slice(cursor)
+        .map((part) => part.value)
+        .join("");
+    return `${dayLabel}${connector}${timePortion}`;
+}

package/dist/internal/monthGridWeekRow.d.ts

@@ -0,0 +1,12 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the 1-based calendar-grid week row that `dayInMonth` falls on for
+ * `firstOfMonth`'s month, given `firstDay` (locale first day of week,
+ * 1 = Monday .. 7 = Sunday).
+ *
+ * Shared by `getWeekOfMonth` (row for the date itself) and
+ * `getWeeksInMonth` (row for the month's last day, i.e. the row count).
+ * Week 1 is the row containing the 1st of the month, even when that row
+ * is a partial week (date-fns's `getWeekOfMonth` convention).
+ */
+export declare function monthGridWeekRow(firstOfMonth: Temporal.PlainDate, firstDay: number, dayInMonth: number): number;

package/dist/internal/monthGridWeekRow.js

@@ -0,0 +1,14 @@
+/**
+ * Return the 1-based calendar-grid week row that `dayInMonth` falls on for
+ * `firstOfMonth`'s month, given `firstDay` (locale first day of week,
+ * 1 = Monday .. 7 = Sunday).
+ *
+ * Shared by `getWeekOfMonth` (row for the date itself) and
+ * `getWeeksInMonth` (row for the month's last day, i.e. the row count).
+ * Week 1 is the row containing the 1st of the month, even when that row
+ * is a partial week (date-fns's `getWeekOfMonth` convention).
+ */
+export function monthGridWeekRow(firstOfMonth, firstDay, dayInMonth) {
+    const leadingOffset = (firstOfMonth.dayOfWeek - firstDay + 7) % 7;
+    return Math.floor((leadingOffset + dayInMonth - 1) / 7) + 1;
+}

package/dist/internal/normalizeDateTime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize formatted date/time strings for stable comparisons.
+ *
+ * - Removes Unicode format and bidi control characters (LRM/RLM/LRE/RLE/etc.)
+ * - Removes zero-width space and BOM
+ * - Normalizes various non-breaking and narrow spaces to plain space
+ * - Collapses repeated whitespace to a single space and trims
+ * - Normalizes common dash/minus characters to ASCII hyphen-minus
+ * - Optionally lowercases the result (disabled by default)
+ */
+export declare function normalizeDateTime(input: string, opts?: {
+    lower?: boolean;
+    locale?: string;
+}): string;

package/dist/internal/normalizeDateTime.js

@@ -0,0 +1,34 @@
+/**
+ * Normalize formatted date/time strings for stable comparisons.
+ *
+ * - Removes Unicode format and bidi control characters (LRM/RLM/LRE/RLE/etc.)
+ * - Removes zero-width space and BOM
+ * - Normalizes various non-breaking and narrow spaces to plain space
+ * - Collapses repeated whitespace to a single space and trims
+ * - Normalizes common dash/minus characters to ASCII hyphen-minus
+ * - Optionally lowercases the result (disabled by default)
+ */
+export function normalizeDateTime(input, opts) {
+    if (typeof input !== "string")
+        return "";
+    const { lower = false, locale = "en-US" } = opts ?? {};
+    // Use NFC where available for stable composed characters
+    let s = typeof input.normalize === "function" ? input.normalize("NFC") : input;
+    // Remove Unicode format characters (includes bidi marks), zero-width space, BOM
+    // \p{Cf} covers most format/control characters like U+200E/U+200F, LRE/RLE, PDF, etc.
+    s = s.replace(/[\p{Cf}\u200B\uFEFF]/gu, "");
+    // Normalize various space characters to ordinary space
+    s = s.replace(/[\u00A0\u202F\u2009\u2007\u2002\u2003\u2004\u2005\u2006\u2008\u200A]/g, " ");
+    // Treat dash/minus characters specially:
+    // - If the dash sits between digits (e.g. dates like 2024–02–03), keep a
+    //   compact hyphen (no added spaces).
+    // - Otherwise convert dash-like characters to a spaced " - " so ranges like
+    //   "AM- 12:00" become "AM - 12:00".
+    s = s.replace(/(?<=\d)[\u2010\u2011\u2012\u2013\u2014\u2015\u2212](?=\d)/g, "-");
+    s = s.replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, " - ");
+    // Collapse whitespace and trim
+    s = s.replace(/\s+/g, " ").trim();
+    // Normalize fraction slash etc. to ASCII slash where appropriate
+    s = s.replace(/[\u2044]/g, "/");
+    return lower ? s.toLocaleLowerCase(locale) : s;
+}