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.
 * @returns A filter function that returns true for spans whose start time is at or before the reference time.
 *
 * @example
 * ```ts
 * const hasStarted = dateCellDurationSpanHasStartedFilterFunction(new Date());
 * const startedSpans = allSpans.filter(hasStarted);
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
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.
 * @returns A filter function that returns true for spans whose start time is strictly after the reference time.
 *
 * @example
 * ```ts
 * const hasNotStarted = dateCellDurationSpanHasNotStartedFilterFunction(new Date());
 * const futureSpans = allSpans.filter(hasNotStarted);
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
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.
 * @returns A filter function that returns true for spans whose computed end time is at or before the reference time.
 *
 * @example
 * ```ts
 * const hasEnded = dateCellDurationSpanHasEndedFilterFunction(new Date());
 * const completedSpans = allSpans.filter(hasEnded);
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
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.
 * @returns A filter function that returns true for spans whose computed end time is strictly after the reference time.
 *
 * @example
 * ```ts
 * const hasNotEnded = dateCellDurationSpanHasNotEndedFilterFunction(new Date());
 * const activeOrFutureSpans = allSpans.filter(hasNotEnded);
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function dateCellDurationSpanHasNotEndedFilterFunction<B extends DateCell = DateCell>(now?: Date): DateCellDurationSpanFilterFunction<B>;
/**
 * 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[];
/**
 * 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.
 * @returns A reusable function that clamps or filters date cells to the configured range.
 *
 * @example
 * ```ts
 * const fitToRange = modifyDateCellsToFitRangeFunction({ i: 5, to: 15 });
 * const fitted = fitToRange(dateCells); // cells clamped to [5, 15]
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
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 - Range that each cell should be clamped to.
 * @param input - Cells to evaluate and clamp.
 * @returns Cells clamped to the range, with non-overlapping cells removed.
 *
 * @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.
 * @returns The clamped date cell, or `undefined` if it does not overlap the range.
 *
 * @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>;