import SpatialReference from '@arcgis/core/geometry/SpatialReference';
import GeographicTransformation from '@arcgis/core/geometry/operators/support/GeographicTransformation';
import GeographicTransformationStep from '@arcgis/core/geometry/operators/support/GeographicTransformationStep';
import { Items } from './CoordinateTransformer.js';
import '@arcgis/core/geometry';
import '@arcgis/core/geometry/Extent';
import '@arcgis/core/geometry/Geometry';

/**
 * A transformation provider supplies custom transformations between spatial reference systems.
 * An implementation can either return a transformation or forward to the default transformation
 * by returning `undefined`.
 * Not all transformation strategies support custom transformations.
 *
 * @example Register a custom TransformationProvider
 *
 * In your manifest.json:
 *
 * ```json
 * "components": [{
 *     "name": "MyCustomTransformationProvider",
 *     "provides": "coordinatetransformer.CustomTransformationProvider"
 * }]
 * ```
 *
 * In your code (MyCustomTransformationProvider.ts):
 *
 * ```ts
 * export default class MyCustomTransformationProvider implements TransformationProvider
 * {
 *     transformationFor(
 *         sourceSRS: SpatialReference,
 *         targetSRS: SpatialReference
 *     ):
 *         | GeographicTransformation
 *         | Items<Partial<GeographicTransformationStep>>
 *         | undefined {
 *         // Pseudo code
 *         if (sourceSRS.wkid === 1234 && targetSRS.wkid === 4567) {
 *             return {
 *                 wkid: 42007,
 *                 isInverse: false
 *             };
 *         }
 *         return undefined;
 *     }
 * }
 * ```
 */
interface TransformationProvider {
    /**
     * Returns an (optional) custom transformation to apply when transforming between the two spatial reference system.
     *
     * This function can return an instance of GeographicTransformation directly (see [details](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-support-GeographicTransformation.html)).
     * It may also return a single object (a single transformation step) or
     * an array of transformation steps for convenience.
     * These will be used * to construct a GeographicTransformation internally.
     *
     * When returning an object, you should either specify the well known id (`wkid`) or
     * the well known text (`wkt`) of the transformation.
     * You can optionally specify `isInverse` to reverse the direction of the transformation.
     * An array of such objects can be used to provide a series of transformation steps.
     *
     * Returning `undefined` indicates that the default transformation should be used, if one exists.
     *
     * @param sourceSpatialReference source spatial reference system
     * @param targetSpatialReference target spatial reference system
     * @returns a custom geographic transformation.
     */
    transformationFor(sourceSpatialReference: SpatialReference, targetSpatialReference: SpatialReference): GeographicTransformation | Items<Partial<GeographicTransformationStep>> | undefined;
}

export type { TransformationProvider };