@timestamp-js/core 0.1.0-rc.2 → 0.1.0-rc.3

package/dist/index.js

@@ -1,5 +1,64 @@
-import { formatCalendarDate, gregorianCalendar } from './calendar.js';
-export { formatCalendarDate, gregorianCalendar } from './calendar.js';
+import { formatCalendarDate as formatCalendarDateImpl, getCalendarDirection as getCalendarDirectionImpl, getCalendarLocale as getCalendarLocaleImpl, getCalendarWeekdays as getCalendarWeekdaysImpl, gregorianCalendar, isCalendarRTL as isCalendarRTLImpl, } from './calendar.js';
+export { gregorianCalendar } from './calendar.js';
+/**
+ * Formats calendar fields using Timestamp's fixed `YYYY-MM-DD` date format.
+ *
+ * @param date Plain calendar date fields.
+ * @returns Date string in `YYYY-MM-DD` form.
+ * @category calendar
+ */
+export function formatCalendarDate(date) {
+    return formatCalendarDateImpl(date);
+}
+/**
+ * Returns the recommended locale for a calendar system.
+ *
+ * Calendar adapters can use this to publish their normal display locale. Callers can still pass
+ * an explicit locale when an application needs a different language or numbering presentation.
+ *
+ * @param {CalendarSystem=} calendar Calendar system to read. Defaults to Gregorian.
+ * @returns {string} BCP 47 locale, defaulting to `en-US`.
+ * @category calendar
+ */
+export function getCalendarLocale(calendar = gregorianCalendar) {
+    return getCalendarLocaleImpl(calendar);
+}
+/**
+ * Returns the recommended text direction for a calendar system.
+ *
+ * Calendar adapters can use this to publish their normal left-to-right or right-to-left
+ * presentation. Callers can still pass an explicit direction when an application needs one.
+ *
+ * @param {CalendarSystem=} calendar Calendar system to read. Defaults to Gregorian.
+ * @returns {CalendarDirection} `ltr` or `rtl`, defaulting to `ltr`.
+ * @category calendar
+ */
+export function getCalendarDirection(calendar = gregorianCalendar) {
+    return getCalendarDirectionImpl(calendar);
+}
+/**
+ * Returns true when a calendar system recommends right-to-left presentation.
+ *
+ * @param {CalendarSystem=} calendar Calendar system to read. Defaults to Gregorian.
+ * @returns {boolean} True when the recommended direction is `rtl`.
+ * @category calendar
+ */
+export function isCalendarRTL(calendar = gregorianCalendar) {
+    return isCalendarRTLImpl(calendar);
+}
+/**
+ * Returns the recommended visible weekday order for a calendar system.
+ *
+ * Calendar adapters can use this to publish their normal visible week. Callers can still pass an
+ * explicit weekday list for application-specific layouts such as a five-day work week.
+ *
+ * @param {CalendarSystem=} calendar Calendar system to read. Defaults to Gregorian.
+ * @returns {number[]} Weekday numbers where Sunday is `0` and Saturday is `6`.
+ * @category calendar
+ */
+export function getCalendarWeekdays(calendar = gregorianCalendar) {
+    return getCalendarWeekdaysImpl(calendar);
+}
 /**
  * Matches supported date and date-time input.
  *
@@ -259,26 +318,27 @@ export function parsed(input) {
     timestamp.time = getTime(timestamp);
     return freezeTimestamp(timestamp);
 }
-function parseDateByMode(date, utc) {
+function parseDateByMode(date, utc, calendar = gregorianCalendar) {
     if (!(date instanceof Date))
         return null;
     if (Number.isNaN(date.getTime()))
         return null;
     const UTC = utc ? 'UTC' : '';
+    const gregorian = {
+        year: date[`get${UTC}FullYear`](),
+        month: date[`get${UTC}Month`]() + 1,
+        day: date[`get${UTC}Date`](),
+    };
     const second = date[`get${UTC}Seconds`]();
     const millisecond = date[`get${UTC}Milliseconds`]();
     const timestamp = {
-        date: padNumber(date[`get${UTC}FullYear`](), 4) +
-            '-' +
-            padNumber(date[`get${UTC}Month`]() + 1, 2) +
-            '-' +
-            padNumber(date[`get${UTC}Date`](), 2),
+        date: formatCalendarDate(gregorian),
         time: padNumber(date[`get${UTC}Hours`]() || 0, 2) +
             ':' +
             padNumber(date[`get${UTC}Minutes`]() || 0, 2),
-        year: date[`get${UTC}FullYear`](),
-        month: date[`get${UTC}Month`]() + 1,
-        day: date[`get${UTC}Date`](),
+        year: gregorian.year,
+        month: gregorian.month,
+        day: gregorian.day,
         hour: date[`get${UTC}Hours`](),
         minute: date[`get${UTC}Minutes`](),
         weekday: 0,
@@ -297,7 +357,13 @@ function parseDateByMode(date, utc) {
     if (millisecond !== 0) {
         timestamp.millisecond = millisecond;
     }
-    return updateFormatted(timestamp);
+    const formatted = updateFormatted(timestamp);
+    if (calendar === gregorianCalendar) {
+        return formatted;
+    }
+    return createCalendarTimestampFromEpochDay(gregorianCalendar.toEpochDay(gregorian), calendar, {
+        ...getCalendarTimestampOptions(formatted),
+    });
 }
 /**
  * Converts a JavaScript Date into a formatted Timestamp using host-local fields.
@@ -306,11 +372,12 @@ function parseDateByMode(date, utc) {
  * with UTC getters instead of host-local getters.
  *
  * @param {Date} date JavaScript Date to convert.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} Formatted Timestamp object, or `null` for invalid input.
  * @category parsing
  */
