@dereekb/date 13.0.6 → 13.1.0

package/src/lib/date/date.cell.filter.d.ts

@@ -1,18 +1,120 @@
 import { type FilterFunction, type Maybe } from '@dereekb/util';
 import { type DateCell, type DateCellDurationSpan } from './date.cell';
 import { type DateCellRange, type UniqueDateCell } from './date.cell.index';
+/**
+ * A filter function that operates on {@link DateCellDurationSpan} values, typically used
+ * to select date cells based on their temporal relationship to a reference point.
+ */
 export type DateCellDurationSpanFilterFunction<B extends DateCell = DateCell> = FilterFunction<DateCellDurationSpan<B>>;
+/**
+ * Creates a filter that passes date cell duration spans whose start time is at or before the given reference time.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const hasStarted = dateCellDurationSpanHasStartedFilterFunction(new Date());
+ * const startedSpans = allSpans.filter(hasStarted);
+ * ```
+ */
 export declare function dateCellDurationSpanHasStartedFilterFunction<B extends DateCell = DateCell>(now?: Date): DateCellDurationSpanFilterFunction<B>;
+/**
+ * Creates a filter that passes date cell duration spans whose start time is strictly after the given reference time.
+ *
+ * The inverse of {@link dateCellDurationSpanHasStartedFilterFunction}. Useful for finding upcoming or future events.
+ *
+ * @param now - Reference time to compare against. Defaults to the current time.
+ *
+ * @example
+ * ```ts
+ * const hasNotStarted = dateCellDurationSpanHasNotStartedFilterFunction(new Date());
+ * const futureSpans = allSpans.filter(hasNotStarted);
+ * ```
+ */
 export declare function dateCellDurationSpanHasNotStartedFilterFunction<B extends DateCell = DateCell>(now?: Date): DateCellDurationSpanFilterFunction<B>;
+/**
+ * Creates a filter that passes date cell duration spans whose computed end time is at or before the given reference time.
+ *
+ * The end time is derived from the span's start time and duration via {@link dateDurationSpanEndDate}.
+ * Useful for identifying completed events.
+ *
+ * @param now - Reference time to compare against. Defaults to the current time.
+ *
+ * @example
+ * ```ts
+ * const hasEnded = dateCellDurationSpanHasEndedFilterFunction(new Date());
+ * const completedSpans = allSpans.filter(hasEnded);
+ * ```
+ */
 export declare function dateCellDurationSpanHasEndedFilterFunction<B extends DateCell = DateCell>(now?: Date): DateCellDurationSpanFilterFunction<B>;
+/**
+ * Creates a filter that passes date cell duration spans whose computed end time is strictly after the given reference time.
+ *
+ * The inverse of {@link dateCellDurationSpanHasEndedFilterFunction}. Useful for finding events that are
+ * still in progress or have not yet occurred.
+ *
+ * @param now - Reference time to compare against. Defaults to the current time.
+ *
+ * @example
+ * ```ts
+ * const hasNotEnded = dateCellDurationSpanHasNotEndedFilterFunction(new Date());
+ * const activeOrFutureSpans = allSpans.filter(hasNotEnded);
+ * ```
+ */
 export declare function dateCellDurationSpanHasNotEndedFilterFunction<B extends DateCell = DateCell>(now?: Date): DateCellDurationSpanFilterFunction<B>;
 /**
- * Modifies or filter out any blocks that are outside the range to fit within the configured range.
+ * Adjusts or removes date cells so they fit within a configured {@link DateCellRange}.
+ *
+ * Cells fully within the range pass through unchanged. Cells that partially overlap are
+ * clamped to the range boundaries. Cells entirely outside the range are removed.
  */
 export type ModifyDateCellsToFitRangeFunction = <B extends DateCell | DateCellRange | UniqueDateCell>(input: B[]) => B[];
 /**
- * Creatse a ModifyDateCellsToFitRangeFunction
+ * Creates a reusable {@link ModifyDateCellsToFitRangeFunction} that clamps or filters date cells
+ * to fit within the given range.
+ *
+ * Cells fully contained in the range are returned as-is. Overlapping cells have their `i` and `to`
+ * indices clamped to the range boundaries. Non-overlapping cells are excluded entirely.
+ *
+ * @param range - The target range to fit cells into.
+ *
+ * @example
+ * ```ts
+ * const fitToRange = modifyDateCellsToFitRangeFunction({ i: 5, to: 15 });
+ * const fitted = fitToRange(dateCells); // cells clamped to [5, 15]
+ * ```
  */
 export declare function modifyDateCellsToFitRangeFunction(range: DateCellRange): ModifyDateCellsToFitRangeFunction;
