@arcgis/charts-components 5.2.0-next.93 → 5.2.0-next.95

package/dist/components/arcgis-chart/customElement.d.ts

@@ -5,7 +5,7 @@ import type SelectionManager from "@arcgis/core/views/SelectionManager.js";
 import type FeatureLayerView from "@arcgis/core/views/layers/FeatureLayerView.js";
 import type { DOMContainerAria } from "@arcgis/core/views/DOMContainer.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
-import type { AxisLabelFormatCallback, ChartOptions, GaugeInnerLabelFormatCallback, GuideTooltipFormatCallback, PieChartLegendValueLabelFormatCallback, PreRenderCallback } from "../../chart-rendering/common/interfaces.js";
+import type { AxisLabelFormatCallback, BarAndLineDataLabelFormatCallback, GaugeInnerLabelFormatCallback, GuideTooltipFormatCallback, HistogramLabelFormatCallback, PieChartLabelFormatCallback, PieChartLegendValueLabelFormatCallback, PreRenderCallback, ScatterplotLabelFormatCallback, TooltipFormatters } from "../../chart-rendering/common/interfaces.js";
 import type { ChartLayerInput, CSVOptions } from "../../interfaces.js";
 import type { ChartModel } from "../../model/chart-model/chart-model.js";
 import type { WebChartTypes, WebChartLegendPositions } from "../../spec/chart-object-literals.js";
@@ -772,7 +772,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * **Note**: Not applicable to gauges and radar charts.
    */
-  accessor dataLabelFormatter: ChartOptions["dataLabelFormatter"] | undefined;
+  accessor dataLabelFormatter: BarAndLineDataLabelFormatCallback | HistogramLabelFormatCallback | PieChartLabelFormatCallback | ScatterplotLabelFormatCallback | undefined;
   /**
    * Disables all interactions on the chart.
    *
@@ -785,7 +785,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * **Note**: Only applicable to multi-series charts.
    *
-   * @deprecated since 5.1. Use [togglingLegendItemsDisabled](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#togglingLegendItemsDisabled) instead.
+   * @deprecated since 5.1. Use [legendInteractionsDisabled](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#legendInteractionsDisabled) instead.
    * @default false
    */
   accessor disableTogglingLegendItems: boolean;