-export function parseDate(date) {
-    return parseDateByMode(date, false);
+export function parseDate(date, calendar = gregorianCalendar) {
+    return parseDateByMode(date, false, calendar);
 }
 /**
  * Converts a JavaScript Date into a formatted Timestamp using UTC fields.
@@ -319,11 +386,12 @@ export function parseDate(date) {
  * and time fields for a native Date instant.
  *
  * @param {Date} date JavaScript Date to convert.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} Formatted Timestamp object, or `null` for invalid input.
  * @category parsing
  */
-export function parseDateUTC(date) {
-    return parseDateByMode(date, true);
+export function parseDateUTC(date, calendar = gregorianCalendar) {
+    return parseDateByMode(date, true, calendar);
 }
 /**
  * Pads a number to a requested string length.
@@ -344,85 +412,86 @@ export function padNumber(x, length) {
 /**
  * Returns if the passed year is a leap year
  * @param {number} year The year to check (ie: 1999, 2020)
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {boolean} True if the year is a leap year
  * @category calendar
  */
-export function isLeapYear(year) {
-    return gregorianCalendar.isLeapYear(year);
+export function isLeapYear(year, calendar = gregorianCalendar) {
+    return calendar.isLeapYear(year);
 }
 /**
  * Returns the days of the specified month in a year
  * @param {number} year The year (ie: 1999, 2020)
- * @param {number} month The Gregorian month number, where January is `1`
+ * @param {number} month The month number in the selected calendar, where January is `1` for Gregorian.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {number} The number of days in the month (corrected for leap years)
  * @category calendar
  */
-export function daysInMonth(year, month) {
-    return gregorianCalendar.daysInMonth(year, month);
+export function daysInMonth(year, month, calendar = gregorianCalendar) {
+    return calendar.daysInMonth(year, month);
 }
 /**
  * Returns a new Timestamp for the next calendar day.
  *
  * @param {Timestamp} timestamp Base Timestamp object.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} New Timestamp representing the next day.
  * @category arithmetic
  */
-export function nextDay(timestamp) {
-    const date = gregorianCalendar.nextDay(toCalendarDateParts(timestamp));
-    return updateFormatted(normalizeTimestamp({
-        ...timestamp,
-        year: date.year,
-        month: date.month,
-        day: date.day,
-    }));
+export function nextDay(timestamp, calendar = gregorianCalendar) {
+    return nextCalendarDay(timestamp, calendar);
 }
 /**
  * Returns a new Timestamp for the previous calendar day.
  *
  * @param {Timestamp} timestamp Base Timestamp object.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} New Timestamp representing the previous day.
  * @category arithmetic
  */
-export function prevDay(timestamp) {
-    const date = gregorianCalendar.prevDay(toCalendarDateParts(timestamp));
-    return updateFormatted(normalizeTimestamp({
-        ...timestamp,
-        year: date.year,
-        month: date.month,
-        day: date.day,
-    }));
+export function prevDay(timestamp, calendar = gregorianCalendar) {
+    return prevCalendarDay(timestamp, calendar);
+}
+function formatCalendarDateFromDate(date, utc, calendar = gregorianCalendar) {
+    const UTC = utc ? 'UTC' : '';
+    const gregorian = {
+        year: date[`get${UTC}FullYear`](),
+        month: date[`get${UTC}Month`]() + 1,
+        day: date[`get${UTC}Date`](),
+    };
+    const epochDay = gregorianCalendar.toEpochDay(gregorian);
+    return formatCalendarDate(calendar.fromEpochDay(epochDay));
 }
 /**
  * Returns today's date using the host runtime timezone.
  *
  * For SSR or static rendering, server and client runtimes can produce different
  * values when they run in different timezones. Use todayUTC() when the app
- * wants a stable UTC calendar date instead.
+ * wants a stable UTC calendar date instead. Pass a calendar system to return
+ * today's date in that calendar's native `YYYY-MM-DD` fields.
  *
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {string} Date string in the form `YYYY-MM-DD`
  * @category state
  */
-export function today() {
-    const d = new Date(), month = d.getMonth() + 1, day = d.getDate(), year = d.getFullYear();
-    return [year, padNumber(month, 2), padNumber(day, 2)].join('-');
+export function today(calendar = gregorianCalendar) {
+    return formatCalendarDateFromDate(new Date(), false, calendar);
 }
 /**
  * Returns today's date using UTC calendar fields.
  *
  * Pass a Date fixture to make SSR, tests, and hydration-sensitive render paths
  * deterministic. This helper reads UTC fields only; it does not convert an
- * existing Timestamp or timezone-suffixed string.
+ * existing Timestamp or timezone-suffixed string. Pass a calendar system to
+ * return today's UTC date in that calendar's native `YYYY-MM-DD` fields.
  *
  * @param {Date} date Date source to read. Defaults to the current Date.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {string} UTC date string in the form `YYYY-MM-DD`
  * @category state
  */
-export function todayUTC(date = new Date()) {
-    return [
-        padNumber(date.getUTCFullYear(), 4),
-        padNumber(date.getUTCMonth() + 1, 2),
-        padNumber(date.getUTCDate(), 2),
-    ].join('-');
+export function todayUTC(date = new Date(), calendar = gregorianCalendar) {
+    return formatCalendarDateFromDate(date, true, calendar);
 }
 /**
  * Returns the current date-time as an immutable Timestamp using UTC fields.
@@ -432,20 +501,22 @@ export function todayUTC(date = new Date()) {
  * caller instead of allowing each runtime to create its own current Date.
  *
  * @param {Date} date Date source to read. Defaults to the current Date.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} Immutable Timestamp built from UTC fields.
  * @category state
  */
-export function nowUTC(date = new Date()) {
-    return parseDateUTC(date);
+export function nowUTC(date = new Date(), calendar = gregorianCalendar) {
+    return parseDateUTC(date, calendar);
 }
 /**
  * Takes a date string ('YYYY-MM-DD') and validates if it is today's date
  * @param {string} date Date string in the form 'YYYY-MM-DD'
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {boolean} True if the date is today's date
  * @category comparison
  */
-export function isToday(date) {
-    return date === today();
+export function isToday(date, calendar = gregorianCalendar) {
+    return date === today(calendar);
 }
 /**
  * Checks whether a date string matches today's UTC date.
@@ -455,11 +526,12 @@ export function isToday(date) {
  *
  * @param {string} date Date string in the form `YYYY-MM-DD`.
  * @param {Date} now Date source to read. Defaults to the current Date.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {boolean} True when the date matches the UTC date.
  * @category comparison
  */
-export function isTodayUTC(date, now = new Date()) {
-    return date === todayUTC(now);
+export function isTodayUTC(date, now = new Date(), calendar = gregorianCalendar) {
+    return date === todayUTC(now, calendar);
 }
 /**
  * Returns the start of the week for a Timestamp and weekday set.
@@ -467,25 +539,12 @@ export function isTodayUTC(date, now = new Date()) {
  * @param {Timestamp} timestamp The Timestamp to use to find the start of the week
  * @param {number[]} weekdays The array is [0,1,2,3,4,5,6] where 0=Sunday and 6=Saturday
  * @param {Timestamp=} today Current timestamp used to update relative information
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} A new Timestamp representing the start of the week
  * @category ranges
  */
-export function getStartOfWeek(timestamp, weekdays, today) {
-    let start = cloneTimestamp(timestamp);
-    if (!weekdays) {
-        return freezeTimestamp(start);
-    }
-    if (start.day === 1 || start.weekday === 0) {
-        while (!weekdays.includes(Number(start.weekday))) {
-            start = nextDay(start);
-        }
-    }
-    start = findWeekday(start, weekdays[0], prevDay);
-    start = updateFormatted(start);
-    if (today) {
-        start = updateRelative(start, today, start.hasTime);
-    }
-    return start;
+export function getStartOfWeek(timestamp, weekdays, today, calendar = gregorianCalendar) {
+    return getCalendarStartOfWeek(timestamp, weekdays, calendar, today);
 }
 /**
  * Returns the end of the week for a Timestamp and weekday set.
@@ -493,51 +552,32 @@ export function getStartOfWeek(timestamp, weekdays, today) {
  * @param {Timestamp} timestamp The Timestamp to use to find the end of the week
  * @param {number[]} weekdays The array is [0,1,2,3,4,5,6] where 0=Sunday and 6=Saturday
  * @param {Timestamp=} today Current timestamp used to update relative information
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} A new Timestamp representing the end of the week
  * @category ranges
  */
-export function getEndOfWeek(timestamp, weekdays, today) {
-    let end = cloneTimestamp(timestamp);
-    if (!weekdays || !Array.isArray(weekdays)) {
-        return freezeTimestamp(end);
-    }
-    // is last day of month?
-    const lastDay = daysInMonth(end.year, end.month);
-    if (lastDay === end.day || end.weekday === weekdays[weekdays.length - 1]) {
-        while (!weekdays.includes(Number(end.weekday))) {
-            end = prevDay(end);
-        }
-    }
-    end = findWeekday(end, weekdays[weekdays.length - 1], nextDay);
-    end = updateFormatted(end);
-    if (today) {
-        end = updateRelative(end, today, end.hasTime);
-    }
-    return end;
+export function getEndOfWeek(timestamp, weekdays, today, calendar = gregorianCalendar) {
+    return getCalendarEndOfWeek(timestamp, weekdays, calendar, today);
 }
 /**
  * Finds the start of the month based on the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use to find the start of the month
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} A Timestamp of the start of the month
  * @category ranges
  */
-export function getStartOfMonth(timestamp) {
-    let start = cloneTimestamp(timestamp);
-    start.day = DAY_MIN;
-    start = updateFormatted(start);
-    return start;
+export function getStartOfMonth(timestamp, calendar = gregorianCalendar) {
+    return getCalendarStartOfMonth(timestamp, calendar);
 }
 /**
  * Finds the end of the month based on the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use to find the end of the month
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} A Timestamp of the end of the month
  * @category ranges
  */
-export function getEndOfMonth(timestamp) {
-    let end = cloneTimestamp(timestamp);
-    end.day = daysInMonth(end.year, end.month);
-    end = updateFormatted(end);
-    return end;
+export function getEndOfMonth(timestamp, calendar = gregorianCalendar) {
+    return getCalendarEndOfMonth(timestamp, calendar);
 }
 /**
  * Converts time input into minutes since midnight.
@@ -671,7 +711,7 @@ export function getDayIdentifier(timestamp) {
  * same serial day space so ranges and comparisons can be calendar-agnostic.
  *
  * @param {Timestamp} timestamp Timestamp object to read.
- * @param {CalendarSystem=} calendar Calendar implementation to use.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {number} Stable serial day.
  * @category conversion
  */
@@ -685,18 +725,43 @@ export function getEpochDay(timestamp, calendar = gregorianCalendar) {
  * range comparisons, or virtualized day rows across different calendar adapters.
  *
  * @param timestamp Timestamp object to read.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns Stable serial day.
  * @category calendar
  */
 export function getCalendarDayIdentifier(timestamp, calendar = gregorianCalendar) {
     return getEpochDay(timestamp, calendar);
 }
+/**
+ * Creates stable native and Gregorian identities for a calendar timestamp.
+ *
+ * Use this when component APIs need to expose adapter-native values while also
+ * preserving a canonical Gregorian key for storage, comparisons, or interop
+ * with existing data.
+ *
+ * @param timestamp Timestamp object to identify.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns Calendar-native date, Gregorian interop date, and shared epoch day.
+ * @category calendar
+ */
+export function getCalendarDateIdentity(timestamp, calendar = gregorianCalendar) {
+    const native = toCalendarDateParts(timestamp);
+    const epochDay = calendar.toEpochDay(native);
+    const gregorian = gregorianCalendar.fromEpochDay(epochDay);
+    return Object.freeze({
+        calendarId: calendar.id,
+        nativeDate: formatCalendarDate(native),
+        native,
+        gregorianDate: formatCalendarDate(gregorian),
+        gregorian,
+        epochDay,
+    });
+}
 /**
  * Returns true when calendar date fields are valid for a calendar system.
  *
  * @param date Calendar date fields to validate.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns True when year, month, and day can exist in the calendar.
  * @category calendar
  */
@@ -714,7 +779,7 @@ export function isValidCalendarDate(date, calendar = gregorianCalendar) {
  * `calendarId`, and derives weekday/day-of-year values from the adapter.
  *
  * @param date Calendar date fields.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param options Optional time and relative comparison settings.
  * @returns Timestamp-shaped calendar value.
  * @category calendar
@@ -760,7 +825,7 @@ export function createCalendarTimestamp(date, calendar = gregorianCalendar, opti
  * calendar and derives weekday/day-of-year values through the adapter.
  *
  * @param input Date or date-time string.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param now Optional comparison timestamp from the same calendar system.
  * @returns Calendar timestamp, or `null` when the input cannot be parsed or validated.
  * @category calendar
@@ -777,11 +842,26 @@ export function parseCalendarTimestamp(input, calendar = gregorianCalendar, now
         now,
     });
 }
+/**
+ * Validates whether an input string can be parsed as a calendar adapter timestamp.
+ *
+ * The default Gregorian calendar preserves existing Timestamp semantics. When
+ * an alternate calendar is supplied, `YYYY-MM-DD` is interpreted as native to
+ * that adapter.
+ *
+ * @param input Date or date-time string.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns True when the string can be parsed and exists in the calendar.
+ * @category calendar
+ */
+export function validateCalendarTimestamp(input, calendar = gregorianCalendar) {
+    return parseCalendarTimestamp(input, calendar) !== null;
+}
 /**
  * Creates a calendar timestamp from a stable serial day.
  *
  * @param epochDay Stable serial day.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param options Optional time and relative comparison settings.
  * @returns Timestamp-shaped calendar value.
  * @category calendar
@@ -793,7 +873,7 @@ export function createCalendarTimestampFromEpochDay(epochDay, calendar = gregori
  * Updates formatted calendar metadata on a timestamp-shaped value.
  *
  * @param timestamp Timestamp object to transform.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns Timestamp with adapter date formatting and metadata.
  * @category calendar
  */
@@ -805,7 +885,7 @@ export function updateCalendarFormatted(timestamp, calendar = gregorianCalendar)
  *
  * @param timestamp Timestamp object to update.
  * @param now Timestamp representing the comparison point in the same calendar.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param time Include time-of-day in the comparison when true.
  * @returns New Timestamp object with relative flags.
  * @category calendar
@@ -830,7 +910,7 @@ export function updateCalendarRelative(timestamp, now, calendar = gregorianCalen
  * Returns a calendar timestamp for the next day.
  *
  * @param timestamp Base timestamp.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns New timestamp for the next adapter day.
  * @category calendar
  */
@@ -841,7 +921,7 @@ export function nextCalendarDay(timestamp, calendar = gregorianCalendar) {
  * Returns a calendar timestamp for the previous day.
  *
  * @param timestamp Base timestamp.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns New timestamp for the previous adapter day.
  * @category calendar
  */
@@ -853,7 +933,7 @@ export function prevCalendarDay(timestamp, calendar = gregorianCalendar) {
  *
  * @param timestamp Base timestamp.
  * @param amount Number of days to move.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns New timestamp after moving.
  * @category calendar
  */
@@ -865,7 +945,7 @@ export function addCalendarDays(timestamp, amount, calendar = gregorianCalendar)
  *
  * @param timestamp Base timestamp.
  * @param amount Number of calendar months to move.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns New timestamp after moving.
  * @category calendar
  */
@@ -896,7 +976,7 @@ export function addCalendarMonths(timestamp, amount, calendar = gregorianCalenda
  *
  * @param timestamp Base timestamp.
  * @param amount Number of calendar years to move.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns New timestamp after moving.
  * @category calendar
  */
@@ -911,7 +991,7 @@ export function addCalendarYears(timestamp, amount, calendar = gregorianCalendar
  * Returns the start of the calendar month for a timestamp.
  *
  * @param timestamp Base timestamp.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns First day of the adapter month.
  * @category calendar
  */
@@ -922,7 +1002,7 @@ export function getCalendarStartOfMonth(timestamp, calendar = gregorianCalendar)
  * Returns the end of the calendar month for a timestamp.
  *
  * @param timestamp Base timestamp.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns Last day of the adapter month.
  * @category calendar
  */
@@ -937,7 +1017,7 @@ export function getCalendarEndOfMonth(timestamp, calendar = gregorianCalendar) {
  * Returns the start of the calendar year for a timestamp.
  *
  * @param timestamp Base timestamp.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns First day of the adapter year.
  * @category calendar
  */
@@ -948,7 +1028,7 @@ export function getCalendarStartOfYear(timestamp, calendar = gregorianCalendar)
  * Returns the end of the calendar year for a timestamp.
  *
  * @param timestamp Base timestamp.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns Last day of the adapter year.
  * @category calendar
  */
@@ -961,7 +1041,7 @@ export function getCalendarEndOfYear(timestamp, calendar = gregorianCalendar) {
  *
  * @param timestamp Base timestamp.
  * @param weekday Weekday number to find.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param direction Direction to search.
  * @param maxDays Maximum days to inspect.
  * @returns Matching timestamp, or the last inspected timestamp.
@@ -980,7 +1060,7 @@ export function findCalendarWeekday(timestamp, weekday, calendar = gregorianCale
  *
  * @param timestamp Base timestamp.
  * @param weekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param now Optional comparison timestamp from the same calendar.
  * @returns Start of the adapter week.
  * @category calendar
@@ -1003,7 +1083,7 @@ export function getCalendarStartOfWeek(timestamp, weekdays, calendar = gregorian
  *
  * @param timestamp Base timestamp.
  * @param weekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param now Optional comparison timestamp from the same calendar.
  * @returns End of the adapter week.
  * @category calendar
@@ -1028,7 +1108,7 @@ export function getCalendarEndOfWeek(timestamp, weekdays, calendar = gregorianCa
  * @param start First day in the list.
  * @param end Last day boundary for the list.
  * @param now Timestamp used to calculate relative flags.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param options Optional weekday, disabled, and size filters.
  * @returns Timestamp days for the adapter calendar.
  * @category calendar
@@ -1056,12 +1136,28 @@ export function createCalendarDayList(start, end, now, calendar = gregorianCalen
         }
         let day = updateCalendarFormatted(current, calendar);
         day = updateCalendarRelative(day, now, calendar);
-        day = updateDisabled(day, disabledBefore, disabledAfter, disabledWeekdays, disabledDays);
+        day = updateCalendarDisabled(day, disabledBefore, disabledAfter, disabledWeekdays, disabledDays, calendar);
         days.push(day);
         current = nextCalendarDay(current, calendar);
     }
     return days;
 }
+/**
+ * Returns true when a timestamp falls outside the reference timestamp's adapter month.
+ *
+ * @param timestamp Timestamp to test.
+ * @param reference Timestamp whose month defines the inside range.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns True when timestamp is outside reference's calendar month.
+ * @category calendar
+ */
+export function isOutsideCalendarMonth(timestamp, reference, calendar = gregorianCalendar) {
+    const start = getCalendarStartOfMonth(reference, calendar);
+    const end = getCalendarEndOfMonth(reference, calendar);
+    const targetIdentifier = getCalendarDayIdentifier(timestamp, calendar);
+    return (targetIdentifier < getCalendarDayIdentifier(start, calendar) ||
+        targetIdentifier > getCalendarDayIdentifier(end, calendar));
+}
 /**
  * Converts a Timestamp time into a sortable numeric identifier.
  *
@@ -1117,13 +1213,14 @@ export function diffTimestamp(ts1, ts2, strict = false) {
  * @param {Timestamp} timestamp Timestamp object to update.
  * @param {Timestamp} now Timestamp representing the comparison point.
  * @param {boolean=} time Include time-of-day in the comparison when true.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} New Timestamp object with relative flags.
  * @category state
  */
-export function updateRelative(timestamp, now, time = false) {
+export function updateRelative(timestamp, now, time = false, calendar = gregorianCalendar) {
     const ts = cloneTimestamp(timestamp);
-    let a = getDayIdentifier(now);
-    let b = getDayIdentifier(ts);
+    let a = getCalendarDayIdentifier(now, calendar);
+    let b = getCalendarDayIdentifier(ts, calendar);
     let current = a === b;
     if (ts.hasTime && time && current) {
         a = getTimeComparisonValue(now);
@@ -1145,10 +1242,11 @@ export function updateRelative(timestamp, now, time = false) {
  * @param {Timestamp} timestamp The Timestamp to transform
  * @param {number} minutes The number of minutes to set from midnight
  * @param {Timestamp=} now Optional Timestamp representing current date and time
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} A new Timestamp
  * @category arithmetic
  */
-export function updateMinutes(timestamp, minutes, now = null) {
+export function updateMinutes(timestamp, minutes, now = null, calendar = gregorianCalendar) {
     let ts = cloneTimestamp(timestamp);
     ts.hasTime = true;
     ts.hour = Math.floor(minutes / TIME_CONSTANTS.MINUTES_IN.HOUR);
@@ -1157,41 +1255,44 @@ export function updateMinutes(timestamp, minutes, now = null) {
     delete ts.millisecond;
     ts.time = getTime(ts);
     if (now) {
-        return updateRelative(ts, now, true);
+        return updateRelative(ts, now, true, calendar);
     }
     return freezeTimestamp(ts);
 }
 /**
  * Updates the Timestamp with the weekday
  * @param {Timestamp} timestamp The Timestamp to transform
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns A new Timestamp
  * @category formatting
  */
-export function updateWeekday(timestamp) {
+export function updateWeekday(timestamp, calendar = gregorianCalendar) {
     const ts = cloneTimestamp(timestamp);
-    ts.weekday = getWeekday(ts);
+    ts.weekday = getWeekday(ts, calendar);
     return freezeTimestamp(ts);
 }
 /**
  * Updates the Timestamp with the day of the year (doy)
  * @param {Timestamp} timestamp The Timestamp to transform
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns A new Timestamp
  * @category formatting
  */
-export function updateDayOfYear(timestamp) {
+export function updateDayOfYear(timestamp, calendar = gregorianCalendar) {
     const ts = cloneTimestamp(timestamp);
-    ts.doy = getDayOfYear(ts) || 0;
+    ts.doy = getDayOfYear(ts, calendar) || 0;
     return freezeTimestamp(ts);
 }
 /**
  * Updates the Timestamp with the workweek
  * @param {Timestamp} timestamp The Timestamp to transform
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns A new Timestamp
  * @category formatting
  */
-export function updateWorkWeek(timestamp) {
+export function updateWorkWeek(timestamp, calendar = gregorianCalendar) {
     const ts = cloneTimestamp(timestamp);
-    ts.workweek = getWorkWeek(ts);
+    ts.workweek = getWorkWeek(ts, calendar);
     return freezeTimestamp(ts);
 }
 function isDisabledDayConfig(value) {
@@ -1239,6 +1340,42 @@ function isTimestampInDisabledDay(timestamp, day) {
     const disabledDay = parseTimestamp(day);
     return disabledDay !== null && getDayIdentifier(disabledDay) === target;
 }
+function parseCalendarDateIdentifier(value, calendar) {
+    const timestamp = parseCalendarTimestamp(value, calendar);
+    return timestamp === null ? null : getCalendarDayIdentifier(timestamp, calendar);
+}
+function isTimestampInCalendarDisabledDay(timestamp, day, calendar) {
+    const target = getCalendarDayIdentifier(timestamp, calendar);
+    if (Array.isArray(day) === true) {
+        if (day.length === 2 && day[0] && day[1]) {
+            const start = parseCalendarDateIdentifier(day[0], calendar);
+            const end = parseCalendarDateIdentifier(day[1], calendar);
+            return (start !== null &&
+                end !== null &&
+                target >= Math.min(start, end) &&
+                target <= Math.max(start, end));
+        }
+        return day.some((date) => parseCalendarDateIdentifier(date, calendar) === target);
+    }
+    if (isDisabledDayConfig(day) === true) {
+        const date = day.date;
+        const startDate = day.from ?? day.start;
+        const endDate = day.to ?? day.end;
+        if (date !== undefined) {
+            return parseCalendarDateIdentifier(date, calendar) === target;
+        }
+        if (startDate !== undefined && endDate !== undefined) {
+            const start = parseCalendarDateIdentifier(startDate, calendar);
+            const end = parseCalendarDateIdentifier(endDate, calendar);
+            return (start !== null &&
+                end !== null &&
+                target >= Math.min(start, end) &&
+                target <= Math.max(start, end));
+        }
+        return false;
+    }
+    return parseCalendarDateIdentifier(day, calendar) === target;
+}
 /**
  * Updates the passed Timestamp with disabled, if needed
  * @param {Timestamp} timestamp The Timestamp to transform
@@ -1288,47 +1425,218 @@ export function updateDisabled(timestamp, disabledBefore, disabledAfter, disable
     }
     return freezeTimestamp(ts);
 }
+/**
+ * Updates a timestamp with disabled state using calendar-native date strings.
+ *
+ * The default Gregorian calendar preserves existing Timestamp behavior. When
+ * an alternate calendar is supplied, `disabledBefore`, `disabledAfter`, and
+ * `disabledDays` are parsed as native dates for that adapter.
+ *
+ * @param timestamp Timestamp to transform.
+ * @param disabledBefore Disable days on or before this adapter date.
+ * @param disabledAfter Disable days on or after this adapter date.
+ * @param disabledWeekdays Weekday numbers to mark disabled.
+ * @param disabledDays Specific adapter dates or date ranges to mark disabled.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns New timestamp with disabled metadata applied.
+ * @category calendar
+ */
+export function updateCalendarDisabled(timestamp, disabledBefore, disabledAfter, disabledWeekdays, disabledDays, calendar = gregorianCalendar) {
+    let ts = cloneTimestamp(timestamp);
+    const target = getCalendarDayIdentifier(ts, calendar);
+    if (disabledBefore !== undefined) {
+        const before = parseCalendarDateIdentifier(disabledBefore, calendar);
+        if (before !== null && target <= before) {
+            ts.disabled = true;
+        }
+    }
+    if (ts.disabled !== true && disabledAfter !== undefined) {
+        const after = parseCalendarDateIdentifier(disabledAfter, calendar);
+        if (after !== null && target >= after) {
+            ts.disabled = true;
+        }
+    }
+    if (ts.disabled !== true && Array.isArray(disabledWeekdays) && disabledWeekdays.length > 0) {
+        for (const weekday of disabledWeekdays) {
+            if (weekday === ts.weekday) {
+                ts.disabled = true;
+                break;
+            }
+        }
+    }
+    if (ts.disabled !== true && Array.isArray(disabledDays) && disabledDays.length > 0) {
+        for (const day of disabledDays) {
+            if (isTimestampInCalendarDisabledDay(ts, day, calendar) === true) {
+                ts = applyDisabledDayConfig(ts, isDisabledDayConfig(day) === true ? day : undefined);
+                break;
+            }
+        }
+    }
+    return freezeTimestamp(ts);
+}
+function isTimestampInCalendarDateCollection(timestamp, dates, calendar) {
+    if (dates === undefined) {
+        return false;
+    }
+    const target = getCalendarDayIdentifier(timestamp, calendar);
+    for (const date of dates) {
+        if (parseCalendarDateIdentifier(date, calendar) === target) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolves selected-date and selected-range state for a calendar timestamp.
+ *
+ * The default Gregorian calendar preserves existing Timestamp behavior. When
+ * an alternate calendar is supplied, selected date strings are parsed as native
+ * adapter dates.
+ *
+ * @param timestamp Timestamp to inspect.
+ * @param options Selected dates and selected start/end dates.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns Selected-date state for the timestamp.
+ * @category calendar
+ */
+export function getCalendarSelectionState(timestamp, options = {}, calendar = gregorianCalendar) {
+    const selectedDate = isTimestampInCalendarDateCollection(timestamp, options.selectedDates, calendar);
+    const target = getCalendarDayIdentifier(timestamp, calendar);
+    const rangeBoundaryDates = options.selectedStartEndDates ?? [];
+    let rangeFirst = false;
+    let range = false;
+    let rangeLast = false;
+    if (rangeBoundaryDates.length === 2 && rangeBoundaryDates[0] && rangeBoundaryDates[1]) {
+        const first = parseCalendarDateIdentifier(rangeBoundaryDates[0], calendar);
+        const last = parseCalendarDateIdentifier(rangeBoundaryDates[1], calendar);
+        if (first !== null && last !== null) {
+            const start = Math.min(first, last);
+            const end = Math.max(first, last);
+            rangeFirst = target === start;
+            rangeLast = target === end;
+            range = target > start && target < end;
+        }
+    }
+    return Object.freeze({
+        selectedDate,
+        rangeFirst,
+        range,
+        rangeLast,
+        selected: selectedDate || rangeFirst || range || rangeLast,
+    });
+}
+/**
+ * Resolves disabled, selected, identity, and outside-month state for one date.
+ *
+ * @param timestamp Timestamp to resolve.
+ * @param options Calendar-aware disabled, selection, and outside-month options.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns Calendar date state suitable for component scopes.
+ * @category calendar
+ */
+export function getCalendarDateState(timestamp, options = {}, calendar = gregorianCalendar) {
+    const disabledTimestamp = updateCalendarDisabled(timestamp, options.disabledBefore, options.disabledAfter, options.disabledWeekdays, options.disabledDays, calendar);
+    const selection = getCalendarSelectionState(disabledTimestamp, options, calendar);
+    const outside = options.outside ??
+        (options.referenceMonth === undefined
+            ? false
+            : isOutsideCalendarMonth(disabledTimestamp, options.referenceMonth, calendar));
+    return Object.freeze({
+        timestamp: disabledTimestamp,
+        identity: getCalendarDateIdentity(disabledTimestamp, calendar),
+        outside,
+        disabled: disabledTimestamp.disabled === true,
+        ...selection,
+    });
+}
+/**
+ * Creates native calendar month view state for component rendering.
+ *
+ * The returned `days` use adapter-native `YYYY-MM-DD` values, while each
+ * state's identity also includes Gregorian interop metadata.
+ *
+ * @param timestamp Reference timestamp in the adapter calendar.
+ * @param now Timestamp used to calculate relative flags.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @param options Calendar-aware disabled, selection, weekday, and size options.
+ * @returns Calendar month view state.
+ * @category calendar
+ */
+export function createCalendarMonthView(timestamp, now, calendar = gregorianCalendar, options = {}) {
+    const weekdays = options.weekdays ?? [0, 1, 2, 3, 4, 5, 6];
+    const reference = updateCalendarFormatted(timestamp, calendar);
+    const start = getCalendarStartOfMonth(reference, calendar);
+    const end = getCalendarEndOfMonth(reference, calendar);
+    const visibleStart = getCalendarStartOfWeek(start, weekdays, calendar, now);
+    const visibleEnd = getCalendarEndOfWeek(end, weekdays, calendar, now);
+    const days = createCalendarDayList(visibleStart, visibleEnd, now, calendar, {
+        weekdays,
+        disabledBefore: options.disabledBefore,
+        disabledAfter: options.disabledAfter,
+        disabledWeekdays: options.disabledWeekdays,
+        disabledDays: options.disabledDays,
+        max: options.max ?? weekdays.length * 6,
+        min: options.min ?? weekdays.length * 6,
+    }).map((day) => getCalendarDateState(day, {
+        ...options,
+        referenceMonth: reference,
+    }, calendar));
+    return Object.freeze({
+        reference,
+        start,
+        end,
+        visibleStart,
+        visibleEnd,
+        days,
+    });
+}
 /**
  * Updates the passed Timestamp with formatted data (time string, date string, weekday, day of year and workweek)
  * @param {Timestamp} timestamp The Timestamp to transform
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns A new Timestamp
  * @category formatting
  */
-export function updateFormatted(timestamp) {
+export function updateFormatted(timestamp, calendar = gregorianCalendar) {
     const ts = cloneTimestamp(timestamp);
     ts.hasTime = true;
     ts.time = getTime(ts);
     ts.date = getDate(ts);
-    ts.weekday = getWeekday(ts);
-    ts.doy = getDayOfYear(ts) || 0;
-    ts.workweek = getWorkWeek(ts);
+    ts.weekday = getWeekday(ts, calendar);
+    ts.doy = getDayOfYear(ts, calendar) || 0;
+    ts.workweek = getWorkWeek(ts, calendar);
     return freezeTimestamp(ts);
 }
 /**
  * Returns day of the year (doy) for the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {number} The day of the year
  * @category formatting
  */
-export function getDayOfYear(timestamp) {
+export function getDayOfYear(timestamp, calendar = gregorianCalendar) {
     if (timestamp.year === 0)
         return;
-    return gregorianCalendar.getDayOfYear(toCalendarDateParts(timestamp));
+    return calendar.getDayOfYear(toCalendarDateParts(timestamp));
 }
 /**
  * Returns workweek for the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {number} The work week
  * @category formatting
  */
-export function getWorkWeek(timestamp) {
+export function getWorkWeek(timestamp, calendar = gregorianCalendar) {
     let ts = timestamp;
     if (ts.year === 0) {
-        const parsedToday = parseTimestamp(today());
+        const parsedToday = parseCalendarTimestamp(today(calendar), calendar);
         if (parsedToday) {
             ts = parsedToday;
         }
     }
+    if (calendar !== gregorianCalendar) {
+        return getCalendarWorkWeek(toCalendarDateParts(ts), calendar);
+    }
     // Remove time components of date
     const weekday = new Date(Date.UTC(ts.year, ts.month - 1, ts.day));
     // Adjust the date to the correct day of the week
@@ -1346,13 +1654,14 @@ export function getWorkWeek(timestamp) {
 /**
  * Returns weekday for the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {number} The weekday
  * @category formatting
  */
-export function getWeekday(timestamp) {
+export function getWeekday(timestamp, calendar = gregorianCalendar) {
     let weekday = timestamp.weekday;
     if (timestamp.hasDay) {
-        weekday = gregorianCalendar.getWeekday(toCalendarDateParts(timestamp));
+        weekday = calendar.getWeekday(toCalendarDateParts(timestamp));
     }
     return weekday ?? 0;
 }
@@ -1406,30 +1715,26 @@ export function getEndOfDay(timestamp) {
     return setTimeParts(timestamp, 23, 59, 59, 999);
 }
 /**
- * Returns a Timestamp at the start of the same Gregorian year.
+ * Returns a Timestamp at the start of the same calendar year.
  *
  * @param {Timestamp} timestamp Timestamp object to transform.
- * @returns {Timestamp} New Timestamp for January 1 at `00:00`.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns {Timestamp} New Timestamp for the first calendar day of the year at `00:00`.
  * @category ranges
  */
-export function getStartOfYear(timestamp) {
-    const ts = cloneTimestamp(timestamp);
-    ts.month = MONTH_MIN;
-    ts.day = DAY_MIN;
-    return getStartOfDay(updateFormatted(ts));
+export function getStartOfYear(timestamp, calendar = gregorianCalendar) {
+    return getStartOfDay(getCalendarStartOfYear(timestamp, calendar));
 }
 /**
- * Returns a Timestamp at the end of the same Gregorian year.
+ * Returns a Timestamp at the end of the same calendar year.
  *
  * @param {Timestamp} timestamp Timestamp object to transform.
- * @returns {Timestamp} New Timestamp for December 31 at `23:59:59.999`.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns {Timestamp} New Timestamp for the last calendar day of the year at `23:59:59.999`.
  * @category ranges
  */
-export function getEndOfYear(timestamp) {
-    const ts = cloneTimestamp(timestamp);
-    ts.month = MONTH_MAX;
-    ts.day = daysInMonth(ts.year, MONTH_MAX);
-    return getEndOfDay(updateFormatted(ts));
+export function getEndOfYear(timestamp, calendar = gregorianCalendar) {
+    return getEndOfDay(getCalendarEndOfYear(timestamp, calendar));
 }
 /**
  * Formats the date portion of a Timestamp object.
@@ -1483,11 +1788,12 @@ export function getDateTime(timestamp) {
  * @param {function} [mover=nextDay] The mover function to use (ie: {nextDay} or {prevDay}).
  * @param {number} [days=1] The number of days to move.
  * @param {number[]} [allowedWeekdays=[ 0, 1, 2, 3, 4, 5, 6 ]] An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns A new Timestamp
  * @category ranges
  */
-export function moveRelativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6]) {
-    return relativeDays(timestamp, mover, days, allowedWeekdays);
+export function moveRelativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6], calendar = gregorianCalendar) {
+    return relativeDays(timestamp, mover, days, allowedWeekdays, calendar);
 }
 /**
  * Moves the Timestamp the number of relative days
@@ -1495,16 +1801,17 @@ export function moveRelativeDays(timestamp, mover = nextDay, days = 1, allowedWe
  * @param {function} [mover=nextDay] The mover function to use (ie: {nextDay} or {prevDay}).
  * @param {number} [days=1] The number of days to move.
  * @param {number[]} [allowedWeekdays=[ 0, 1, 2, 3, 4, 5, 6 ]] An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns A new Timestamp
  * @category ranges
  */
-export function relativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6]) {
+export function relativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6], calendar = gregorianCalendar) {
     let ts = copyTimestamp(timestamp);
     if (!allowedWeekdays.includes(Number(ts.weekday)) && ts.weekday === 0 && mover === nextDay) {
         ++days;
     }
     while (--days >= 0) {
-        ts = mover(ts);
+        ts = mover(ts, calendar);
         if (allowedWeekdays.length < 7 && !allowedWeekdays.includes(Number(ts.weekday))) {
             ++days;
         }
@@ -1517,13 +1824,14 @@ export function relativeDays(timestamp, mover = nextDay, days = 1, allowedWeekda
  * @param {number} weekday The weekday number (Sun = 0, ..., Sat = 6)
  * @param {function} [mover=nextDay] The function to use ({prevDay} or {nextDay}).
  * @param {number} [maxDays=6] The number of days to look forward or back.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns A new Timestamp
  * @category ranges
  */
-export function findWeekday(timestamp, weekday, mover = nextDay, maxDays = 6) {
+export function findWeekday(timestamp, weekday, mover = nextDay, maxDays = 6, calendar = gregorianCalendar) {
     let ts = copyTimestamp(timestamp);
     while (ts.weekday !== weekday && --maxDays >= 0)
-        ts = mover(ts);
+        ts = mover(ts, calendar);
     return ts;
 }
 /**
@@ -1542,10 +1850,22 @@ export function findWeekday(timestamp, weekday, mover = nextDay, maxDays = 6) {
  * @param {DisabledDays} [disabledDays] Specific dates or date ranges to mark disabled.
  * @param {number} [max=42] Maximum number of days to return.
  * @param {number} [min=0] Minimum number of days to return.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp[]} Timestamp days.
  * @category ranges
  */
-export function createDayList(start, end, now, weekdays = [0, 1, 2, 3, 4, 5, 6], disabledBefore = undefined, disabledAfter = undefined, disabledWeekdays = [], disabledDays = [], max = 42, min = 0) {
+export function createDayList(start, end, now, weekdays = [0, 1, 2, 3, 4, 5, 6], disabledBefore = undefined, disabledAfter = undefined, disabledWeekdays = [], disabledDays = [], max = 42, min = 0, calendar = gregorianCalendar) {
+    if (calendar !== gregorianCalendar) {
+        return createCalendarDayList(start, end, now, calendar, {
+            weekdays,
+            disabledBefore,
+            disabledAfter,
+            disabledWeekdays,
+            disabledDays,
+            max,
+            min,
+        });
+    }
     const begin = getDayIdentifier(start);
     const stop = getDayIdentifier(end);
     const days = [];
@@ -1663,7 +1983,7 @@ export function createNativeLocaleFormatterUTC(locale, cb) {
  * `calendar` option. The helper supplies `timeZone: "UTC"` unless the caller
  * provides a different timezone.
  *
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @param locale The locale to use.
  * @param cb Callback that returns Intl formatting options.
  * @returns Function that formats a calendar timestamp.
@@ -1714,7 +2034,7 @@ export function makeDateUTC(timestamp) {
  * can format the adapter date correctly when paired with a calendar option.
  *
  * @param timestamp Calendar timestamp object to convert.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns JavaScript Date object built with `Date.UTC()`.
  * @category calendar
  */
@@ -1736,7 +2056,7 @@ export function makeDateTime(timestamp) {
  * Converts an adapter calendar timestamp date-time into a UTC JavaScript Date.
  *
  * @param timestamp Calendar timestamp object to convert.
- * @param calendar Calendar implementation to use.
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns JavaScript Date object built with `Date.UTC()`.
  * @category calendar
  */
@@ -2063,10 +2383,80 @@ export function isOverlappingDates(startTimestamp, endTimestamp, firstTimestamp,
  * @param {number=} options.minute If positive, adds minutes. If negative, removes minutes.
  * @param {number=} options.second If positive, adds seconds. If negative, removes seconds.
  * @param {number=} options.millisecond If positive, adds milliseconds. If negative, removes milliseconds.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} New normalized Timestamp object.
  * @category arithmetic
  */
-export function addToDate(timestamp, options) {
+function addToCalendarDateTime(timestamp, options, calendar) {
+    let ts = updateCalendarFormatted(timestamp, calendar);
+    if (options.year)
+        ts = addCalendarYears(ts, options.year, calendar);
+    if (options.month)
+        ts = addCalendarMonths(ts, options.month, calendar);
+    if (options.day)
+        ts = addCalendarDays(ts, options.day, calendar);
+    const hasTimeOffset = options.hour !== undefined ||
+        options.minute !== undefined ||
+        options.second !== undefined ||
+        options.millisecond !== undefined;
+    if (hasTimeOffset) {
+        const totalMilliseconds = (ts.hour + (options.hour ?? 0)) * MILLISECONDS_IN_HOUR +
+            (ts.minute + (options.minute ?? 0)) * MILLISECONDS_IN_MINUTE +
+            ((ts.second ?? 0) + (options.second ?? 0)) * MILLISECONDS_IN_SECOND +
+            ((ts.millisecond ?? 0) + (options.millisecond ?? 0));
+        const dayOffset = Math.floor(totalMilliseconds / MILLISECONDS_IN_DAY);
+        let timeMilliseconds = totalMilliseconds % MILLISECONDS_IN_DAY;
+        if (timeMilliseconds < 0) {
+            timeMilliseconds += MILLISECONDS_IN_DAY;
+        }
+        if (dayOffset !== 0) {
+            ts = addCalendarDays(ts, dayOffset, calendar);
+        }
+        const next = cloneTimestamp(ts);
+        next.hasTime = true;
+        next.hour = Math.floor(timeMilliseconds / MILLISECONDS_IN_HOUR);
+        timeMilliseconds %= MILLISECONDS_IN_HOUR;
+        next.minute = Math.floor(timeMilliseconds / MILLISECONDS_IN_MINUTE);
+        timeMilliseconds %= MILLISECONDS_IN_MINUTE;
+        next.second = Math.floor(timeMilliseconds / MILLISECONDS_IN_SECOND);
+        next.millisecond = timeMilliseconds % MILLISECONDS_IN_SECOND;
+        if (next.second === 0 && timestamp.second === undefined && options.second === undefined) {
+            delete next.second;
+        }
+        if (next.millisecond === 0 &&
+            timestamp.millisecond === undefined &&
+            options.millisecond === undefined) {
+            delete next.millisecond;
+        }
+        ts = next;
+    }
+    return updateCalendarFormatted(ts, calendar);
+}
+/**
+ * Adds or subtracts date/time units from a timestamp.
+ *
+ * This function returns a new frozen Timestamp; it does not mutate the
+ * timestamp passed in. Gregorian dates are normalized through JavaScript Date
+ * rules. Adapter-native dates use the supplied calendar system for year,
+ * month, and day math.
+ *
+ * @param {Timestamp} timestamp Timestamp object to offset.
+ * @param {Object} options Date/time units to add or subtract.
+ * @param {number=} options.year If positive, adds years. If negative, removes years.
+ * @param {number=} options.month If positive, adds months. If negative, removes month.
+ * @param {number=} options.day If positive, adds days. If negative, removes days.
+ * @param {number=} options.hour If positive, adds hours. If negative, removes hours.
+ * @param {number=} options.minute If positive, adds minutes. If negative, removes minutes.
+ * @param {number=} options.second If positive, adds seconds. If negative, removes seconds.
+ * @param {number=} options.millisecond If positive, adds milliseconds. If negative, removes milliseconds.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns {Timestamp} New normalized Timestamp object.
+ * @category arithmetic
+ */
+export function addToDate(timestamp, options, calendar = gregorianCalendar) {
+    if (calendar !== gregorianCalendar) {
+        return addToCalendarDateTime(timestamp, options, calendar);
+    }
     const ts = cloneTimestamp(timestamp);
     if (options.year)
         ts.year += options.year;
@@ -2105,10 +2495,14 @@ export function addToDate(timestamp, options) {
  * @param {number=} options.minute If positive, adds minutes. If negative, removes minutes.
  * @param {number=} options.second If positive, adds seconds. If negative, removes seconds.
  * @param {number=} options.millisecond If positive, adds milliseconds. If negative, removes milliseconds.
+ * @param {CalendarSystem=} calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
  * @returns {Timestamp} New normalized Timestamp object.
  * @category arithmetic
  */
-export function addToDateClamped(timestamp, options) {
+export function addToDateClamped(timestamp, options, calendar = gregorianCalendar) {
+    if (calendar !== gregorianCalendar) {
+        return addToCalendarDateTime(timestamp, options, calendar);
+    }
     const ts = cloneTimestamp(timestamp);
     if (options.year || options.month) {
         const target = normalizeYearMonth(ts.year + (options.year ?? 0), ts.month + (options.month ?? 0));
@@ -2456,6 +2850,61 @@ export function getMonthFormatter() {
     }
     return monthFormatter;
 }
+/**
+ * Returns a function that formats one-based calendar adapter month numbers.
+ *
+ * This is the calendar-aware counterpart to getMonthFormatter(). It converts
+ * adapter fields through the adapter's epoch-day mapping, then asks Intl to
+ * format the equivalent Gregorian Date with the adapter's Intl calendar id
+ * when one is available.
+ *
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @returns Function that formats one-based month numbers for the adapter.
+ * @category calendar
+ */
+export function getCalendarMonthFormatter(calendar = gregorianCalendar) {
+    const options = {
+        long: { timeZone: 'UTC', month: 'long' },
+        short: { timeZone: 'UTC', month: 'short' },
+        narrow: { timeZone: 'UTC', month: 'narrow' },
+    };
+    const fallbackFormatter = (month) => Number.isFinite(month) && month >= 1 ? `Month ${month}` : '';
+    if (typeof Intl === 'undefined' || typeof Intl.DateTimeFormat === 'undefined') {
+        return fallbackFormatter;
+    }
+    return (month, type = 'long', locale, year = 1) => {
+        const calendarMonth = Math.trunc(month);
+        const calendarYear = Math.trunc(year);
+        const date = {
+            year: calendarYear,
+            month: calendarMonth,
+            day: 1,
+        };
+        if (Number.isFinite(calendarMonth) === false ||
+            Number.isFinite(calendarYear) === false ||
+            isValidCalendarDate(date, calendar) === false) {
+            return '';
+        }
+        try {
+            const resolvedOptions = resolveIntlNameFormat(options, type);
+            const formatterOptions = calendar.intlCalendar === undefined || resolvedOptions.calendar !== undefined
+                ? resolvedOptions
+                : {
+                    ...resolvedOptions,
+                    calendar: calendar.intlCalendar,
+                };
+            const gregorianDate = gregorianCalendar.fromEpochDay(calendar.toEpochDay(date));
+            const nativeDate = new Date(Date.UTC(gregorianDate.year, gregorianDate.month - 1, gregorianDate.day));
+            return new Intl.DateTimeFormat(locale || undefined, formatterOptions).format(nativeDate);
+        }
+        catch (e) {
+            if (e instanceof Error) {
+                console.error(`Intl.DateTimeFormat: ${e.message} -> calendar month: ${calendarMonth}`);
+            }
+            return fallbackFormatter(calendarMonth);
+        }
+    };
+}
 /**
  * Retrieves localized month names.
  *
@@ -2468,4 +2917,22 @@ export function getMonthNames(type, locale) {
     const monthFormatter = getMonthFormatter();
     return [...Array(12).keys()].map((month) => monthFormatter(month, type, locale));
 }
+/**
+ * Retrieves localized month names for a calendar adapter.
+ *
+ * Month numbers are generated from `1` through `calendar.monthsInYear(year)`.
+ * Pass a year when the calendar can have leap months or year-specific month
+ * naming rules.
+ *
+ * @param calendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.
+ * @param type Format type: `narrow`, `short`, or `long`.
+ * @param locale Locale to use for formatting, such as `en-US`.
+ * @param year Calendar year to sample. Defaults to `1`.
+ * @returns Localized month names in calendar-native order.
+ * @category calendar
+ */
+export function getCalendarMonthNames(calendar = gregorianCalendar, type = 'long', locale, year = 1) {
+    const monthFormatter = getCalendarMonthFormatter(calendar);
+    return [...Array(calendar.monthsInYear(year)).keys()].map((month) => monthFormatter(month + 1, type, locale, year));
+}
 //# sourceMappingURL=index.js.map