+/**
+ * Convenience function that applies {@link modifyDateCellsToFitRangeFunction} directly to an array of date cells.
+ *
+ * Prefer {@link modifyDateCellsToFitRangeFunction} when processing multiple arrays against the same range
+ * to avoid recomputing the range boundaries each time.
+ *
+ * @param range - The target range to fit cells into.
+ * @param input - The date cells to clamp or filter.
+ *
+ * @example
+ * ```ts
+ * const fitted = modifyDateCellsToFitRange({ i: 0, to: 10 }, dateCells);
+ * ```
+ */
 export declare function modifyDateCellsToFitRange<B extends DateCell | DateCellRange | UniqueDateCell>(range: DateCellRange, input: B[]): B[];
+/**
+ * Convenience function that fits a single date cell to the given range, returning `undefined` if
+ * the cell does not overlap the range at all.
+ *
+ * @param range - The target range to fit the cell into.
+ * @param input - The single date cell to clamp or exclude.
+ *
+ * @example
+ * ```ts
+ * const fitted = modifyDateCellToFitRange({ i: 0, to: 10 }, dateCell);
+ * if (fitted) {
+ *   // cell overlaps the range
+ * }
+ * ```
+ */
 export declare function modifyDateCellToFitRange<B extends DateCell | DateCellRange | UniqueDateCell>(range: DateCellRange, input: B): Maybe<B>;

package/src/lib/date/date.cell.index.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe, type SortCompareFunction, type RequiredOnKeys, type ArrayOrValue, type UniqueModel, type IndexNumber, type FactoryWithRequiredInput, type DateRelativeState } from '@dereekb/util';
-import { DateCell, type DateOrDateCellIndex, type DateCellIndex } from './date.cell';
+import { type DateCell, type DateOrDateCellIndex, type DateCellIndex } from './date.cell';
 import { type DateRange } from './date.range';
 /**
  * Represents a range of DateCell values.
@@ -12,17 +12,19 @@ export interface DateCellRange extends DateCell {
      */
     to?: DateCellIndex;
 }
-export declare class DateCellRange extends DateCell {
-    to?: DateCellIndex;
-    constructor(template?: DateCellRange);
-}
+/**
+ * ArkType schema for {@link DateCellRange}.
+ */
+export declare const dateCellRangeType: import("arktype/internal/variants/object.ts").ObjectType<{
+    i: number;
+    to?: number | undefined;
+}, {}>;
 /**
  * Returns true if the input is a DateCellRange.
  *
- * Does not check validity. Use isValidDateCellRange()
+ * Does not check validity. Use {@link isValidDateCellRange} for that.
  *
- * @param input
- * @returns
+ * @param input - value to check
  */
 export declare function isDateCellRange(input: unknown): input is DateCellRange;
 /**
@@ -32,39 +34,56 @@ export type DateCellOrDateCellIndexOrDateCellRange = DateCellIndex | DateCell |
 /**
  * Returns true if the input is a valid DateCellRange.
  *
- * @param input
- * @returns
+ * A valid range has a non-negative integer `i`, and if `to` is defined it must also be a valid index
+ * that is greater than or equal to `i`.
+ *
+ * @param input - range to validate
  */
 export declare function isValidDateCellRange(input: DateCellRange): boolean;
 /**
  * Returns true if the input is a sorted DateCellRange array and there are no repeat indexes.
  *
- * @param input
- * @returns
+ * 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
  */
 export declare function isValidDateCellRangeSeries(input: DateCellRange[]): boolean;
 /**
  * Returns the lowest index between all the input date block ranges. Returns 0 by default if there is no minimum or input blocks.
  *
  * The input range is not expected to be sorted.
+ *
+ * @param input - unsorted array of date cell ranges to scan
  */
 export declare function getLeastDateCellIndexInDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellIndex;
 /**
  * Returns the largest index between all the input date block ranges. Returns 0 by default.
  *
  * The input range is not expected to be sorted.
+ *
+ * @param input - unsorted array of date cell ranges to scan
  */
 export declare function getGreatestDateCellIndexInDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellIndex;
