import { type Factory } from '../getter/getter';
import { type NumberPrecision, type RoundToPrecisionFunctionType } from '../number/round';
import { type Maybe } from './maybe.type';
/**
 * Latitude value in degrees, ranging from -90 to 90.
 */
export type Latitude = number;
/**
 * Longitude value in degrees, ranging from -180 to 180.
 */
export type Longitude = number;
/**
 * Minimum valid latitude value (-90 degrees).
 */
export declare const MIN_LATITUDE_VALUE = -90;
/**
 * Maximum valid latitude value (90 degrees).
 */
export declare const MAX_LATITUDE_VALUE = 90;
/**
 * Total range of latitude values (180 degrees).
 */
export declare const TOTAL_LATITUDE_RANGE: number;
/**
 * Minimum valid longitude value (-180 degrees).
 */
export declare const MIN_LONGITUDE_VALUE = -180;
/**
 * Maximum valid longitude value (180 degrees).
 */
export declare const MAX_LONGITUDE_VALUE = 180;
/**
 * Total range of longitude values (360 degrees).
 */
export declare const TOTAL_LONGITUDE_RANGE: number;
/**
 * A geographic point represented by latitude and longitude.
 */
export interface LatLngPoint {
    lat: Latitude;
    lng: Longitude;
}
/**
 * A point decorated as LonLat.
 *
 * NOTE: This library (dbx-components) prefers the use of LatLngPoint over LonLatPoint. This is only provided as compatability for libraries (like Mapbox) that have LonLat-like points
 */
export interface LonLatPoint {
    lat: Latitude;
    lon: Longitude;
}
/**
 * Type guard that checks whether the input is a {@link LatLngPoint} by testing for `lat` and `lng` properties.
 *
 * @param input - the value to test
 * @returns `true` if the input has both `lat` and `lng` properties
 */
export declare function isLatLngPoint(input: LatLngPoint | unknown): input is LatLngPoint;
/**
 * Creates a shallow copy of the point so that mutations to the copy do not affect the original.
 *
 * @param input - point to copy
 * @returns a new point with the same coordinates
 */
export declare function copyLatLngPoint(input: LatLngPoint): LatLngPoint;
/**
 * Checks whether two points have identical coordinates. Handles `null`/`undefined` by returning `true` only if both are nullish.
 *
 * @param a - first point
 * @param b - second point
 * @returns `true` if both points have the same `lat` and `lng`, or both are nullish
 */
export declare function isSameLatLngPoint(a: Maybe<LatLngPoint>, b: Maybe<LatLngPoint>): boolean;
/**
 * Computes the difference between two points (`a - b`), optionally wrapping the result to valid lat/lng ranges.
 *
 * @param a - the point to subtract from
 * @param b - the point to subtract
 * @param wrap - whether to wrap the result to valid lat/lng ranges; defaults to `true`
 * @returns a point representing the difference
 */
export declare function diffLatLngPoints(a: LatLngPoint, b: LatLngPoint, wrap?: boolean): LatLngPoint;
/**
 * Computes the sum of two points (`a + b`), optionally wrapping the result to valid lat/lng ranges.
 *
 * @param a - the first point
 * @param b - the second point
 * @param wrap - whether to wrap the result to valid lat/lng ranges; defaults to `true`
 * @returns a point representing the sum
 */
export declare function addLatLngPoints(a: LatLngPoint, b: LatLngPoint, wrap?: boolean): LatLngPoint;
/**
 * Wraps a point so its latitude is capped to [-90, 90] and its longitude wraps around [-180, 180].
 *
 * @param a - point to wrap
 * @returns a new point with valid coordinates
 */
export declare function wrapLatLngPoint(a: LatLngPoint): LatLngPoint;
/**
 * Caps a latitude value to the valid range [-90, 90]. Values outside are clamped to the nearest boundary.
 */
export declare const capLatValue: import("..").BoundNumberFunction<number>;
/**
 * Wraps a longitude value into the valid range [-180, 180]. Values that exceed the range wrap around to the opposite side.
 *
 * @example
 * ```ts
 * wrapLngValue(-190);
 * // 170
 *
 * wrapLngValue(190);
 * // -170
 * ```
 */
