@dereekb/date 13.4.0 → 13.4.2

package/index.cjs.js

@@ -9,6 +9,14 @@ var model = require('@dereekb/model');
 var rxjs = require('rxjs');
 var rrule = require('rrule');
 
+function _array_like_to_array$7(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes$5(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$7(arr);
+}
 function _define_property$h(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -22,6 +30,12 @@ function _define_property$h(obj, key, value) {
     }
     return obj;
 }
+function _iterable_to_array$5(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread$5() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
 function _object_spread$e(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
@@ -37,6 +51,17 @@ function _object_spread$e(target) {
     }
     return target;
 }
+function _to_consumable_array$5(arr) {
+    return _array_without_holes$5(arr) || _iterable_to_array$5(arr) || _unsupported_iterable_to_array$7(arr) || _non_iterable_spread$5();
+}
+function _unsupported_iterable_to_array$7(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$7(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$7(o, minLen);
+}
 /**
  * Sentinel date representing the maximum future date (January 1, 9999 UTC).
  *
@@ -134,6 +159,8 @@ function _object_spread$e(target) {
  *
  * Useful as a default for "no expiration" comparisons.
  *
+ * @returns the MAX_FUTURE_DATE sentinel
+ *
  * @example
  * ```ts
  * const futureDate = maxFutureDate();
@@ -204,8 +231,7 @@ function _object_spread$e(target) {
  * // tz === 'America/New_York' (or similar)
  * ```
  */ function guessCurrentTimezone() {
-    var _Intl_DateTimeFormat_resolvedOptions, _Intl_DateTimeFormat;
-    return (_Intl_DateTimeFormat = Intl.DateTimeFormat()) === null || _Intl_DateTimeFormat === void 0 ? void 0 : (_Intl_DateTimeFormat_resolvedOptions = _Intl_DateTimeFormat.resolvedOptions()) === null || _Intl_DateTimeFormat_resolvedOptions === void 0 ? void 0 : _Intl_DateTimeFormat_resolvedOptions.timeZone;
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
 }
 /**
  * Returns the current system's timezone, throwing if detection fails.
@@ -295,15 +321,15 @@ function isBefore(a, b) {
 }
 function isSameDate(a, b) {
     var defaultValue = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : null;
-    return a != null && b != null ? dateFns.isEqual(a, b) : defaultValue != null ? defaultValue : a == b;
+    return a != null && b != null ? dateFns.isEqual(a, b) : defaultValue !== null && defaultValue !== void 0 ? defaultValue : a == b;
 }
 function isSameDateHoursAndMinutes(a, b) {
     var defaultValue = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : null;
-    return a != null && b != null ? dateFns.isEqual(roundDownToMinute(a), roundDownToMinute(b)) : defaultValue != null ? defaultValue : a == b;
+    return a != null && b != null ? dateFns.isEqual(roundDownToMinute(a), roundDownToMinute(b)) : defaultValue !== null && defaultValue !== void 0 ? defaultValue : a == b;
 }
 function isSameDateDay(a, b) {
     var defaultValue = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : null;
-    return a != null && b != null ? dateFns.isSameDay(a, b) : defaultValue != null ? defaultValue : a == b;
+    return a != null && b != null ? dateFns.isSameDay(a, b) : defaultValue !== null && defaultValue !== void 0 ? defaultValue : a == b;
 }
 // MARK: Unix Date/Time
 /**
@@ -347,6 +373,10 @@ function isSameDateDay(a, b) {
  * Sets the hours and optionally minutes on a target date (defaults to now), with optional rounding to strip seconds/milliseconds.
  *
  * @param config - hours, optional minutes, and rounding options
+ * @param config.hours - the hours value to set
+ * @param config.minutes - optional minutes value to set
+ * @param config.removeSeconds - whether to zero out seconds
+ * @param config.roundDownToMinute - whether to zero out seconds and milliseconds (defaults to true)
  * @param target - date to modify (defaults to the current date/time)
  * @returns a new Date with the specified time values applied
  *
@@ -576,7 +606,7 @@ function roundDateTo(date, roundToUnit) {
  * // names === ['Mon', 'Tue']
  * ```
  */ function readDaysOfWeekNames(values, readDate, nameFunction) {
-    return Array.from(readDaysOfWeek(values, readDate)).sort(util.sortNumbersAscendingFunction).map(nameFunction);
+    return _to_consumable_array$5(readDaysOfWeek(values, readDate)).sort(util.sortNumbersAscendingFunction).map(nameFunction);
 }
 /**
  * Checks whether the given date falls exactly at midnight (00:00:00.000) in UTC.
@@ -845,6 +875,9 @@ function _is_native_reflect_construct$2() {
 /**
  * Type guard to check if a value conforms to the {@link DateRangeStart} interface.
  *
+ * @param value - the value to check
+ * @returns true if the value has a valid Date `start` property
+ *
  * @example
  * ```ts
  * isDateRangeStart({ start: new Date() }); // true
@@ -873,6 +906,9 @@ function _is_native_reflect_construct$2() {
  * Counts the total number of calendar days spanned by the range, inclusive of both endpoints.
  * Always returns at least 1, even for same-day ranges.
  *
+ * @param dateRange - the date range to measure
+ * @returns the number of days in the range, inclusive
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-01-03') };
@@ -884,6 +920,9 @@ function _is_native_reflect_construct$2() {
 /**
  * Type guard to check if a value is a valid {@link DateRange} with both start and end as Date objects.
  *
+ * @param input - the value to check
+ * @returns true if the value has valid Date `start` and `end` properties
+ *
  * @example
  * ```ts
  * isDateRange({ start: new Date(), end: new Date() }); // true
@@ -897,6 +936,10 @@ function _is_native_reflect_construct$2() {
  * Compares two date ranges for exact millisecond equality on both start and end.
  * Returns true if both are nullish.
  *
+ * @param a - first date range to compare
+ * @param b - second date range to compare
+ * @returns true if both ranges are equal or both are nullish
+ *
  * @example
  * ```ts
  * const a = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
@@ -911,6 +954,10 @@ function _is_native_reflect_construct$2() {
  * Compares two date ranges for calendar-day equality, ignoring time-of-day differences.
  * Returns true if both are nullish.
  *
+ * @param a - first date range to compare
+ * @param b - second date range to compare
+ * @returns true if both ranges fall on the same calendar days or both are nullish
+ *
  * @example
  * ```ts
  * const a = { start: new Date('2024-01-01T08:00:00'), end: new Date('2024-01-31T10:00:00') };
@@ -923,6 +970,9 @@ function _is_native_reflect_construct$2() {
 /**
  * Checks whether the range is unbounded (neither start nor end is set), meaning it conceptually includes all dates.
  *
+ * @param input - the partial date range to check
+ * @returns true if neither start nor end is set
+ *
  * @example
  * ```ts
  * isInfiniteDateRange({}); // true
@@ -934,6 +984,9 @@ function _is_native_reflect_construct$2() {
 /**
  * Checks whether the range has only one of start or end set, but not both.
  *
+ * @param input - the partial date range to check
+ * @returns true if exactly one of start or end is set
+ *
  * @example
  * ```ts
  * isPartialDateRange({ start: new Date() }); // true
@@ -945,6 +998,9 @@ function _is_native_reflect_construct$2() {
 /**
  * Checks whether the range has both start and end set.
  *
+ * @param input - the partial date range to check
+ * @returns true if both start and end are set
+ *
  * @example
  * ```ts
  * isFullDateRange({ start: new Date(), end: new Date() }); // true
@@ -957,6 +1013,10 @@ function _is_native_reflect_construct$2() {
  * Normalizes a Date or {@link DateRange} into a DateRange. When given a single Date,
  * uses it as start and optionally uses the provided end date (defaults to the same date).
  *
+ * @param startOrDateRange - a Date or existing DateRange
+ * @param end - optional end date when the first argument is a plain Date
+ * @returns a DateRange
+ *
  * @example
  * ```ts
  * const range = dateOrDateRangeToDateRange(new Date('2024-01-01'), new Date('2024-01-31'));
@@ -1029,6 +1089,9 @@ exports.DateRangeType = void 0;
  * Creates a {@link DateRange} from the given type and optional parameters. Supports many range
  * strategies including fixed periods (day, week, month), directional ranges, and radii.
  *
+ * @param input - the range type or full configuration object
+ * @param inputRoundToMinute - optional override to round the date to the start of its minute
+ * @returns a computed DateRange
  * @throws Error if the type is not a recognized {@link DateRangeType}
  *
  * @example
@@ -1062,25 +1125,27 @@ exports.DateRangeType = void 0;
         start = startOfFn(preStart);
         end = endOfFn(preEnd);
     }
-    function calculateStartAndEndForBetween(addFn) {
-        var distance = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 0, startOfFn = arguments.length > 2 ? arguments[2] : void 0, endOfFn = arguments.length > 3 ? arguments[3] : void 0;
+    function calculateStartAndEndForBetween(config) {
+        var addFn = config.addFn, tmp = config.distance, betweenDistance = tmp === void 0 ? 0 : tmp, startOfFn = config.startOfFn, endOfFn = config.endOfFn;
         var preStart;
         var preEnd;
-        switch(distance){
+        switch(betweenDistance){
             case 0:
                 preStart = date;
                 preEnd = date;
                 break;
             default:
-                var hasNegativeDistance = distance < 0;
-                if (hasNegativeDistance) {
-                    preStart = addFn(date, distance);
-                    preEnd = date;
-                } else {
-                    preStart = date;
-                    preEnd = addFn(date, distance);
+                {
+                    var hasNegativeDistance = betweenDistance < 0;
+                    if (hasNegativeDistance) {
+                        preStart = addFn(date, betweenDistance);
+                        preEnd = date;
+                    } else {
+                        preStart = date;
+                        preEnd = addFn(date, betweenDistance);
+                    }
+                    break;
                 }
-                break;
         }
         start = startOfFn(preStart);
         end = endOfFn(preEnd);
@@ -1102,19 +1167,44 @@ exports.DateRangeType = void 0;
             calculateStartAndEndForDate(dateFns.startOfMinute, dateFns.endOfMinute);
             break;
         case exports.DateRangeType.MINUTES_RANGE:
-            calculateStartAndEndForBetween(dateFns.addMinutes, rawDistance, dateFns.startOfMinute, dateFns.endOfMinute);
+            calculateStartAndEndForBetween({
+                addFn: dateFns.addMinutes,
+                distance: rawDistance,
+                startOfFn: dateFns.startOfMinute,
+                endOfFn: dateFns.endOfMinute
+            });
             break;
         case exports.DateRangeType.HOURS_RANGE:
-            calculateStartAndEndForBetween(dateFns.addHours, rawDistance, dateFns.startOfHour, dateFns.endOfHour);
+            calculateStartAndEndForBetween({
+                addFn: dateFns.addHours,
+                distance: rawDistance,
+                startOfFn: dateFns.startOfHour,
+                endOfFn: dateFns.endOfHour
+            });
             break;
         case exports.DateRangeType.DAYS_RANGE:
-            calculateStartAndEndForBetween(dateFns.addDays, rawDistance, dateFns.startOfDay, dateFns.endOfDay);
+            calculateStartAndEndForBetween({
+                addFn: dateFns.addDays,
+                distance: rawDistance,
+                startOfFn: dateFns.startOfDay,
+                endOfFn: dateFns.endOfDay
+            });
             break;
         case exports.DateRangeType.WEEKS_RANGE:
-            calculateStartAndEndForBetween(dateFns.addWeeks, rawDistance, dateFns.startOfWeek, dateFns.endOfWeek);
+            calculateStartAndEndForBetween({
+                addFn: dateFns.addWeeks,
+                distance: rawDistance,
+                startOfFn: dateFns.startOfWeek,
+                endOfFn: dateFns.endOfWeek
+            });
             break;
         case exports.DateRangeType.MONTHS_RANGE:
-            calculateStartAndEndForBetween(dateFns.addMonths, rawDistance, dateFns.startOfMonth, dateFns.endOfMonth);
+            calculateStartAndEndForBetween({
+                addFn: dateFns.addMonths,
+                distance: rawDistance,
+                startOfFn: dateFns.startOfMonth,
+                endOfFn: dateFns.endOfMonth
+            });
             break;
         case exports.DateRangeType.MINUTES_RADIUS:
             distance = Math.abs(distance);
@@ -1137,10 +1227,12 @@ exports.DateRangeType = void 0;
             end = dateFns.addDays(date, distance * 7);
             break;
         case exports.DateRangeType.CALENDAR_MONTH:
-            var monthStart = dateFns.startOfMonth(dateFns.endOfWeek(date));
-            start = dateFns.startOfWeek(monthStart);
-            end = dateFns.endOfWeek(dateFns.endOfMonth(monthStart));
-            break;
+            {
+                var monthStart = dateFns.startOfMonth(dateFns.endOfWeek(date));
+                start = dateFns.startOfWeek(monthStart);
+                end = dateFns.endOfWeek(dateFns.endOfMonth(monthStart));
+                break;
+            }
         default:
             throw new Error("Unknown date range type: ".concat(type));
     }
@@ -1153,6 +1245,9 @@ exports.DateRangeType = void 0;
  * Returns a range spanning the full calendar day (first to last millisecond) of the given date.
  * Convenience wrapper around {@link dateRange} with {@link DateRangeType.DAY}.
  *
+ * @param date - the date whose full day range to return
+ * @returns a DateRange from start of day to end of day
+ *
  * @example
  * ```ts
  * const range = dateRangeFromStartAndEndOfDay(new Date('2024-06-15T14:30:00'));
@@ -1191,6 +1286,8 @@ var DEFAULT_ITERATE_DAYS_IN_DATE_RANGE_MAX_ITERATIONS = 4000;
  * Creates a reusable function that iterates over dates within a range using a configurable step function.
  * Supports max iteration limits and early bail-out via {@link endItreateDaysInDateRangeEarly}.
  *
+ * @param input - configuration or a step function for advancing between dates
+ * @returns a reusable iteration function
  * @throws Error if max iterations is exceeded and throwErrorOnMaxIterations is true
  *
  * @example
@@ -1244,6 +1341,8 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Creates a reusable function that expands a {@link DateRange} into an array of individual day dates.
  * Includes a configurable safety limit to prevent accidental memory exhaustion from large ranges.
  *
+ * @param config - optional configuration for the max expansion size
+ * @returns a function that expands a DateRange into an array of Dates
  * @throws Error if the range spans more days than the configured maxExpansionSize
  *
  * @example
@@ -1273,6 +1372,9 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Expands a {@link DateRange} into an array of one Date per day. Uses the default max expansion size.
  * Convenience wrapper around {@link expandDaysForDateRangeFunction}.
  *
+ * @param range - the date range to expand
+ * @returns an array of Dates, one per day in the range
+ *
  * @example
  * ```ts
  * const days = expandDaysForDateRange({ start: new Date('2024-01-01'), end: new Date('2024-01-03') });
@@ -1284,6 +1386,12 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
 /**
  * Determines whether the current moment (or provided `now`) falls before, within, or after the given range.
  *
+ * @param dateRange - the date range to compare against
+ * @param dateRange.start - the start of the range
+ * @param dateRange.end - the end of the range
+ * @param now - the reference date, defaults to the current moment
+ * @returns 'past', 'present', or 'future'
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
@@ -1306,6 +1414,10 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
 /**
  * Groups an array of date ranges into past, present, and future buckets based on the current moment (or provided `now`).
  *
+ * @param dateRanges - the date ranges to group
+ * @param _now - the reference date, defaults to the current moment
+ * @returns an object with past, present, and future arrays
+ *
  * @example
  * ```ts
  * const ranges = [
@@ -1324,6 +1436,10 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Checks whether a date falls within a (possibly partial) date range.
  * Convenience wrapper around {@link isDateInDateRangeFunction}.
  *
+ * @param date - the date to test
+ * @param dateRange - the range to test against
+ * @returns true if the date falls within the range
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
@@ -1338,6 +1454,9 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Handles partial ranges: if only start is set, checks >= start; if only end, checks <= end;
  * if neither, all dates are considered in range.
  *
+ * @param dateRange - the boundary range to test against
+ * @returns a function that tests whether a date falls within the range
+ *
  * @example
  * ```ts
  * const isInQ1 = isDateInDateRangeFunction({
@@ -1372,7 +1491,7 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
             return time <= endTime1;
         };
     } else {
-        fn = function fn(input) {
+        fn = function fn(_input) {
             return true;
         };
     }
@@ -1383,6 +1502,10 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Checks whether a date range is fully contained within another (possibly partial) date range.
  * Convenience wrapper around {@link isDateRangeInDateRangeFunction}.
  *
+ * @param compareDateRange - the range to test for containment
+ * @param dateRange - the boundary range
+ * @returns true if compareDateRange is fully within dateRange
+ *
  * @example
  * ```ts
  * const outer = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
@@ -1396,6 +1519,9 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Creates a reusable function that tests whether a given date range is fully contained within
  * the configured boundary range. Both start and end of the input must be within bounds.
  *
+ * @param dateRange - the boundary range
+ * @returns a function that tests containment of other ranges
+ *
  * @example
  * ```ts
  * const isInYear = isDateRangeInDateRangeFunction({
@@ -1417,6 +1543,10 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Checks whether two date ranges overlap in any way (partial or full).
  * Convenience wrapper around {@link dateRangeOverlapsDateRangeFunction}.
  *
+ * @param compareDateRange - the range to test for overlap
+ * @param dateRange - the reference range
+ * @returns true if the ranges overlap
+ *
  * @example
  * ```ts
  * const a = { start: new Date('2024-01-01'), end: new Date('2024-06-30') };
@@ -1430,6 +1560,9 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Creates a reusable function that tests whether input ranges overlap the configured boundary range.
  * Two ranges overlap if one starts before the other ends, and vice versa.
  *
+ * @param dateRange - the boundary range to test overlap against
+ * @returns a function that tests overlap of other ranges
+ *
  * @example
  * ```ts
  * const overlapsQ1 = dateRangeOverlapsDateRangeFunction({
@@ -1461,6 +1594,9 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  *
  * Operates in UTC, so daylight savings transitions are not considered.
  *
+ * @param dateRange - the date range to fit into a single day period
+ * @returns a new date range with the same start and an end within 24 hours of start
+ *
  * @example
  * ```ts
  * // 10AM to 1PM across 3 days becomes same-day 10AM to 1PM
@@ -1488,6 +1624,9 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Dates before start are clamped to start; dates after end are clamped to end.
  * Partial ranges clamp only on the side that is defined.
  *
+ * @param dateRange - the boundary range for clamping
+ * @returns a function that clamps dates to the range
+ *
  * @example
  * ```ts
  * const clamp = clampDateFunction({
@@ -1503,15 +1642,16 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
     var hasStartDate = dateRange.start != null;
     var hasEndDate = dateRange.end != null;
     if (hasStartDate || hasEndDate) {
+        var _ref, _ref1;
         var _dateRange_start, _dateRange_end;
         // Start Clamp
-        var startTime = ((_dateRange_start = dateRange.start) === null || _dateRange_start === void 0 ? void 0 : _dateRange_start.getTime()) || 0;
+        var startTime = (_ref = (_dateRange_start = dateRange.start) === null || _dateRange_start === void 0 ? void 0 : _dateRange_start.getTime()) !== null && _ref !== void 0 ? _ref : 0;
         var clampStart = function clampStart(input) {
             var time = input.getTime();
             return time >= startTime ? input : dateRange.start;
         };
         // End Clamp
-        var endTime = ((_dateRange_end = dateRange.end) === null || _dateRange_end === void 0 ? void 0 : _dateRange_end.getTime()) || 0;
+        var endTime = (_ref1 = (_dateRange_end = dateRange.end) === null || _dateRange_end === void 0 ? void 0 : _dateRange_end.getTime()) !== null && _ref1 !== void 0 ? _ref1 : 0;
         var clampEnd = function clampEnd(input) {
             var time = input.getTime();
             return time <= endTime ? input : dateRange.end;
@@ -1541,6 +1681,10 @@ var DEFAULT_EXPAND_DAYS_FOR_DATE_RANGE_MAX_EXPANSION_SIZE = 1500;
  * Clamps a single date to fall within the given range boundaries.
  * Convenience wrapper around {@link clampDateFunction}.
  *
+ * @param date - the date to clamp
+ * @param dateRange - the boundary range
+ * @returns the clamped date
+ *
  * @example
  * ```ts
  * const range = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
@@ -1568,6 +1712,10 @@ function clampDateRangeFunction(dateRange) {
  * Clamps a date range to fit within a boundary range.
  * Convenience wrapper around {@link clampDateRangeFunction}.
  *
+ * @param inputDateRange - the date range to clamp
+ * @param limitToDateRange - the boundary range
+ * @returns the clamped date range
+ *
  * @example
  * ```ts
  * const input = { start: new Date('2023-06-01'), end: new Date('2024-06-30') };
@@ -1581,6 +1729,9 @@ function clampDateRangeFunction(dateRange) {
 /**
  * Creates a function that applies a date transformation to both start and end of a {@link DateRange}.
  *
+ * @param transform - the transformation to apply to both dates
+ * @returns a function that transforms both dates of a DateRange
+ *
  * @example
  * ```ts
  * import { startOfHour } from 'date-fns';
@@ -1604,6 +1755,9 @@ function clampDateRangeFunction(dateRange) {
  * Returns each unique day of the week present in the range, in the order they appear starting from
  * the range's start day. For ranges spanning 7+ days, returns all days of the week.
  *
+ * @param dateRange - the date range to inspect
+ * @returns an array of unique day-of-week values present in the range
+ *
  * @example
  * ```ts
  * // Wednesday through Friday
@@ -1767,8 +1921,11 @@ function _type_of$6(obj) {
  * isValidDateTimezoneConversionConfig({ timezone: 'America/Chicago' }); // true
  * isValidDateTimezoneConversionConfig({}); // false
  * ```
+ *
+ * @param input - the conversion config to validate
+ * @returns true if the config has at least one meaningful conversion property set
  */ function isValidDateTimezoneConversionConfig(input) {
-    return input.useSystemTimezone || input.timezone != null || input.timezoneOffset != null || input.noConversion || false;
+    return input.useSystemTimezone === true || input.timezone != null || input.timezoneOffset != null || input.noConversion === true;
 }
 /**
  * Compares two configs for logical equivalence, accounting for the fact that
@@ -1779,12 +1936,16 @@ function _type_of$6(obj) {
  * isSameDateTimezoneConversionConfig({ timezone: 'UTC' }, { timezone: undefined }); // true
  * isSameDateTimezoneConversionConfig({ useSystemTimezone: true }, { timezone: 'America/Denver' }); // false
  * ```
+ *
+ * @param a - first conversion config to compare
+ * @param b - second conversion config to compare
+ * @returns true if both configs are logically equivalent
  */ function isSameDateTimezoneConversionConfig(a, b) {
     var isSame = false;
     if (a.useSystemTimezone || b.useSystemTimezone || a.timezoneOffset || b.timezoneOffset) {
         isSame = util.isSameNonNullValue(a.useSystemTimezone, b.useSystemTimezone) || util.isSameNonNullValue(a.timezoneOffset, b.timezoneOffset);
     } else {
-        isSame = util.isConsideredUtcTimezoneString(a.timezone) && util.isConsideredUtcTimezoneString(b.timezone) || a != null && a === b;
+        isSame = util.isConsideredUtcTimezoneString(a.timezone) && util.isConsideredUtcTimezoneString(b.timezone) || a === b;
     }
     return isSame;
 }
@@ -1803,6 +1964,7 @@ function _type_of$6(obj) {
  * ```
  *
  * @param date - required to determine the correct offset for that instant (DST-aware)
+ * @returns the system timezone UTC offset in milliseconds
  */ function getCurrentSystemOffsetInMs(date) {
     // Use native getTimezoneOffset() instead of calculateTimezoneOffset() to avoid
     // a DST edge case where toZonedTime() creates an epoch that lands on the system's
@@ -1819,6 +1981,7 @@ function _type_of$6(obj) {
  * ```
  *
  * @param date - required to determine the correct offset for that instant (DST-aware)
+ * @returns the system timezone UTC offset truncated to whole hours
  */ function getCurrentSystemOffsetInHours(date) {
     return dateFns.millisecondsToHours(getCurrentSystemOffsetInMs(date));
 }
@@ -1835,6 +1998,7 @@ function _type_of$6(obj) {
  * ```
  *
  * @param date - required to determine the correct offset for that instant (DST-aware)
+ * @returns the system timezone UTC offset in minutes
  */ function getCurrentSystemOffsetInMinutes(date) {
     return dateFns.millisecondsToMinutes(getCurrentSystemOffsetInMs(date));
 }
@@ -1855,6 +2019,7 @@ function _type_of$6(obj) {
  *
  * @param timezone - IANA timezone string (e.g. 'America/New_York')
  * @param date - the instant to evaluate, since DST may shift the offset
+ * @returns the UTC offset for the given timezone at the given instant, in milliseconds
  */ function calculateTimezoneOffset(timezone, date) {
     var tzOffset;
     // UTC always has zero offset; skip toZonedTime which can produce wrong results
@@ -1881,7 +2046,15 @@ function _type_of$6(obj) {
     }
     return tzOffset;
 }
-function calculateAllConversions(date, converter) {
+/**
+ * Calculates offset values for every pair of conversion targets (target, base, system)
+ * and returns them as a keyed map (e.g. `'target-base'`, `'base-system'`).
+ *
+ * @param date - the reference date used to compute offsets
+ * @param converter - the converter instance providing offset calculations
+ * @param map - optional mapping function applied to each raw millisecond offset
+ * @returns a map of conversion-pair keys to their computed offset values
+ */ function calculateAllConversions(date, converter) {
     var map = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : function(x) {
         return x;
     };
@@ -1908,6 +2081,9 @@ function calculateAllConversions(date, converter) {
  * inverseDateTimezoneUtcNormalInstanceTransformType('targetDateToBaseDate'); // 'baseDateToTargetDate'
  * inverseDateTimezoneUtcNormalInstanceTransformType('systemDateToTargetDate'); // 'targetDateToSystemDate'
  * ```
+ *
+ * @param input - the transform type to invert
+ * @returns the inverse transform type for round-trip conversion
  */ function inverseDateTimezoneUtcNormalInstanceTransformType(input) {
     var result;
     switch(input){
@@ -1929,6 +2105,8 @@ function calculateAllConversions(date, converter) {
         case 'targetDateToSystemDate':
             result = 'systemDateToTargetDate';
             break;
+        default:
+            throw new Error("Unexpected transform type: ".concat(input));
     }
     return result;
 }
@@ -1960,8 +2138,7 @@ function calculateAllConversions(date, converter) {
             };
         };
         var calculateOffset = function calculateOffset(date) {
-            var offset = getOffsetInMsFn(date);
-            return offset;
+            return getOffsetInMsFn(date);
         };
         var calculateSystemNormalDifference = function calculateSystemNormalDifference(date) {
             var normalOffset = calculateOffset(date);
@@ -2070,12 +2247,11 @@ function calculateAllConversions(date, converter) {
      * For example, when daylight savings changed on November 3, 2024 the offset returned was 5 but to get back to the original an offset of 6 was required.
      * This is where some contextual data was not being used. This function uses that contextual data to make sure the reverse will be consistent.
      *
-     * @param baseDate The base date. Should have been derived from the originalContextDate using the convertDate() function
-     * @param originalContextDate Original date used to derive the baseDate.
-     * @param fromOrTo the "type" of date the originalContextDate is
+     * @param config - configuration for the safe mirrored conversion
+     * @returns the converted date and the DST offset adjustment applied
      */ key: "safeMirroredConvertDate",
-            value: function safeMirroredConvertDate(baseDate, originalContextDate, contextType) {
-                var safeConvert = arguments.length > 3 && arguments[3] !== void 0 ? arguments[3] : true;
+            value: function safeMirroredConvertDate(config) {
+                var baseDate = config.baseDate, originalContextDate = config.originalContextDate, contextType = config.contextType, _config_safeConvert = config.safeConvert, safeConvert = _config_safeConvert === void 0 ? true : _config_safeConvert;
                 if (contextType === 'base') {
                     return {
                         date: baseDate,
@@ -2238,7 +2414,8 @@ function calculateAllConversions(date, converter) {
             /**
      * Returns true if the input is midnight in the target timezone.
      *
-     * @param date
+     * @param date - the date to check
+     * @returns true if the date is at the start of the day in the target timezone
      */ key: "isStartOfDayInTargetTimezone",
             value: function isStartOfDayInTargetTimezone(date) {
                 var utcNormal = this.baseDateToTargetDate(date);
@@ -2249,7 +2426,8 @@ function calculateAllConversions(date, converter) {
             /**
      * Start of the given day in the target timezone.
      *
-     * @param date The input is treated as an instant in time.
+     * @param date - the input is treated as an instant in time
+     * @returns the start-of-day date in the target timezone
      */ key: "startOfDayInTargetTimezone",
             value: function startOfDayInTargetTimezone(date) {
                 var baseDay = this.startOfDayInBaseDate(date);
@@ -2260,7 +2438,8 @@ function calculateAllConversions(date, converter) {
             /**
      * Start of the given day in UTC.
      *
-     * @param date
+     * @param date - the date or ISO8601 day string to get the start of day for
+     * @returns the start of the day as a BaseDateAsUTC
      */ key: "startOfDayInBaseDate",
             value: function startOfDayInBaseDate(date) {
                 if (typeof date === 'string') {
@@ -2275,8 +2454,8 @@ function calculateAllConversions(date, converter) {
             /**
      * End of the given day in UTC.
      *
-     * @param date
-     * @returns
+     * @param date - the date or ISO8601 day string to get the end of day for
+     * @returns the end of the day as a BaseDateAsUTC (23:59:59.999)
      */ key: "endOfDayInBaseDate",
             value: function endOfDayInBaseDate(date) {
                 var result = this.startOfDayInBaseDate(date);
@@ -2288,8 +2467,8 @@ function calculateAllConversions(date, converter) {
             /**
      * Start of the given day for the system.
      *
-     * @param date
-     * @returns
+     * @param date - the date or ISO8601 day string to get the start of day for
+     * @returns the start of the day in the system timezone
      */ key: "startOfDayInSystemDate",
             value: function startOfDayInSystemDate(date) {
                 if (typeof date === 'string') {
@@ -2304,8 +2483,8 @@ function calculateAllConversions(date, converter) {
             /**
      * End of the given day for the system.
      *
-     * @param date
-     * @returns
+     * @param date - the date or ISO8601 day string to get the end of day for
+     * @returns the end of the day in the system timezone
      */ key: "endOfDayInSystemDate",
             value: function endOfDayInSystemDate(date) {
                 return dateFns.endOfDay(this.startOfDayInSystemDate(date));
@@ -2313,9 +2492,10 @@ function calculateAllConversions(date, converter) {
         },
         {
             /**
-     * Whether or not the system experiences daylight savings for the given year.
+     * Whether or not the target timezone experiences daylight savings for the given year.
      *
-     * @param year
+     * @param year - the year to check, as a Date or number; defaults to the current year
+     * @returns true if the target timezone has different offsets in January and July
      */ key: "targetTimezoneExperiencesDaylightSavings",
             value: function targetTimezoneExperiencesDaylightSavings() {
                 var year = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : new Date();
@@ -2372,6 +2552,8 @@ function calculateAllConversions(date, converter) {
  * const same = dateTimezoneUtcNormal(denver); // same reference
  * ```
  *
+ * @param config - timezone input: an existing instance, timezone string, millisecond offset, or config object
+ * @returns a DateTimezoneUtcNormalInstance for the given input
  * @throws Error if the input type is not recognized
  */ function dateTimezoneUtcNormal(config) {
     var instance;
@@ -2394,7 +2576,7 @@ function calculateAllConversions(date, converter) {
                 });
                 break;
             default:
-                throw new Error('Invalid input passed to dateTimezoneUtcNormal()');
+                throw new Error('Invalid input type "'.concat(type, '" passed to dateTimezoneUtcNormal()'));
         }
     }
     return instance;
@@ -2417,6 +2599,8 @@ function calculateAllConversions(date, converter) {
  *
  * Prefer this over constructing a new instance when you need system-timezone conversions,
  * as the singleton avoids unnecessary allocations.
+ *
+ * @returns the shared system-timezone DateTimezoneUtcNormalInstance singleton
  */ function systemDateTimezoneUtcNormal() {
     return SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE;
 }
@@ -2433,10 +2617,13 @@ function calculateAllConversions(date, converter) {
  * const target = baseDateToTargetDate(base, 'America/Denver');
  * // target is 2024-06-15T14:00:00.000-06:00 (2PM MDT)
  * ```
+ *
+ * @param date - the BaseDateAsUTC to convert
+ * @param timezone - the target IANA timezone string
+ * @returns a real instant in the specified timezone
  */ function baseDateToTargetDate(date, timezone) {
     var instance = new DateTimezoneUtcNormalInstance(timezone);
-    var result = instance.baseDateToTargetDate(date);
-    return result;
+    return instance.baseDateToTargetDate(date);
 }
 /**
  * Convenience function that strips the timezone offset from a target-timezone date,
@@ -2451,30 +2638,46 @@ function calculateAllConversions(date, converter) {
  * const base = targetDateToBaseDate(target, 'America/Denver');
  * // base is 2024-06-15T14:00:00.000Z — wall-clock 2PM preserved as UTC
  * ```
+ *
+ * @param date - the target-timezone date to convert
+ * @param timezone - the IANA timezone the date is expressed in
+ * @returns a BaseDateAsUTC with wall-clock time preserved as UTC
  */ function targetDateToBaseDate(date, timezone) {
     return new DateTimezoneUtcNormalInstance(timezone).targetDateToBaseDate(date);
 }
 /**
  * Converts a {@link BaseDateAsUTC} to a target date in the system's local timezone
  * using the shared system-timezone instance.
+ *
+ * @param date - the BaseDateAsUTC to convert
+ * @returns the date converted to the system's local timezone
  */ function systemBaseDateToNormalDate(date) {
     return SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE.baseDateToTargetDate(date);
 }
 /**
  * Converts a target date in the system's local timezone back to a {@link BaseDateAsUTC}
  * using the shared system-timezone instance.
+ *
+ * @param date - the system-timezone target date to convert back to base
+ * @returns the corresponding BaseDateAsUTC
  */ function systemNormalDateToBaseDate(date) {
     return SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE.targetDateToBaseDate(date);
 }
 /**
  * Returns the millisecond offset needed to convert a {@link BaseDateAsUTC} to a target date
  * in the system's local timezone.
+ *
+ * @param date - the date to compute the offset for
+ * @returns the offset in milliseconds
  */ function systemBaseDateToNormalDateOffset(date) {
     return SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE.baseDateToTargetDateOffset(date);
 }
 /**
  * Returns the millisecond offset needed to convert a target date in the system's
  * local timezone back to a {@link BaseDateAsUTC}.
+ *
+ * @param date - the date to compute the offset for
+ * @returns the offset in milliseconds
  */ function systemNormalDateToBaseDateOffset(date) {
     return SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE.targetDateToBaseDateOffset(date);
 }
@@ -2482,6 +2685,9 @@ function calculateAllConversions(date, converter) {
  * Returns whether the system's local timezone observes daylight saving time in the given year.
  *
  * Compares the offset on January 1 and July 1; if they differ, DST is in effect for part of the year.
+ *
+ * @param year - the year to check, as a Date
+ * @returns true if the system timezone observes DST in the given year
  */ function systemExperiencesDaylightSavings(year) {
     return SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE.targetTimezoneExperiencesDaylightSavings(year);
 }
@@ -2497,7 +2703,9 @@ function calculateAllConversions(date, converter) {
  * const result = fn(someDate, (d) => startOfDay(d));
  * ```
  *
+ * @param timezoneInput - timezone configuration for the conversion
  * @param transformType - defaults to `'systemDateToTargetDate'`
+ * @returns a function that transforms dates within the specified timezone normalization
  */ function transformDateInTimezoneNormalFunction(timezoneInput) {
     var transformType = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 'systemDateToTargetDate';
     var timezoneInstance = dateTimezoneUtcNormal(timezoneInput);
@@ -2516,7 +2724,9 @@ function calculateAllConversions(date, converter) {
  * Creates a {@link TransformDateRangeToTimezoneFunction} that converts both dates in
  * a {@link DateRange} using the specified transform type.
  *
+ * @param timezoneInput - timezone configuration for the conversion
  * @param transformType - defaults to `'systemDateToTargetDate'`
+ * @returns a function that converts DateRange dates using the specified transform
  */ function transformDateRangeToTimezoneFunction(timezoneInput) {
     var transformType = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 'systemDateToTargetDate';
     var timezoneInstance = dateTimezoneUtcNormal(timezoneInput);
@@ -2529,7 +2739,9 @@ function calculateAllConversions(date, converter) {
  * Creates a {@link TransformDateRangeInTimezoneNormalFunction} that converts a date range
  * into the specified date space, applies a user-provided range transformation, then converts back.
  *
+ * @param timezoneInput - timezone configuration for the conversion
  * @param transformType - defaults to `'systemDateToTargetDate'`
+ * @returns a function that transforms date ranges within the specified timezone normalization
  */ function transformDateRangeInTimezoneNormalFunction(timezoneInput) {
     var transformType = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 'systemDateToTargetDate';
     var timezoneInstance = dateTimezoneUtcNormal(timezoneInput);
@@ -2553,6 +2765,9 @@ function calculateAllConversions(date, converter) {
  * const midnight = startOfDayInDenver('2024-06-15');
  * // midnight is 2024-06-15T06:00:00.000Z (midnight MDT = 6AM UTC)
  * ```
+ *
+ * @param timezone - timezone configuration to bind the factory to
+ * @returns a factory that converts ISO8601 day strings to start-of-day dates
  */ function startOfDayInTimezoneDayStringFactory(timezone) {
     var timezoneInstance = dateTimezoneUtcNormal(timezone);
     return function(day) {
@@ -2568,6 +2783,10 @@ function calculateAllConversions(date, converter) {
  * ```ts
  * const midnight = startOfDayInTimezoneFromISO8601DayString('2024-06-15', 'America/Denver');
  * ```
+ *
+ * @param day - the ISO8601 day string to parse
+ * @param timezone - timezone configuration for the start-of-day calculation
+ * @returns the start-of-day instant in the given timezone
  */ function startOfDayInTimezoneFromISO8601DayString(day, timezone) {
     return startOfDayInTimezoneDayStringFactory(timezone)(day);
 }
@@ -2584,6 +2803,9 @@ function calculateAllConversions(date, converter) {
  * const result = setOnDate({ date: someDate, hours: 14, minutes: 30, inputType: 'target' });
  * // result is someDate with hours set to 14:30 in Denver time
  * ```
+ *
+ * @param timezone - the timezone configuration to bind to
+ * @returns a function that sets hours/minutes on dates in the given timezone
  */ function setOnDateWithTimezoneNormalFunction(timezone) {
     var timezoneInstance = dateTimezoneUtcNormal(timezone);
     var fn = function fn(input) {
@@ -2601,7 +2823,7 @@ function calculateAllConversions(date, converter) {
                 return roundDownToMinute ? roundDateDownTo(inputDate, 'minute') : inputDate;
             }
             if (inputType !== 'base') {
-                copyFrom = copyFrom != null ? timezoneInstance.convertDate(copyFrom, 'base', inputType) : undefined;
+                copyFrom = timezoneInstance.convertDate(copyFrom, 'base', inputType);
             }
         }
         // set baseDate
@@ -2650,6 +2872,7 @@ function calculateAllConversions(date, converter) {
  *
  * @param input - the date whose day is preserved
  * @param timezone - the timezone context for the hour/minute interpretation
+ * @returns the input date with hours and minutes set to the current time in the given timezone
  */ function copyHoursAndMinutesFromNowWithTimezoneNormal(input, timezone) {
     return copyHoursAndMinutesFromDateWithTimezoneNormal(input, 'now', timezone);
 }
@@ -2670,16 +2893,16 @@ function calculateAllConversions(date, converter) {
  * @param input - the date whose day is preserved
  * @param copyFrom - the date (or `'now'`) whose hours/minutes are copied
  * @param timezone - the timezone context for interpreting both dates
+ * @returns the input date with hours and minutes copied from the source
  */ function copyHoursAndMinutesFromDateWithTimezoneNormal(input, copyFrom, timezone) {
     var timezoneInstance = dateTimezoneUtcNormal(timezone);
-    var result = timezoneInstance.setOnDate({
+    return timezoneInstance.setOnDate({
         date: input,
         copyFrom: copyFrom,
         inputType: 'target',
         copyHours: true,
         copyMinutes: true
     });
-    return result;
 }
 
 function _define_property$e(obj, key, value) {
@@ -2740,6 +2963,7 @@ function _object_spread$c(target) {
  *
  * @param dateRange - the range to fit
  * @param timezone - the timezone for day boundary calculation
+ * @returns the date range fitted to a single day period
  */ function fitDateRangeToDayPeriod(dateRange, timezone) {
     return fitDateRangeToDayPeriodFunction(timezone)(dateRange);
 }
@@ -2750,6 +2974,7 @@ function _object_spread$c(target) {
  * Useful when the same range formatting logic needs to be applied repeatedly with consistent settings.
  *
  * @param inputConfig - format function or full configuration
+ * @returns a reusable function that formats date ranges into strings
  *
  * @example
  * ```ts
@@ -2786,6 +3011,7 @@ function _object_spread$c(target) {
  * @param range - date range to format
  * @param inputConfig - format function or full configuration
  * @param separator - optional separator override when inputConfig is a function
+ * @returns the formatted date range string
  *
  * @example
  * ```ts
@@ -2809,6 +3035,7 @@ function _object_spread$c(target) {
  * (e.g., "3 hours", "about 2 days"). Delegates to date-fns `formatDistance` or `formatDistanceStrict`.
  *
  * @param inputConfig - controls distance formatting, optional transforms, and same-day handling
+ * @returns a reusable function that computes and formats date range distances
  *
  * @example
  * ```ts
@@ -2862,6 +3089,7 @@ function _object_spread$c(target) {
  *
  * @param range - date range to compute distance for
  * @param inputConfig - optional distance formatting configuration
+ * @returns the human-readable distance string
  *
  * @example
  * ```ts
@@ -2902,7 +3130,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
             end = endOrFormat;
         }
     }
-    var format = inputFormat !== null && inputFormat !== void 0 ? inputFormat : formatToShortDateString;
+    var format = inputFormat !== null && inputFormat !== void 0 ? inputFormat : formatToMonthDaySlashDate;
     return formatDateRange(dateOrDateRangeToDateRange(startOrDateRange, end), {
         format: format,
         simplifySameDate: true
@@ -2913,6 +3141,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * instead of throwing.
  *
  * @param input - date, date string, or nullish value
+ * @returns the ISO 8601 date string, or `undefined` if the input is invalid or nullish
  *
  * @example
  * ```ts
@@ -2935,6 +3164,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * Formats a Date to a full ISO 8601 date-time string via `Date.toISOString()`. Defaults to the current date/time.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the full ISO 8601 date-time string
  *
  * @example
  * ```ts
@@ -2954,6 +3184,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * Use {@link toISO8601DayStringForUTC} when the UTC date is needed instead.
  *
  * @param dateOrString - date or existing day string
+ * @returns the ISO 8601 day string in system timezone
  *
  * @example
  * ```ts
@@ -2973,6 +3204,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the ISO 8601 day string in system timezone
  *
  * @example
  * ```ts
@@ -2992,6 +3224,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * Use {@link toISO8601DayStringForSystem} when the system-local date is needed instead.
  *
  * @param dateOrString - date or existing day string
+ * @returns the ISO 8601 day string in UTC
  *
  * @example
  * ```ts
@@ -3012,6 +3245,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the ISO 8601 day string using UTC date components
  *
  * @example
  * ```ts
@@ -3024,12 +3258,18 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
     var date = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : new Date();
     return "".concat(date.getUTCFullYear(), "-").concat((date.getUTCMonth() + 1).toString().padStart(2, '0'), "-").concat(date.getUTCDate().toString().padStart(2, '0'));
 }
-/** date-fns format string for `MM/dd/yyyy` (e.g., `"01/15/2024"`). */ var MONTH_DAY_SLASH_DATE_STRING_FORMAT = 'MM/dd/yyyy';
-/** @deprecated use MONTH_DAY_SLASH_DATE_STRING_FORMAT instead. */ var monthDaySlashDateStringFormat = MONTH_DAY_SLASH_DATE_STRING_FORMAT;
+/**
+ * date-fns format string for `MM/dd/yyyy` (e.g., `"01/15/2024"`).
+ */ var MONTH_DAY_SLASH_DATE_STRING_FORMAT = 'MM/dd/yyyy';
+/**
+ * @deprecated Use MONTH_DAY_SLASH_DATE_STRING_FORMAT instead.
+ */ // eslint-disable-next-line @typescript-eslint/naming-convention
+var monthDaySlashDateStringFormat = MONTH_DAY_SLASH_DATE_STRING_FORMAT;
 /**
  * Formats a Date as a month/day/year slash-separated string (`MM/dd/yyyy`). Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the formatted `MM/dd/yyyy` string
  *
  * @example
  * ```ts
@@ -3045,12 +3285,18 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
 /**
  * @deprecated use formatToMonthDaySlashDate instead.
  */ var formatToShortDateString = formatToMonthDaySlashDate;
-/** date-fns format string for `MM/dd` (e.g., `"01/15"`). */ var DATE_MONTH_DAY_STRING_FORMAT = 'MM/dd';
-/** @deprecated use DATE_MONTH_DAY_STRING_FORMAT instead. */ var dateMonthDayStringFormat = DATE_MONTH_DAY_STRING_FORMAT;
+/**
+ * date-fns format string for `MM/dd` (e.g., `"01/15"`).
+ */ var DATE_MONTH_DAY_STRING_FORMAT = 'MM/dd';
+/**
+ * @deprecated Use DATE_MONTH_DAY_STRING_FORMAT instead.
+ */ // eslint-disable-next-line @typescript-eslint/naming-convention
+var dateMonthDayStringFormat = DATE_MONTH_DAY_STRING_FORMAT;
 /**
  * Formats a Date as a month/day string (`MM/dd`) without the year. Defaults to the current date.
  *
  * @param date - date to format; defaults to `new Date()`
+ * @returns the formatted `MM/dd` string
  *
  * @example
  * ```ts
@@ -3067,6 +3313,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * Formats a Date as a human-friendly weekday and month/day string (e.g., `"Mon, Jan 15th"`).
  *
  * @param date - date to format
+ * @returns the formatted weekday and month/day string
  *
  * @example
  * ```ts
@@ -3078,12 +3325,18 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  */ function formatToDateString(date) {
     return dateFns.format(date, 'EEE, MMM do');
 }
-/** date-fns format string for 12-hour time with AM/PM (e.g., `"9:00 AM"`). */ var DATE_TIME_STRING_FORMAT = 'h:mm a';
-/** @deprecated use DATE_TIME_STRING_FORMAT instead. */ var dateTimeStringFormat = DATE_TIME_STRING_FORMAT;
+/**
+ * date-fns format string for 12-hour time with AM/PM (e.g., `"9:00 AM"`).
+ */ var DATE_TIME_STRING_FORMAT = 'h:mm a';
+/**
+ * @deprecated Use DATE_TIME_STRING_FORMAT instead.
+ */ // eslint-disable-next-line @typescript-eslint/naming-convention
+var dateTimeStringFormat = DATE_TIME_STRING_FORMAT;
 /**
  * Formats a Date as a 12-hour time string with AM/PM (e.g., `"9:00 AM"`).
  *
  * @param date - date to format
+ * @returns the formatted 12-hour time string with AM/PM
  *
  * @example
  * ```ts
@@ -3095,12 +3348,18 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  */ function formatToTimeString(date) {
     return dateFns.format(date, DATE_TIME_STRING_FORMAT);
 }
-/** Combined date-fns format string for `MM/dd/yyyy h:mm a` (e.g., `"01/15/2024 9:00 AM"`). */ var DATE_SHORT_DATE_AND_TIME_STRING_FORMAT = "".concat(MONTH_DAY_SLASH_DATE_STRING_FORMAT, " ").concat(DATE_TIME_STRING_FORMAT);
-/** @deprecated use DATE_SHORT_DATE_AND_TIME_STRING_FORMAT instead. */ var dateShortDateAndTimeStringFormat = DATE_SHORT_DATE_AND_TIME_STRING_FORMAT;
+/**
+ * Combined date-fns format string for `MM/dd/yyyy h:mm a` (e.g., `"01/15/2024 9:00 AM"`).
+ */ var DATE_SHORT_DATE_AND_TIME_STRING_FORMAT = "".concat(MONTH_DAY_SLASH_DATE_STRING_FORMAT, " ").concat(DATE_TIME_STRING_FORMAT);
+/**
+ * @deprecated Use DATE_SHORT_DATE_AND_TIME_STRING_FORMAT instead.
+ */ // eslint-disable-next-line @typescript-eslint/naming-convention
+var dateShortDateAndTimeStringFormat = DATE_SHORT_DATE_AND_TIME_STRING_FORMAT;
 /**
  * Formats a Date as a short date and time string (e.g., `"01/15/2024 9:00 AM"`).
  *
  * @param date - date to format
+ * @returns the formatted short date and time string
  *
  * @example
  * ```ts
@@ -3118,6 +3377,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  *
  * @param start - start date/time
  * @param end - end date/time
+ * @returns the formatted time string with an appended duration indicator
  *
  * @example
  * ```ts
@@ -3139,7 +3399,8 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
             includeSeconds: false
         }), ")");
     } else {
-        subtitle = "".concat(minutes ? "(".concat(minutes, " Minutes)") : '');
+        var minutesLabel = minutes ? "(".concat(minutes, " Minutes)") : '';
+        subtitle = minutesLabel;
     }
     return "".concat(formatToTimeString(start), " ").concat(subtitle);
 }
@@ -3162,6 +3423,11 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * formatStartedEndedDistanceString(activeRange);
  * // "started about 1 hour ago"
  * ```
+ *
+ * @param dateRange - date range with start and end dates
+ * @param dateRange.start - the start date of the range
+ * @param dateRange.end - the end date of the range
+ * @returns the relative-time label describing the date range state
  */ function formatStartedEndedDistanceString(param) {
     var start = param.start, end = param.end;
     var state = dateRangeRelativeState({
@@ -3193,6 +3459,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * Useful for converting heterogeneous date inputs into a consistent midnight-aligned Date.
  *
  * @param input - date or day string to normalize
+ * @returns a Date set to midnight of the corresponding day in the system timezone
  *
  * @example
  * ```ts
@@ -3212,6 +3479,7 @@ function formatToDayRangeString(startOrDateRange, endOrFormat, inputFormat) {
  * in the system timezone. Supports year formats with more than 4 digits but does not support negative years.
  *
  * @param dayString - ISO 8601 day or date string to parse
+ * @returns a Date at the start of the parsed day in the system timezone
  *
  * @example
  * ```ts
@@ -3428,6 +3696,11 @@ function _type_of$5(obj) {
  * The end date is used just to determine the number of days, but a minimum of 1 day is always enforced as a DateCellTiming must contain atleast 1 day.
  *
  * The start date from the inputDate is considered to to have the offset noted in DateCell, and will be retained.
+ *
+ * @param durationInput - the duration span containing the startsAt time and event duration in minutes
+ * @param rangeInput - specifies the date range: a number of days, a DateRange, or a DateRangeDayDistanceInput
+ * @param timezoneInput - optional timezone configuration; defaults to the system timezone if omitted
+ * @returns a fully computed FullDateCellTiming with start, startsAt, end, duration, and timezone
  */ function dateCellTiming(durationInput, rangeInput, timezoneInput) {
     var duration = durationInput.duration;
     if (duration > util.MINUTES_IN_DAY) {
@@ -3482,7 +3755,12 @@ function _type_of$5(obj) {
     var utcDay = formatToISO8601DayStringForUTC(startsAtInUtc);
     var start = normalInstance.startOfDayInTargetTimezone(utcDay);
     var safeMirror = util.isEqualDate(startsAtInUtc, startsAtInUtcInitial);
-    var _normalInstance_safeMirroredConvertDate = normalInstance.safeMirroredConvertDate(startsAtInUtc, inputStartsAt, 'target', safeMirror), startsAt = _normalInstance_safeMirroredConvertDate.date, daylightSavingsOffset = _normalInstance_safeMirroredConvertDate.daylightSavingsOffset;
+    var _normalInstance_safeMirroredConvertDate = normalInstance.safeMirroredConvertDate({
+        baseDate: startsAtInUtc,
+        originalContextDate: inputStartsAt,
+        contextType: 'target',
+        safeConvert: safeMirror
+    }), startsAt = _normalInstance_safeMirroredConvertDate.date, daylightSavingsOffset = _normalInstance_safeMirroredConvertDate.daylightSavingsOffset;
     // calculate end to be the ending date/time of the final duration span
     var lastStartsAtInBaseTimezone = dateFns.addHours(startsAtInUtc, numberOfDayBlocks * 24 + daylightSavingsOffset); // use addHours instead of addDays, since addDays will take into account a daylight savings change if the system time changes
     var lastStartInTarget = normalInstance.targetDateToBaseDate(lastStartsAtInBaseTimezone);
@@ -3742,8 +4020,16 @@ function _calculateExpectedDateCellTimingDurationPair(timing) {
     var normalInstance = dateTimezoneUtcNormal(timezone);
     var startsAtInUtcNormal = normalInstance.baseDateToTargetDate(startsAt); // convert to UTC normal
     var endInUtcNormal = normalInstance.baseDateToTargetDate(end);
-    var _normalInstance_safeMirroredConvertDate = normalInstance.safeMirroredConvertDate(startsAtInUtcNormal, startsAt, 'target'), startDaylightSavingsOffset = _normalInstance_safeMirroredConvertDate.daylightSavingsOffset;
-    var _normalInstance_safeMirroredConvertDate1 = normalInstance.safeMirroredConvertDate(endInUtcNormal, end, 'target'), endDaylightSavingsOffset = _normalInstance_safeMirroredConvertDate1.daylightSavingsOffset;
+    var _normalInstance_safeMirroredConvertDate = normalInstance.safeMirroredConvertDate({
+        baseDate: startsAtInUtcNormal,
+        originalContextDate: startsAt,
+        contextType: 'target'
+    }), startDaylightSavingsOffset = _normalInstance_safeMirroredConvertDate.daylightSavingsOffset;
+    var _normalInstance_safeMirroredConvertDate1 = normalInstance.safeMirroredConvertDate({
+        baseDate: endInUtcNormal,
+        originalContextDate: end,
+        contextType: 'target'
+    }), endDaylightSavingsOffset = _normalInstance_safeMirroredConvertDate1.daylightSavingsOffset;
     if (startDaylightSavingsOffset) {
         startsAtInUtcNormal = dateFns.addHours(startsAtInUtcNormal, startDaylightSavingsOffset);
     }
@@ -3829,7 +4115,7 @@ function _calculateExpectedDateCellTimingDurationPair(timing) {
         isExpectedValidEnd = expectedDuration === duration; // should be the expected duration
         isValid = isExpectedValidEnd;
     }
-    var result = {
+    return {
         isValid: isValid,
         endIsAfterTheStartsAtTime: endIsAfterTheStartsAtTime,
         durationGreaterThanZero: durationGreaterThanZero,
@@ -3838,7 +4124,6 @@ function _calculateExpectedDateCellTimingDurationPair(timing) {
         isExpectedValidEnd: isExpectedValidEnd,
         normalInstance: normalInstance
     };
-    return result;
 }
 /**
  * Returns true if the {@link DateCellTiming} passes all validation checks.
@@ -3903,13 +4188,13 @@ function _calculateExpectedDateCellTimingDurationPair(timing) {
     return isValid;
 }
 
-function _array_like_to_array$5(arr, len) {
+function _array_like_to_array$6(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$2(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$5(arr);
+function _array_without_holes$4(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$6(arr);
 }
 function _define_property$c(obj, key, value) {
     if (key in obj) {
@@ -3924,10 +4209,10 @@ function _define_property$c(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$2(iter) {
+function _iterable_to_array$4(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread$2() {
+function _non_iterable_spread$4() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _object_spread$a(target) {
@@ -3964,20 +4249,20 @@ function _object_spread_props$8(target, source) {
     }
     return target;
 }
-function _to_consumable_array$2(arr) {
-    return _array_without_holes$2(arr) || _iterable_to_array$2(arr) || _unsupported_iterable_to_array$5(arr) || _non_iterable_spread$2();
+function _to_consumable_array$4(arr) {
+    return _array_without_holes$4(arr) || _iterable_to_array$4(arr) || _unsupported_iterable_to_array$6(arr) || _non_iterable_spread$4();
 }
 function _type_of$4(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
-function _unsupported_iterable_to_array$5(o, minLen) {
+function _unsupported_iterable_to_array$6(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$5(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$6(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$5(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$6(o, minLen);
 }
 /**
  * Returns true if the input is a DateCellRange.
@@ -3985,6 +4270,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Does not check validity. Use {@link isValidDateCellRange} for that.
  *
  * @param input - value to check
+ * @returns true if the input is a DateCellRange
  */ function isDateCellRange(input) {
     return (typeof input === "undefined" ? "undefined" : _type_of$4(input)) === 'object' ? Number.isInteger(input.i) && input.to === undefined || Number.isInteger(input.to) : false;
 }
@@ -3995,6 +4281,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * that is greater than or equal to `i`.
  *
  * @param input - range to validate
+ * @returns true if the range has valid non-negative indexes and `to` (when defined) is greater than or equal to `i`
  */ function isValidDateCellRange(input) {
     var i = input.i, to = input.to;
     if (!isValidDateCellIndex(i)) {
@@ -4010,6 +4297,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Validates that each range is individually valid and that no ranges overlap or appear out of order.
  *
  * @param input - array of ranges to validate as a non-overlapping ascending series
+ * @returns true if the array is sorted in ascending order with no overlapping or duplicate indexes
  */ function isValidDateCellRangeSeries(input) {
     if (!Array.isArray(input)) {
         return false;
@@ -4021,13 +4309,30 @@ function _unsupported_iterable_to_array$5(o, minLen) {
         return false;
     }
     var greatestIndex = -1;
-    for(var i = 0; i < input.length; i += 1){
-        var range = input[i];
-        if (range.i <= greatestIndex) {
-            return false;
-        } else {
-            var nextGreatestIndex = range.to || range.i; // to is greater than or equal to i in a valid date block range.
-            greatestIndex = nextGreatestIndex;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = input[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var range = _step.value;
+            if (range.i <= greatestIndex) {
+                return false;
+            } else {
+                var _range_to;
+                var nextGreatestIndex = (_range_to = range.to) !== null && _range_to !== void 0 ? _range_to : range.i; // to is greater than or equal to i in a valid date block range.
+                greatestIndex = nextGreatestIndex;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
         }
     }
     return true;
@@ -4038,6 +4343,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * The input range is not expected to be sorted.
  *
  * @param input - unsorted array of date cell ranges to scan
+ * @returns the smallest starting index found, or 0 if the input is empty
  */ function getLeastDateCellIndexInDateCellRanges(input) {
     var _ref;
     var _getLeastAndGreatestDateCellIndexInDateCellRanges;
@@ -4049,6 +4355,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * The input range is not expected to be sorted.
  *
  * @param input - unsorted array of date cell ranges to scan
+ * @returns the largest ending index found, or 0 if the input is empty
  */ function getGreatestDateCellIndexInDateCellRanges(input) {
     var _ref;
     var _getLeastAndGreatestDateCellIndexInDateCellRanges;
@@ -4060,6 +4367,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * The input range is not expected to be sorted.
  *
  * @param input - unsorted array of date cell ranges to scan
+ * @returns an object with the least and greatest indexes and their source items, or null if the input is empty
  */ function getLeastAndGreatestDateCellIndexInDateCellRanges(input) {
     if (!input.length) {
         return null;
@@ -4068,17 +4376,34 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     var greatestIndex = 0;
     var leastIndexItem = input[0];
     var greatestIndexItem = input[0];
-    for(var i = 0; i < input.length; i += 1){
-        var range = input[i];
-        var leastRangeIndex = range.i;
-        var greatestRangeIndex = range.to || range.i;
-        if (leastRangeIndex < leastIndex) {
-            leastIndex = leastRangeIndex;
-            leastIndexItem = range;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = input[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var range = _step.value;
+            var _range_to;
+            var leastRangeIndex = range.i;
+            var greatestRangeIndex = (_range_to = range.to) !== null && _range_to !== void 0 ? _range_to : range.i;
+            if (leastRangeIndex < leastIndex) {
+                leastIndex = leastRangeIndex;
+                leastIndexItem = range;
+            }
+            if (greatestRangeIndex > greatestIndex) {
+                greatestIndex = greatestRangeIndex;
+                greatestIndexItem = range;
+            }
         }
-        if (greatestRangeIndex > greatestIndex) {
-            greatestIndex = greatestRangeIndex;
-            greatestIndexItem = range;
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
         }
     }
     return {
@@ -4094,6 +4419,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * @param i - starting cell index
  * @param to - ending cell index (inclusive); defaults to `i`
+ * @returns a DateCellRangeWithRange spanning from `i` to `to`
  */ function dateCellRange(i, to) {
     return {
         i: i,
@@ -4104,6 +4430,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Creates a single-cell {@link DateCellRangeWithRange} where both `i` and `to` equal the given index.
  *
  * @param dateCellIndex - the index for both start and end of the range
+ * @returns a DateCellRangeWithRange where `i` and `to` both equal the given index
  */ function dateCellRangeWithRangeFromIndex(dateCellIndex) {
     return dateCellRange(dateCellIndex, dateCellIndex);
 }
@@ -4112,6 +4439,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * ensuring the result always has an explicit `to` value.
  *
  * @param input - index, cell, or range to normalize
+ * @returns a DateCellRangeWithRange with an explicit `to` value
  */ function dateCellRangeWithRange(input) {
     if (typeof input === 'number') {
         return dateCellRangeWithRangeFromIndex(input);
@@ -4124,12 +4452,12 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * fully contains the configured `inputRange`.
  *
  * @param inputRange - the range that must be fully included
+ * @returns a function that returns true when its argument fully contains `inputRange`
  */ function dateCellRangeIncludedByRangeFunction(inputRange) {
     var _dateCellRangeWithRange = dateCellRangeWithRange(inputRange), i = _dateCellRangeWithRange.i, to = _dateCellRangeWithRange.to;
     return function(input) {
-        var _ref;
         var range = dateCellRangeWithRange(input);
-        return range.i <= i && ((_ref = range === null || range === void 0 ? void 0 : range.to) !== null && _ref !== void 0 ? _ref : range.i) >= to;
+        return range.i <= i && range.to >= to;
     };
 }
 /**
@@ -4137,12 +4465,12 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * has any overlap with the configured `inputRange`.
  *
  * @param inputRange - the range to test for overlap against
+ * @returns a function that returns true when its argument overlaps with `inputRange`
  */ function dateCellRangeOverlapsRangeFunction(inputRange) {
     var _dateCellRangeWithRange = dateCellRangeWithRange(inputRange), i = _dateCellRangeWithRange.i, to = _dateCellRangeWithRange.to;
     return function(input) {
-        var _ref;
         var range = dateCellRangeWithRange(input);
-        return range.i <= to && ((_ref = range === null || range === void 0 ? void 0 : range.to) !== null && _ref !== void 0 ? _ref : range.i) >= i;
+        return range.i <= to && range.to >= i;
     };
 }
 /**
@@ -4150,6 +4478,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * @param rangeA - first range to compare
  * @param rangeB - second range to compare
+ * @returns true if the two ranges share at least one common index
  */ function dateCellRangeOverlapsRange(rangeA, rangeB) {
     return dateCellRangeOverlapsRangeFunction(rangeA)(rangeB);
 }
@@ -4157,6 +4486,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Returns a sort comparator that orders ranges first by starting index (`i`), then by ending index (`to`).
  *
  * In many cases {@link sortAscendingIndexNumberRefFunction} may be preferential when `to` ordering is not needed.
+ *
+ * @returns a comparator function that sorts ranges by `i` then by `to`
  */ function sortDateCellRangeAndSizeFunction() {
     return function(a, b) {
         var _a_to, _b_to;
@@ -4167,6 +4498,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Sorts the input date ranges in-place by ascending index using {@link sortAscendingIndexNumberRefFunction}.
  *
  * @param input - array of ranges to sort (mutated in place)
+ * @returns the same array, sorted in ascending index order
  */ function sortDateCellRanges(input) {
     return input.sort(util.sortAscendingIndexNumberRefFunction());
 }
@@ -4177,6 +4509,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * The input is sorted internally before grouping.
  *
  * @param input - cells or ranges to merge into contiguous groups
+ * @returns an array of non-overlapping contiguous DateCellRangeWithRange values
  *
  * @example
  * ```ts
@@ -4224,6 +4557,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Returns an array containing every individual index in the given date cell range (inclusive of both `i` and `to`).
  *
  * @param input - range to expand into individual indexes
+ * @returns an array of every DateCellIndex from `i` to `to` inclusive
  */ function allIndexesInDateCellRange(input) {
     return input.to != null ? util.range(input.i, input.to + 1) : [
         input.i
@@ -4233,6 +4567,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Flattens an array of indexes and/or ranges into a single array of individual {@link DateCellIndex} values.
  *
  * @param input - mix of raw indexes and ranges to flatten
+ * @returns a flat array of all individual DateCellIndex values
  */ function allIndexesInDateCellRangesToArray(input) {
     var result = [];
     input.forEach(function(x) {
@@ -4249,6 +4584,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Returns a deduplicated {@link Set} of all indexes within the input ranges.
  *
  * @param input - mix of raw indexes and ranges to collect
+ * @returns a Set containing every unique DateCellIndex from the input
  */ function allIndexesInDateCellRanges(input) {
     return new Set(allIndexesInDateCellRangesToArray(input));
 }
@@ -4257,6 +4593,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * @param blocks - cells or ranges to filter
  * @param range - bounding range that blocks must fall within
+ * @returns only the blocks that fall entirely within the given range
  */ function filterDateCellsInDateCellRange(blocks, range) {
     var dateCellIsWithinDateCellRange = isDateCellWithinDateCellRangeFunction(range);
     return blocks.filter(dateCellIsWithinDateCellRange);
@@ -4266,6 +4603,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * is fully contained within `inputRange`.
  *
  * @param inputRange - the bounding range to test containment against
+ * @returns a function that returns true when its argument is fully contained within `inputRange`
  */ function isDateCellWithinDateCellRangeFunction(inputRange) {
     var range = dateCellRangeWithRange(inputRange);
     return function(input) {
@@ -4287,6 +4625,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * @param range - the outer bounding range
  * @param contains - the cell or range to test for containment
+ * @returns true if `contains` is fully within `range`
  */ function isDateCellWithinDateCellRange(range, contains) {
     return isDateCellWithinDateCellRangeFunction(range)(dateCellRangeWithRange(contains));
 }
@@ -4296,6 +4635,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Internally groups overlapping ranges before counting so each index is counted only once.
  *
  * @param inputDateCellRange - one or more cells/ranges to analyze
+ * @returns count, total, and average statistics for the given ranges
  */ function dateCellRangeBlocksCountInfo(inputDateCellRange) {
     var group = groupToDateCellRanges(util.asArray(inputDateCellRange));
     var count = 0;
@@ -4318,6 +4658,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Shorthand for `dateCellRangeBlocksCountInfo(input).count`.
  *
  * @param inputDateCellRange - one or more cells/ranges to count
+ * @returns the total number of individual cell indexes
  *
  * @example
  * ```ts
@@ -4332,13 +4673,14 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * grouped range from `ranges` fully covers a given input range.
  *
  * @param ranges - the covering ranges to test against
+ * @returns a function that returns true when any single grouped range fully covers the input range
  */ function dateCellRangesFullyCoverDateCellRangeFunction(ranges) {
     var groupedRanges = Array.isArray(ranges) ? groupToDateCellRanges(ranges) : [
         dateCellRangeWithRange(ranges)
     ];
     return function(inputRange) {
         var fn = dateCellRangeIncludedByRangeFunction(inputRange);
-        return groupedRanges.findIndex(fn) !== -1;
+        return groupedRanges.some(fn);
     };
 }
 /**
@@ -4349,6 +4691,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * nearest future range's starting index is used.
  *
  * @param input - the current index and ranges to evaluate
+ * @returns classification of ranges as past/present/future and the next upcoming index
  *
  * @example
  * ```ts
@@ -4405,6 +4748,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * @param range - the date cell range to classify
  * @param nowIndex - the reference index representing "now"
+ * @returns 'past', 'present', or 'future' depending on the range's position relative to `nowIndex`
  */ function dateRelativeStateForDateCellRangeComparedToIndex(range, nowIndex) {
     var _dateCellRange = dateCellRange(range.i, range.to), i = _dateCellRange.i, to = _dateCellRange.to;
     var state;
@@ -4422,6 +4766,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * from `i` to `to` (inclusive). Each copy retains all properties of the original block.
  *
  * @param block - the range to expand
+ * @returns an array of single-cell copies, one per index from `i` to `to`
  *
  * @example
  * ```ts
@@ -4440,6 +4785,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Returns true if the input spans more than one cell (i.e., has a `to` value strictly greater than `i`).
  *
  * @param input - range or cell to check
+ * @returns true if `to` is defined and strictly greater than `i`
  */ function dateCellRangeHasRange(input) {
     return input.to != null && input.to > input.i;
 }
@@ -4447,6 +4793,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * Returns the effective ending index of a range: `to` if defined, otherwise `i`.
  *
  * @param input - range or cell to read
+ * @returns the `to` index if defined, otherwise `i`
  */ function dateCellEndIndex(input) {
     var _input_to;
     return (_input_to = input.to) !== null && _input_to !== void 0 ? _input_to : input.i;
@@ -4457,8 +4804,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * and `to` is the maximum ending index across all blocks.
  *
  * @param input - cells or ranges to group
+ * @returns a UniqueDateCellRangeGroup containing the sorted blocks with `i` at 0
  */ function groupUniqueDateCells(input) {
-    var blocks = sortDateCellRanges(_to_consumable_array$2(input));
+    var blocks = sortDateCellRanges(_to_consumable_array$4(input));
     var i = 0;
     var to;
     if (blocks.length === 0) {
@@ -4479,6 +4827,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * according to the provided configuration. Handles overlap resolution, gap filling, and boundary clamping.
  *
  * @param config - controls start/end bounds, fill strategy, and overlap retention behavior
+ * @returns a function that merges, fills, and resolves overlaps in date cell range arrays
  *
  * @example
  * ```ts
@@ -4496,9 +4845,10 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     var retainOnOverlap = inputRetainOnOverlap !== null && inputRetainOnOverlap !== void 0 ? inputRetainOnOverlap : 'next';
     var maxAllowedIndex = endAtIndex !== null && endAtIndex !== void 0 ? endAtIndex : Number.MAX_SAFE_INTEGER;
     var fillFactory = inputFillFactory;
-    if (!fillFactory && fill === 'fill') {
+    if (!inputFillFactory && fill === 'fill') {
         throw new Error('fillFactory is required when fillOption is "fill".');
     }
+    // eslint-disable-next-line sonarjs/cognitive-complexity
     return function(input, newBlocks) {
         var addBlockWithRange = function addBlockWithRange(inputBlock, i) {
             var inputTo = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : i;
@@ -4536,7 +4886,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
                     to: to
                 };
                 var block = fillFactory(dateCellRange);
-                addBlockWithRange(block, i, to !== null && to !== void 0 ? to : i);
+                addBlockWithRange(block, i, to);
             } else if (fill === 'empty') ; else if (blocks.length > 0) {
                 // only extend if one or more blocks have been pushed
                 var blockToExtend = util.lastValue(blocks);
@@ -4557,6 +4907,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
         };
         var shouldRetainCurrentOverNext = /**
          * Used to determine how to handle two neighboring objects.
+         *
+         * @returns true if the current block should be retained over the next block
          */ function shouldRetainCurrentOverNext() {
             if (current.priority === next.priority) {
                 return retainOnOverlap === 'current';
@@ -4727,12 +5079,11 @@ function _unsupported_iterable_to_array$5(o, minLen) {
         } else if (fill === 'fill') {
             completeBlocks();
         }
-        var result = {
+        return {
             i: 0,
             blocks: blocks,
             discarded: discarded
         };
-        return result;
     };
 }
 
@@ -4795,6 +5146,9 @@ function _type_of$3(obj) {
  * When `limitToCompletedIndexes` is true, only indexes whose timing duration has fully elapsed are included,
  * with the max boundary lazily refreshed as time passes.
  *
+ * @param config - Configuration specifying the timing, range fit, and completion constraints.
+ * @returns A factory function that produces a clamped {@link DateCellRangeWithRange} from optional start/end input.
+ *
  * @example
  * ```ts
  * const timing = dateCellTiming({ startsAt, duration: 60 }, 5);
@@ -4870,6 +5224,10 @@ function _type_of$3(obj) {
  * Computes a {@link DateCellRangeWithRange} from a timing and optional start/end input.
  *
  * Shorthand for creating a {@link dateCellRangeOfTimingFactory} and immediately invoking it.
+ *
+ * @param config - A {@link DateCellTiming} or full factory configuration.
+ * @param input - Optional start/end boundaries for the range.
+ * @returns A clamped {@link DateCellRangeWithRange} derived from the timing and input.
  */ function dateCellRangeOfTiming(config, input) {
     return dateCellRangeOfTimingFactory(isDateCellTiming(config) ? {
         timing: config
@@ -4880,6 +5238,10 @@ function _type_of$3(obj) {
  * of the timing schedule. Useful for determining which days have already finished.
  *
  * By default fitToTimingRange is true.
+ *
+ * @param timing - The timing schedule to evaluate.
+ * @param config - Optional configuration for the current time reference and range fitting.
+ * @returns A {@link DateCellRangeWithRange} covering only the completed day indexes.
  */ function dateCellTimingCompletedTimeRange(timing, config) {
     var _ref;
     return dateCellRangeOfTiming({
@@ -4893,6 +5255,10 @@ function _type_of$3(obj) {
  * Returns the latest completed day index for a {@link DateCellTiming}.
  *
  * Returns -1 if no days have been completed yet.
+ *
+ * @param timing - The timing schedule to evaluate.
+ * @param now - Optional reference time; defaults to the current time.
+ * @returns The zero-based index of the last fully completed day, or -1 if none.
  */ function dateCellTimingLatestCompletedIndex(timing, now) {
     return dateCellTimingCompletedTimeRange(timing, {
         now: now
@@ -4900,6 +5266,9 @@ function _type_of$3(obj) {
 }
 /**
  * Converts a {@link DateCellRange} (inclusive `to`) to a {@link DateCellIndexRange} (exclusive `maxIndex`).
+ *
+ * @param range - The inclusive date cell range to convert.
+ * @returns A {@link DateCellIndexRange} with exclusive `maxIndex`.
  */ function dateCellRangeToDateCellIndexRange(range) {
     var _range_to;
     return {
@@ -4909,6 +5278,9 @@ function _type_of$3(obj) {
 }
 /**
  * Converts a {@link DateCellIndexRange} (exclusive `maxIndex`) back to a {@link DateCellRangeWithRange} (inclusive `to`).
+ *
+ * @param range - The exclusive date cell index range to convert.
+ * @returns A {@link DateCellRangeWithRange} with inclusive `to`.
  */ function dateCellIndexRangeToDateCellRange(range) {
     return {
         i: range.minIndex,
@@ -4920,6 +5292,11 @@ function _type_of$3(obj) {
  *
  * An arbitrary limit can also be applied. When `fitToTimingRange` is true (default),
  * the limit is intersected with the timing's own range; otherwise the limit is used as-is.
+ *
+ * @param timing - The timing schedule to derive the range from.
+ * @param limit - Optional range input to constrain the output.
+ * @param fitToTimingRange - Whether to intersect the limit with the timing's own range. Defaults to true.
+ * @returns A {@link DateCellIndexRange} representing the computed index bounds.
  */ function dateCellIndexRange(timing, limit) {
     var fitToTimingRange = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : true;
     var indexFactory = dateCellTimingRelativeIndexFactory(timing);
@@ -4948,6 +5325,9 @@ function _type_of$3(obj) {
  * by combining its timing and blocks.
  *
  * Shorthand for calling {@link expandDateCellTiming} with `collection.timing` and `collection.blocks`.
+ *
+ * @param collection - The date cell collection containing timing and blocks to expand.
+ * @returns An array of {@link DateCellDurationSpan} values with concrete start times and durations.
  */ function expandDateCellCollection(collection) {
     return expandDateCellTiming(collection.timing, collection.blocks);
 }
@@ -4955,6 +5335,10 @@ function _type_of$3(obj) {
  * Expands the given blocks into {@link DateCellDurationSpan} values using the provided timing.
  *
  * Shorthand for creating a {@link dateCellTimingExpansionFactory} and immediately invoking it.
+ *
+ * @param timing - The timing schedule providing start times and duration.
+ * @param blocks - The date cell blocks to expand into duration spans.
+ * @returns An array of {@link DateCellDurationSpan} values with concrete start times.
  */ function expandDateCellTiming(timing, blocks) {
     return dateCellTimingExpansionFactory({
         timing: timing
@@ -4968,6 +5352,9 @@ function _type_of$3(obj) {
  * Filtering is applied both at the block level and at the computed duration span level,
  * and evaluation can be capped for performance with large datasets.
  *
+ * @param config - Configuration specifying the timing, range limits, filters, and output caps.
+ * @returns A factory function that expands date cell blocks into {@link DateCellDurationSpan} arrays.
+ *
  * @example
  * ```ts
  * const timing = dateCellTiming({ startsAt, duration: 60 }, 5);
@@ -5065,6 +5452,9 @@ function _type_of$3(obj) {
  * const dateInfo = infoFactory(someDate);
  * console.log(dateInfo.dayIndex);    // which day index this date falls on
  * ```
+ *
+ * @param config - Configuration providing the timing and optional range limit.
+ * @returns A factory that computes {@link DateCellDayTimingInfo} for any date or day index.
  */ function dateCellDayTimingInfoFactory(config) {
     var timing = config.timing, rangeLimit = config.rangeLimit;
     var duration = timing.duration;
@@ -5129,8 +5519,11 @@ function _type_of$3(obj) {
  * Type guard that returns true if the input is a {@link DateCellTimingRelativeIndexFactory}.
  *
  * Checks for the presence of `_timing` and `_normalInstance` properties on a function.
+ *
+ * @param input - The value to check.
+ * @returns True if the input is a {@link DateCellTimingRelativeIndexFactory}.
  */ function isDateCellTimingRelativeIndexFactory(input) {
-    return typeof input === 'function' && input._timing != null && input._normalInstance != null;
+    return typeof input === 'function' && '_timing' in input && '_normalInstance' in input;
 }
 /**
  * Creates a {@link DateCellTimingRelativeIndexFactory} that converts dates, ISO8601 day strings,
@@ -5158,6 +5551,9 @@ function _type_of$3(obj) {
  * indexFactory._timing;         // the original timing
  * indexFactory._normalInstance;  // timezone normalizer
  * ```
+ *
+ * @param input - A timing configuration or an existing factory (returned as-is).
+ * @returns A factory that converts dates, ISO8601 day strings, or indexes to zero-based day offsets.
  */ function dateCellTimingRelativeIndexFactory(input) {
     if (isDateCellTimingRelativeIndexFactory(input)) {
         return input;
@@ -5196,6 +5592,9 @@ function _type_of$3(obj) {
  * dates, date ranges, and cell ranges into a flat array of day indexes.
  *
  * Date ranges and cell ranges are expanded to include every index within the range.
+ *
+ * @param indexFactory - The relative index factory used for date-to-index conversion.
+ * @returns A factory that flattens mixed date/range arrays into day index arrays.
  */ function dateCellTimingRelativeIndexArrayFactory(indexFactory) {
     var factory = function factory(input) {
         var inputAsArray = util.asArray(input);
@@ -5237,6 +5636,10 @@ function _type_of$3(obj) {
  * // Get the index for a specific date
  * const index = getRelativeIndexForDateCellTiming(timing, someDate);
  * ```
+ *
+ * @param timing - The timing providing the start date and timezone context.
+ * @param date - A date or index to convert; defaults to the current date/time.
+ * @returns The zero-based day index relative to the timing's start.
  */ function getRelativeIndexForDateCellTiming(timing) {
     var date = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : new Date();
     return dateCellTimingRelativeIndexFactory(timing)(date);
@@ -5263,6 +5666,9 @@ function _type_of$3(obj) {
  * // Convert index 3 to a date with a specific reference time
  * const dateForDay3AtNoon = dateFactory(3, noonDate);
  * ```
+ *
+ * @param timing - The timing providing the start date and timezone context.
+ * @returns A factory that maps day indexes to calendar dates preserving the current time-of-day.
  */ function dateCellTimingDateFactory(timing) {
     var _dateCellTimingStartPair = dateCellTimingStartPair(timing), start = _dateCellTimingStartPair.start, normalInstance = _dateCellTimingStartPair.normalInstance;
     var utcStartDate = normalInstance.baseDateToTargetDate(start);
@@ -5278,8 +5684,8 @@ function _type_of$3(obj) {
             if (startUtcHours > nowHours) {
                 input += 1;
             }
-            var nowWithDateForIndex = dateFns.addHours(utcStartDateWithNowTime, input * util.HOURS_IN_DAY); // add days to apply the correct offset to the target index
-            return nowWithDateForIndex;
+            // add days to apply the correct offset to the target index
+            return dateFns.addHours(utcStartDateWithNowTime, input * util.HOURS_IN_DAY);
         }
     };
     factory._timing = timing;
@@ -5296,6 +5702,9 @@ function _type_of$3(obj) {
  * const timing = dateCellTiming({ startsAt, duration: 60 }, 5);
  * const lastIndex = dateCellTimingEndIndex(timing); // 4 (zero-based, 5 days)
  * ```
+ *
+ * @param input - A timing or an existing relative index factory.
+ * @returns The zero-based index of the last day in the schedule.
  */ function dateCellTimingEndIndex(input) {
     var factory = dateCellTimingRelativeIndexFactory(input);
     return factory(factory._timing.end);
@@ -5305,6 +5714,9 @@ function _type_of$3(obj) {
  * for any day index relative to the timing's start.
  *
  * The returned date represents the beginning of the day in the timing's timezone context.
+ *
+ * @param input - A timing or an existing relative index factory.
+ * @returns A factory that maps day indexes to the start-of-day date in the timing's timezone.
  */ function dateCellTimingStartDateFactory(input) {
     var indexFactory = dateCellTimingRelativeIndexFactory(input);
     var _dateCellTimingStartPair = dateCellTimingStartPair(indexFactory._timing), start = _dateCellTimingStartPair.start, normalInstance = _dateCellTimingStartPair.normalInstance;
@@ -5342,6 +5754,10 @@ function dateCellTimingEndDateFactory(input) {
 /**
  * Convenience function that returns the calendar date for a given day index or date
  * relative to the timing. Shorthand for creating a {@link dateCellTimingDateFactory} and invoking it.
+ *
+ * @param timing - The timing providing the start date and timezone context.
+ * @param input - A date or day index to convert.
+ * @returns The calendar date corresponding to the input, preserving current time-of-day.
  */ function getRelativeDateForDateCellTiming(timing, input) {
     return dateCellTimingDateFactory(timing)(input);
 }
@@ -5367,6 +5783,9 @@ function dateCellTimingEndDateFactory(input) {
  * });
  * // result has the same start day and end day, but new time-of-day and 90-minute duration
  * ```
+ *
+ * @param input - Configuration specifying the timing to update, the event source, and which aspects to replace.
+ * @returns A new {@link FullDateCellTiming} with the requested aspects replaced.
  */ function updateDateCellTimingWithDateCellTimingEvent(input) {
     var timing = input.timing, event = input.event, replaceStartDay = input.replaceStartDay, replaceStartsAt = input.replaceStartsAt, startDateDay = input.startDayDate, endOnEvent = input.endOnEvent, replaceDuration = input.replaceDuration;
     var timezone = timing.timezone;
@@ -5383,7 +5802,8 @@ function dateCellTimingEndDateFactory(input) {
             var _dateCellTimingStartPair = dateCellTimingStartPair({
                 startsAt: event.startsAt,
                 timezone: timezone
-            }), eventStartDate = _dateCellTimingStartPair.start, normalInstance = _dateCellTimingStartPair.normalInstance;
+            }), initialEventStartDate = _dateCellTimingStartPair.start, normalInstance = _dateCellTimingStartPair.normalInstance;
+            var eventStartDate = initialEventStartDate;
             if (startDateDay != null) {
                 var startDateFactory = dateCellTimingStartDateFactory(timing);
                 eventStartDate = startDateFactory(startDateDay);
@@ -5447,6 +5867,9 @@ function dateCellTimingEndDateFactory(input) {
  * isInRange(6);        // false - index 6 is outside [2, 5]
  * isInRange(someDate); // converts date to index, then checks containment
  * ```
+ *
+ * @param config - Configuration specifying the reference range and optional timezone context.
+ * @returns A predicate function that checks containment within the configured range.
  */ function isDateWithinDateCellRangeFunction(config) {
     var inputStartsAt = config.startsAt, inputRange = config.range;
     var startsAt = inputStartsAt;
@@ -5467,13 +5890,11 @@ function dateCellTimingEndDateFactory(input) {
     } else {
         rangeInput = inputRange;
     }
-    if (!inputStartsAt) {
-        if (dateRange && isDateInput) {
-            startsAt = {
-                startsAt: inputRange,
-                timezone: guessCurrentTimezone()
-            };
-        }
+    if (!inputStartsAt && dateRange && isDateInput) {
+        startsAt = {
+            startsAt: inputRange,
+            timezone: guessCurrentTimezone()
+        };
     }
     if (!startsAt) {
         throw new Error('Invalid isDateWithinDateCellRangeFunction() config. StartsAt date info could not be determined from input.');
@@ -5626,6 +6047,7 @@ function _object_spread_props$6(target, source) {
  * Useful for identifying events or blocks that have already begun relative to a point in time.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose start time is at or before the reference time
  *
  * @example
  * ```ts
@@ -5644,6 +6066,7 @@ function _object_spread_props$6(target, source) {
  * The inverse of {@link dateCellDurationSpanHasStartedFilterFunction}. Useful for finding upcoming or future events.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose start time is strictly after the reference time
  *
  * @example
  * ```ts
@@ -5663,6 +6086,7 @@ function _object_spread_props$6(target, source) {
  * Useful for identifying completed events.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose computed end time is at or before the reference time
  *
  * @example
  * ```ts
@@ -5683,6 +6107,7 @@ function _object_spread_props$6(target, source) {
  * still in progress or have not yet occurred.
  *
  * @param now - Reference time to compare against. Defaults to the current time.
+ * @returns a filter function that returns true for spans whose computed end time is strictly after the reference time
  *
  * @example
  * ```ts
@@ -5704,6 +6129,7 @@ function _object_spread_props$6(target, source) {
  * indices clamped to the range boundaries. Non-overlapping cells are excluded entirely.
  *
  * @param range - The target range to fit cells into.
+ * @returns a reusable function that clamps or filters date cells to the configured range
  *
  * @example
  * ```ts
@@ -5744,6 +6170,7 @@ function _object_spread_props$6(target, source) {
  *
  * @param range - The target range to fit cells into.
  * @param input - The date cells to clamp or filter.
+ * @returns an array of date cells clamped to the range, with non-overlapping cells removed
  *
  * @example
  * ```ts
@@ -5758,6 +6185,7 @@ function _object_spread_props$6(target, source) {
  *
  * @param range - The target range to fit the cell into.
  * @param input - The single date cell to clamp or exclude.
+ * @returns the clamped date cell, or `undefined` if it does not overlap the range
  *
  * @example
  * ```ts
@@ -5772,7 +6200,7 @@ function _object_spread_props$6(target, source) {
     ])[0];
 }
 
-function _array_like_to_array$4(arr, len) {
+function _array_like_to_array$5(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
@@ -5780,6 +6208,9 @@ function _array_like_to_array$4(arr, len) {
 function _array_with_holes$2(arr) {
     if (Array.isArray(arr)) return arr;
 }
+function _array_without_holes$3(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$5(arr);
+}
 function _instanceof(left, right) {
     if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
         return !!right[Symbol.hasInstance](left);
@@ -5787,6 +6218,9 @@ function _instanceof(left, right) {
         return left instanceof right;
     }
 }
+function _iterable_to_array$3(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
 function _iterable_to_array_limit$2(arr, i) {
     var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
     if (_i == null) return;
@@ -5814,16 +6248,22 @@ function _iterable_to_array_limit$2(arr, i) {
 function _non_iterable_rest$2() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
+function _non_iterable_spread$3() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
 function _sliced_to_array$2(arr, i) {
-    return _array_with_holes$2(arr) || _iterable_to_array_limit$2(arr, i) || _unsupported_iterable_to_array$4(arr, i) || _non_iterable_rest$2();
+    return _array_with_holes$2(arr) || _iterable_to_array_limit$2(arr, i) || _unsupported_iterable_to_array$5(arr, i) || _non_iterable_rest$2();
 }
-function _unsupported_iterable_to_array$4(o, minLen) {
+function _to_consumable_array$3(arr) {
+    return _array_without_holes$3(arr) || _iterable_to_array$3(arr) || _unsupported_iterable_to_array$5(arr) || _non_iterable_spread$3();
+}
+function _unsupported_iterable_to_array$5(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$4(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$5(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$5(o, minLen);
 }
 /**
  * Used for default YearWeekCode values
@@ -5929,8 +6369,7 @@ function _unsupported_iterable_to_array$4(o, minLen) {
  * @param input - timezone string, config, or instance
  * @returns the resolved normal instance
  */ function yearWeekCodeDateTimezoneInstance(input) {
-    var normal = input ? _instanceof(input, DateTimezoneUtcNormalInstance) ? input : dateTimezoneUtcNormal(input) : SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE;
-    return normal;
+    return input ? _instanceof(input, DateTimezoneUtcNormalInstance) ? input : dateTimezoneUtcNormal(input) : SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE;
 }
 function yearWeekCode(dateOrYear, inputWeek) {
     return yearWeekCodeFactory({
@@ -5982,6 +6421,7 @@ function yearWeekCode(dateOrYear, inputWeek) {
  *
  * @param dateRange - the range to compute week codes for
  * @param dateRangeTimezone - the timezone context for accurate week boundary calculation
+ * @returns an array of YearWeekCode values covering the range
  */ function yearWeekCodeForDateRangeInTimezone(dateRange, dateRangeTimezone) {
     return yearWeekCodeForDateRangeFactory(yearWeekCodeFactory({
         timezone: dateRangeTimezone
@@ -6014,6 +6454,7 @@ function yearWeekCode(dateOrYear, inputWeek) {
  * Returns all {@link YearWeekCode} values for the calendar month containing the given date, using the system timezone.
  *
  * @param date - a date within the target month
+ * @returns an array of YearWeekCode values for the month
  */ function yearWeekCodeForCalendarMonth(date) {
     return yearWeekCodeForCalendarMonthFactory(yearWeekCodeFactory({
         timezone: SYSTEM_DATE_TIMEZONE_UTC_NORMAL_INSTANCE
@@ -6057,8 +6498,8 @@ function yearWeekCode(dateOrYear, inputWeek) {
         var utcYearDate = new Date(Date.UTC(pair.year, 0, 1, 0, 0, 0, 0));
         var systemYearDate = normal.systemDateToBaseDate(utcYearDate); // convert to system before using system date functions
         var date = dateFns.startOfWeek(dateFns.setWeek(systemYearDate, pair.week));
-        var fixed = normal.targetDateToSystemDate(date); // back to timezone
-        return fixed;
+        // back to timezone
+        return normal.targetDateToSystemDate(date);
     };
 }
 /**
@@ -6112,10 +6553,10 @@ function yearWeekCode(dateOrYear, inputWeek) {
             }
             return yearWeekCode;
         });
-        var groups = Array.from(map.entries()).map(function(param) {
+        var groups = _to_consumable_array$3(map.entries()).map(function(param) {
             var _param = _sliced_to_array$2(param, 2), week = _param[0], _$items = _param[1];
             return {
-                week: week || 0,
+                week: week !== null && week !== void 0 ? week : 0,
                 items: _$items
             };
         });
@@ -6154,8 +6595,7 @@ function yearWeekCode(dateOrYear, inputWeek) {
     var normalInstance = startDateFactory._indexFactory._normalInstance;
     return function(indexOrDate) {
         var dateInSystemTimezone = normalInstance.systemDateToTargetDate(startDateFactory(indexOrDate));
-        var yearWeekCode = yearWeekCodeFromDate(dateInSystemTimezone);
-        return yearWeekCode;
+        return yearWeekCodeFromDate(dateInSystemTimezone);
     };
 }
 /**
@@ -6166,21 +6606,20 @@ function yearWeekCode(dateOrYear, inputWeek) {
  */ function dateCellIndexYearWeekCodeGroupFactory(config) {
     var dateCellIndexReader = config.dateCellIndexReader, inputDateCellIndexYearWeekCodeFactory = config.dateCellIndexYearWeekCodeFactory;
     var dateCellIndexYearWeekCode = typeof inputDateCellIndexYearWeekCodeFactory === 'function' ? inputDateCellIndexYearWeekCodeFactory : dateCellIndexYearWeekCodeFactory(inputDateCellIndexYearWeekCodeFactory);
-    var factory = yearWeekCodeGroupFactory({
+    return yearWeekCodeGroupFactory({
         yearWeekCodeFactory: dateCellIndexYearWeekCode,
         yearWeekCodeReader: dateCellIndexYearWeekCode,
         dateReader: dateCellIndexReader
     });
-    return factory;
 }
 
-function _array_like_to_array$3(arr, len) {
+function _array_like_to_array$4(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$1(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$3(arr);
+function _array_without_holes$2(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$4(arr);
 }
 function _define_property$9(obj, key, value) {
     if (key in obj) {
@@ -6195,10 +6634,10 @@ function _define_property$9(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$1(iter) {
+function _iterable_to_array$2(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread$1() {
+function _non_iterable_spread$2() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _object_spread$7(target) {
@@ -6235,20 +6674,20 @@ function _object_spread_props$5(target, source) {
     }
     return target;
 }
-function _to_consumable_array$1(arr) {
-    return _array_without_holes$1(arr) || _iterable_to_array$1(arr) || _unsupported_iterable_to_array$3(arr) || _non_iterable_spread$1();
+function _to_consumable_array$2(arr) {
+    return _array_without_holes$2(arr) || _iterable_to_array$2(arr) || _unsupported_iterable_to_array$4(arr) || _non_iterable_spread$2();
 }
 function _type_of$2(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
-function _unsupported_iterable_to_array$3(o, minLen) {
+function _unsupported_iterable_to_array$4(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$3(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$4(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$3(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
 }
 /**
  * Encodes days of the week as numeric codes for use in schedule filtering.
@@ -6313,7 +6752,7 @@ function _unsupported_iterable_to_array$3(o, minLen) {
  * @param input - schedule day codes to convert (WEEKDAY/WEEKEND shorthand codes are expanded)
  * @returns an EnabledDays object with boolean flags for each day
  */ function enabledDaysFromDateCellScheduleDayCodes(input) {
-    var days = expandDateCellScheduleDayCodesToDayOfWeekSet(Array.from(new Set(input)));
+    var days = expandDateCellScheduleDayCodesToDayOfWeekSet(_to_consumable_array$2(new Set(input)));
     return util.enabledDaysFromDaysOfWeek(days);
 }
 /**
@@ -6461,7 +6900,7 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  * @param input - day codes to expand
  * @returns sorted array of individual day codes (1-7 only, no shorthand)
  */ function expandDateCellScheduleDayCodes(input) {
-    return Array.from(expandDateCellScheduleDayCodesToDayCodesSet(input)).sort(util.sortNumbersAscendingFunction);
+    return _to_consumable_array$2(expandDateCellScheduleDayCodesToDayCodesSet(input)).sort(util.sortNumbersAscendingFunction);
 }
 /**
  * Expands the input DateCellScheduleDayCodesInput to a Set of individual DateCellScheduleDayCode values (1-7), expanding shorthand codes like WEEKDAY and WEEKEND.
@@ -6499,7 +6938,7 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
     var dayCodes;
     switch(typeof input === "undefined" ? "undefined" : _type_of$2(input)){
         case 'string':
-            dayCodes = Array.from(new Set(input)).map(function(x) {
+            dayCodes = _to_consumable_array$2(new Set(input)).map(function(x) {
                 return Number(x);
             });
             break;
@@ -6509,7 +6948,7 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
             ];
             break;
         default:
-            dayCodes = Array.from(input);
+            dayCodes = _to_consumable_array$2(input);
             break;
     }
     return dayCodes.filter(function(x) {
@@ -6618,7 +7057,6 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
     var timezone = inputTimezone !== null && inputTimezone !== void 0 ? inputTimezone : requireCurrentTimezone(); // treat input as the current timezone
     var normalInstance = dateTimezoneUtcNormal(timezone);
     var start;
-    var end;
     // either start or startsAt is provided
     if (inputStart != null) {
         var startInSystemTimezone = normalInstance.systemDateToTargetDate(inputStart); // start needs to be in the system timezone normal before processing.
@@ -6635,7 +7073,7 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
         }
     }
     // set the end value
-    end = inputEnd !== null && inputEnd !== void 0 ? inputEnd : dateFns.addMinutes(start, 1); // default the end to one minute after the start
+    var end = inputEnd !== null && inputEnd !== void 0 ? inputEnd : dateFns.addMinutes(start, 1); // default the end to one minute after the start
     return {
         w: w,
         ex: ex,
@@ -6837,11 +7275,12 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  * filter(5);  // false (Saturday Jan 11)
  * ```
  */ function dateCellScheduleDateFilter(config) {
+    var _ref;
     var w = config.w, inputStart = config.start, inputStartsAt = config.startsAt, inputEnd = config.end, inputTimezone = config.timezone, _config_setStartAsMinDate = config.setStartAsMinDate, setStartAsMinDate = _config_setStartAsMinDate === void 0 ? true : _config_setStartAsMinDate, minMaxDateRange = config.minMaxDateRange;
     var timezone = inputTimezone !== null && inputTimezone !== void 0 ? inputTimezone : requireCurrentTimezone(); // if the timezone is not provided, assume the startsAt is a system timezone normal.
     var normalInstance = dateTimezoneUtcNormal(timezone);
     // derive the startsAt time for the range. If not provided, defaults to inputStart, or midnight today in the target timezone.
-    var startsAt = inputStartsAt != null ? inputStartsAt : inputStart !== null && inputStart !== void 0 ? inputStart : normalInstance.startOfDayInTargetTimezone();
+    var startsAt = (_ref = inputStartsAt !== null && inputStartsAt !== void 0 ? inputStartsAt : inputStart) !== null && _ref !== void 0 ? _ref : normalInstance.startOfDayInTargetTimezone();
     var allowedDays = expandDateCellScheduleDayCodesToDayOfWeekSet(w);
     var startsAtInSystem = normalInstance.systemDateToTargetDate(startsAt); // convert to the system date
     var firstDateDay = dateFns.getDay(startsAtInSystem);
@@ -6867,15 +7306,13 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
     var excludedIndexes = new Set(config.ex);
     var fn = function fn(input) {
         var i;
-        var day;
         if (typeof input === 'number') {
             i = input;
         } else {
             i = _dateCellTimingRelativeIndexFactory(input);
         }
-        day = dayForIndex(i);
-        var result = i >= minAllowedIndex && i <= maxAllowedIndex && allowedDays.has(day) && !excludedIndexes.has(i) || includedIndexes.has(i);
-        return result;
+        var day = dayForIndex(i);
+        return i >= minAllowedIndex && i <= maxAllowedIndex && allowedDays.has(day) && !excludedIndexes.has(i) || includedIndexes.has(i);
     };
     fn._dateCellTimingRelativeIndexFactory = _dateCellTimingRelativeIndexFactory;
     return fn;
@@ -6929,6 +7366,8 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  * Creates a DateCellScheduleDateCellTimingFilter that tests whether a DateCell block's index is allowed by the schedule within the given timing.
  *
  * @param config - timing and schedule to build the filter from
+ * @param config.timing - the DateCellTiming that defines the date range and event times for the filter
+ * @param config.schedule - the DateCellSchedule that controls which day codes and indices are included or excluded
  * @returns a decision function returning true for allowed blocks
  */ function dateCellScheduleDateCellTimingFilter(param) {
     var timing = param.timing, schedule = param.schedule;
@@ -6952,7 +7391,6 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  * @returns an expansion factory that converts DateCellRange arrays into filtered DateCellDurationSpan arrays
  */ function expandDateCellScheduleFactory(config) {
     var _config_invertSchedule = config.invertSchedule, invertSchedule = _config_invertSchedule === void 0 ? false : _config_invertSchedule, now = config.now, onlyBlocksThatHaveEnded = config.onlyBlocksThatHaveEnded, onlyBlocksThatHaveStarted = config.onlyBlocksThatHaveStarted, onlyBlocksNotYetEnded = config.onlyBlocksNotYetEnded, onlyBlocksNotYetStarted = config.onlyBlocksNotYetStarted, maxDateCellsToReturn = config.maxDateCellsToReturn, inputDurationSpanFilter = config.durationSpanFilter;
-    var durationSpanFilter;
     var durationSpanFilters = [];
     if (inputDurationSpanFilter) {
         durationSpanFilters.push(inputDurationSpanFilter);
@@ -6969,14 +7407,13 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
             durationSpanFilters.push(dateCellDurationSpanHasNotEndedFilterFunction(now));
         }
     }
-    durationSpanFilter = util.mergeFilterFunctions.apply(void 0, _to_consumable_array$1(durationSpanFilters));
-    var expansionFactory = dateCellTimingExpansionFactory({
+    var durationSpanFilter = util.mergeFilterFunctions.apply(void 0, _to_consumable_array$2(durationSpanFilters));
+    return dateCellTimingExpansionFactory({
         timing: config.timing,
         filter: util.invertFilter(dateCellScheduleDateCellTimingFilter(config), invertSchedule),
         durationSpanFilter: durationSpanFilter,
         maxDateCellsToReturn: maxDateCellsToReturn
     });
-    return expansionFactory;
 }
 /**
  * Expands a DateCellTiming and DateCellSchedule into concrete DateCellDurationSpan values representing each active block in the event.
@@ -7062,16 +7499,155 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
     });
 }
 
+function _define_property$8(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _object_spread$6(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$8(target, key, source[key]);
+        });
+    }
+    return target;
+}
+/**
+ * Distinguishes between time-based calendar events and all-day/multi-day events.
+ */ exports.CalendarDateType = void 0;
+(function(CalendarDateType) {
+    /**
+     * Event starts at a specific time and lasts for a certain duration.
+     */ CalendarDateType["TIME"] = "time";
+    /**
+     * Event is specifically for a number of days. Duration is still tracked in minutes.
+     */ CalendarDateType["DAYS"] = "days";
+})(exports.CalendarDateType || (exports.CalendarDateType = {}));
+/**
+ * Creates a {@link CalendarDateFactory} that produces all-day calendar events with timezone-aware start times.
+ *
+ * The factory converts an ISO 8601 day string to a UTC date, then applies timezone normalization
+ * so the resulting `startsAt` represents the correct moment for the target timezone.
+ *
+ * @param config - optional timezone configuration
+ * @returns a factory function that creates CalendarDate objects
+ *
+ * @example
+ * ```ts
+ * const factory = calendarDateFactory({ timezone: 'America/Denver' });
+ * const event = factory('2024-01-15', 3);
+ * // event.type === CalendarDateType.DAYS
+ * // event.duration === daysToMinutes(3)
+ * ```
+ */ function calendarDateFactory(config) {
+    var normalConfig = (config === null || config === void 0 ? void 0 : config.timezone) === undefined ? {
+        useSystemTimezone: true
+    } : {
+        timezone: config.timezone ? config.timezone : undefined
+    };
+    var normal = dateTimezoneUtcNormal(normalConfig);
+    return function(day, days) {
+        var date = util.parseISO8601DayStringToUTCDate(day);
+        var startsAt = normal.targetDateToBaseDate(date);
+        return {
+            type: exports.CalendarDateType.DAYS,
+            startsAt: startsAt,
+            duration: daysToMinutes(days)
+        };
+    };
+}
+/**
+ * Convenience function that creates a single all-day {@link CalendarDate} with optional timezone.
+ *
+ * Shorthand for creating a factory and immediately invoking it.
+ *
+ * @param day - ISO 8601 day string (e.g. '2024-01-15')
+ * @param days - number of days the event spans
+ * @param timezone - IANA timezone string, false for UTC, or undefined for system timezone
+ * @returns a CalendarDate with type DAYS
+ *
+ * @example
+ * ```ts
+ * const event = calendarDate('2024-01-15', 1, 'America/Denver');
+ * // event.type === CalendarDateType.DAYS
+ * ```
+ */ function calendarDate(day, days, timezone) {
+    return calendarDateFactory({
+        timezone: timezone
+    })(day, days);
+}
+/**
+ * Wraps an existing {@link DateDurationSpan} as a time-based {@link CalendarDate}.
+ *
+ * @param dateDurationSpan - the duration span to wrap
+ * @returns a CalendarDate with type TIME
+ *
+ * @example
+ * ```ts
+ * const span: DateDurationSpan = { startsAt: new Date(), duration: 60 };
+ * const event = calendarDateForDateDurationSpan(span);
+ * // event.type === CalendarDateType.TIME
+ * ```
+ */ function calendarDateForDateDurationSpan(dateDurationSpan) {
+    return _object_spread$6({
+        type: exports.CalendarDateType.TIME
+    }, dateDurationSpan);
+}
+
+function _array_like_to_array$3(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes$1(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$3(arr);
+}
+function _iterable_to_array$1(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread$1() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array$1(arr) {
+    return _array_without_holes$1(arr) || _iterable_to_array$1(arr) || _unsupported_iterable_to_array$3(arr) || _non_iterable_spread$1();
+}
+function _unsupported_iterable_to_array$3(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$3(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$3(o, minLen);
+}
 /**
  * Returns all recognized IANA timezone strings, including the explicit UTC entry.
  *
+ * @returns all known IANA timezone strings plus UTC
+ *
  * @example
  * ```ts
  * const zones = allTimezoneStrings();
  * // ['Africa/Abidjan', ..., 'UTC']
  * ```
  */ function allTimezoneStrings() {
-    return tzdb.timeZonesNames.concat(util.UTC_TIMEZONE_STRING);
+    return _to_consumable_array$1(tzdb.timeZonesNames).concat([
+        util.UTC_TIMEZONE_STRING
+    ]);
 }
 /**
  * Lazily-computed set of all known timezone strings for O(1) membership checks.
@@ -7097,6 +7673,8 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
 /**
  * Returns the {@link TimezoneInfo} for the current system timezone, falling back to UTC.
  *
+ * @returns timezone info for the current system timezone
+ *
  * @example
  * ```ts
  * const info = timezoneInfoForSystem();
@@ -7112,6 +7690,10 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  * The date matters because abbreviations change with DST transitions.
  * Returns `"UKNOWN"` if no timezone is provided.
  *
+ * @param timezone - the IANA timezone string (or UTC abbreviation) to get the abbreviation for
+ * @param date - the date at which to evaluate the abbreviation (defaults to now)
+ * @returns the short timezone abbreviation
+ *
  * @example
  * ```ts
  * getTimezoneAbbreviation('America/New_York'); // 'EST' or 'EDT'
@@ -7125,6 +7707,10 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  *
  * Returns `"Unknown Timezone"` if no timezone is provided.
  *
+ * @param timezone - the IANA timezone string to get the long name for
+ * @param date - the date at which to evaluate the name (defaults to now)
+ * @returns the full timezone display name
+ *
  * @example
  * ```ts
  * getTimezoneLongName('America/New_York'); // 'Eastern Standard Time'
@@ -7136,6 +7722,10 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
 /**
  * Builds a {@link TimezoneInfo} for the given timezone, computing abbreviation and search variants.
  *
+ * @param timezone - the IANA timezone string to build info for
+ * @param date - the date at which to evaluate the abbreviation (defaults to now)
+ * @returns the computed TimezoneInfo
+ *
  * @example
  * ```ts
  * const info = timezoneStringToTimezoneInfo('America/Chicago');
@@ -7145,14 +7735,13 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  */ function timezoneStringToTimezoneInfo(timezone) {
     var date = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : new Date();
     var abbreviation = getTimezoneAbbreviation(timezone, date);
-    var result = {
+    return {
         timezone: timezone,
         search: timezoneStringToSearchableString(timezone),
         lowercase: timezone.toLowerCase(),
         abbreviation: abbreviation,
         lowercaseAbbreviation: abbreviation.toLowerCase()
     };
-    return result;
 }
 /**
  * Filters timezone infos by a search string, matching against the searchable name,
@@ -7160,6 +7749,10 @@ var DATE_CELL_SCHEDULE_ENCODED_WEEK_REGEX = /^[0-9]{0,9}$/;
  *
  * For queries longer than 2 characters, substring matching on the searchable name is also used.
  *
+ * @param search - the search query string
+ * @param infos - the array of TimezoneInfo objects to filter
+ * @returns the matching TimezoneInfo entries
+ *
  * @example
  * ```ts
  * const results = searchTimezoneInfos('eastern', allTimezoneInfos());
@@ -7182,6 +7775,9 @@ var timezoneStringToSearchableStringReplace = util.replaceStringsFunction({
  *
  * Replaces `/` and `_` with spaces (e.g., `"America/New_York"` becomes `"america new york"`).
  *
+ * @param timezone - the IANA timezone string to convert
+ * @returns the searchable lowercase string
+ *
  * @example
  * ```ts
  * timezoneStringToSearchableString('America/New_York'); // 'america new york'
@@ -7194,6 +7790,9 @@ var timezoneStringToSearchableStringReplace = util.replaceStringsFunction({
  *
  * Uses the cached set from {@link allKnownTimezoneStrings} for O(1) lookup.
  *
+ * @param input - the string to check
+ * @returns whether the input is a known timezone
+ *
  * @example
  * ```ts
  * isKnownTimezone('America/New_York'); // true
@@ -7203,116 +7802,6 @@ var timezoneStringToSearchableStringReplace = util.replaceStringsFunction({
     return allKnownTimezoneStrings().has(input);
 }
 
-function _define_property$8(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
-function _object_spread$6(target) {
-    for(var i = 1; i < arguments.length; i++){
-        var source = arguments[i] != null ? arguments[i] : {};
-        var ownKeys = Object.keys(source);
-        if (typeof Object.getOwnPropertySymbols === "function") {
-            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
-                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
-            }));
-        }
-        ownKeys.forEach(function(key) {
-            _define_property$8(target, key, source[key]);
-        });
-    }
-    return target;
-}
-/**
- * Distinguishes between time-based calendar events and all-day/multi-day events.
- */ exports.CalendarDateType = void 0;
-(function(CalendarDateType) {
-    /**
-     * Event starts at a specific time and lasts for a certain duration.
-     */ CalendarDateType["TIME"] = "time";
-    /**
-     * Event is specifically for a number of days. Duration is still tracked in minutes.
-     */ CalendarDateType["DAYS"] = "days";
-})(exports.CalendarDateType || (exports.CalendarDateType = {}));
-/**
- * Creates a {@link CalendarDateFactory} that produces all-day calendar events with timezone-aware start times.
- *
- * The factory converts an ISO 8601 day string to a UTC date, then applies timezone normalization
- * so the resulting `startsAt` represents the correct moment for the target timezone.
- *
- * @param config - optional timezone configuration
- * @returns a factory function that creates CalendarDate objects
- *
- * @example
- * ```ts
- * const factory = calendarDateFactory({ timezone: 'America/Denver' });
- * const event = factory('2024-01-15', 3);
- * // event.type === CalendarDateType.DAYS
- * // event.duration === daysToMinutes(3)
- * ```
- */ function calendarDateFactory(config) {
-    var normalConfig = (config === null || config === void 0 ? void 0 : config.timezone) === undefined ? {
-        useSystemTimezone: true
-    } : {
-        timezone: config.timezone ? config.timezone : undefined
-    };
-    var normal = dateTimezoneUtcNormal(normalConfig);
-    return function(day, days) {
-        var date = util.parseISO8601DayStringToUTCDate(day);
-        var startsAt = normal.targetDateToBaseDate(date);
-        return {
-            type: exports.CalendarDateType.DAYS,
-            startsAt: startsAt,
-            duration: daysToMinutes(days)
-        };
-    };
-}
-/**
- * Convenience function that creates a single all-day {@link CalendarDate} with optional timezone.
- *
- * Shorthand for creating a factory and immediately invoking it.
- *
- * @param day - ISO 8601 day string (e.g. '2024-01-15')
- * @param days - number of days the event spans
- * @param timezone - IANA timezone string, false for UTC, or undefined for system timezone
- * @returns a CalendarDate with type DAYS
- *
- * @example
- * ```ts
- * const event = calendarDate('2024-01-15', 1, 'America/Denver');
- * // event.type === CalendarDateType.DAYS
- * ```
- */ function calendarDate(day, days, timezone) {
-    return calendarDateFactory({
-        timezone: timezone
-    })(day, days);
-}
-/**
- * Wraps an existing {@link DateDurationSpan} as a time-based {@link CalendarDate}.
- *
- * @param dateDurationSpan - the duration span to wrap
- * @returns a CalendarDate with type TIME
- *
- * @example
- * ```ts
- * const span: DateDurationSpan = { startsAt: new Date(), duration: 60 };
- * const event = calendarDateForDateDurationSpan(span);
- * // event.type === CalendarDateType.TIME
- * ```
- */ function calendarDateForDateDurationSpan(dateDurationSpan) {
-    return _object_spread$6({
-        type: exports.CalendarDateType.TIME
-    }, dateDurationSpan);
-}
-
 function _array_like_to_array$2(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -7352,7 +7841,7 @@ var _type, _type1;
  * const result = knownTimezoneType('America/Denver');
  * ```
  */ var knownTimezoneType = arktype.type('string > 0').narrow(function(val, ctx) {
-    return val != null && isKnownTimezone(val) || ctx.mustBe('a known timezone');
+    return isKnownTimezone(val) || ctx.mustBe('a known timezone');
 });
 // MARK: DateDurationSpan
 /**
@@ -7466,21 +7955,21 @@ var _type, _type1;
  * Accepts both Date objects and date strings (parsed via `string.date.parse`), then validates the resulting timing
  * using {@link isValidDateCellTiming}.
  */ var validDateCellTimingType = dateCellTimingType.narrow(function(val, ctx) {
-    return val != null && isValidDateCellTiming(val) || ctx.mustBe('a valid DateCellTiming');
+    return isValidDateCellTiming(val) || ctx.mustBe('a valid DateCellTiming');
 });
 /**
  * ArkType DTO schema that validates a value is a valid {@link DateCellRange} (non-negative indexes, `to >= i`).
  *
  * Validates cell range data from JSON/DTO input.
  */ var validDateCellRangeType = dateCellRangeType.narrow(function(val, ctx) {
-    return val != null && isValidDateCellRange(val) || ctx.mustBe('a valid DateCellRange');
+    return isValidDateCellRange(val) || ctx.mustBe('a valid DateCellRange');
 });
 /**
  * ArkType DTO schema that validates a value is a sorted array of non-overlapping {@link DateCellRange} values.
  *
  * Validates cell range series data from JSON/DTO input.
  */ var validDateCellRangeSeriesType = arktype.type(dateCellRangeType.array()).narrow(function(val, ctx) {
-    return val != null && isValidDateCellRangeSeries(val) || ctx.mustBe('a valid DateCellRange series with items sorted in ascending order and no repeat indexes');
+    return isValidDateCellRangeSeries(val) || ctx.mustBe('a valid DateCellRange series with items sorted in ascending order and no repeat indexes');
 });
 
 function _assert_this_initialized$1(self) {
@@ -7760,7 +8249,7 @@ function _object_spread_props$4(target, source) {
         logicalDate = 'now';
     }
     var intervalPeriod = period !== null && period !== void 0 ? period : util.MS_IN_SECOND;
-    var factory = inputFactory ? inputFactory : util.protectedFactory(logicalDateStringCodeDateFactory(logicalDate));
+    var factory = inputFactory !== null && inputFactory !== void 0 ? inputFactory : util.protectedFactory(logicalDateStringCodeDateFactory(logicalDate));
     var obs = rxjs.interval(intervalPeriod, scheduler).pipe(rxjs.startWith(-1), rxjs.map(factory));
     if (emitAll !== true) {
         obs = obs.pipe(rxjs.distinctUntilChanged(isSameDate));
@@ -7852,7 +8341,8 @@ function _define_property$6(obj, key, value) {
         {
             key: "instant",
             get: function get() {
-                return this._config.instant || 'now';
+                var _this__config_instant;
+                return (_this__config_instant = this._config.instant) !== null && _this__config_instant !== void 0 ? _this__config_instant : 'now';
             }
         },
         {
@@ -7897,10 +8387,8 @@ function _define_property$6(obj, key, value) {
                 var _this__config = this._config, _this__config_instant = _this__config.instant, instant = _this__config_instant === void 0 ? new Date() : _this__config_instant, _this__config_limits = _this__config.limits, limits = _this__config_limits === void 0 ? {} : _this__config_limits;
                 var isPast = limits.isPast, max = limits.max;
                 var limit = max;
-                if (typeof max !== 'string' && isPast) {
-                    if (!max || dateFns.isBefore(max, instant)) {
-                        limit = util.DATE_NOW_VALUE;
-                    }
+                if (typeof max !== 'string' && isPast && (!max || dateFns.isBefore(max, instant))) {
+                    limit = util.DATE_NOW_VALUE;
                 }
                 return limit;
             }
@@ -7915,6 +8403,8 @@ function _define_property$6(obj, key, value) {
      * const limiter = new LimitDateTimeInstance({ limits: { isFuture: true } });
      * const range = limiter.dateRange(); // { start: <now>, end: undefined }
      * ```
+     *
+     * @returns A partial {@link DateRange} with `start` and/or `end` derived from the limits.
      */ key: "dateRange",
             value: function dateRange() {
                 var _this__config = this._config, _this__config_instant = _this__config.instant, instant = _this__config_instant === void 0 ? new Date() : _this__config_instant;
@@ -7927,6 +8417,7 @@ function _define_property$6(obj, key, value) {
      * like "now" or relative future offsets to resolve against the given moment.
      *
      * @param instant - The reference point in time for resolving dynamic limits.
+     * @returns A partial {@link DateRange} resolved against the given instant.
      */ key: "dateRangeForInstant",
             value: function dateRangeForInstant(instant) {
                 var _this = this, min = _this.min, max = _this.max;
@@ -7950,6 +8441,8 @@ function _define_property$6(obj, key, value) {
      * });
      * const safe = limiter.clamp(new Date()); // at least 30 minutes from now
      * ```
+     *
+     * @returns The clamped date within the allowed range.
      */ key: "clamp",
             value: function clamp(date) {
                 var result = date;
@@ -7987,6 +8480,8 @@ function _define_property$6(obj, key, value) {
      * const clamped = limiter.clampDateRange({ start: pastDate, end: futureDate });
      * // clamped.start will be at least now
      * ```
+     *
+     * @returns The date range clamped to the allowed limits.
      */ key: "clampDateRange",
             value: function clampDateRange(dateRange) {
                 return clampDateRangeToDateRange(dateRange, this.dateRange());
@@ -8008,6 +8503,8 @@ function _define_property$6(obj, key, value) {
  * });
  * const clamped = limiter.clamp(someDate);
  * ```
+ *
+ * @returns A new {@link LimitDateTimeInstance}.
  */ function limitDateTimeInstance(config) {
     return new LimitDateTimeInstance(config);
 }
@@ -8099,14 +8596,14 @@ function _object_spread_props$3(target, source) {
     function DateTimeMinuteInstance() {
         var config = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {}, dateOverride = arguments.length > 1 ? arguments[1] : void 0;
         _class_call_check$5(this, DateTimeMinuteInstance);
-        var _config_step;
+        var _ref, _config_step;
         _define_property$5(this, "_config", void 0);
         _define_property$5(this, "_date", void 0);
         _define_property$5(this, "_step", void 0);
         _define_property$5(this, "_limit", void 0);
         _define_property$5(this, "_dateFilter", void 0);
         this._config = config;
-        this._date = (dateOverride == undefined ? config.date : dateOverride) || new Date();
+        this._date = (_ref = dateOverride !== null && dateOverride !== void 0 ? dateOverride : config.date) !== null && _ref !== void 0 ? _ref : new Date();
         this._step = (_config_step = config.step) !== null && _config_step !== void 0 ? _config_step : 1;
         this._limit = new LimitDateTimeInstance(config);
         this._dateFilter = config.schedule ? dateCellScheduleDateFilter(config.schedule) : undefined;
@@ -8140,6 +8637,8 @@ function _object_spread_props$3(target, source) {
             key: "limitInstance",
             get: /**
      * Returns the LimitDateTimeInstance. This does not take the schedule into consideration.
+     *
+     * @returns The underlying {@link LimitDateTimeInstance}.
      */ function get() {
                 return this._limit;
             }
@@ -8162,6 +8661,8 @@ function _object_spread_props$3(target, source) {
      * // true if June 15 is a weekday and overlaps the limit range
      * instance.dateDayContainsValidDateValue(new Date('2024-06-15'));
      * ```
+     *
+     * @returns `true` if the day contains at least one valid date/time value.
      */ key: "dateDayContainsValidDateValue",
             value: function dateDayContainsValidDateValue(date) {
                 var isInSchedule = this.dateIsInSchedule(date);
@@ -8200,6 +8701,8 @@ function _object_spread_props$3(target, source) {
      *
      * instance.isInValidRange(new Date('2024-06-15T10:00:00')); // true if a weekday
      * ```
+     *
+     * @returns `true` if the date is within the min/max limits and on a scheduled day.
      */ key: "isInValidRange",
             value: function isInValidRange(date) {
                 var result = this.getStatus(date);
@@ -8222,6 +8725,8 @@ function _object_spread_props$3(target, source) {
      *
      * instance.isValid(new Date('2099-03-15T10:00:00')); // true if all constraints pass
      * ```
+     *
+     * @returns `true` if the date passes all configured constraints.
      */ key: "isValid",
             value: function isValid(date) {
                 var result = this.getStatus(date);
@@ -8245,6 +8750,8 @@ function _object_spread_props$3(target, source) {
      * // status.isAfterMinimum === false (before min)
      * // status.inFuture === false (if date is in the past)
      * ```
+     *
+     * @returns A {@link DateTimeMinuteDateStatus} snapshot for the given date.
      */ key: "getStatus",
             value: function getStatus() {
                 var date = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : this.date;
@@ -8303,6 +8810,8 @@ function _object_spread_props$3(target, source) {
      *
      * instance.dateIsInSchedule(new Date('2024-06-15')); // true (Saturday = false)
      * ```
+     *
+     * @returns `true` if the date is on a scheduled day or no schedule is configured.
      */ key: "dateIsInSchedule",
             value: function dateIsInSchedule() {
                 var date = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : this.date;
@@ -8327,6 +8836,8 @@ function _object_spread_props$3(target, source) {
      * instance.round({ roundToSteps: true }); // 2024-06-15T09:00:00
      * instance.round({ roundToSteps: true, roundToBound: true }); // clamped to min if below
      * ```
+     *
+     * @returns The rounded (and optionally clamped) date.
      */ key: "round",
             value: function round(round) {
                 var _round_step;
@@ -8356,6 +8867,8 @@ function _object_spread_props$3(target, source) {
      *
      * instance.clamp(new Date('2024-05-25')); // clamped to min, then nearest weekday
      * ```
+     *
+     * @returns The date clamped to both the limits and the schedule.
      */ key: "clamp",
             value: function clamp() {
                 var date = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : this.date, maxClampDistance = arguments.length > 1 ? arguments[1] : void 0;
@@ -8376,6 +8889,8 @@ function _object_spread_props$3(target, source) {
      *
      * instance.clampToLimit(new Date('2025-03-01')); // returns max (2024-12-31)
      * ```
+     *
+     * @returns The date clamped to the configured min/max limits.
      */ key: "clampToLimit",
             value: function clampToLimit() {
                 var date = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : this.date;
@@ -8400,6 +8915,8 @@ function _object_spread_props$3(target, source) {
      * // If June 15, 2024 is a Saturday, returns the next Monday
      * instance.clampToSchedule(new Date('2024-06-15'));
      * ```
+     *
+     * @returns The nearest valid scheduled date, or the input date if already valid or no schedule is configured.
      */ key: "clampToSchedule",
             value: function clampToSchedule() {
                 var date = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : this.date, maxClampDistance = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 370;
@@ -8434,9 +8951,7 @@ function _object_spread_props$3(target, source) {
                             }
                         }
                         // set a default from the given input if applicable
-                        if (nextAvailableDate == null) {
-                            nextAvailableDate = this.clampToLimit(date);
-                        }
+                        nextAvailableDate !== null && nextAvailableDate !== void 0 ? nextAvailableDate : nextAvailableDate = this.clampToLimit(date);
                     }
                 }
                 return nextAvailableDate !== null && nextAvailableDate !== void 0 ? nextAvailableDate : date;
@@ -8461,6 +8976,8 @@ function _object_spread_props$3(target, source) {
      * // Find the next weekday after a Saturday
      * instance.findNextAvailableDayInSchedule(new Date('2024-06-15'), 'future');
      * ```
+     *
+     * @returns The next valid schedule date, or `undefined` if none found within the max distance.
      */ key: "findNextAvailableDayInSchedule",
             value: function findNextAvailableDayInSchedule(date, direction) {
                 var maxDistance = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : 370;
@@ -8496,6 +9013,8 @@ function _object_spread_props$3(target, source) {
      * instance.isInSchedule(new Date('2024-06-17')); // true (Monday)
      * instance.isInSchedule(new Date('2024-06-16')); // false (Sunday)
      * ```
+     *
+     * @returns `true` if the date is on a scheduled day or no schedule is configured.
      */ key: "isInSchedule",
             value: function isInSchedule(date) {
                 return this._dateFilter ? this._dateFilter(date) : true;
@@ -8555,6 +9074,8 @@ function _object_spread_props$3(target, source) {
  *
  * isValid(new Date('2024-06-17T10:00:00')); // true if future weekday after min
  * ```
+ *
+ * @returns A decision function that returns `true` for valid dates.
  */ function dateTimeMinuteDecisionFunction(config) {
     var instance = new DateTimeMinuteInstance(config, null);
     return function(date) {
@@ -8587,6 +9108,8 @@ function _object_spread_props$3(target, source) {
  * // true only if both 00:00 and 23:59 on June 15 pass all constraints
  * isFullDayValid(new Date('2024-06-15'));
  * ```
+ *
+ * @returns A decision function that returns `true` for valid days.
  */ function dateTimeMinuteWholeDayDecisionFunction(config) {
     var startAndEndOfDayMustBeValid = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : false;
     var instance = new DateTimeMinuteInstance(config, null);
@@ -8671,6 +9194,7 @@ function _object_spread_props$2(target, source) {
  * guaranteeing that `raw` and `result` are defined.
  *
  * @param result - The parse result to check.
+ * @returns `true` if the result is valid, narrowing the type to {@link ValidDateFromTimestringResult}.
  *
  * @example
  * ```ts
@@ -8714,6 +9238,7 @@ function _object_spread_props$2(target, source) {
      *
      * @param date - The date to check. Defaults to now.
      * @param timezone - Overrides the instance's configured timezone for this call.
+     * @returns {@link TimeAM.AM} or {@link TimeAM.PM} depending on the time of day.
      *
      * @example
      * ```ts
@@ -8733,6 +9258,7 @@ function _object_spread_props$2(target, source) {
      *
      * @param date - The date to format.
      * @param timezone - Overrides the instance's configured timezone for this call.
+     * @returns The formatted time string (e.g., "1:30PM").
      *
      * @example
      * ```ts
@@ -8827,18 +9353,35 @@ function _object_spread_props$2(target, source) {
                         'h:mm',
                         'HH:mm' // 01:20
                     ];
-                    // tslint:disable-next-line: prefer-for-of
-                    for(var i = 0; i < formats.length; i += 1){
-                        systemParsedDateTime = dateFns.parse(input, formats[i], relativeDate);
-                        if (dateFns.isValid(systemParsedDateTime)) {
-                            valid = true;
-                            break; // Use time.
+                    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        // tslint:disable-next-line: prefer-for-of
+                        for(var _iterator = formats[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            var format = _step.value;
+                            systemParsedDateTime = dateFns.parse(input, format, relativeDate);
+                            if (dateFns.isValid(systemParsedDateTime)) {
+                                valid = true;
+                                break; // Use time.
+                            }
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
                         }
                     }
                     var removedPm = false;
                     function removeAmPm(inputString) {
                         inputString = inputString.toLowerCase();
-                        removedPm = inputString.indexOf('pm') !== -1;
+                        removedPm = inputString.includes('pm');
                         inputString = inputString.replace(/am|pm/g, '');
                         return inputString;
                     }
@@ -8938,6 +9481,8 @@ function _object_spread_props$2(target, source) {
 /**
  * Creates a {@link DateTimeUtilityInstance} configured for UTC.
  *
+ * @returns A new {@link DateTimeUtilityInstance} using the UTC timezone.
+ *
  * @example
  * ```ts
  * const utcInstance = dateTimeInstanceUtc();
@@ -8951,6 +9496,7 @@ function _object_spread_props$2(target, source) {
  * Defaults to UTC when no timezone is provided.
  *
  * @param timezone - The IANA timezone identifier (e.g., 'America/New_York').
+ * @returns A new {@link DateTimeUtilityInstance} for the specified timezone.
  *
  * @example
  * ```ts
@@ -8965,6 +9511,7 @@ function _object_spread_props$2(target, source) {
  *
  * @param date - The date to check. Defaults to now.
  * @param timezone - The IANA timezone to evaluate in. Defaults to UTC.
+ * @returns {@link TimeAM.AM} or {@link TimeAM.PM} depending on the time of day.
  *
  * @example
  * ```ts
@@ -8982,6 +9529,7 @@ function _object_spread_props$2(target, source) {
  * unlike {@link toReadableTimeString} which defaults to UTC.
  *
  * @param date - The date to format.
+ * @returns The formatted time string in the system's local timezone.
  *
  * @example
  * ```ts
@@ -8995,6 +9543,7 @@ function _object_spread_props$2(target, source) {
  *
  * @param date - The date to format.
  * @param timezone - The IANA timezone to format in. Defaults to UTC.
+ * @returns The formatted time string (e.g., "10:30AM").
  *
  * @example
  * ```ts
@@ -9010,6 +9559,7 @@ function _object_spread_props$2(target, source) {
  *
  * @param input - A time string such as "1:30PM", "13:30", or "1PM".
  * @param config - Optional configuration specifying the timezone and reference date.
+ * @returns The parsed time string result, or `undefined` if parsing failed.
  *
  * @example
  * ```ts
@@ -9028,6 +9578,7 @@ function _object_spread_props$2(target, source) {
  *
  * @param input - A time string such as "1:30PM" or "13:30".
  * @param config - Optional configuration specifying the timezone and reference date.
+ * @returns The resolved date, or `undefined` if the input could not be parsed.
  *
  * @example
  * ```ts
@@ -9041,6 +9592,7 @@ function _object_spread_props$2(target, source) {
  * Creates a {@link LimitDateTimeInstance} for clamping and constraining dates to a configured range.
  *
  * @param config - The limit configuration specifying min/max bounds, future requirements, etc.
+ * @returns A new {@link LimitDateTimeInstance} configured with the given bounds.
  *
  * @example
  * ```ts
@@ -9150,6 +9702,7 @@ function _object_spread_props$1(target, source) {
         date: dateFnsTz.toZonedTime(find.range.date, find.timezone)
     }) : find.range;
     var dates = dateRange(range);
+    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
     switch(range.type){
         case exports.DateRangeType.DAY:
         case exports.DateRangeType.WEEK:
@@ -9345,13 +9898,12 @@ function _object_spread$1(target) {
                 // A single field that manages start/end will start and end at the same instant (end = start)
                 // so we merge the gte/lte values.
                 var merged = mergeMongoDBLikeRangeFilters(startsAt, endsAt);
-                startsAtFilter = merged ? _define_property$2({}, fields.start, merged) : undefined;
+                startsAtFilter = _define_property$2({}, fields.start, merged);
             } else {
                 startsAtFilter = startsAt ? _define_property$2({}, fields.start, startsAt) : undefined;
                 endsAtFilter = endsAt && fields.end ? _define_property$2({}, fields.end, endsAt) : undefined;
             }
-            var filter = _object_spread$1({}, startsAtFilter, endsAtFilter);
-            return filter;
+            return _object_spread$1({}, startsAtFilter, endsAtFilter);
         }
     };
 }
@@ -9474,6 +10026,8 @@ function _is_native_reflect_construct() {
      * const rule = new DateRRule({ freq: RRule.DAILY, count: 5, dtstart: startDate });
      * const lastDate = rule.last(); // fifth occurrence
      * ```
+     *
+     * @returns The last occurrence date, or `undefined` if there are none.
      */ key: "last",
             value: function last() {
                 return this._iter(new LastIterResult());
@@ -9488,6 +10042,9 @@ function _is_native_reflect_construct() {
      * const rule = new DateRRule({ freq: RRule.WEEKLY, dtstart: startDate });
      * const nextDate = rule.next(new Date());
      * ```
+     *
+     * @param minDate - The earliest date to consider.
+     * @returns The first occurrence on or after `minDate`, or `undefined` if none.
      */ key: "next",
             value: function next(minDate) {
                 return this._iter(new NextIterResult(minDate));
@@ -9502,6 +10059,11 @@ function _is_native_reflect_construct() {
      * const rule = new DateRRule({ freq: RRule.DAILY, dtstart: startDate });
      * const exists = rule.any({ minDate: rangeStart, maxDate: rangeEnd });
      * ```
+     *
+     * @param filter - Optional date bounds with `minDate` and `maxDate`.
+     * @param filter.minDate - Optional minimum date bound.
+     * @param filter.maxDate - Optional maximum date bound.
+     * @returns `true` if at least one recurrence falls within the bounds.
      */ key: "any",
             value: function any() {
                 var filter = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
@@ -9762,7 +10324,10 @@ function _unsupported_iterable_to_array$1(o, minLen) {
 /**
  * Delimiter separating the property name/params from values in an RRule line.
  */ var RRULE_STRING_SPLITTER = ':';
-/** @deprecated use RRULE_STRING_SPLITTER instead. */ var RRuleStringSplitter = RRULE_STRING_SPLITTER;
+/**
+ * @deprecated use RRULE_STRING_SPLITTER instead.
+ */ // eslint-disable-next-line @typescript-eslint/naming-convention
+var RRuleStringSplitter = RRULE_STRING_SPLITTER;
 /**
  * Utility class for parsing and manipulating RFC 5545 RRule strings.
  *
@@ -9793,6 +10358,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
      * // result.basic = ['RRULE:FREQ=DAILY']
      * // result.exdates contains the parsed exclusion dates
      * ```
+     *
+     * @param input - The RRule string line set to separate.
+     * @returns The separated basic rules and parsed EXDATE exclusion dates.
      */ function separateRRuleStringSetValues(input) {
                 var basic = [];
                 var exdateRules = [];
@@ -9822,6 +10390,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             /**
      * Parses an EXDATE line into its timezone and date components.
      *
+     * @param line - The raw EXDATE line string to parse.
+     * @returns The parsed EXDATE attribute with timezone and dates.
      * @throws Error if the line is not an EXDATE property.
      */ function parseExdateAttributeFromLine(line) {
                 var property = this.parseProperty(line);
@@ -9833,6 +10403,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             key: "parseExdateAttributeFromProperty",
             value: /**
      * Extracts timezone and UTC-normalized dates from an already-parsed EXDATE property.
+     *
+     * @param property - The parsed EXDATE property to extract from.
+     * @returns The EXDATE attribute containing timezone and UTC-normalized dates.
      */ function parseExdateAttributeFromProperty(property) {
                 var _property_params_find;
                 var timezone = (_property_params_find = property.params.find(function(x) {
@@ -9856,6 +10429,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             value: /**
      * Convenience wrapper that creates a timezone converter and delegates to {@link parseDateTimeString}.
      *
+     * @param rfcDateString - The RFC 5545 date or date-time string to parse.
+     * @param timezone - Optional timezone for non-UTC date strings.
+     * @returns The parsed JavaScript Date.
      * @throws Error if the date string is not UTC and no timezone is provided.
      */ function parseDateTimeStringWithTimezone(rfcDateString, timezone) {
                 return DateRRuleParseUtility.parseDateTimeString(rfcDateString, timezone ? new DateTimezoneUtcNormalInstance({
@@ -9871,6 +10447,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
      * If the string does not end in `Z` (indicating UTC), the converter is used to normalize
      * the local date representation to its true UTC equivalent.
      *
+     * @param rfcDateString - The RFC 5545 date or date-time string to parse.
+     * @param converter - Optional timezone converter for non-UTC date strings.
+     * @returns The parsed JavaScript Date.
      * @throws Error if the string cannot be parsed or a non-UTC string lacks a converter.
      */ function parseDateTimeString(rfcDateString, converter) {
                 var RFC5545_DATE_TIME_FORMAT = /^((\d{4})(\d{2})(\d{2}))(T(\d{2})(\d{2})(\d{2})Z?)?$/;
@@ -9914,6 +10493,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
      * DateRRuleParseUtility.formatDateTimeString(new Date('2021-06-11T11:00:00Z'));
      * // => '20210611T110000Z'
      * ```
+     *
+     * @param date - The date to format.
+     * @returns The RFC 5545 UTC date-time string representation.
      */ function formatDateTimeString(date) {
                 return dateFnsTz.format(date, "yyyyMMdd'T'HHmmss'Z'");
             }
@@ -9922,6 +10504,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             key: "parseProperty",
             value: /**
      * Parses a full RRule line string into a structured {@link RRuleProperty}.
+     *
+     * @param line - The raw RRule line string to parse.
+     * @returns The structured property with type, params, and values.
      */ function parseProperty(line) {
                 var rawLine = DateRRuleParseUtility.parseRawLine(line);
                 return DateRRuleParseUtility.propertyFromRawLine(rawLine);
@@ -9931,6 +10516,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             key: "propertyFromRawLine",
             value: /**
      * Converts an {@link RRuleRawLine} into a structured {@link RRuleProperty} by splitting the type and params.
+     *
+     * @param rawLine - The raw line to convert.
+     * @returns The structured property with separated type, params, and values.
      */ function propertyFromRawLine(rawLine) {
                 var typeAndParams = rawLine.params.split(';');
                 var type = typeAndParams[0].toUpperCase();
@@ -9946,6 +10534,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             key: "parseRawParam",
             value: /**
      * Splits a raw param string (e.g., `"TZID=America/New_York"`) into key-value form.
+     *
+     * @param param - The raw param string to split.
+     * @returns The parsed key-value param.
      */ function parseRawParam(param) {
                 var _splitJoinRemainder = _sliced_to_array$1(util.splitJoinRemainder(param, '=', 2), 2), key = _splitJoinRemainder[0], value = _splitJoinRemainder[1];
                 return {
@@ -9959,6 +10550,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             value: /**
      * Splits a raw line at the colon delimiter into params and values portions.
      * Falls back to treating a single-segment line as an RRULE value.
+     *
+     * @param line - The raw RRule line string to split.
+     * @returns The raw line with separated params and values.
      */ function parseRawLine(line) {
                 var _splitJoinRemainder = _sliced_to_array$1(util.splitJoinRemainder(line, RRULE_STRING_SPLITTER, 2), 2), params = _splitJoinRemainder[0], values = _splitJoinRemainder[1];
                 var result;
@@ -9981,6 +10575,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             value: // MARK: String
             /**
      * Splits a newline-delimited RRule string into individual line strings.
+     *
+     * @param lines - The newline-delimited RRule string to split.
+     * @returns An array of individual RRule line strings.
      */ function toRRuleStringSet(lines) {
                 return lines.split('\n');
             }
@@ -9989,6 +10586,9 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             key: "toRRuleLines",
             value: /**
      * Joins an array of RRule line strings into a single newline-delimited string.
+     *
+     * @param rruleStringSet - The array of RRule line strings to join.
+     * @returns A single newline-delimited RRule string.
      */ function toRRuleLines(rruleStringSet) {
                 return rruleStringSet.join('\n');
             }
@@ -9999,6 +10599,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             /**
      * Asserts that the property has the expected type, throwing if it does not match.
      *
+     * @param type - The expected property type.
+     * @param property - The property to check.
      * @throws Error if the property type does not match the expected type.
      */ function assertPropertyType(type, property) {
                 if (property.type !== type) {
@@ -10139,7 +10741,7 @@ function _unsupported_iterable_to_array(o, minLen) {
         this.options = options;
         var tzid = rrule.origOptions.tzid;
         var dtstart = rrule.origOptions.dtstart;
-        var timezone = tzid || options.timezone;
+        var timezone = tzid !== null && tzid !== void 0 ? tzid : options.timezone;
         /**
          * The normal instance for DateRRuleInstance is used backwards in most cases because DateRRule always
          * parses dates as UTC, so we handle all input dates as base dates, an
@@ -10190,8 +10792,7 @@ function _unsupported_iterable_to_array(o, minLen) {
                 var from = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : new Date();
                 var baseFrom = this.normalInstance.baseDateToTargetDate(from);
                 var rawNext = this.rrule.next(baseFrom);
-                var next = rawNext ? this.normalInstance.targetDateToBaseDate(rawNext) : undefined;
-                return next;
+                return rawNext ? this.normalInstance.targetDateToBaseDate(rawNext) : undefined;
             }
         },
         {
@@ -10332,11 +10933,12 @@ function _unsupported_iterable_to_array(o, minLen) {
             /**
      * Returns `true` when the underlying RRule has neither a `count` nor an
      * `until` constraint, meaning it recurs indefinitely.
+     *
+     * @returns `true` if the rule recurs indefinitely.
      */ key: "hasForeverRange",
             value: function hasForeverRange() {
                 var options = this.rrule.options;
-                var forever = !options.count && !options.until;
-                return forever;
+                return !options.count && !options.until;
             }
         }
     ], [