+/**
+ * Result containing both the smallest and largest indexes found across a set of date cell ranges,
+ * along with references to the items that contain those extreme indexes.
+ */
 export interface LeastAndGreatestDateCellIndexResult<T> {
+    /** Smallest starting index found. */
     leastIndex: number;
+    /** The item containing the smallest starting index. */
     leastIndexItem: T;
+    /** Largest ending index found (considers `to` values). */
     greatestIndex: number;
+    /** The item containing the largest ending index. */
     greatestIndexItem: T;
 }
 /**
- * Returns the largest index between all the input date block ranges. Returns null if the input is empty.
+ * Returns both the least and greatest indexes across all input date cell ranges, or null if the input is empty.
  *
  * The input range is not expected to be sorted.
+ *
+ * @param input - unsorted array of date cell ranges to scan
  */
 export declare function getLeastAndGreatestDateCellIndexInDateCellRanges<T extends DateCellRange>(input: T[]): Maybe<LeastAndGreatestDateCellIndexResult<T>>;
 /**
@@ -74,28 +93,33 @@ export interface DateCellRangeOrDateRange {
     start?: Maybe<DateOrDateCellIndex>;
     end?: Maybe<DateOrDateCellIndex>;
 }
+/**
+ * Union type allowing a Date, DateCellIndex, or DateCellRange as input.
+ */
 export type DateOrDateCellIndexOrDateCellRange = DateOrDateCellIndex | DateCellRange;