export declare const wrapLngValue: import("..").WrapNumberFunction<number>;
/**
 * Checks whether a latitude value is within the valid range [-90, 90].
 *
 * @param lat - latitude value to validate
 * @returns `true` if the value is a valid latitude
 */
export declare function isValidLatitude(lat: Latitude): boolean;
/**
 * Checks whether a longitude value is within the valid range [-180, 180].
 *
 * @param lat - longitude value to validate
 * @returns `true` if the value is a valid longitude
 */
export declare function isValidLongitude(lat: Longitude): boolean;
/**
 * Returns the default {@link LatLngPoint} at the origin (0, 0).
 *
 * @returns a point at latitude 0, longitude 0
 */
export declare function defaultLatLngPoint(): LatLngPoint;
/**
 * Checks whether a point or string represents the default (0, 0) location.
 * Treats empty strings as the default.
 *
 * @param point - a point or lat/lng string to check
 * @returns `true` if the input represents the default location
 */
export declare function isDefaultLatLngPoint(point: LatLngPoint | LatLngString | ''): boolean;
/**
 * Checks whether a point has coordinates of exactly (0, 0).
 *
 * @param point - point to check
 * @returns `true` if both `lat` and `lng` are 0
 */
export declare function isDefaultLatLngPointValue(point: LatLngPoint): boolean;
/**
 * Returns the south-west-most possible point (-90, -180).
 *
 * @returns the minimum corner of the valid coordinate space
 */
export declare function swMostLatLngPoint(): LatLngPoint;
/**
 * Returns the north-east-most possible point (90, 180).
 *
 * @returns the maximum corner of the valid coordinate space
 */
export declare function neMostLatLngPoint(): LatLngPoint;
/**
 * Returns true if the input point's lat/lng values are within the acceptable values range.
 *
 * @param input - point to validate
 * @returns `true` if both lat and lng are within valid ranges
 */
export declare function isValidLatLngPoint(input: LatLngPoint): boolean;
/**
 * Latitude, Longitude tuple, representative.
 */
export type LatLngTuple = [Latitude, Longitude];
/**
 * Longitude, Latitude tuple. This is more analogous of x,y coordinates.
 */
export type LonLatTuple = [Longitude, Latitude];
/**
 * Converts the input to a {@link LatLngTuple} using the default configuration.
 *
 * @param lat - a latitude value or any lat/lng point input
 * @param lng - optional longitude when `lat` is a numeric latitude
 * @returns a `[lat, lng]` tuple
 */
export declare function latLngTuple(lat: LatLngPointInput, lng?: Longitude): LatLngTuple;
/**
 * Converts the input to a {@link LonLatTuple} (longitude-first ordering), useful for interop with libraries like Mapbox.
 *
 * @param lat - a latitude value or any lat/lng point input
 * @param lng - optional longitude when `lat` is a numeric latitude
 * @returns a `[lng, lat]` tuple
 *
 * @example
 * ```ts
 * const result: LonLatTuple = lonLatTuple([-120, 80]);
 * // result === [-120, 80]
 * ```
 */
export declare function lonLatTuple(lat: LatLngPointInput, lng?: Longitude): LonLatTuple;
/**
 * Converts various lat/lng input formats into a {@link LatLngTuple}.
 */
export type LatLngTupleFunction = ((lat: LatLngPointInput, lng?: Longitude) => LatLngTuple) & ((latLng: string | LatLngTuple) => LatLngTuple) & ((latLng: LatLngPoint | LonLatPoint) => LatLngTuple) & ((lat: Latitude, lng?: Longitude) => LatLngTuple);
export type LatLngTupleFunctionConfig = LatLngPointFunctionConfig;
/**
 * Creates a {@link LatLngTupleFunction} that converts various input formats into `[lat, lng]` tuples,
 * applying optional precision configuration.
 *
 * @param config - optional configuration for precision and wrapping behavior
 * @returns a function that produces lat/lng tuples from flexible inputs
 */
export declare function latLngTupleFunction(config?: LatLngTupleFunctionConfig): LatLngTupleFunction;
/**
 * A lat,lng encoded value as a comma-separated string.
 */
