@arcgis/core/smartMapping/labels/bins.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * This object contains a helper method for generating default labels to be set on
 * a layer's [binning configuration](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/#labelingInfo).
 * The default label is based on the [FeatureReductionBinning.renderer](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/#renderer). In most cases the default label configuration will
 * be the total number of features in the bin. This value will be rounded and formatted (e.g. instead of `2385`, the
 * bin label will display `2.4k`).
 *
 * This includes secondary labeling schemes you can experiment with using on your bins.
 * This module only applies to layers with a point geometry type.
 *
 * @since 4.27
 * @see [FeatureReductionBinning.labelingInfo](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/#labelingInfo)
 */
import type LabelClass from "../../layers/support/LabelClass.js";
import type { RendererUnion } from "../../renderers/types.js";
import type { BinningSupportedLayer } from "../types.js";

/**
 * Generates default [FeatureReductionBinning.labelingInfo](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/#labelingInfo)
 * schemes to be set on a FeatureLayer's [FeatureLayer.featureReduction](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#featureReduction) property.
 * Returns one or more suggested LabelClasses
 * for [FeatureReductionBinning](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/) based on its renderer.
 *
 * @param parameters - The function parameters.
 * @returns Returns an object containing suggested primary
 *   and secondary labeling schemes to be set on the layer's `featureReduction` property.
 * @example
 * // Sets a suggested label scheme for the binning config based on its renderer
 * const { primaryScheme } = await binLabelCreator.getLabelSchemes({
 *   layer: featureLayer
 * });
 *
 * const featureReduction = featureLayer.featureReduction.clone();
 * featureReduction.labelingInfo = primaryScheme.labelingInfo;
 * featureLayer.featureReduction = featureReduction;
 */
export function getLabelSchemes(parameters: SchemeParameters): Promise<Schemes | null | undefined>;

export interface SchemeParameters {
  /**
   * The name of the [AggregateField.name](https://developers.arcgis.com/javascript/latest/references/core/layers/support/AggregateField/#name)
   *   to use in the primary label scheme. If not specified, then the label will be based on the aggregate count field.
   */
  field?: string;
  /** The renderer to set on `layer.featureReduction.renderer` when binning is enabled. */
  renderer?: RendererUnion;
  /** The point layer that has or will have binning enabled. */
  layer: BinningSupportedLayer;
}

/** Contains suggested labelingInfo to be set on the layer's [featureReduction.labelingInfo](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/#labelingInfo). */
export interface Scheme {
  /**
   * The name of the generated binning labeling scheme.
   *   This can be used in the UI of web map authoring apps.
   */
  name: string;
  /**
   * An array of
   *   LabelClass objects to set on the layer's [featureReduction.labelingInfo](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureReductionBinning/#labelingInfo)
   *   property.
   */
  labelingInfo: LabelClass[];
  /**
   * The name of the aggregate field used in the labeling scheme.
   *   This can be used in the UI of web map authoring apps.
   */
  fieldName: string;
}

/** The return object of the [getLabelSchemes()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/labels/bins/#getLabelSchemes) method. */
export interface Schemes {
  /** Includes the primary labeling scheme suggested for the input layer's bins. */
  primaryScheme: Scheme;
  /** Includes secondary labeling schemes suggested for the input layer's bins. */
  secondarySchemes: Scheme[];
}