@northguild/gmt 1.14.2

package/dist/plain/calculate/getLargestDateTimeDurationUnit.js

@@ -0,0 +1,35 @@
+/**
+ * Return the largest DateTimeDurationUnit from the provided array.
+ *
+ * - Returns the largest unit based on Temporal's unit order: years > months > weeks > days > hours > minutes > seconds > milliseconds > microseconds > nanoseconds.
+ * - Defaults to "seconds" if no valid unit is found in the array.
+ *
+ * @param units array of DateTimeDurationUnit to evaluate
+ * @returns the largest DateTimeDurationUnit found, or "seconds" if none are valid
+ *
+ * @example getLargestDateTimeDurationUnit(["hours", "minutes", "seconds"]) // "hours"
+ * @example getLargestDateTimeDurationUnit(["minutes", "seconds"]) // "minutes"
+ * @example getLargestDateTimeDurationUnit(["seconds"]) // "seconds"
+ * @example getLargestDateTimeDurationUnit([]) // "seconds"
+ */
+export function getLargestDateTimeDurationUnit(units) {
+    const order = [
+        "years",
+        "months",
+        "weeks",
+        "days",
+        "hours",
+        "minutes",
+        "seconds",
+        "milliseconds",
+        "microseconds",
+        "nanoseconds",
+    ];
+    for (const unit of order) {
+        if (units.includes(unit)) {
+            return unit;
+        }
+    }
+    // Default to seconds if no valid unit found, though this case should be prevented by validation
+    return "seconds";
+}

package/dist/plain/calculate/getLargestTimeDurationUnit.d.ts

@@ -0,0 +1,16 @@
+import type { TimeDurationUnit } from "../../types/index.js";
+/**
+ * Return the largest TimeDurationUnit from the provided array.
+ *
+ * - Returns the largest unit based on Temporal's unit order: hours > minutes > seconds > milliseconds > microseconds > nanoseconds.
+ * - Defaults to "seconds" if no valid unit is found in the array.
+ *
+ * @param units array of TimeDurationUnits to evaluate
+ * @returns the largest TimeDurationUnit found in the array, or "seconds" if none are valid
+ *
+ * @example getLargestTimeDurationUnit(["minutes", "seconds"]) // "minutes"
+ * @example getLargestTimeDurationUnit(["seconds", "milliseconds"]) // "seconds"
+ * @example getLargestTimeDurationUnit(["milliseconds", "microseconds"]) // "milliseconds"
+ * @example getLargestTimeDurationUnit([]) // "seconds"
+ */
+export declare function getLargestTimeDurationUnit(units: TimeDurationUnit[]): TimeDurationUnit;

package/dist/plain/calculate/getLargestTimeDurationUnit.js

@@ -0,0 +1,31 @@
+/**
+ * Return the largest TimeDurationUnit from the provided array.
+ *
+ * - Returns the largest unit based on Temporal's unit order: hours > minutes > seconds > milliseconds > microseconds > nanoseconds.
+ * - Defaults to "seconds" if no valid unit is found in the array.
+ *
+ * @param units array of TimeDurationUnits to evaluate
+ * @returns the largest TimeDurationUnit found in the array, or "seconds" if none are valid
+ *
+ * @example getLargestTimeDurationUnit(["minutes", "seconds"]) // "minutes"
+ * @example getLargestTimeDurationUnit(["seconds", "milliseconds"]) // "seconds"
+ * @example getLargestTimeDurationUnit(["milliseconds", "microseconds"]) // "milliseconds"
+ * @example getLargestTimeDurationUnit([]) // "seconds"
+ */
+export function getLargestTimeDurationUnit(units) {
+    const order = [
+        "hours",
+        "minutes",
+        "seconds",
+        "milliseconds",
+        "microseconds",
+        "nanoseconds",
+    ];
+    for (const unit of order) {
+        if (units.includes(unit)) {
+            return unit;
+        }
+    }
+    // Default to seconds if no valid unit found, though this case should be prevented by validation
+    return "seconds";
+}