export type LatLngString = `${Latitude},${Longitude}`;
/**
 * Default LatLng value as a string.
 */
export declare const DEFAULT_LAT_LNG_STRING_VALUE = "0,0";
/**
 * Returns the default {@link LatLngString} value (`'0,0'`).
 *
 * @returns the default lat/lng string
 */
export declare function defaultLatLngString(): typeof DEFAULT_LAT_LNG_STRING_VALUE;
/**
 * Union type of all accepted input formats for creating a {@link LatLngPoint}: a numeric latitude, a point object, a lat/lng string, or a tuple.
 */
export type LatLngPointInput = Latitude | LatLngPoint | LonLatPoint | LatLngString | LatLngTuple | string;
/**
 * Precision for lat/lng rounding, expressed as the number of decimal places.
 */
export type LatLngPrecision = NumberPrecision;
/**
 * Creates a {@link LatLngString} from the input using the default configuration.
 *
 * @param lat - latitude value or a point input
 * @param lng - optional longitude when `lat` is a numeric latitude
 * @returns a comma-separated lat/lng string
 */
export declare function latLngString(lat: Latitude, lng?: Longitude): LatLngString;
export declare function latLngString(latLng: LatLngPoint): LatLngString;
export declare function latLngString(latLng: LatLngString): LatLngString;
/**
 * Maximum number of decimal places supported by the lat/lng regex pattern.
 */
export declare const LAT_LNG_PATTERN_MAX_PRECISION = 15;
/**
 * A lat/lng regex with capture groups for lat and lng.
 *
 * https://stackoverflow.com/questions/3518504/regular-expression-for-matching-latitude-longitude-coordinates
 *
 * Has a max precision of 15 because Google Maps returns a 15 decimal places when copying a position.
 */
export declare const LAT_LNG_PATTERN: RegExp;
/**
 * Checks whether the input string matches the expected lat/lng pattern (e.g., `"30.5,-96.3"`).
 *
 * @param input - string to test
 * @returns `true` if the string is a valid lat/lng format
 */
export declare function isLatLngString(input: string): input is LatLngString;
/**
 * 111KM meter precision, 0 decimal places
 */
export declare const LAT_LONG_100KM_PRECISION = 0;
/**
 * 11.1KM meter precision, 1 decimal place
 */
export declare const LAT_LONG_10KM_PRECISION = 1;
/**
 * 1.11KM meter precision, 2 decimal places
 */
export declare const LAT_LONG_1KM_PRECISION = 2;
/**
 * 111 meter precision, 3 decimal places
 */
export declare const LAT_LONG_100M_PRECISION = 3;
/**
 * 11.1 meter precision, 4 decimal places
 */
export declare const LAT_LONG_10M_PRECISION = 4;
/**
 * 001.11 meter precision, 5 decimal places
 */
export declare const LAT_LONG_1M_PRECISION = 5;
/**
 * 011.10 centimeter precision, 6 decimal places
 */
export declare const LAT_LONG_10CM_PRECISION = 6;
/**
 * 001.11 centimeter precision, 7 decimal places
 */
export declare const LAT_LONG_1CM_PRECISION = 7;
/**
 * 001.11 millimeter precision, 8 decimal places
 */
export declare const LAT_LONG_1MM_PRECISION = 8;
/**
 * 0.1mm precision, 9 decimal places
 *
 * "Hey, check out this specific sand grain!"
 *
 * https://xkcd.com/2170/
 */
export declare const LAT_LONG_GRAINS_OF_SAND_PRECISION = 9;
/**
 * Rounds the input latLng value to a given precision.
 */
export type LatLngPointPrecisionFunction = (latLngPoint: LatLngPoint) => LatLngPoint;
/**
 * Creates a {@link LatLngPointPrecisionFunction} that rounds both lat and lng values
 * to the specified number of decimal places.
 *
 * @param precision - number of decimal places to retain
 * @param precisionRounding - optional rounding strategy (e.g., floor, ceil, round)
 * @returns a function that rounds points to the given precision
 */
