/// <reference path="../../index.d.ts" />
import type { DataLine, HistogramColorStops, HistogramLabelFormatFunction, HistogramLayout } from "./types.js";
import type { HistogramBin } from "@arcgis/core/smartMapping/statistics/types.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina/PublicLitElement";
import type { T9nMeta } from "@arcgis/lumina/controllers";

/**
 * Renders a histogram to visualize the spread of a dataset based on [bins](#bins) representing buckets, or sub-ranges, of
 * data. Each [bin](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-statistics-types.html#HistogramBin) is defined by a minimum and maximum value and a total count.
 *
 * You can generate the underlying histogram's bins with the [histogram](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-statistics-histogram.html)
 * module, then apply them to the component, as shown in the example below.
 *
 * ```js
 * const params = {
 *   layer: povLayer,
 *   field: "POP_POVERTY",
 *   normalizationField: "TOTPOP_CY",
 *   numBins: 30
 * };
 *
 * const results = await histogram(params);
 * const histogramElement = document.querySelector("arcgis-histogram");
 *
 * histogramElement.bins = results.bins;
 * histogramElement.min = results.minValue;
 * histogramElement.max = results.maxValue;
 * ```
 *
 * Other properties of this component allow you to display meaningful values on the histogram, such as the [average](#average),
 * [one standard deviation](#standardDeviation), and the [dataLines](#dataLines) properties.
 *
 * The [layout](#layout) property allows you to set the orientation of the histogram, and the [colorStops](#colorStops)
 * property allows you to set a gradient or color scheme for the histogram bars.
 *
 * <a name="image-annotations"></a>
 * See the image below for a summary of the configurable options available on this slider.
 *
 * ![Histogram with annotations](https://developers.arcgis.com/javascript/latest/assets/img/apiref/widgets/histogram-basic-labels.png "Histogram with annotations")
 *
 * The [colorStops](#colorStops) property may be used to define a color scheme for the histogram bars.
 *
 * ![Histogram with color](https://developers.arcgis.com/javascript/latest/assets/img/apiref/widgets/histogram-colors.png "Histogram with color")
 *
 * **See also:**
 * - [histogram module](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-statistics-histogram.html)
 *
 * @cssproperty [--arcgis-histogram-bar-color] - Specifies the color of the histogram bars when the bin doesn't have a corresponding color stop.
 * @cssproperty [--arcgis-histogram-stop-color] - Specifies the default color for color stops.
 */