package/dist/plain/calculate/getLocaleDayOfWeek.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Return the locale-relative day-of-week index for `value`.
+ *
+ * - `0` = the locale's first day of week (e.g. Sunday for en-US, Monday for fr-FR).
+ * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - Returns `null` if `value` is not a valid ISO date or `locale` is unresolvable.
+ *
+ * @param value ISO 8601 date string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns locale-relative day-of-week index (0–6) or null on invalid input
+ *
+ * @example getLocaleDayOfWeek("2024-02-25", "en-US") // 0 (Sunday)
+ * @example getLocaleDayOfWeek("2024-02-26", "en-US") // 1 (Monday)
+ * @example getLocaleDayOfWeek("2024-02-26", "fr-FR") // 0 (Monday)
+ * @example getLocaleDayOfWeek("invalid-date", "en-US") // null
+ * @example getLocaleDayOfWeek("2024-02-29", "not-a-locale") // null
+ */
+export declare function getLocaleDayOfWeek(value: string, locale: string): number | null;

package/dist/plain/calculate/getLocaleDayOfWeek.js

@@ -0,0 +1,36 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the locale-relative day-of-week index for `value`.
+ *
+ * - `0` = the locale's first day of week (e.g. Sunday for en-US, Monday for fr-FR).
+ * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - Returns `null` if `value` is not a valid ISO date or `locale` is unresolvable.
+ *
+ * @param value ISO 8601 date string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns locale-relative day-of-week index (0–6) or null on invalid input
+ *
+ * @example getLocaleDayOfWeek("2024-02-25", "en-US") // 0 (Sunday)
+ * @example getLocaleDayOfWeek("2024-02-26", "en-US") // 1 (Monday)
+ * @example getLocaleDayOfWeek("2024-02-26", "fr-FR") // 0 (Monday)
+ * @example getLocaleDayOfWeek("invalid-date", "en-US") // null
+ * @example getLocaleDayOfWeek("2024-02-29", "not-a-locale") // null
+ */
+export function getLocaleDayOfWeek(value, locale) {
+    if (!isValidDate(value))
+        return null;
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return (date.dayOfWeek - firstDay + 7) % 7;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/calculate/getLocaleEndOfWeek.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Return the end of the week containing `value`, using `locale`'s first
+ * day of week (e.g. en-US: week ends Saturday, fr-FR: week ends Sunday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday-start (so the week ends Sunday) if the runtime's
+ *   `weekInfo` data doesn't resolve a first day for the locale.
+ * - Distinct from `endOfDate(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value ISO 8601 date string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns ISO 8601 date string for the end of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleEndOfWeek("2024-02-29", "en-US") // "2024-03-02" (Saturday)
+ * @example getLocaleEndOfWeek("2024-02-29", "fr-FR") // "2024-03-03" (Sunday)
+ * @example getLocaleEndOfWeek("invalid-date", "en-US") // ""
+ * @example getLocaleEndOfWeek("2024-02-29", "not-a-locale") // ""
+ */
+export declare function getLocaleEndOfWeek(value: string, locale: string): string;

package/dist/plain/calculate/getLocaleEndOfWeek.js

@@ -0,0 +1,40 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the end of the week containing `value`, using `locale`'s first
+ * day of week (e.g. en-US: week ends Saturday, fr-FR: week ends Sunday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday-start (so the week ends Sunday) if the runtime's
+ *   `weekInfo` data doesn't resolve a first day for the locale.
+ * - Distinct from `endOfDate(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value ISO 8601 date string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns ISO 8601 date string for the end of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleEndOfWeek("2024-02-29", "en-US") // "2024-03-02" (Saturday)
+ * @example getLocaleEndOfWeek("2024-02-29", "fr-FR") // "2024-03-03" (Sunday)
+ * @example getLocaleEndOfWeek("invalid-date", "en-US") // ""
+ * @example getLocaleEndOfWeek("2024-02-29", "not-a-locale") // ""
+ */
+export function getLocaleEndOfWeek(value, locale) {
+    if (!isValidDate(value))
+        return "";
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return "";
+    try {
+        const source = Temporal.PlainDate.from(value);
+        const daysToSubtract = (source.dayOfWeek - firstDay + 7) % 7;
+        return source.add({ days: 6 - daysToSubtract }).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/getLocaleStartOfWeek.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Return the start of the week containing `value`, using `locale`'s
+ * first day of week (e.g. en-US: Sunday, fr-FR: Monday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - Distinct from `startOfDate(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value ISO 8601 date string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns ISO 8601 date string for the start of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleStartOfWeek("2024-02-29", "en-US") // "2024-02-25" (Sunday)
+ * @example getLocaleStartOfWeek("2024-02-29", "fr-FR") // "2024-02-26" (Monday)
+ * @example getLocaleStartOfWeek("invalid-date", "en-US") // ""
+ * @example getLocaleStartOfWeek("2024-02-29", "not-a-locale") // ""
+ */
+export declare function getLocaleStartOfWeek(value: string, locale: string): string;

package/dist/plain/calculate/getLocaleStartOfWeek.js

@@ -0,0 +1,40 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the start of the week containing `value`, using `locale`'s
+ * first day of week (e.g. en-US: Sunday, fr-FR: Monday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - Distinct from `startOfDate(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value ISO 8601 date string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns ISO 8601 date string for the start of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleStartOfWeek("2024-02-29", "en-US") // "2024-02-25" (Sunday)
+ * @example getLocaleStartOfWeek("2024-02-29", "fr-FR") // "2024-02-26" (Monday)
+ * @example getLocaleStartOfWeek("invalid-date", "en-US") // ""
+ * @example getLocaleStartOfWeek("2024-02-29", "not-a-locale") // ""
+ */
+export function getLocaleStartOfWeek(value, locale) {
+    if (!isValidDate(value))
+        return "";
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return "";
+    try {
+        const source = Temporal.PlainDate.from(value);
+        const daysToSubtract = (source.dayOfWeek - firstDay + 7) % 7;
+        return source.subtract({ days: daysToSubtract }).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/getLocaleWeekYear.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Return the locale-relative week-numbering year `value` belongs to,
+ * using `locale`'s first day of week and minimal-days-in-first-week
+ * (e.g. en-US: week 1 always contains Jan 1; ISO/most European locales:
+ * week 1 always contains Jan 4).
+ *
+ * - Distinct from `value`'s calendar year, for the same reason
+ *   `getWeekYear` is — late-December/early-January dates can belong to a
+ *   different week-year than their calendar year, and the boundary
+ *   depends on the locale's week-numbering rule.
+ * - Distinct from `getWeekYear`: this uses the locale's first day of
+ *   week and minimal-days rule (via `Intl.Locale.prototype.weekInfo`)
+ *   instead of the fixed ISO rule (Monday-start, 4 minimal days) — the
+ *   two can disagree on the same date near a year boundary.
+ * - Resolves `locale`'s week-numbering rule via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns locale-relative week-numbering year, or null on invalid input
+ *
+ * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024
+ * @example getLocaleWeekYear("2022-01-01", "en-US") // 2022 (Jan 1 is always week 1 in en-US)
+ * @example getLocaleWeekYear("2022-01-01", "de-DE") // 2021 (ISO-style: Jan 1, 2022 is a Saturday, in week 52 of 2021)
+ * @example getLocaleWeekYear("invalid", "en-US") // null
+ */
+export declare function getLocaleWeekYear(value: string, locale: string): number | null;

package/dist/plain/calculate/getLocaleWeekYear.js

@@ -0,0 +1,45 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek, getLocaleMinimalDaysInFirstWeek, getLocaleWeekYearBounds, } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the locale-relative week-numbering year `value` belongs to,
+ * using `locale`'s first day of week and minimal-days-in-first-week
+ * (e.g. en-US: week 1 always contains Jan 1; ISO/most European locales:
+ * week 1 always contains Jan 4).
+ *
+ * - Distinct from `value`'s calendar year, for the same reason
+ *   `getWeekYear` is — late-December/early-January dates can belong to a
+ *   different week-year than their calendar year, and the boundary
+ *   depends on the locale's week-numbering rule.
+ * - Distinct from `getWeekYear`: this uses the locale's first day of
+ *   week and minimal-days rule (via `Intl.Locale.prototype.weekInfo`)
+ *   instead of the fixed ISO rule (Monday-start, 4 minimal days) — the
+ *   two can disagree on the same date near a year boundary.
+ * - Resolves `locale`'s week-numbering rule via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns locale-relative week-numbering year, or null on invalid input
+ *
+ * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024
+ * @example getLocaleWeekYear("2022-01-01", "en-US") // 2022 (Jan 1 is always week 1 in en-US)
+ * @example getLocaleWeekYear("2022-01-01", "de-DE") // 2021 (ISO-style: Jan 1, 2022 is a Saturday, in week 52 of 2021)
+ * @example getLocaleWeekYear("invalid", "en-US") // null
+ */
+export function getLocaleWeekYear(value, locale) {
+    if (!isValidDate(value))
+        return null;
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    const minimalDays = getLocaleMinimalDaysInFirstWeek(locale);
+    if (firstDay === null || minimalDays === null)
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return getLocaleWeekYearBounds(date, firstDay, minimalDays).weekYear;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/calculate/getQuarterForDate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Return the quarter of the year (1-4) for a given ISO date.
+ *
+ * - Returns the quarter (1-4) containing the input date.
+ * - Q1 = months 1-3, Q2 = months 4-6, Q3 = months 7-9, Q4 = months 10-12.
+ * - Validates input using isValidDate.
+ *
+ * @param value ISO PlainDate string
+ * @returns number (1-4) or null for invalid input
+ *
+ * @example getQuarterForDate("2024-01-15") // 1
+ * @example getQuarterForDate("2024-04-15") // 2
+ * @example getQuarterForDate("2024-07-15") // 3
+ * @example getQuarterForDate("2024-10-15") // 4
+ * @example getQuarterForDate("invalid") // null
+ */
+export declare function getQuarterForDate(value: string): number | null;

package/dist/plain/calculate/getQuarterForDate.js

@@ -0,0 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the quarter of the year (1-4) for a given ISO date.
+ *
+ * - Returns the quarter (1-4) containing the input date.
+ * - Q1 = months 1-3, Q2 = months 4-6, Q3 = months 7-9, Q4 = months 10-12.
+ * - Validates input using isValidDate.
+ *
+ * @param value ISO PlainDate string
+ * @returns number (1-4) or null for invalid input
+ *
+ * @example getQuarterForDate("2024-01-15") // 1
+ * @example getQuarterForDate("2024-04-15") // 2
+ * @example getQuarterForDate("2024-07-15") // 3
+ * @example getQuarterForDate("2024-10-15") // 4
+ * @example getQuarterForDate("invalid") // null
+ */
+export function getQuarterForDate(value) {
+    if (!isValidDate(value)) {
+        return null;
+    }
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return Math.floor((date.month - 1) / 3) + 1;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/calculate/getQuarterForDateTime.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Return the quarter of the year (1-4) for a given ISO datetime.
+ *
+ * - Returns the quarter (1-4) containing the input datetime.
+ * - Q1 = months 1-3, Q2 = months 4-6, Q3 = months 7-9, Q4 = months 10-12.
+ * - Validates input using isValidDateTime.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns number (1-4) or null for invalid input
+ *
+ * @example getQuarterForDateTime("2024-01-15T12:00:00") // 1
+ * @example getQuarterForDateTime("2024-04-15T12:00:00") // 2
+ * @example getQuarterForDateTime("2024-07-15T12:00:00") // 3
+ * @example getQuarterForDateTime("2024-10-15T12:00:00") // 4
+ * @example getQuarterForDateTime("invalid") // null
+ */
+export declare function getQuarterForDateTime(value: string): number | null;

package/dist/plain/calculate/getQuarterForDateTime.js

@@ -0,0 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the quarter of the year (1-4) for a given ISO datetime.
+ *
+ * - Returns the quarter (1-4) containing the input datetime.
+ * - Q1 = months 1-3, Q2 = months 4-6, Q3 = months 7-9, Q4 = months 10-12.
+ * - Validates input using isValidDateTime.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns number (1-4) or null for invalid input
+ *
+ * @example getQuarterForDateTime("2024-01-15T12:00:00") // 1
+ * @example getQuarterForDateTime("2024-04-15T12:00:00") // 2
+ * @example getQuarterForDateTime("2024-07-15T12:00:00") // 3
+ * @example getQuarterForDateTime("2024-10-15T12:00:00") // 4
+ * @example getQuarterForDateTime("invalid") // null
+ */
+export function getQuarterForDateTime(value) {
+    if (!isValidDateTime(value)) {
+        return null;
+    }
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        return Math.floor((dateTime.month - 1) / 3) + 1;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/calculate/getWeekNumber.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Calculate the week number based on configurable week start day.
+ *
+ * - ISO (monday): Week 1 is the week containing the first Thursday (has at least 4 days in the year)
+ * - US (sunday): Week 1 is the week containing Jan 1 (first week has at least 1 day)
+ *
+ * @param dateStr ISO PlainDate string (e.g. "2024-03-15")
+ * @param weekStartsOn optional: "monday" (default) or "sunday"
+ * @returns Week number (1-53), or null on invalid input
+ *
+ * @example getWeekNumber("2024-01-01") // 1
+ * @example getWeekNumber("2024-01-08") // 2
+ * @example getWeekNumber("2024-12-31") // 1
+ * @example getWeekNumber("2024-01-01", "sunday") // 1
+ * @example getWeekNumber("invalid") // null
+ */
+export declare function getWeekNumber(dateStr: string, weekStartsOn?: "monday" | "sunday"): number | null;

package/dist/plain/calculate/getWeekNumber.js

@@ -0,0 +1,39 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Calculate the week number based on configurable week start day.
+ *
+ * - ISO (monday): Week 1 is the week containing the first Thursday (has at least 4 days in the year)
+ * - US (sunday): Week 1 is the week containing Jan 1 (first week has at least 1 day)
+ *
+ * @param dateStr ISO PlainDate string (e.g. "2024-03-15")
+ * @param weekStartsOn optional: "monday" (default) or "sunday"
+ * @returns Week number (1-53), or null on invalid input
+ *
+ * @example getWeekNumber("2024-01-01") // 1
+ * @example getWeekNumber("2024-01-08") // 2
+ * @example getWeekNumber("2024-12-31") // 1
+ * @example getWeekNumber("2024-01-01", "sunday") // 1
+ * @example getWeekNumber("invalid") // null
+ */
+export function getWeekNumber(dateStr, weekStartsOn = "monday") {
+    try {
+        const date = Temporal.PlainDate.from(dateStr);
+        if (weekStartsOn === "monday") {
+            const isoWeek = date.weekOfYear;
+            return isoWeek ?? null;
+        }
+        const yearStart = Temporal.PlainDate.from({
+            year: date.year,
+            month: 1,
+            day: 1,
+        });
+        const firstDayOfWeek = yearStart.dayOfWeek;
+        const daysSinceSunday = firstDayOfWeek === 7 ? 0 : firstDayOfWeek;
+        const daysSinceJan1 = date.dayOfYear - 1;
+        const result = Math.floor((daysSinceJan1 + daysSinceSunday) / 7) + 1;
+        return result;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/calculate/getWeekOfMonth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Return the 1-based row `value` falls on within its month's calendar
+ * grid, using `locale`'s first day of week.
+ *
+ * - Week 1 is the row containing the 1st of the month, even when that row
+ *   is a partial week (matches date-fns's `getWeekOfMonth`, verified
+ *   against date-fns source 2026-08-21) — this is the convention every
+ *   calendar-grid UI (and `@internationalized/date`'s `getWeeksInMonth`)
+ *   expects for sizing a month grid.
+ * - Distinct from ISO `weekOfYear`: this counts rows within a single
+ *   month's grid, reset every month, rather than weeks since Jan 1.
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns 1-based week-of-month row, or null on invalid input
+ *
+ * @example getWeekOfMonth("2024-02-01", "en-US") // 1
+ * @example getWeekOfMonth("2024-02-29", "en-US") // 5
+ * @example getWeekOfMonth("2026-02-01", "en-US") // 1
+ * @example getWeekOfMonth("2026-02-01", "en-GB") // 1
+ * @example getWeekOfMonth("invalid", "en-US") // null
+ */
+export declare function getWeekOfMonth(value: string, locale: string): number | null;

package/dist/plain/calculate/getWeekOfMonth.js

@@ -0,0 +1,43 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek, monthGridWeekRow } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the 1-based row `value` falls on within its month's calendar
+ * grid, using `locale`'s first day of week.
+ *
+ * - Week 1 is the row containing the 1st of the month, even when that row
+ *   is a partial week (matches date-fns's `getWeekOfMonth`, verified
+ *   against date-fns source 2026-08-21) — this is the convention every
+ *   calendar-grid UI (and `@internationalized/date`'s `getWeeksInMonth`)
+ *   expects for sizing a month grid.
+ * - Distinct from ISO `weekOfYear`: this counts rows within a single
+ *   month's grid, reset every month, rather than weeks since Jan 1.
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns 1-based week-of-month row, or null on invalid input
+ *
+ * @example getWeekOfMonth("2024-02-01", "en-US") // 1
+ * @example getWeekOfMonth("2024-02-29", "en-US") // 5
+ * @example getWeekOfMonth("2026-02-01", "en-US") // 1
+ * @example getWeekOfMonth("2026-02-01", "en-GB") // 1
+ * @example getWeekOfMonth("invalid", "en-US") // null
+ */
+export function getWeekOfMonth(value, locale) {
+    if (!isValidDate(value))
+        return null;
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const firstOfMonth = date.with({ day: 1 });
+        return monthGridWeekRow(firstOfMonth, firstDay, date.day);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/calculate/getWeekYear.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return the ISO 8601 week-numbering year `value` belongs to.
+ *
+ * - Distinct from `value`'s calendar year — late-December/early-January
+ *   dates can belong to a different ISO week-year than their calendar
+ *   year (e.g. 2024-12-30 is a Monday in ISO week 1 of **2025**).
+ *   Pair this with `weekOfYearForDate` when bucketing by week: a week
+ *   number alone is ambiguous without the week-year it belongs to.
+ * - Uses `Temporal.PlainDate.yearOfWeek` (ISO weeks: Monday-start, week 1
+ *   contains the year's first Thursday).
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns ISO week-numbering year, or null on invalid input
+ *
+ * @example getWeekYear("2024-06-15") // 2024
+ * @example getWeekYear("2024-12-30") // 2025 (Monday of ISO week 1, 2025)
+ * @example getWeekYear("2021-01-01") // 2020 (belongs to ISO week 53 of 2020)
+ * @example getWeekYear("invalid") // null
+ */
+export declare function getWeekYear(value: string): number | null;

package/dist/plain/calculate/getWeekYear.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the ISO 8601 week-numbering year `value` belongs to.
+ *
+ * - Distinct from `value`'s calendar year — late-December/early-January
+ *   dates can belong to a different ISO week-year than their calendar
+ *   year (e.g. 2024-12-30 is a Monday in ISO week 1 of **2025**).
+ *   Pair this with `weekOfYearForDate` when bucketing by week: a week
+ *   number alone is ambiguous without the week-year it belongs to.
+ * - Uses `Temporal.PlainDate.yearOfWeek` (ISO weeks: Monday-start, week 1
+ *   contains the year's first Thursday).
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns ISO week-numbering year, or null on invalid input
+ *
+ * @example getWeekYear("2024-06-15") // 2024
+ * @example getWeekYear("2024-12-30") // 2025 (Monday of ISO week 1, 2025)
+ * @example getWeekYear("2021-01-01") // 2020 (belongs to ISO week 53 of 2020)
+ * @example getWeekYear("invalid") // null
+ */
+export function getWeekYear(value) {
+    if (!isValidDate(value))
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return date.yearOfWeek ?? null;
+    }
+    catch {
+        return null;
+    }
+}