/**
 * Object containing helper methods for generating optimal colors for
 * heatmap visualizations.
 * The [getSchemes()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/symbology/heatmap/#getSchemes) method is used to get the heatmap color schemes best suited to
 * the given basemap.
 *
 * @since 4.11
 */
import type Basemap from "../../Basemap.js";
import type { HeatmapScheme, HeatmapSchemes, BasemapTheme, Theme } from "./types.js";

/**
 * Returns metadata for the available themes. If a basemap is provided, returns themes that work best
 * with the given basemap.
 *
 * @param basemap - The [Esri basemap string](https://developers.arcgis.com/javascript/latest/references/core/Map/#basemap)
 *   or object that will be used with the returned theme(s).
 * @returns Returns an object containing information about the available themes for the given basemap.
 */
export function getThemes(basemap?: Basemap | string): Theme[];

/**
 * Returns a primary scheme and secondary schemes defining properties for
 * heatmap visualizations in
 * a point [Layer](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/). The `basemap` parameter determines the color schemes of the
 * heatmap.
 *
 * @param params - The function parameters.
 * @returns Returns an object containing the optimal heatmap scheme to use for the given
 * basemap and secondary schemes that may also be used.
 * @example
 * // gets the primary scheme for the basemap
 * let schemes = heatmapSchemes.getSchemes({
 *   basemap: map.basemap
 * });
 *
 * // the best default scheme for the layer, basemap, and theme
 * let primaryScheme = schemes.primaryScheme;
 */
export function getSchemes(params: GetSchemesParameters): HeatmapSchemes | null | undefined;

export interface GetSchemesParameters {
  /**
   * The Esri basemap to pair with the visualization. This
   *   value indicates the best colors for visualizing features against the given basemap. If you have a
   *   non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, then use the `basemapTheme` parameter
   *   instead of this parameter.
   */
  basemap?: Basemap | string | null;
  /**
   * If you have a
   *   non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, use this parameter to indicate
   *   whether the background of the visualization is `light` or `dark`.
   */
  basemapTheme?: BasemapTheme | null;
}

/**
 * Returns a heatmap scheme with the provided name.
 *
 * @param params - The function parameters.
 * @returns Returns the heatmap scheme
 *   with the given name.
 * @since 4.12
 * @example
 * // Returns the Heatmap 4 scheme
 * let heatmapScheme = heatmapSchemes.getSchemeByName({
 *   basemap: map.basemap,
 *   name: "Heatmap 4"
 * });
 */
export function getSchemeByName(params: GetSchemesByNameParameters): HeatmapScheme | null | undefined;

/**
 * Returns an array of heatmap schemes with the provided tags. These schemes define color stop properties for
 * any layer that can be rendered with a [HeatmapRenderer](https://developers.arcgis.com/javascript/latest/references/core/renderers/HeatmapRenderer/).
 *
 * @param params - The function parameters.
 * @returns Returns an array of heatmap schemes
 *   either including or excluding the provided tags.
 * @since 4.12
 * @example
 * // Returns all the heatmap schemes that look good in grayscale
 * let grayscaleSchemes = heatmapSchemes.getSchemesByTag({
 *   basemap: map.basemap,
 *   includedTags: [ "heatmap", "grayscale" ]
 * });
 */
export function getSchemesByTag(params: GetSchemesByTagParameters): HeatmapScheme[];

/**
 * Clones a heatmap scheme object.
 *
 * @param scheme - The heatmap scheme object to clone.
 * @returns A clone of the given heatmap scheme object.
 * @example
 * // clones the primary scheme returned from the getSchemes() method
 * let heatmapScheme = primaryScheme.clone();
 */
export function cloneScheme(scheme: HeatmapScheme | null | undefined): HeatmapScheme | null | undefined;

export interface GetSchemesByNameParameters {
  /** The name of the scheme to retrieve. */
  name: string;
  /**
   * The basemap to pair with the visualization. This
   *   value indicates the best colors for visualizing features against the given basemap.
   */
  basemap?: Basemap | string | null;
  /**
   * If you have a
   *   non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, use this parameter to indicate
   *   whether the background of the visualization is `light` or `dark`.
   */
  basemapTheme?: BasemapTheme | null;
}

export interface GetSchemesByTagParameters {
  /**
   * When provided, only schemes containing all the matching tags will be returned.
   *
   * **Known Tags:** light | dark | reds | yellows | oranges | greens | blues | purples | pinks | browns | grays |
   * bright | subdued | deuteranopia | protanopia | tritanopia | grayscale | types | dot-density
   */
  includedTags?: string[] | null;
  /**
   * When provided, only schemes missing all the provided tags will be returned.
   *
   * **Known Tags:** light | dark | reds | yellows | oranges | greens | blues | purples | pinks | browns | grays |
   * bright | subdued | deuteranopia | protanopia | tritanopia | grayscale | types | dot-density
   */
  excludedTags?: string[] | null;
  /**
   * The basemap to pair with the visualization. This
   * value indicates the best symbol colors for visualizing features against the given basemap.
   */
  basemap: Basemap | string;
}