/**
 * This module provides convenience methods for querying color ramps (arrays of colors) used in the smart mapping
 * [color symbology](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html) module.
 *
 * @since 4.14
 * @see [color](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html)
 */
import type { ColorRamp } from "../types.js";

/**
 * Returns all color ramps available in smartMapping [color schemes](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html).
 *
 * @returns An array of all
 *   color ramps available in the smartMapping [color schemes](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html).
 * @example
 * // returns all 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 color ramps available in the smartMapping [color schemes](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html).
 * Any of the returned names can be used to query for color schemes using
 * [colorSchemes.getSchemeByName()](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html#getSchemeByName) or
 * the color ramp using [byName()](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-support-colorRamps.html#byName).
 *
 * @returns An array of all
 *   color ramp names available in the smartMapping [color schemes](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html).
 * @example
 * // returns all color ramp names available in the JS API
 * const rampNames = colorRamps.names();
 */
export function names(): string[];

/**
 * Returns the color ramp available in the smartMapping [color schemes](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html)
 * matching the given name.
 *
 * @param name - The name of the desired color ramp.
 * @returns The
 *   color ramp matching the given name.
 * @example
 * // returns the colors of the Flower Field color ramp
 * const flowerFieldRamp = colorRamps.byName("Flower Field");
 * const colorRamp = symbolUtils.renderColorRampPreviewHTML(flowerFieldRamp.colors, {
 *   align: "horizontal"
 * });
 * body.appendChild(colorRamp);
 */
export function byName(name: string): ColorRamp | null | undefined;

/**
 * Returns the color ramps available in the smartMapping [color schemes](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-symbology-color.html)
 * matching the given tags.
 *
 * @param params - See the table below for details of each parameter that may be passed to this function.
 * @returns The
 *   color ramps matching the given tags.
 * @example
 * // returns all bright red color ramps available in the JS API
 * const ramps = colorRamps.byTag({
 *   includedTags: [ "reds", "bright" ]
 * });
 */
export function byTag(params: ByTagParams): ColorRamp[];

export interface ByTagParams {
  /**
   * When provided, only ramps missing all the provided tags will be returned.
   *
   * **Known Tags:** light | dark | reds | yellows | oranges | greens | blues | purples | pinks | browns | grays |
   * bright | subdued | colorblind-friendly | diverging | sequential | categorical | heatmap | 3d
   */
  excludedTags: string[];
  /**
   * When provided, only ramps containing all the matching tags will be returned.
   *
   * **Known Tags:** light | dark | reds | yellows | oranges | greens | blues | purples | pinks | browns | grays |
   * bright | subdued | colorblind-friendly | diverging | sequential | categorical | heatmap | 3d
   */
  includedTags: string[];
}