export abstract class ArcgisHistogram extends LitElement {
  /** @internal */
  protected _messages: Partial<{
      componentLabel: string;
      barLabel: string;
  }> & T9nMeta<{
      componentLabel: string;
      barLabel: string;
  }>;
  /**
   * The statistical average of the data in the histogram. You would typically
   * get this value from the `avg` property of
   * [SummaryStatisticsResult](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-statistics-summaryStatistics.html#SummaryStatisticsResult),
   * which is the result of the
   * [summaryStatistics](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-statistics-summaryStatistics.html#summaryStatistics) function.
   *
   * When set, this value will render on the histogram with a symbol indicating it is the average.
   *
   * @see [summaryStatistics](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-statistics-summaryStatistics.html#summaryStatistics)
   * @example
   * ```js
   * // sets result returned from a smart mapping method
   * // to the histogram
   * histogram.average = response.statistics.avg;
   * ```
   * @example
   * ```js
   * histogram.average = 34.5;
   * ```
   */
  accessor average: number | undefined;
  /**
   * An array of objects representing each bin in the histogram. This
   * information is typically returned from the
   * [histogram](https://developers.arcgis.com/javascript/latest/api-reference/esri-smartMapping-statistics-histogram.html#histogram) function.
   *
   * @example
   * ```js
   * // sets the bins of the histogram from the bins in the histogram() result
   * histogram.bins = histogramResult.bins;
   * ```
   * @example
   * ```js
   * // Creates a histogram with 7 bins.
   * histogram.bins = [
   *   { minValue: 0, maxValue: 10, count: 4 },
   *   { minValue: 10.1, maxValue: 20, count: 14 },
   *   { minValue: 20.1, maxValue: 30, count: 9 },
   *   { minValue: 30.1, maxValue: 40, count: 34 },
   *   { minValue: 40.1, maxValue: 50, count: 351 },
   *   { minValue: 50.1, maxValue: 60, count: 100 },
   *   { minValue: 60.1, maxValue: 70, count: 1 }
   * ];
   * ```
   */
  accessor bins: HistogramBin[] | undefined;
  /**
   * When set to `true`, overlapping classed color stops will be blended together to create the color of the bar.
   * This allows to show a if a bar representing a bin overlaps with multiple classed color stops.
   *
   * This property is only applicable when the [colorStops](#colorStops) property is set to classed color stops.
   *
   * @default false
   */
  accessor colorBlendingEnabled: boolean;
  /**
   * An array of color stops used to define the color scheme for the histogram bars.
   * There are two types of color stops:
   * - **Continuous color stops**: Each stop is defined by a color and a value. The color of the bar is determined by interpolating between the
   *   colors of the stops surrounding the value of the bin.
   * - **Classed color stops**: Each stop is defined by a color and a minValue and maxValue. The color of the bar is determined by the color of the stop
   *  that contains the value of the bin.
   *
   * @example
   * ```js
   * // Define continuous color stops on the histogram.
   * // The color of the bar is determined by interpolating between the colors of the stops surrounding the value of the bin.
   * histogram.colorStops = [
   *   { color: "#ff0000", value: 0 },
   *   { color: "#ffff00", value: 50 },
   *   { color: "#00ff00", value: 100 }
   * ];
   * ```
   * @example
   * ```js
   * // Define classed color stops on the histogram.
   * // The color of the bar is determined by the color of the stop that contains the value of the bin.
   * histogram.colorStops = [
   *   { color: "#ff0000", minValue: 0, maxValue: 50 },
   *   { color: "#00ff00", minValue: 50, maxValue: 100 },
   * ];
   * ```
   */
  accessor colorStops: HistogramColorStops | undefined;
  /**
   * When set, renders lines on the histogram that indicate important or
   * meaningful values to the end user.
   *
   * @example
   * ```js
   * // will render lines at the 25th, 50th, 75th, and 99th percentiles
   * histogram.dataLines = [{
   *   value: 30,
   *   label: "25 pctl"
   * }, {
   *   value: 45,
   *   label: "50 pctl"
   * }, {
   *   value: 65,
   *   label: "75 pctl"
   * }, {
   *   value: 89,
   *   label: "99 pctl"
   * }];
   * ```
   * @example
   * ```js
   * // calculate standard deviations from mean using stats
   * // returned from smart mapping statistic methods
   * const stddevs = smartMappingUtils.getDeviationValues(stats.stddev, stats.avg, 2);
   * histogram.dataLines = stddevs.map((stddev) => {
   *   return {
   *     value: stddev
   *   };
   * });
   * ```
   * @see [smartMappingUtils.getDeviationValues](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-smartMapping-support-utils.html#getDeviationValues)
   */
  accessor dataLines: DataLine[] | undefined;
  /**
   * Icon which represents the component.
   * Typically used when the component is controlled by another component (e.g. by the Expand component).
   * Search [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/) for possible values.
   *
   * @default "graph-histogram"
   */
  accessor icon: string | undefined;
  /** The component's default label. */
  accessor label: string | undefined;
  /**
   * A function used to format labels on the histogram. Overrides the default label formatter.
   *
   * @example
   * ```js
   * // For thumb values, rounds each label to whole numbers.
   * slider.labelFormatFunction = (value) => {
   *   return value.toFixed(0);
   * }
   * ```
   */
  accessor labelFormatFunction: HistogramLabelFormatFunction | undefined;
  /**
   * Determines the orientation of the histogram.
   *
   * @default "horizontal"
   * @example
   * ```js
   * histogram.layout = "vertical";
   * ```
   */
  accessor layout: HistogramLayout;
  /**
   * The maximum value or bound of the entire histogram. This
   * should match the maximum bound of the last [bin](#bins).
   *
   * @example
   * ```js
   * histogram.max = 100;
   * ```
   * @example
   * ```js
   * // sets result returned from a smart mapping method
   * // to the histogram
   * histogram.max = response.statistics.max;
   * ```
   */
  accessor max: number | undefined;
  /** Replace localized message strings with your own strings. */
  accessor messageOverrides: {
      componentLabel?: string | undefined;
      barLabel?: string | undefined;
  };
  /**
   * The minimum value or bound of the entire histogram. This
   * should match the minimum bound of the first [bin](#bins).
   *
   * @example
   * ```js
   * histogram.min = 0;
   * ```
   * @example
   * ```js
   * // sets result returned from a smart mapping method
   * // to the histogram
   * histogram.min = response.statistics.min;
   * ```
   */
  accessor min: number | undefined;
  accessor standardDeviation: number | undefined;
}