export declare function latLngPointPrecisionFunction(precision: LatLngPrecision, precisionRounding?: RoundToPrecisionFunctionType): LatLngPointPrecisionFunction;
/**
 * Converts various lat/lng input formats into a {@link LatLngString}.
 */
export type LatLngStringFunction = ((lat: LatLngPointInput, lng?: Longitude) => LatLngString) & ((latLng: string | LatLngString) => LatLngString) & ((latLng: LatLngPoint | LonLatPoint) => LatLngString) & ((lat: Latitude, lng?: Longitude) => LatLngString);
export type LatLngStringFunctionConfig = LatLngPointFunctionConfig;
/**
 * Creates a {@link LatLngStringFunction} that converts various input formats into comma-separated lat/lng strings,
 * applying optional precision configuration.
 *
 * @param config - optional configuration for precision and wrapping behavior
 * @returns a function that produces lat/lng strings from flexible inputs
 */
export declare function latLngStringFunction(config?: LatLngStringFunctionConfig): LatLngStringFunction;
/**
 * Converts various lat/lng input formats into a {@link LatLngPoint}.
 */
export type LatLngPointFunction = ((lat: LatLngPointInput, lng?: Longitude) => LatLngPoint) & ((latLng: string | LatLngString) => LatLngPoint) & ((latLng: LatLngPoint | LonLatPoint) => LatLngPoint) & ((lat: Latitude, lng: Longitude) => LatLngPoint);
/**
 * Configuration for creating a {@link LatLngPointFunction}.
 */
export interface LatLngPointFunctionConfig {
    /**
     * LatLngPrecision to use
     */
    precision?: LatLngPrecision | null;
    /**
     * Precision rounding to use.
     */
    precisionRounding?: RoundToPrecisionFunctionType;
    /**
     * Whether or not to wrap invalid LatLng values. If false, the values are validated and a default value is used instead.
     *
     * Is true by default.
     */
    wrap?: boolean;
    /**
     * Whether or not to valiate the input. Is ignored if wrap is not false.
     */
    validate?: boolean;
    /**
     * The default LatLngPoint to return if an invalid point is entered. Only used if validate is true.
     */
    default?: Factory<LatLngPoint>;
    /**
     * Treat tuples as LonLat instead of LatLng.
     *
     * False by default
     */
    readLonLatTuples?: boolean;
}
/**
 * Creates a {@link LatLngPoint} using the default configuration. Convenience wrapper around {@link latLngPointFunction}.
 *
 * @param lat - a latitude value or any lat/lng point input
 * @param lng - optional longitude when `lat` is a numeric latitude
 * @returns the parsed and normalized point
 *
 * @example
 * ```ts
 * const point = latLngPoint(30.59929, -96.38315);
 * // point.lat === 30.59929, point.lng === -96.38315
 * ```
 */
export declare function latLngPoint(lat: LatLngPointInput, lng?: Longitude): LatLngPoint;
/**
 * Creates a {@link LatLngPointFunction} that normalizes various input formats (numbers, strings, tuples, objects)
 * into a {@link LatLngPoint}, with configurable precision, wrapping, and validation.
 *
 * @param config - optional configuration for precision, wrapping, validation, and tuple ordering
 * @returns a function that produces points from flexible inputs
 * @throws {Error} when the input cannot be parsed into a valid point
 *
 * @example
 * ```ts
 * const fn = latLngPointFunction({ precision: 3 });
 * const result = fn(30.59929, -96.38315);
 * // result.lat === 30.599, result.lng === -96.383
 * ```
 */
export declare function latLngPointFunction(config?: LatLngPointFunctionConfig): LatLngPointFunction;
/**
 * Parses a comma-separated lat/lng string into a {@link LatLngPoint}. Invalid numeric values default to 0.
 *
 * @param latLngString - string in the format `"lat,lng"`
 * @returns the parsed point
 */
export declare function latLngPointFromString(latLngString: LatLngString | string): LatLngPoint;
/**
 * Validates a point and returns it if valid, or a default point otherwise.
 *
 * @param latLngPoint - point to validate
 * @param defaultValue - optional factory for the fallback point; defaults to `defaultLatLngPoint`
 * @returns the original point if valid, or the default
 */
