@kelvininc/ui-components
Version:
Kelvin UI Components
140 lines (139 loc) • 5.95 kB
TypeScript
import dayjs from 'dayjs';
import { ERelativeTimeComparisonConfig, IRelativeTimePickerOption } from '../../types';
import { DayjsTimeRange, TimestampRange, type SelectedRange } from '../types';
import { DateTimeCalculation, ERelativeTimeRangeKey, IDateTimeRangeFormatter } from './relative-time.types';
/** Date range builders */
export declare const buildOptionRange: (option: IRelativeTimePickerOption, timeZone: string) => DayjsTimeRange;
export declare const buildStartDateEndDateConfigRange: (option: IRelativeTimePickerOption, timeZone: string) => DayjsTimeRange;
export declare const buildSingleDateConfigRange: (option: IRelativeTimePickerOption, timeZone: string) => DayjsTimeRange;
export declare const buildAbsoluteAmountOfUnitsConfigRange: (option: IRelativeTimePickerOption, timeZone: string) => DayjsTimeRange;
export declare const buildRelativeAmountOfUnitsConfigRange: (option: IRelativeTimePickerOption, timeZone: string) => DayjsTimeRange;
/**
* Builds the range of the start and end date and returns the range array, ordering the dates if needed
* @param dateA date (start or end)
* @param dateB date (start or end)
* @returns range containing start date and end date ordered
*/
export declare const buildDayjsRange: (dateA: dayjs.Dayjs, dateB: dayjs.Dayjs) => DayjsTimeRange;
export declare const buildTimestampRange: ([startDate, endDate]: DayjsTimeRange) => TimestampRange;
/**
* Finds a relative time option by its key from the provided options groups.
*
* @param key - The option key to search for
* @param options - Optional: The option groups to search in (defaults to DEFAULT_RELATIVE_TIME_OPTIONS_GROUPS)
* @returns The matching option or undefined
*/
export declare const getRelativeTimeOption: (key: string, options?: IRelativeTimePickerOption[][]) => IRelativeTimePickerOption;
/**
* Derives DateTimeCalculation configuration from a relative time range key.
* This eliminates manual duplication of offset data.
*
* @param key - The relative time range key
* @returns DateTimeCalculation object ready for use in IRelativeTimePickerOption
*
* @example
* ```typescript
* // Simple offset
* getRelativeTimeCalculation(ERelativeTimeRangeKey.Last_5_m)
* // Returns: { amount: -5, unit: 'minutes' }
* ```
*
* @example
* ```typescript
* // Unit reference offset
* getRelativeTimeCalculation(ERelativeTimeRangeKey.Today)
* // Returns: { amount: 0, unit: 'day', unitReference: EUnitReference.StartOfUnit }
* ```
*
* @throws {Error} If no configuration is found for the provided key
*/
export declare const getRelativeTimeCalculation: (key: ERelativeTimeRangeKey) => DateTimeCalculation;
/**
* Builder function to create IRelativeTimePickerOption with automatic
* startDate/endDate derivation from RELATIVE_TIME_OFFSETS.
*
* @param label - Display label for the option
* @param value - Relative time range key
* @param comparisonConfig - How the time calculation should be performed
* @param labelRangeFormatter - Optional formatter for date range display
* @param endDateKey - Optional: If provided, derives endDate from this key
* @returns Complete IRelativeTimePickerOption
*
* @example
* ```typescript
* // Simple option
* buildRelativeTimeOption(
* 'Last 5 minutes',
* ERelativeTimeRangeKey.Last_5_m,
* ERelativeTimeComparisonConfig.RelativeAmountOfUnits,
* {
* startDateFormatter: 'HH:mm',
* separator: 'to',
* endDateFormatter: 'HH:mm'
* }
* )
* ```
*
* @example
* ```typescript
* // Option with endDate
* buildRelativeTimeOption(
* 'Yesterday',
* ERelativeTimeRangeKey.Yesterday,
* ERelativeTimeComparisonConfig.AbsoluteAmountOfUnits,
* { startDateFormatter: 'D MMM' },
* ERelativeTimeRangeKey.Yesterday_End
* )
* ```
*/
export declare const buildRelativeTimeOption: (label: string, value: ERelativeTimeRangeKey, comparisonConfig: ERelativeTimeComparisonConfig, labelRangeFormatter?: IDateTimeRangeFormatter, endDateKey?: ERelativeTimeRangeKey) => IRelativeTimePickerOption;
/**
* Validates that all keys in RELATIVE_TIME_OFFSETS are valid enum values.
* Useful for development/testing to ensure consistency.
*
* @returns true if all keys are valid
* @throws {Error} If any invalid keys are found
*
* @example
* ```typescript
* // In tests or development
* validateRelativeTimeOffsets(); // throws if config is invalid
* ```
*/
export declare const validateRelativeTimeOffsets: () => boolean;
/**
* Default relative time option groups for the time picker component.
*
* @remarks
* This configuration is built using the `buildRelativeTimeOption` helper to ensure
* consistency with `RELATIVE_TIME_OFFSETS` and avoid data duplication.
*
* Organized into 5 groups:
* 1. Today/Yesterday
* 2. Day/Month ranges (24h, 48h, 7d, 30d, 90d, 6M)
* 3. Minute/Hour ranges (5m, 15m, 30m, 1h, 3h, 6h, 12h)
* 4. Long-term ranges (365d, 2y)
* 5. "So far" ranges (week, month, quarter, year)
*/
export declare const DEFAULT_RELATIVE_TIME_OPTIONS_GROUPS: IRelativeTimePickerOption[][];
/**
* Returns a start and end time according to a relative time range in utc.
* @param key the relative time key
* @param cursor the relative timestamp cursor
* @returns an array with datetime strings
*/
export declare const getRelativeTimeRangeISO: (key: ERelativeTimeRangeKey, cursor?: string | number | Date) => [string, string];
/**
* Returns a start and end time according to a relative time range as timestamps.
* @param key the relative time key
* @param cursor the relative timestamp cursor
* @returns an array with timestamps
*/
export declare const getRelativeTimeRangeTimestamp: (key: ERelativeTimeRangeKey, cursor?: dayjs.Dayjs) => [number, number];
/**
* Returns the provided range in utc.
* @range the absolute time range
* @offset the timezone offset
* @returns an array with datetime strings
*/
export declare const getAbsoluteTimeRange: (range: SelectedRange, offset?: number) => [string, string];