@arcgis/map-components/dist/components/arcgis-histogram-range-slider/customElement.d.ts

ArcGIS Map Components

/// <reference path="../../index.d.ts" />
import type Color from "@arcgis/core/Color.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, IconName } from "../types.js";
import type { ColorLike } from "@arcgis/core/Color.js";
import type { BarCreatedFunction, DataLineCreatedFunction, DataLineInfos } from "@arcgis/core/widgets/Histogram/types.js";
import type { HistogramBin } from "@arcgis/core/smartMapping/statistics/types.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { LabelFormatFunction } from "@arcgis/core/widgets/types.js";
import type { RangeType } from "@arcgis/core/widgets/HistogramRangeSlider/types.js";
import type { SliderViewModelState } from "@arcgis/core/widgets/Slider/SliderViewModel.js";

/** @internal */
export abstract class ArcgisHistogramRangeSlider extends LitElement {
  /**
   * If true, the component will not be destroyed automatically when it is
   * disconnected from the document. This is useful when you want to move the
   * component to a different place on the page, or temporarily hide it. If this
   * is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-histogram-range-slider/#destroy) method when you are done to
   * prevent memory leaks.
   *
   * @default false
   */
  accessor autoDestroyDisabled: boolean;
  /**
   * 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/types/#SummaryStatisticsResult),
   * which is the result of the
   * [summaryStatistics](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/summaryStatistics/) function.
   *
   * When set, this value will render on the histogram with a line and an average symbol.
   *
   * @example
   * // sets result returned from a smart mapping method
   * // to the histogram
   * slider.average = response.statistics.avg;
   * @example slider.average = 34.5;
   */
  accessor average: number | null | undefined;
  /**
   * Function for styling bars representing histogram bins.
   * This can be used to color bins with the same color of features in the
   * view that fall into bins representing the same range of data.
   *
   * @example
   * slider.barCreatedFunction = function(index, element){
   *   const bin = slider.bins[index];
   *   element.addEventListener("focus", function(){
   *     layerView.filter = {
   *       where: `POPULATION >= ${bin.minValue} AND POPULATION < ${bin.maxValue}`
   *     };
   *   });
   *   element.addEventListener("blur", function(){
   *     layerView.filter = null;
   *   });
   * };
   */
  accessor barCreatedFunction: BarCreatedFunction | null | 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/) function.
   *
   * @example
   * // sets the bins of the histogram from the bins in the histogram() result
   * histogram.bins = histogramResult.bins;
   * @example
   * // 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: Array<HistogramBin> | null | undefined;
  /**
   * Function that fires each time a data line is created.
   * You can use this to style individual [dataLines](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#dataLines) on the data axis.
   *
   * @example
   * histogram.dataLineCreatedFunction = function (lineElement, labelElement) {
   *   lineElement.setAttribute("y2", "25%");
   *   lineElement.classList.add("line-style");
   * };
   */
  accessor dataLineCreatedFunction: DataLineCreatedFunction | null | undefined;
  /**
   * When set, renders lines on the histogram that indicate important or
   * meaningful values to the end user.
   *
   * @example
   * // 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
   * // 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(function(stddev){
   *   return {
   *     value: stddev
   *   };
   * });
   */
  accessor dataLines: Array<DataLineInfos> | null | undefined;
  /**
   * Sets the color of the histogram bars that are excluded based on the specified
   * [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType). For example, when a rangeType of `between` is used,
   * all bars **not** between the slider thumbs will be rendered with the color set here.
   *
   * To change the style of histogram bars representing included data based on the
   * [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType), use the [includedBarColor](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#includedBarColor) property.
   *
   * @default "#d7e5f0"
   * @see [includedBarColor](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#includedBarColor)
   * @see [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType)
   * @example slider.excludedBarColor = "black";
   */
  get excludedBarColor(): Color;
  set excludedBarColor(value: ColorLike);
  /**
   * Icon which represents the component.
   * Typically used when the component is controlled by another component (e.g. by the Expand component).
   *
   * @default "arrow-double-horizontal"
   * @since 4.27
   * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: IconName);
  /**
   * Sets the color of the histogram bars that are included in the specified
   * [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType). For example, when a rangeType of `between` is used,
   * all bars between the slider thumbs will be rendered with the color set here.
   *
   * To change the style of histogram bars representing excluded data based on the
   * [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType), use the [excludedBarColor](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#excludedBarColor) property.
   *
   * @default "#599dd4"
   * @see [excludedBarColor](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#excludedBarColor)
   * @see [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType)
   * @example slider.includedBarColor = "green";
   */
  get includedBarColor(): Color;
  set includedBarColor(value: ColorLike);
  /**
   * The component's default label.
   *
   * @since 4.11
   */
  accessor label: string;
  /**
   * A function used to format labels. Overrides the default label formatter.
   *
   * By default labels are formatted in the following way:
   *
   * - When the data range is less than `10` (`(max - min) < 10`), labels
   *   are rounded based on the value set in the [precision](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#precision) property.
   * - When the data range is larger than `10`, [HistogramRangeSliderViewModel#labels](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/HistogramRangeSliderViewModel/#labels) display with a precision of
   *   no more than two decimal places, though actual slider thumb values will maintain the
   *   precision specified in [precision](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#precision).
   *
   * Use this property to override the behavior defined above.
   *
   * @example
   * // For thumb values, rounds each label to whole numbers.
   * // Note the actual value of the thumb continues to be stored
   * // based on the indicated data `precision` despite this formatting
   * slider.labelFormatFunction = function(value, type) {
   *   return (type === "value") ? value.toFixed(0) : value;
   * }
   * @example
   * // Format thumb values as dates
   * slider.labelFormatFunction = function(value, type) {
   *   return new Date(value).toLocaleDateString();
   * }
   */
  accessor labelFormatFunction: LabelFormatFunction;
  /**
   * The maximum value or upper bound of the slider. If the largest
   * slider [value](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values) _in the constructor_ is greater than the `maxValue` set in
   * this property, then the `maxValue` will update to match the largest
   * slider [value](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values).
   *
   * @example slider.max = 150;
   */
  accessor max: number | null | undefined;
  /**
   * The minimum value or lower bound of the slider. If the smallest
   * slider [value](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values) _in the constructor_ is greater than the `minValue` set in
   * this property, then the `minValue` will update to match the smallest
   * slider [value](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values).
   *
   * @example slider.min = -150;
   */
  accessor min: number | null | undefined;
  /**
   * Defines how slider thumb values should be rounded. This number indicates the number
   * of decimal places slider thumb values should round to when they have been moved.
   *
   * This value also indicates the precision of thumb [HistogramRangeSliderViewModel#labels](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/HistogramRangeSliderViewModel/#labels) when the data range
   * ([max](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#max) - [min](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#min)) is less than `10`.
   *
   * When the data range is larger than `10`, [HistogramRangeSliderViewModel#labels](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/HistogramRangeSliderViewModel/#labels) display with a precision of
   * no more than two decimal places, though actual slider thumb values will maintain the
   * precision specified in this property.
   *
   * For example, given the default precision of `4`, and the following slider configuration,
   * The label of the thumb will display two decimal places, but the precision of the actual
   * thumb value will not be lost even when the user slides or moves the thumb.
   *
   * ```js
   * const slider = new HistogramRangeSliderViewModel({
   *   min: 20,
   *   max: 100,  // data range of 80
   *   values: [50.4331],
   *   // thumb label will display 50.43
   *   // thumb value will maintain precision, so
   *   // value will remain at 50.4331
   * });
   * ```
   *
   * If the user manually enters a value that has a higher precision than what's indicated by
   * this property, the precision of that thumb value will be maintained until the thumb
   * is moved by the user. At that point, the value will be rounded according to the indicated precision.
   *
   * Keep in mind this property rounds thumb [values](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values) and shouldn't be used exclusively
   * for formatting purposes. To format thumb `labels`, use the [labelFormatFunction](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#labelFormatFunction)
   * property.
   *
   * @default 4
   * @example histogramRangeSlider.precision = 7;
   */
  accessor precision: number;
  /**
   * Indicates how the histogram bins should be rendered as the user slides the thumbs. By default,
   * blue bars indicate data bins included in the range. Gray bars indicate data bins excluded from
   * the range. These colors can be customized with the [includedBarColor](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#includedBarColor) and
   * [excludedBarColor](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#includedBarColor) properties.
   *
   * This property also determines the SQL where clause generated in [generateWhereClause()](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#generateWhereClause)
   * for filtering purposes. The value set here determines the number of [values](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values)
   * allowed on the slider.
   *
   * See the table below for a description and requirements of all possible values. `value1` refers to
   * the value of the first thumb position. `value2` refers to the value of the final thumb position, if applicable.
   *
   * Possible Value | Number of [values](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values) | [Where clause](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#generateWhereClause)
   * ---------------|----------------------------|----------------------
   * equal | 1 | `${field} = ${value1}`
   * not-equal | 1 | `${field} <> ${value1}`
   * less-than | 1 | `${field} < ${value1}`
   * greater-than | 1 | `${field} > ${value1}`
   * at-most | 1 | `${field} <= ${value1}`
   * at-least | 1 | `${field} >= ${value1}`
   * between | 2 | `${field} BETWEEN ${value1} AND ${value2}`
   * not-between | 2 | `${field} NOT BETWEEN ${value1} AND ${value2}`
   *
   * @see [values](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#values)
   * @see [generateWhereClause()](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#generateWhereClause)
   * @example
   * // renders the histogram so that all bins between
   * // the two handles are shaded with a blue color
   * slider.rangeType = "between";
   *
   * // filters the layer view based on the configuration
   * // of the slider
   * layerView.filter = {
   *   where: slider.generateWhereClause("POPULATION")
   * }
   */
  accessor rangeType: RangeType;
  /**
   * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
   *
   * @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
   */
  accessor referenceElement: ArcgisReferenceElement | string | undefined;
  /**
   * Indicates the standard deviation of the dataset.
   * When set, computed [dataLines](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#dataLines) will render on the histogram
   * at the location of the given standard deviation
   * above and below the `average`.
   *
   * @example
   * // stddev returned from summaryStatistics
   * slider.standardDeviation = stats.stddev;
   */
  accessor standardDeviation: number | null | undefined;
  /**
   * Indicates the number of standard deviation lines to render on the histogram
   * from the [average].
   *
   * @default 1
   * @example slider.standardDeviationCount = 2;
   */
  accessor standardDeviationCount: number;
  /** The current state of the component. */
  get state(): SliderViewModelState;
  /**
   * An array of either one or two numbers representing thumb positions on the slider.
   * The number of values that should be indicated here depends on the associated [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType).
   *
   * @see [rangeType](https://developers.arcgis.com/javascript/latest/references/core/widgets/HistogramRangeSlider/#rangeType)
   * @example
   * const slider = new HistogramRangeSlider({
   *   min: 20,
   *   max: 100,  // data range of 80
   *   values: [50.4331],
   *   rangeType: "at-least"
   *   container: "sliderDiv"
   * });
   */
  accessor values: Array<number> | null | undefined;
  /** Permanently destroy the component. */
  destroy(): Promise<void>;
  /**
   * Generates a SQL where clause based on a given field and the slider's
   * rangeType
   *
   * @param field
   */
  generateWhereClause(field: string): Promise<string | null | undefined>;
  "@setterTypes": {
    excludedBarColor?: ColorLike;
    icon?: IconName;
    includedBarColor?: ColorLike;
  };
  /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
  readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "state"; }>;
  /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
  readonly "@eventTypes": {
    arcgisPropertyChange: ArcgisHistogramRangeSlider["arcgisPropertyChange"]["detail"];
    arcgisReady: ArcgisHistogramRangeSlider["arcgisReady"]["detail"];
  };
}