/**
 * This module provides convenience methods for querying color ramps (arrays of colors) used for raster renderers
 * in the `module:esri/smartMapping/raster/color/renderers` modules.
 *
 * @since 4.29
 * @see [Sample - ImageryTileLayer - shaded relief renderer](https://developers.arcgis.com/javascript/latest/sample-code/layers-imagery-renderer/)
 */
import type Color from "../../../Color.js";
import type AlgorithmicColorRamp from "../../../rest/support/AlgorithmicColorRamp.js";
import type MultipartColorRamp from "../../../rest/support/MultipartColorRamp.js";

/** Defines a ramp of colors to use for visualizing raster data. */
export interface ColorRamp {
  /** An array of colors intended for displaying a continuous color ramp. */
  colors: Color[];
  /** The unique name of the color ramp. */
  name: string;
}

/**
 * Returns all color ramps designed for raster renderers, each as an array of colors.
 *
 * @returns An array of all
 *   color ramps available for visualizing raster data.
 * @example
 * // returns all raster color ramps available in the JS API
 * const ramps = colorRamps.all();
 * @example
 * // Renders all color ramps as continuous color ramps in the body of the html
 * const ramps = colorRamps.all();
 *
 * ramps.forEach( ramp => {
 *   const colorRamp = symbolUtils.renderColorRampPreviewHTML(ramp.colors, {
 *     align: "horizontal"
 *   });
 *   body.appendChild(colorRamp);
 * });
 */
export function all(): ColorRamp[];

/**
 * Returns the names of all raster color ramps.
 *
 * @returns An array of all raster color ramp names.
 * @example
 * // returns all color ramp names available in the JS API
 * const rampNames = colorRamps.names();
 */
export function names(): string[];

/**
 * Returns the color ramp matching the given name.
 *
 * @param name - The name of the desired color ramp.
 * @returns The
 *   color ramp matching the given name.
 * @see [names()](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-raster-support-colorRamps.html#names)
 * @example
 * // returns the colors of the Elevation #1 color ramp
 * const elevationRamp = colorRamps.byName("Elevation #1");
 * const colorRampElement = symbolUtils.renderColorRampPreviewHTML(elevationRamp.colors, {
 *   align: "horizontal"
 * });
 * body.appendChild(colorRampElement);
 */
export function byName(name: string): ColorRamp | null | undefined;

/**
 * Creates a raster color ramp from a list of colors.
 *
 * @param options - Options for creating a raster color ramp with the following properties:
 * @returns Returns the raster color ramp given an input array of colors.
 * @see [AlgorithmicColorRamp#algorithm](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-support-AlgorithmicColorRamp.html#algorithm)
 * @see [Sample - ImageryTileLayer - shaded relief renderer](https://developers.arcgis.com/javascript/latest/sample-code/layers-imagery-renderer/)
 */
export function createColorRamp(options: CreateColorRampOptions): MultipartColorRamp | AlgorithmicColorRamp | null | undefined;

export interface CreateColorRampOptions {
  /**
   * The algorithm used to interpolate colors between stops.
   *
   * Possible Value | Description
   * ---------------|------------
   * cie-lab | Blends the from and to colors without traversing the intervening hue space.
   * lab-lch | The hue, saturation, value (hsv) algorithm is a linear traverse of colors between pairs: Color 1 H to Color 2 H, Color 1 S to Color 2 S, and Color 1 V to Color 2 V.
   * hsv | The lab-lch algorithm is very similar to the cie-lab but does not seek the shortest path between colors.
   *
   * @default cie-lab
   */
  algorithm?: AlgorithmicColorRamp["algorithm"];
  /** An array of colors to convert to a multi-part or algorithmic color ramp. */
  colors: Color[];
}

/** The name of a color ramp and whether it is inverted. */
export interface ColorRampName {
  /** Indicates if the ramp's colors are inverted. */
  inverted: boolean;
  /** The unique name of the color ramp. */
  name: string;
}

/**
 * Returns a raster color ramp's name.
 *
 * @param colorRamp - The raster color ramp from which to get the name.
 * @returns Returns
 *   the color ramp name and whether it is inverted.
 */
export function getColorRampName(colorRamp: MultipartColorRamp | AlgorithmicColorRamp): ColorRampName | null | undefined;