import { UnitSource } from '../models/region-info/types';
export type UnitConversionSource = string | UnitSource;
/**
 * Region-aware unit conversion utility that can be used to convert between units of measure.
 *
 * When converting between units of measure, the source and target unit can be specified as a string or as a {@see UnitSource} object.
 * @example
 * in the simplest case, the source and target units can be specified as strings so long as they belong to the same measure (volume, length etc):
 *
 * ```typescript
 * import { convert } from "@kosdev-code/kos-ui-sdk";
 *
 * const value = convert(1000, "milliliter", "fluid-ounce");
 * ```
 *
 * The to unit can be omitted in which case the value will be converted to the default unit for the selected region measure:
 * @example
 * ```typescript
 * import { convert } from "@kosdev-code/kos-ui-sdk";
 *
 * // convert 1000 milliliters to the default unit for the region. If the region is set to US, the value will be converted to fluid ounces.
 * const value = convert(1000, "milliliter");
 * ```
 *
 * The source and target units can also be specified as {@see UnitSource} objects:
 * @example
 * ```typescript
 * import { convert } from "@kosdev-code/kos-ui-sdk";
 *
 * const value = convert(1000, {name: "milliliter", measure: "volume", system: "si"}, {name: "fluid-ounce", measure: "volume", system: "us"});
 * ```
 * In this case properties on the source and target are all optional so long as either the name or measure is specified.
 *
 * @param value - the value to convert
 * @param from - the source unit
 * @param to - the target unit. If omitted, the value will be converted to the default unit for the region measure.
 * @returns the converted value
 */
export declare const convert: (value: number, from: UnitConversionSource, to?: UnitConversionSource) => string;
/**
 * Converts a numeric value from one unit to another, formats the result, and returns
 * an object containing the converted value, display strings, and the unit.
 *
 * @example
 * convert and format a value, letting the region determine the target unit:
 *
 * ```typescript
 * import { convertWithUnits } from "@kosdev-code/kos-ui-sdk";
 *
 * // If the region is set to US, the value is converted to fluid ounces.
 * const result = convertWithUnits(1000, "milliliter");
 * // result.value       -> the converted numeric value as a string
 * // result.display     -> "33.81 fluid ounces"  (long form)
 * // result.shortDisplay -> "33.81 fl oz"         (short form)
 * // result.unit        -> "fluid-ounce"
 * ```
 *
 * @example
 * specify the target unit and control the number of decimal places:
 *
 * ```typescript
 * import { convertWithUnits } from "@kosdev-code/kos-ui-sdk";
 *
 * const result = convertWithUnits(1000, "milliliter", "fluid-ounce", {
 *   minDecimals: 1,
 *   maxDecimals: 1,
 * });
 * ```
 *
 * @param value - The numeric value to convert.
 * @param from - The source unit or unit system to convert from.
 * @param to - (Optional) The target unit or unit system to convert to. If not provided, uses the default unit system.
 * @param format - (Optional) Formatting options for the output, including minimum and maximum decimal places.
 * @param format.minDecimals - (Optional) Minimum number of decimal places in the formatted output.
 * @param format.maxDecimals - (Optional) Maximum number of decimal places in the formatted output.
 * @returns An object containing:
 *   - `value`: The converted value as a string.
 *   - `display`: The formatted value with unit in long form.
 *   - `shortDisplay`: The formatted value with unit in short form.
 *   - `unit`: The unit used for the converted value.
 * @throws If the RegionInfo model is not found.
 */
export declare const convertWithUnits: (value: number, from: UnitConversionSource, to?: UnitConversionSource, format?: {
    minDecimals?: number;
    maxDecimals?: number;
}) => {
    value: string;
    display: string;
    shortDisplay: string;
    unit: string;
};
//# sourceMappingURL=conversion-utils.d.ts.map