export declare function validLatLngPoint(latLngPoint: LatLngPoint, defaultValue?: Factory<LatLngPoint>): LatLngPoint;
/**
 * Returns a valid LatLngPoint by validating the input and returns the input value if it is valid, or a default value that is valid.
 */
export type ValidLatLngPointFunction = (latLngPoint: LatLngPoint) => LatLngPoint;
/**
 * Creates a {@link ValidLatLngPointFunction} that returns the input point when valid, or a default point otherwise.
 *
 * @param defaultValue - factory for the fallback point; defaults to `defaultLatLngPoint`
 * @returns a validation function
 */
export declare function validLatLngPointFunction(defaultValue?: Factory<LatLngPoint>): ValidLatLngPointFunction;
/**
 * References a latLng using a LatLngPoint
 */
export type LatLngPointRef = {
    readonly latLng: LatLngPoint;
};
/**
 * References a latLng using a LatLngTuple
 */
export type LatLngTupleRef = {
    readonly latLng: LatLngTuple;
};
/**
 * References a latLng using a LatLngString
 */
export type LatLngStringRef = {
    readonly latLng: LatLngString;
};
/**
 * An object that references a latLng
 */
export type LatLngRef = LatLngPointRef | LatLngStringRef | LatLngTupleRef;
/**
 * References a latLng using a LatLngPointInput.
 */
export type LatLngInputRef = {
    readonly latLng: LatLngPointInput;
};
/**
 * A LatLngPointRef with arbitrary data
 */
export type LatLngDataPoint<T> = LatLngPointRef & {
    readonly data: T;
};
/**
 * Converts the input value to a LatLngDataPoint
 */
export type LatLngDataPointFunction<T extends LatLngRef> = (data: T) => LatLngDataPoint<T>;
/**
 * Creates a {@link LatLngDataPointFunction} that wraps a {@link LatLngRef} object with its resolved point coordinates.
 *
 * @param config - optional configuration for precision and wrapping behavior
 * @returns a function that produces data points from lat/lng references
 */
export declare function latLngDataPointFunction<T extends LatLngRef>(config?: LatLngPointFunctionConfig): LatLngDataPointFunction<T>;
/**
 * Configuration for {@link randomLatLngFactory}.
 */
export interface RandomLatLngFactoryConfig {
    /**
     * South-west corner of the bounding box for random generation. Partial values default to the minimum valid coordinates.
     */
    sw?: Partial<LatLngPoint>;
    /**
     * North-east corner of the bounding box for random generation. Partial values default to the maximum valid coordinates.
     */
    ne?: Partial<LatLngPoint>;
    /**
     * Precision of the LatLng to keep.
     */
    precision?: LatLngPrecision;
}
/**
 * A factory that produces random {@link LatLngPoint} values.
 */
export type RandomLatLngFactory = () => LatLngPoint;
/**
 * Creates a {@link RandomLatLngFactory} that generates random points within the specified bounding box.
 * The bounding box corners are capped/wrapped to valid coordinate ranges.
 *
 * @param config - optional bounding box and precision configuration
 * @returns a factory that produces random points within the bounds
 */
export declare function randomLatLngFactory(config?: RandomLatLngFactoryConfig): RandomLatLngFactory;
/**
 * Configuration for {@link randomLatLngFromCenterFactory}.
 */
export interface RandomLatLngFromCenterFactoryConfig extends Pick<RandomLatLngFactoryConfig, 'precision'> {
    /**
     * Center from which a rectangle is generated to pick random
     */
    center: LatLngPoint;
    /**
     * Max distance from the center.
     */
    latDistance: number;
    /**
     * Max lng distance from the center.
     */
    lngDistance: number;
}
/**
 * Creates a {@link RandomLatLngFactory} that generates random points within a rectangle
 * centered on the given point, extending by `latDistance` and `lngDistance` in each direction.
 *
 * @param config - center point, distances, and optional precision
 * @returns a factory that produces random points near the center
 */
export declare function randomLatLngFromCenterFactory(config: RandomLatLngFromCenterFactoryConfig): RandomLatLngFactory;