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

/**
 * Renders a histogram to visualize the spread of a dataset based on [bins](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#bins) representing buckets, or sub-ranges, of
 * data. Each [bin](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/types/#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/references/core/smartMapping/statistics/histogram/)
 * 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](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#average),
 * [standardDeviation](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#standardDeviation), and the [dataLines](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#dataLines) properties.
 *
 * The [layout](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#layout) property allows you to set the orientation of the histogram, and the [colorStops](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#colorStops)
 * property allows you to set a gradient or color scheme for the histogram bars.
 *
 * See the image below for a summary of the configurable options available on the histogram.
 *
 * ![Histogram with annotations](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/histogram-basic-labels.avif "Histogram with annotations")
 *
 * The [colorStops](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#colorStops) property may be used to define a color scheme for the histogram bars.
 *
 * ![Histogram with color](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/histogram-colors.avif "Histogram with color")
 *
 * @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.
 * @see [histogram module](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/histogram/)
 * @see [Sample - Histogram component](https://developers.arcgis.com/javascript/latest/sample-code/histogram/)
 * @since 5.0
 */
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/references/core/smartMapping/statistics/summaryStatistics/#SummaryStatisticsResult),
   * which is the result of the
   * [summaryStatistics](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/summaryStatistics/#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/references/core/smartMapping/statistics/summaryStatistics/#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/references/core/smartMapping/statistics/histogram/#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](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#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. If the `color` is omitted, the bar will be colored using the CSS variable `--arcgis-histogram-stop-color`.
   *
   * When a bar is not covered by any color stop, it will be colored using the CSS variable `--arcgis-histogram-bar-color`.
   *
   * @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/references/core/widgets/smartMapping/support/utils/#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;
  /**
   * 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 [bins](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#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.
   *
   * _**Note**: Individual message keys may change between releases._
   */
  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 [bins](https://developers.arcgis.com/javascript/latest/references/common-components/components/arcgis-histogram/#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;
  /**
   * The statistical standard deviation of the data in the histogram. You would typically
   * get this value from the `stddev` property of
   * [SummaryStatisticsResult](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/summaryStatistics/#SummaryStatisticsResult),
   * which is the result of the
   * [summaryStatistics](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/summaryStatistics/#summaryStatistics) function.
   *
   * When set, this value will render on the histogram with symbols indicating standard deviation intervals from the mean.
   *
   * @see [summaryStatistics](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/summaryStatistics/#summaryStatistics)
   * @example
   * ```js
   * // sets result returned from a smart mapping method
   * // to the histogram
   * histogram.standardDeviation = response.statistics.stddev;
   * ```
   */
  accessor standardDeviation: number | undefined;
}