+/**
+ * Union type extending {@link DateOrDateCellIndexOrDateCellRange} to also accept a {@link DateRange}.
+ */
 export type DateOrDateRangeOrDateCellIndexOrDateCellRange = DateRange | DateOrDateCellIndexOrDateCellRange;
 /**
- * Creates a DateCellRange
+ * Creates a {@link DateCellRangeWithRange} with the given start and optional end index.
+ * If `to` is omitted the range covers a single cell at index `i`.
  *
- * @param i
- * @param to
- * @returns
+ * @param i - starting cell index
+ * @param to - ending cell index (inclusive); defaults to `i`
  */
 export declare function dateCellRange(i: number, to?: number): DateCellRangeWithRange;
 /**
- * Creates a DateCellRangeWithRange from the input DateCellIndex.
+ * Creates a single-cell {@link DateCellRangeWithRange} where both `i` and `to` equal the given index.
  *
- * @param dateCellIndex
- * @returns
+ * @param dateCellIndex - the index for both start and end of the range
  */
 export declare function dateCellRangeWithRangeFromIndex(dateCellIndex: DateCellIndex): DateCellRangeWithRange;
 /**
- * Creates a DateCellRangeWithRange from the input DateCellIndex, DateCell, or DateCellRange.
+ * Normalizes any {@link DateCellOrDateCellIndexOrDateCellRange} into a {@link DateCellRangeWithRange},
+ * ensuring the result always has an explicit `to` value.
  *
- * @param input
- * @returns
+ * @param input - index, cell, or range to normalize
  */
 export declare function dateCellRangeWithRange(input: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeWithRange;
 /**
@@ -103,10 +127,10 @@ export declare function dateCellRangeWithRange(input: DateCellOrDateCellIndexOrD
  */
 export type DateCellRangeIncludedByRangeFunction = (range: DateCellOrDateCellIndexOrDateCellRange) => boolean;
 /**
- * Creates a DateCellRangeIncludedByRangeFunction
+ * Creates a {@link DateCellRangeIncludedByRangeFunction} that checks whether a given range
+ * fully contains the configured `inputRange`.
  *
- * @param inputRange
- * @returns
+ * @param inputRange - the range that must be fully included
  */
 export declare function dateCellRangeIncludedByRangeFunction(inputRange: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeIncludedByRangeFunction;
 /**
@@ -114,33 +138,29 @@ export declare function dateCellRangeIncludedByRangeFunction(inputRange: DateCel
  */
 export type DateCellRangeOverlapsRangeFunction = (range: DateCellOrDateCellIndexOrDateCellRange) => boolean;
 /**
- * Creates a DateCellRangeOverlapsRangeFunction
+ * Creates a {@link DateCellRangeOverlapsRangeFunction} that checks whether a given range
+ * has any overlap with the configured `inputRange`.
  *
- * @param inputRange
- * @returns
+ * @param inputRange - the range to test for overlap against
  */
 export declare function dateCellRangeOverlapsRangeFunction(inputRange: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeOverlapsRangeFunction;
 /**
- * Returns true if either of the ranges overlap eachother.
+ * Returns true if the two ranges share at least one common index.
  *
- * @param rangeA
- * @param rangeB
- * @returns
+ * @param rangeA - first range to compare
+ * @param rangeB - second range to compare
  */
 export declare function dateCellRangeOverlapsRange(rangeA: DateCellOrDateCellIndexOrDateCellRange, rangeB: DateCellOrDateCellIndexOrDateCellRange): boolean;
 /**
- * Sorts the input ranges by index and distance (to values).
+ * Returns a sort comparator that orders ranges first by starting index (`i`), then by ending index (`to`).
  *
- * In many cases sortAscendingIndexNumberRefFunction may be preferential.
- *
- * @returns
+ * In many cases {@link sortAscendingIndexNumberRefFunction} may be preferential when `to` ordering is not needed.
  */
 export declare function sortDateCellRangeAndSizeFunction<T extends DateCellRange>(): SortCompareFunction<T>;
 /**
- * Sorts the input date ranges. This will retain the before/after order while also sorting items by index.
+ * Sorts the input date ranges in-place by ascending index using {@link sortAscendingIndexNumberRefFunction}.
  *
- * @param input
- * @returns
+ * @param input - array of ranges to sort (mutated in place)
  */
 export declare function sortDateCellRanges<T extends DateCellRange>(input: T[]): T[];
 /**
@@ -148,77 +168,109 @@ export declare function sortDateCellRanges<T extends DateCellRange>(input: T[]):
  */
 export type DateCellRangeWithRange = RequiredOnKeys<DateCellRange, 'to'>;
 /**
- * Groups the input values into DateCellRange values.
+ * Merges an array of {@link DateCell} or {@link DateCellRange} values into the smallest set of
+ * contiguous {@link DateCellRangeWithRange} values. Adjacent or overlapping ranges are combined.
+ *
+ * The input is sorted internally before grouping.
+ *
+ * @param input - cells or ranges to merge into contiguous groups
  *
- * @param input
+ * @example
+ * ```ts
+ * // Three adjacent cells collapse into one range
+ * groupToDateCellRanges([{ i: 0 }, { i: 1 }, { i: 2 }]);
+ * // => [{ i: 0, to: 2 }]
+ *
+ * // Non-adjacent cells produce separate ranges
+ * groupToDateCellRanges([{ i: 0 }, { i: 5 }]);
+ * // => [{ i: 0, to: 0 }, { i: 5, to: 5 }]
+ * ```
  */
 export declare function groupToDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellRangeWithRange[];
 /**
- * Returns an array containing all indexes in the date block range.
+ * 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
  */
 export declare function allIndexesInDateCellRange(input: DateCellRange): DateCellIndex[];
 /**
- * Returns an array of all indexes within the input.
+ * Flattens an array of indexes and/or ranges into a single array of individual {@link DateCellIndex} values.
  *
- * @param input
- * @returns
+ * @param input - mix of raw indexes and ranges to flatten
  */
 export declare function allIndexesInDateCellRangesToArray(input: (DateCellIndex | DateCellRange)[]): DateCellIndex[];
 /**
- * Returns the set of all indexes within the input.
+ * Returns a deduplicated {@link Set} of all indexes within the input ranges.
  *
- * @param input
- * @returns
+ * @param input - mix of raw indexes and ranges to collect
  */
 export declare function allIndexesInDateCellRanges(input: (DateCellIndex | DateCellRange)[]): Set<DateCellIndex>;
 /**
- * Returns blocks that are only in the given DateCellRange.
+ * Filters the input blocks, returning only those that fall entirely within the given range.
  *
- * @param blocks
- * @param range
- * @returns
+ * @param blocks - cells or ranges to filter
+ * @param range - bounding range that blocks must fall within
  */
 export declare function filterDateCellsInDateCellRange<T extends DateCell | DateCellRange>(blocks: T[], range: DateCellRangeWithRange): T[];
+/**
+ * Accepted input types for range-containment checks: a raw index, a {@link DateCell}, or a {@link DateCellRange}.
+ */
 export type IsDateCellWithinDateCellRangeInput = DateCellOrDateCellIndexOrDateCellRange;
 /**
  * Function that returns true if the input range is equal or falls within the configured DateCellRange.
  */
 export type IsDateCellWithinDateCellRangeFunction = (input: IsDateCellWithinDateCellRangeInput) => boolean;
+/**
+ * Creates an {@link IsDateCellWithinDateCellRangeFunction} that tests whether a given cell or range
+ * is fully contained within `inputRange`.
+ *
+ * @param inputRange - the bounding range to test containment against
+ */
 export declare function isDateCellWithinDateCellRangeFunction(inputRange: IsDateCellWithinDateCellRangeInput): IsDateCellWithinDateCellRangeFunction;
 /**
- * Returns true if the first DateCell or DateCellRange contains the second input.
+ * Returns true if `contains` is fully within `range`.
  *
- * @param range
- * @param isContainedWithin
- * @returns
+ * @param range - the outer bounding range
+ * @param contains - the cell or range to test for containment
  */
 export declare function isDateCellWithinDateCellRange(range: IsDateCellWithinDateCellRangeInput, contains: IsDateCellWithinDateCellRangeInput): boolean;
+/**
+ * Statistical information about the blocks in a set of date cell ranges.
+ */
 export interface DateCellRangeBlockCountInfo {
     /**
-     * Total number of blocks.
+     * Total number of individual cell indexes across all ranges.
      */
     readonly count: number;
     /**
-     * The "total" if all indexes were added together. Used for calculating the average.
+     * Sum of all individual indexes. Used for calculating the average.
      */
     readonly total: number;
     /**
-     * The average block index
+     * The average block index (total / count), or 0 if count is 0.
      */
     readonly average: number;
 }
 /**
- * Counts the number of blocks in the input range.
+ * Computes {@link DateCellRangeBlockCountInfo} (count, total, average) for the given date cell ranges.
+ *
+ * Internally groups overlapping ranges before counting so each index is counted only once.
  *
- * @param inputDateCellRange
- * @returns
+ * @param inputDateCellRange - one or more cells/ranges to analyze
  */
 export declare function dateCellRangeBlocksCountInfo(inputDateCellRange: ArrayOrValue<DateCell | DateCellRange>): DateCellRangeBlockCountInfo;
 /**
- * Counts the number of blocks in the input range.
+ * Counts the total number of individual cell indexes across the given date cell ranges.
+ *
+ * Shorthand for `dateCellRangeBlocksCountInfo(input).count`.
  *
- * @param inputDateCellRange
- * @returns
+ * @param inputDateCellRange - one or more cells/ranges to count
+ *
+ * @example
+ * ```ts
+ * dateCellRangeBlocksCount({ i: 0, to: 4 }); // => 5
+ * dateCellRangeBlocksCount([{ i: 0, to: 2 }, { i: 10, to: 12 }]); // => 6
+ * ```
  */
 export declare function dateCellRangeBlocksCount(inputDateCellRange: ArrayOrValue<DateCell | DateCellRange>): number;
 /**
@@ -226,66 +278,98 @@ export declare function dateCellRangeBlocksCount(inputDateCellRange: ArrayOrValu
  */
 export type DateCellRangesFullyCoverDateCellRangeFunction = (range: DateCellRange) => boolean;
 /**
- * Creates a dateCellRangesFullyCoverDateCellRangeFunction
+ * Creates a {@link DateCellRangesFullyCoverDateCellRangeFunction} that checks whether any single
+ * grouped range from `ranges` fully covers a given input range.
  *
- * @param ranges
- * @returns
+ * @param ranges - the covering ranges to test against
  */
 export declare function dateCellRangesFullyCoverDateCellRangeFunction(ranges: ArrayOrValue<DateCellRange>): DateCellRangesFullyCoverDateCellRangeFunction;
+/**
+ * Input configuration for {@link getNextDateCellTimingIndex}.
+ */
 export interface GetNextDateCellTimingIndexInput<T extends DateCellRange> {
     /**
-     * Relevant index for now.
+     * The "current" index to evaluate against (typically represents "now").
      */
     readonly currentIndex: DateCellIndex;
     /**
-     * All possible ranges to pick from.
+     * All possible ranges to classify as past, present, or future relative to `currentIndex`.
      */
     readonly ranges: ArrayOrValue<T>;
 }
+/**
+ * Result of {@link getNextDateCellTimingIndex}, classifying ranges relative to a current index
+ * and identifying the next upcoming index/range.
+ */
 export interface GetNextDateCellTimingIndexResult<T extends DateCellRange> {
     /**
-     * The item that matches the current index first out of the options.
+     * The first range that contains the current index, if any.
      */
     readonly currentResult: Maybe<T>;
     /**
-     * The next picked index, if available.
+     * The next index after `currentIndex` that is covered by a range, or undefined if no future ranges exist.
      */
     readonly nextIndex: Maybe<DateCellIndex>;
     /**
-     * The item that matches the next index first out of the options.
+     * The range that contains {@link nextIndex}, if available.
      */
     readonly nextResult: Maybe<T>;
     /**
-     * All ranges that match/contain the current index.
+     * All ranges that contain the current index (i.e., the index falls within their `i..to` span).
      */
     readonly presentResults: T[];
     /**
-     * All ranges that come before the current index.
+     * All ranges whose `to` is before the current index.
      */
     readonly pastResults: T[];
     /**
-     * All ranges that come after the current index.
+     * All ranges whose `i` is after the current index.
      */
     readonly futureResults: T[];
 }
 /**
- * Computes a GetNextDateCellTimingIndexResult from the input.
+ * Classifies the given ranges as past, present, or future relative to `currentIndex`, and determines
+ * the next upcoming index. Useful for "what comes next" scheduling logic against date cell timings.
  *
- * @param input
+ * If a present range continues past `currentIndex`, its next index is preferred. Otherwise the
+ * nearest future range's starting index is used.
+ *
+ * @param input - the current index and ranges to evaluate
+ *
+ * @example
+ * ```ts
+ * const result = getNextDateCellTimingIndex({
+ *   currentIndex: 5,
+ *   ranges: [
+ *     { i: 0, to: 3 },   // past
+ *     { i: 4, to: 7 },   // present (contains 5)
+ *     { i: 10, to: 12 }  // future
+ *   ]
+ * });
+ * // result.currentResult => { i: 4, to: 7 }
+ * // result.nextIndex => 6
+ * // result.pastResults.length => 1
+ * ```
  */
 export declare function getNextDateCellTimingIndex<T extends DateCellRange>(input: GetNextDateCellTimingIndexInput<T>): GetNextDateCellTimingIndexResult<T>;
 /**
- * Returns the DateRelativeState for the given index and range.
+ * Determines whether a range is in the past, present, or future relative to a given index.
  *
- * @param nowIndex
- * @param range
+ * @param range - the date cell range to classify
+ * @param nowIndex - the reference index representing "now"
  */
 export declare function dateRelativeStateForDateCellRangeComparedToIndex(range: DateCellRange, nowIndex: DateCellIndex): DateRelativeState;
 /**
- * Expands a DateCellRange into an array of DateCell values.
+ * Expands a {@link DateCellRange} into an array of individual single-cell copies, one per index
+ * from `i` to `to` (inclusive). Each copy retains all properties of the original block.
+ *
+ * @param block - the range to expand
  *
- * @param block
- * @returns
+ * @example
+ * ```ts
+ * expandDateCellRange({ i: 2, to: 4, data: 'x' });
+ * // => [{ i: 2, to: 2, data: 'x' }, { i: 3, to: 3, data: 'x' }, { i: 4, to: 4, data: 'x' }]
+ * ```
  */
 export declare function expandDateCellRange<B extends DateCellRange | DateCellRangeWithRange>(block: B): B[];
 /**
@@ -299,16 +383,15 @@ export interface UniqueDateCell extends DateCell, UniqueModel {
 export interface UniqueDateCellRange extends UniqueDateCell, DateCellRange {
 }
 /**
- * Returns true if the input DateCellRange is longer than 1 block (I.E. has a "to" value greater than it's "i" value).
+ * Returns true if the input spans more than one cell (i.e., has a `to` value strictly greater than `i`).
  *
- * @param input
+ * @param input - range or cell to check
  */
 export declare function dateCellRangeHasRange(input: DateCellRange | UniqueDateCell): input is DateCellRangeWithRange;
 /**
- * Reads the to index if it exists, or returns the block's index itself.
+ * Returns the effective ending index of a range: `to` if defined, otherwise `i`.
  *
- * @param input
- * @returns
+ * @param input - range or cell to read
  */
 export declare function dateCellEndIndex(input: DateCellRange | UniqueDateCell): IndexNumber;
 /**
@@ -321,7 +404,11 @@ export interface UniqueDateCellRangeGroup<B extends DateCellRange | UniqueDateCe
     blocks: B[];
 }
 /**
- * Groups all input DateCellRange or UniqueDateCell values into a UniqueDateCellRangeGroup value amd sorts the input.
+ * Groups all input {@link DateCellRange} or {@link UniqueDateCell} values into a single
+ * {@link UniqueDateCellRangeGroup}, sorting them by index. The group's `i` is always 0
+ * and `to` is the maximum ending index across all blocks.
+ *
+ * @param input - cells or ranges to group
  */
 export declare function groupUniqueDateCells<B extends DateCellRange | UniqueDateCell>(input: B[]): UniqueDateCellRangeGroup<B>;
 /**
@@ -368,9 +455,14 @@ export interface ExpandUniqueDateCellsConfig<B extends DateCellRange | UniqueDat
      */
     fillFactory?: FactoryWithRequiredInput<B, DateCellRangeWithRange>;
 }
+/**
+ * Result of {@link ExpandUniqueDateCellsFunction}, containing the merged/expanded blocks
+ * and any blocks that were fully discarded during the merge process.
+ */
 export interface ExpandUniqueDateCellsResult<B extends DateCellRange | UniqueDateCell> extends UniqueDateCellRangeGroup<B> {
     /**
-     * Blocks that were competely removed. Some blocks stay partially retained.
+     * Blocks that were completely removed due to overlap resolution. Some blocks may be partially retained
+     * (with adjusted `i`/`to`) and appear in `blocks` instead.
      */
     discarded: B[];
 }
@@ -380,4 +472,22 @@ export interface ExpandUniqueDateCellsResult<B extends DateCellRange | UniqueDat
  * Can optionally specify a second array/group of blocks that are treated as "next" blocks which can take priority or not depending on the retain options.
  */
 export type ExpandUniqueDateCellsFunction<B extends DateCellRange | UniqueDateCell> = (input: B[] | UniqueDateCellRangeGroup<B>, newBlocks?: B[] | UniqueDateCellRangeGroup<B>) => ExpandUniqueDateCellsResult<B>;
+/**
+ * Creates an {@link ExpandUniqueDateCellsFunction} that sorts, merges, and fills date cell ranges
+ * 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
+ *
+ * @example
+ * ```ts
+ * const expand = expandUniqueDateCellsFunction({
+ *   fillOption: 'empty',
+ *   startAtIndex: 0,
+ *   endAtIndex: 10
+ * });
+ *
+ * const result = expand([{ i: 2, to: 5 }, { i: 8, to: 10 }]);
+ * // result.blocks => [{ i: 2, to: 5 }, { i: 8, to: 10 }]
+ * ```
+ */
 export declare function expandUniqueDateCellsFunction<B extends DateCellRange | UniqueDateCell>(config: ExpandUniqueDateCellsConfig<B>): ExpandUniqueDateCellsFunction<B>;