@@ -1011,6 +1011,15 @@ export abstract class ArcgisChart extends LitElement {
    * @default "refresh"
    */
   accessor layerRendererChangePolicy: LayerRendererChangePolicy;
+  /**
+   * When `true`, disables the toggling of series or slices from the legend items. Clicking on the legend items will not hide or show the corresponding elements on the chart.
+   *
+   * **Note**: Only applicable to charts with multiple series and while the legend is displayed.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor legendInteractionsDisabled: boolean | undefined;
   /**
    * Sets the legend's position on the chart.
    *
@@ -1747,6 +1756,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * **Note**: Only applicable to charts with multiple series and while the legend is displayed.
    *
+   * @deprecated since 5.2. Use [legendInteractionsDisabled](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#legendInteractionsDisabled) instead.
    * @default false
    */
   accessor togglingLegendItemsDisabled: boolean | undefined;
@@ -1768,7 +1778,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * **Note**: Not applicable to gauges.
    */
-  accessor tooltipFormatter: ChartOptions["tooltipFormatter"] | undefined;
+  accessor tooltipFormatter: TooltipFormatters | undefined;
   /**
    * Whether to automatically add the missing series to cover the split-by values not referenced in the configuration.
    * - This property only applies to plain chart configuration object that's constructed following the [WebChart](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChart) specification.
@@ -1846,6 +1856,7 @@ export abstract class ArcgisChart extends LitElement {
    * - The "No data available to display" warning message will be displayed in the chart container.
    *
    * @default false
+   * @since 5.2
    */
   accessor zeroCountAsValid: boolean;
   /**
@@ -1982,51 +1993,174 @@ export abstract class ArcgisChart extends LitElement {
    * **Note**: Not applicable to gauges.
    */
   switchSelection(): Promise<void>;
-  /** Event triggered once the chart axes min/max values are computed. */
+  /**
+   * Emitted when the chart's axes minimum or maximum values are computed.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisAxesMinMaxChange", (event) => {
+   *   const { bounds, model } = event.detail;
+   *   // Handle the new bounds and model
+   * });
+   * ```
+   */
   readonly arcgisAxesMinMaxChange: import("@arcgis/lumina").TargetedEvent<this, AxesMinMaxChangePayload>;
-  /** Event triggered when an error is detected with the data set. */
+  /**
+   * Emitted when the chart's data is incompatible with its model. Bad data such as empty dataset, axis logarithmic scale being incompatible with the data will trigger this event.
+   * The event details contain information about the error.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisBadDataWarningRaise", (event) => {
+   *    const { keyword, header, message, params } = event.detail;
+   *    // Handle the bad data warning
+   * });
+   * ```
+   */
   readonly arcgisBadDataWarningRaise: import("@arcgis/lumina").TargetedEvent<this, DataWarningObject>;
-  /** Event triggered when the chart is not found for the given [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) property. */
+  /**
+   * Emitted when the chart is not found for the given [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) property with a valid [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId).
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisChartNotFoundWarning", (event) => {
+   *    const warningMessage = event.detail;
+   *    // Handle the warning message
+   * });
+   * ```
+   */
   readonly arcgisChartNotFoundWarning: import("@arcgis/lumina").TargetedEvent<this, string>;
-  /** Event triggered when the chart config is changed. */
+  /**
+   * Emitted when the chart configuration is changed.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisConfigChange", (event) => {
+   *    const { newConfig, oldConfig, functionCalled } = event.detail;
+   *    // Handle the configuration change
+   * });
+   * ```
+   */
   readonly arcgisConfigChange: import("@arcgis/lumina").TargetedEvent<this, {
       newConfig: WebChart | undefined;
       oldConfig: WebChart | undefined;
       functionCalled: string | undefined;
   }>;
   /**
-   * Event triggered once the chart data has been fetched but not yet fully processed.
-   *
-   * For instance it can be useful to see all the slices before they get grouped into an 'other' slice during the post-processing step.
+   * Emitted once the chart data has been fetched but not yet fully processed. This event can be used to see all the slices before they get grouped into the 'other' slice during the post-processing step for pie charts.
+   * The event details contain the pie chart's data with its ungrouped slices.
    *
    * **Note**: Applicable to pie charts only.
    */
   readonly arcgisDataFetchComplete: import("@arcgis/lumina").TargetedEvent<this, WebChartDataTypes>;
-  /** Event triggered once the chart data has been processed. */
+  /**
+   * Emitted once the chart data is updated and any subsequent updates to the chart's data.
+   * The event details contain the chart's data.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisDataProcessComplete", (event) => {
+   *    const { chartData, model } = event.detail;
+   *   // Handle the processed chart data
+   * });
+   * ```
+   */
   readonly arcgisDataProcessComplete: import("@arcgis/lumina").TargetedEvent<this, DataProcessCompletePayload>;
-  /** Event triggered when an error occurred while fetching of processing the data for the chart. */
+  /**
+   * Emitted when an error occurred while fetching or processing the data for the chart.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisDataProcessError", () => {
+   *    // Handle the data process error
+   * });
+   * ```
+   */
   readonly arcgisDataProcessError: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
-   * Event triggered when an invalid configuration is detected.
+   * Emitted when an invalid configuration is detected.
    *
    * @deprecated since 5.1. Won't be replaced.
    */
   readonly arcgisInvalidConfigWarningRaise: import("@arcgis/lumina").TargetedEvent<this, DataWarningObject>;
-  /** Event triggered once a legend item visibility has been changed. */
+  /**
+   * Emitted once a legend item visibility has been changed.
+   * The event details contain the toggled item's visibility and related information (series or slice id).
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisLegendItemVisibilityChange", (event) => {
+   *    const { legendItemVisibility, model } = event.detail;
+   *    // Handle the legend item visibility change
+   * });
+   * ```
+   */
   readonly arcgisLegendItemVisibilityChange: import("@arcgis/lumina").TargetedEvent<this, LegendItemVisibilityChangePayload>;
-  /** Event triggered when a no-render prop is changed. */
+  /** Emitted when a no-render property ([rotated](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#rotated), [legendPosition](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#legendPosition), [legendVisibility](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#legendVisibility), [view](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#view) and [featureIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#featureIndex)) is changed. */
   readonly arcgisNoRenderPropChange: import("@arcgis/lumina").TargetedEvent<this, NoRenderPropChangePayload>;
-  /** Event triggered once the chart rendering is complete. */
+  /**
+   * Emitted once the chart is created and the rendering is complete. This event also emits with any subsequent chart updates, including when the chart is refreshed or when the configuration is changed.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisRenderingComplete", () => {
+   *  // Handle the rendering complete event
+   * });
+   */
   readonly arcgisRenderingComplete: import("@arcgis/lumina").TargetedEvent<this, void>;
-  /** Event triggered when an error occurred that prevents the chart from being created or updated. */
+  /**
+   * Emitted when an error occurred that prevents the chart from being created or updated.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisRuntimeError", () => {
+   *  // Handle the runtime error
+   * });
+   */
   readonly arcgisRuntimeError: import("@arcgis/lumina").TargetedEvent<this, void>;
-  /** Event triggered when a selection is applied to the chart. */
+  /**
+   * Emitted when a selection is applied to the chart.
+   * The [`selectionData`](/references/charts-components/utils/misc/interfaces/#SelectionData) event detail contains various information about the selection, including the selected OIDs.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisSelectionComplete", (event) => {
+   *    const { selectionData, model } = event.detail;
+   *    // Handle the selection complete event
+   * });
+   * ```
+   */
   readonly arcgisSelectionComplete: import("@arcgis/lumina").TargetedEvent<this, SelectionCompletePayload>;
-  /** Event triggered once the chart series color have been assigned. */
+  /** Emitted once one of the chart's series color has been assigned or changed. */
   readonly arcgisSeriesColorChange: import("@arcgis/lumina").TargetedEvent<this, SeriesColorChangePayload>;
-  /** Event carrying the series id as they have been sorted following the `orderOptions` instructions. */
+  /**
+   * Emitted when the chart is created and at every update to confirm the order of the series on the chart.
+   * The event details contain the modified series' indexes and names.
+   *
+   * @example
+   * ```ts
+   * const chartElement = document.querySelector("arcgis-chart");
+   * chartElement.addEventListener("arcgisSeriesOrder", (event) => {
+   *    // Handle the series order change
+   * });
+   * ```
+   */
   readonly arcgisSeriesOrder: import("@arcgis/lumina").TargetedEvent<this, string[]>;
-  /** Event triggered once the chart is updated. */
+  /**
+   * Emitted once the chart is updated.
+   *
+   * @deprecated since 5.2. Use [@arcgisRenderingComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisRenderingComplete) instead.
+   */
   readonly arcgisUpdateComplete: import("@arcgis/lumina").TargetedEvent<this, ValidationStatus>;
   readonly "@eventTypes": {
     arcgisAxesMinMaxChange: ArcgisChart["arcgisAxesMinMaxChange"]["detail"];