/**
 * Various utilities for accessing renderer colors that match to fields, Arcade expressions, or values.
 *
 * @since 4.28
 */
import type Color from "../../Color.js";
import type { RendererUnion } from "../types.js";

/**
 * Resolves with a [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) of fields matched to the color that the field is represented by in the renderer.
 * If the renderer has a default symbol, the string returned in the map will be "default".
 *
 * @param renderer - The renderer from which to extract fields and their associated matching colors.
 * @returns Resolves with a Map of string fields matched to the color that the field is represented by in the renderer. If there is no color matching to a field key, the value will be `null`.
 * @example
 * const fieldToColorMap = await rendererUtils.getColorsFromRenderer(renderer);
 * // Loop through the returned fieldToColorMap to access the fields and their matching color.
 * for (const field in Object.fromEntries(fieldToColorMap)) {
 *   const color = fieldToColorMap.get(field);
 * }
 */
export function getColorsFromRenderer(renderer: RendererUnion | null | undefined): Promise<Map<string, (Color | null | undefined)[]>>;

/** A Map object that holds a renderer value and its corresponding color. Type definition for [FieldToValueColorMap](https://developers.arcgis.com/javascript/latest/references/core/renderers/support/utils/#FieldToValueColorMap). */
export type ValueToColorMap = Map<string | number | null | undefined, Color | null | undefined>;

/** A mapping of the field or Arcade expression to a [ValueToColorMap](https://developers.arcgis.com/javascript/latest/references/core/renderers/support/utils/#ValueToColorMap) object. */
export type FieldToValueColorMap = Map<string, ValueToColorMap>;

/**
 * Resolves with a [FieldToValueColorMap](https://developers.arcgis.com/javascript/latest/references/core/renderers/support/utils/#FieldToValueColorMap) that contains the fields and a map of values to its matched color in the renderer.
 * If the renderer has a default symbol, the string value in the returned [FieldToValueColorMap](https://developers.arcgis.com/javascript/latest/references/core/renderers/support/utils/#FieldToValueColorMap) will be "default".
 *
 * @param renderer - The renderer from which to match values with their associated colors.
 * @returns Resolves with a [FieldToValueColorMap](https://developers.arcgis.com/javascript/latest/references/core/renderers/support/utils/#FieldToValueColorMap).
 * @example
 * const fieldToValueColorMap = await rendererUtils.getColorsForRendererValues(renderer);
 * // Loop through the returned fieldToValueColorMap to access the fields and their matching ValueToColorMap object.
 * for (const expressionOrField in Object.fromEntries(fieldToValueColorMap)) {
 *   const valueToColorMap = fieldToValueColorMap.get(expressionOrField);
 * }
 */
export function getColorsForRendererValues(renderer: RendererUnion | null | undefined): Promise<FieldToValueColorMap>;