import { type Milliseconds, type TimeUnit } from '@dereekb/util';
/**
 * Represents a time duration decomposed into individual unit fields.
 *
 * Each field is optional and defaults to 0 if not provided.
 * Used for parsing, formatting, and popover picker state.
 */
export interface TimeDurationData {
    readonly weeks?: number;
    readonly days?: number;
    readonly hours?: number;
    readonly minutes?: number;
    readonly seconds?: number;
    readonly milliseconds?: number;
}
/**
 * Returns true if the input TimeDurationData has no meaningful values (all zero or undefined).
 *
 * @param data - The duration data to check.
 * @returns True if empty.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, empty, check, time, zero
 * @dbxUtilRelated duration-data-to-milliseconds, milliseconds-to-duration-data
 *
 * @example
 * ```typescript
 * timeDurationDataIsEmpty({}); // true
 * timeDurationDataIsEmpty({ hours: 0, minutes: 0 }); // true
 * timeDurationDataIsEmpty({ hours: 1 }); // false
 * ```
 */
export declare function timeDurationDataIsEmpty(data: TimeDurationData): boolean;
/**
 * Converts a TimeDurationData to total milliseconds by summing all fields.
 *
 * @param data - The duration data to convert.
 * @returns Total milliseconds.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, milliseconds, convert, sum, time, total
 * @dbxUtilRelated milliseconds-to-duration-data, parse-duration-string-to-milliseconds, time-duration-data-is-empty
 *
 * @example
 * ```typescript
 * durationDataToMilliseconds({ hours: 1, minutes: 30 }); // 5400000
 * durationDataToMilliseconds({ days: 1, hours: 2 }); // 93600000
 * ```
 */
export declare function durationDataToMilliseconds(data: TimeDurationData): Milliseconds;
/**
 * Decomposes milliseconds into a TimeDurationData object using the specified units.
 *
 * Breaks down from largest to smallest unit, only using units in the provided list.
 *
 * @param ms - The total milliseconds to decompose.
 * @param units - Which units to decompose into (defaults to days, hours, minutes, seconds)
 * @returns A TimeDurationData with the decomposed values.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, milliseconds, decompose, convert, breakdown, units, time
 * @dbxUtilRelated duration-data-to-milliseconds, parse-duration-string, format-duration-string
 *
 * @example
 * ```typescript
 * millisecondsToDurationData(5400000); // { days: 0, hours: 1, minutes: 30, seconds: 0 }
 * millisecondsToDurationData(90000, ['min', 's']); // { minutes: 1, seconds: 30 }
 * ```
 */
export declare function millisecondsToDurationData(ms: Milliseconds, units?: readonly TimeUnit[]): TimeDurationData;
/**
 * Reads a specific time unit value from a TimeDurationData object.
 *
 * @param data - The duration data.
 * @param unit - The time unit to read.
 * @returns The value for that unit, or 0 if not set.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, get, read, value, unit, time, field
 * @dbxUtilRelated set-duration-data-value, duration-data-to-milliseconds
 */
export declare function getDurationDataValue(data: TimeDurationData, unit: TimeUnit): number;
/**
 * Returns a new TimeDurationData with the specified unit set to the given value.
 *
 * @param data - The original duration data.
 * @param unit - The time unit to set.
 * @param value - The new value.
 * @returns A new TimeDurationData with the updated value.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, set, update, value, unit, time, field, immutable
 * @dbxUtilRelated get-duration-data-value, duration-data-to-milliseconds
 */
export declare function setDurationDataValue(data: TimeDurationData, unit: TimeUnit, value: number): TimeDurationData;
/**
 * Parses a human-readable duration string into a TimeDurationData object.
 *
 * Supports compact formats ("3d10h5m8s"), spaced formats ("3d 10h 5m 8s"),
 * and long formats ("3 days 10 hours 5 minutes 8 seconds"). Mixed formats
 * are also supported. If the same unit appears multiple times, values are summed.
 *
 * If the string contains only a number with no unit, it is treated as the
 * smallest unit that would make sense (milliseconds by default).
 *
 * @param input - The duration string to parse.
 * @returns A TimeDurationData object with the parsed values.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, parse, string, time, human-readable, decode
 * @dbxUtilRelated parse-duration-string-to-milliseconds, format-duration-string, format-duration-string-long, milliseconds-to-duration-data
 *
 * @example
 * ```typescript
 * parseDurationString('3d10h5m8s'); // { days: 3, hours: 10, minutes: 5, seconds: 8 }
 * parseDurationString('2 hours 30 minutes'); // { hours: 2, minutes: 30 }
 * parseDurationString('1w 2d'); // { weeks: 1, days: 2 }
 * parseDurationString('500ms'); // { milliseconds: 500 }
 * ```
 */
export declare function parseDurationString(input: string): TimeDurationData;
/**
 * Parses a duration string directly to milliseconds.
 *
 * @param input - The duration string to parse.
 * @returns Total milliseconds.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, parse, string, milliseconds, convert, decode
 * @dbxUtilRelated parse-duration-string, duration-data-to-milliseconds, format-duration-string
 *
 * @example
 * ```typescript
 * parseDurationStringToMilliseconds('1h30m'); // 5400000
 * ```
 */
export declare function parseDurationStringToMilliseconds(input: string): Milliseconds;
/**
 * Formats a TimeDurationData to a compact string like "3d10h5m8s".
 *
 * Omits zero-value units. Returns "0s" if all fields are zero or empty.
 *
 * @param data - The duration data to format.
 * @returns A compact duration string.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, format, string, compact, encode, time
 * @dbxUtilRelated format-duration-string-long, parse-duration-string, duration-data-to-milliseconds
 *
 * @example
 * ```typescript
 * formatDurationString({ days: 3, hours: 10, minutes: 5, seconds: 8 }); // "3d10h5m8s"
 * formatDurationString({ hours: 2, minutes: 30 }); // "2h30m"
 * formatDurationString({}); // "0s"
 * ```
 */
export declare function formatDurationString(data: TimeDurationData): string;
/**
 * Formats a TimeDurationData to a long human-readable string.
 *
 * Omits zero-value units. Returns "0 seconds" if all fields are zero or empty.
 *
 * @param data - The duration data to format.
 * @returns A human-readable duration string.
 *
 * @dbxUtil
 * @dbxUtilCategory date
 * @dbxUtilTags date, duration, format, string, long, human-readable, encode, time
 * @dbxUtilRelated format-duration-string, parse-duration-string, duration-data-to-milliseconds
 *
 * @example
 * ```typescript
 * formatDurationStringLong({ days: 3, hours: 10 }); // "3 days 10 hours"
 * formatDurationStringLong({ hours: 1, minutes: 1 }); // "1 hour 1 minute"
 * ```
 */
export declare function formatDurationStringLong(data: TimeDurationData): string;