import type Basemap from "../../Basemap.js";

/**
 * This function is used by the [PortalBasemapsSource#filterFunction](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-BasemapGallery-support-PortalBasemapsSource.html#filterFunction) property to filter
 * basemaps after they are fetched from the Portal.
 *
 * _Support for asynchronous filter functions was added at version 4.27._
 *
 * @param item - The current Basemap item being assessed in the array.
 * @param index - The index of the Basemap being assessed.
 * @param array - The array of basemaps being filtered.
 * @returns Returns true if the test passes, false otherwise.
 */
export type BasemapFilter = (item: Basemap, index: number, array: Basemap[]) => boolean | Promise<boolean>;

/**
 * This function is used by the [PortalBasemapsSource#updateBasemapsCallback](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-BasemapGallery-support-PortalBasemapsSource.html#updateBasemapsCallback) property for
 * updating basemaps after being fetched and filtered.
 *
 * _Support for asynchronous update functions was added at version 4.29._
 *
 * @param items - An array of basemaps that have been fetched and filtered from the Portal.
 * @returns The array of basemaps to display in the BasemapGallery widget.
 * @example
 * // Create custom basemap to be added to the array of portal basemaps
 * const basemapGallery = new BasemapGallery({
 *    view: view,
 *    source: {
 *      query: {
 *        title: "United States Basemaps",
 *        owner: "Esri_cy_US"
 *      },
 *      updateBasemapsCallback: (items) => {
 *        // create custom basemap to be added to the array of portal basemaps
 *        let bm = new Basemap({
 *          portalItem: {
 *            id: "8dda0e7b5e2d4fafa80132d59122268c"  // WGS84 Streets Vector webmap
 *          }
 *        });
 *        // add basemap to the array
 *        items.push(bm);
 *        // return the array of basemaps
 *        return items;
 *      }
 *    }
 * });
 * @example
 * // Add current basemap if not already present
 * const currentBasemap = map.basemap;
 * const basemapGallery = new BasemapGallery({
 *   view,
 *   source: {
 *     portal: "https://arcgis.com",
 *     async updateBasemapsCallback(items) {
 *       for (const item of items) {
 *         // load basemap for proper comparison
 *         await item.load();
 *         if (basemapGallery.viewModel.basemapEquals(currentBasemap, item))
 *           return items;
 *       }
 *       // add the current basemap if not found in the array of basemap items
 *       return [currentBasemap, ...items];
 *     }
 *   }
 * });
 */
export type UpdateBasemapsCallback = (items: Basemap[]) => Basemap[] | Promise<Basemap[]>;

export type BasemapsSourceState = "ready" | "loading" | "not-loaded";