@arcgis/charts-components 5.2.0-next.12 → 5.2.0-next.121

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

@@ -2,11 +2,10 @@
 import type MapView from "@arcgis/core/views/MapView.js";
 import type SceneView from "@arcgis/core/views/SceneView.js";
 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 { CSVOptions, SupportedLayer, SupportedRasterLayer } from "../../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";
 import type { WebChartDataTypes } from "../../spec/data-source.js";
@@ -22,125 +21,35 @@ import type { ErrorPolicy, LayerFieldsChangePolicy, LayerFilterChangePolicy, Lay
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
 /**
- * The Chart component renders a chart based on the provided model. Get started by reading the [introduction to charts](https://developers.arcgis.com/javascript/latest/charts-components-intro/) page.
+ * The ArcGIS Chart component renders a chart by setting a [model](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#model) object that defines the chart's configuration and data.
  *
- * Supported chart types include bar charts, box plots, line charts, combo bar-line charts, gauges, heat charts, histograms, pie charts, scatterplots, and radar charts.
+ * You can render a chart either by:
+ * - Setting [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId) and [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) to load a saved chart from a layer item.
+ * - Create a new chart by using the [`createModel()`](/references/charts-components/model/shared/setup-utils/#createModel) function to create a chart model and set it to the [model](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#model) property.
  *
- * @slot [action-bar] - Slot for adding a `charts-action-bar` component or `calcite-action-bar`.
- * @see [Introduction to charts](https://developers.arcgis.com/javascript/latest/charts-components-intro/)
- * @see
- * [Tutorial: Display a chart](https://developers.arcgis.com/javascript/latest/tutorials/display-a-chart/)
+ * > [!IMPORTANT]
+ * >
+ * > See the [Introduction to charts](https://developers.arcgis.com/javascript/latest/charts-components-intro/) guide for detailed examples on how to render a chart using the above patterns.
  *
- * **Note**: When the chart is getting rendered while its container is not yet fully sized, a console error about the chart's attribute height may appear. This is a known issue and should not affect the functionality of the chart.
+ * There are 10 supported chart types, each with its own model properties and methods. Refer to the [chart types documentation](https://developers.arcgis.com/javascript/latest/charts/chart-types/) for more information on each chart type.
+ *
+ * ##### See also:
+ * - [Tutorial: Display a chart](https://developers.arcgis.com/javascript/latest/tutorials/display-a-chart/)
+ * - [Tutorial: Chart and map interactions](https://developers.arcgis.com/javascript/latest/tutorials/chart-and-map-interactions/)
+ *
+ * > [!WARNING]
+ * > When the chart is rendering while its container is not yet fully sized, a console error about the chart's attribute height may appear. This is a known issue and should not affect the functionality of the chart.
+ *
+ * @slot [action-bar] - Slot for the [arcgis-charts-action-bar](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-charts-action-bar/) component or [calcite-action-bar](https://developers.arcgis.com/calcite-design-system/components/action-bar/) component.
  * @since 4.32
  */
 export abstract class ArcgisChart extends LitElement {
-  /** @internal */
-  protected _messages: Partial<{ chartNotFoundWarning: string; }> & T9nMeta<{ chartNotFoundWarning: string; }>;
-  /**
-   * Specifies the user action behavior for the chart.
-   *
-   * - `monoSelection`: Select a single data point or series, new selection replaces the previous one.
-   * - `multiSelection`: Select multiple data points or series, new selection adds to the previous one.
-   * - `multiSelectionWithCtrlKey`: Select multiple data points or series while holding the Ctrl key (Cmd on Mac). When the key is held, each new selection is added; otherwise, the selection is replaced.
-   * - `none`: No action is performed on user interaction.
-   * - `zoom`: Zoom into a specific area of the chart.
-   *
-   * **Note**: Not applicable to gauges.
-   */
-  accessor actionMode: ActionModes | undefined;
-  /**
-   * Whether to allow the object id to be used as a statistic other than `Count`.
-   *
-   * @default false
-   */
-  accessor allowUsingObjectIdStat: boolean;
-  /**
-   * Enable animation on the chart.
-   *
-   * @default false
-   */
-  accessor animationEnabled: boolean | undefined;
-  /**
-   * The ARIA attributes for the chart. Provides accessibility information to assistive technologies such as screen readers. Supports the following properties: [\`label\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), [\`description\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), [\`describedByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaDescribedByElements), and [\`labelledByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaLabelledByElements).
-   *
-   * @since 5.0
-   */
-  accessor aria: DOMContainerAria | undefined;
-  /**
-   * 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/charts-components/components/arcgis-chart/#destroy)  method when you are done to prevent memory leaks.
-   *
-   * @default false
-   * @since 5.0
-   */
-  accessor autoDestroyDisabled: boolean;
-  /**
-   * Auto disposes the chart when a new one is created in the same container.
-   *
-   * @deprecated since 5.0. Use [autoDestroyDisabled](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#autoDestroyDisabled) instead.
-   * @default false
-   */
-  accessor autoDisposeChart: boolean;
-  /**
-   * When `true`, the data label text color is automatically adjusted for readability based on its background.
-   * If the label is dark and appears over a dark series area, the text color is switched to either the chart background color or white.
-   *
-   * **Note**: Applicable to heat charts only.
-   *
-   * @default false
-   */
-  accessor autoInverseDataLabelTextColor: boolean;
-  /**
-   * Allows picking the Calcite CSS variables to use when applying a Calcite theme.
-   *
-   * By default the following variables are used:
-   * - background: `--calcite-color-foreground-1`
-   * - text: `--calcite-color-text-1`
-   * - line: `--calcite-color-border-1`
-   * - secondary line: `--calcite-color-text-3`
-   * - spinner: `--calcite-color-brand-hover`
-   *
-   * The charts colors are overridden by those associated to those CSS variables, but only if they have not been
-   * customized beforehand.
-   *
-   * @since 5.1
-   */
-  accessor calciteThemingCSSVariables: CalciteThemeCSSVariables;
-  /**
-   * The index of the chart to be rendered from the layer. Must be used in conjunction with the `layerItemId` or `layer` property.
-   *
-   * If a `layer` or `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
-   *
-   * If the `chartIndex` is out of bounds, the first chart in the layer will be rendered and a warning event will be emitted.
-   *
-   * @example
-   * ```html
-   * <arcgis-chart layer-item-id="8871626e970a4f3e9d6113ec63a92f2f" chart-index="2"></arcgis-chart>
-   * ```
-   */
-  accessor chartIndex: number | undefined;
-  /**
-   * Customize the maximum number of series allowed on the chart.
-   *
-   * The chart's behavior once that limit is reached can be adjusted through the `behaviorAfterLimit` nested property, to either reject the creation
-   * or update of the chart, or render the elements up to the given limits.
-   *
-   * **Note**: Not applicable to gauges.
-   */
-  accessor chartLimits: ChartElementLimit | undefined;
-  /**
-   * Lifecycle function executed after the data has been processed and before the chart renders.
-   * Can be used to alter the model from information extracted from the data.
-   *
-   * **Note**: Applicable to gauges and pie charts only.
-   */
-  accessor chartWillRender: PreRenderCallback | undefined;
   /**
    * Localized common strings.
    *
    * @internal
    */
-  protected commonStrings: {
+  protected _commonStrings: {
       utilsStrings: {
           chartType: {
               chart: string;
@@ -278,6 +187,10 @@ export abstract class ArcgisChart extends LitElement {
               twoTemporalSeriesLineCountCannotExceedLimit: string;
               threePlusTemporalSeriesLineCountCannotExceedLimit: string;
               lineSeriesCountCannotExceedLimit: string;
+              uniqueSeriesRadarCountCannotExceedLimit: string;
+              twoSeriesRadarCountCannotExceedLimit: string;
+              threePlusSeriesRadarCountCannotExceedLimit: string;
+              radarSeriesCountCannotExceedLimit: string;
               uniqueSeriesBoxCountCannotExceedLimit: string;
               twoSeriesBoxCountCannotExceedLimit: string;
               threePlusBoxLineCountCannotExceedLimit: string;
@@ -545,6 +458,10 @@ export abstract class ArcgisChart extends LitElement {
               twoTemporalSeriesLineCountCannotExceedLimit: string;
               threePlusTemporalSeriesLineCountCannotExceedLimit: string;
               lineSeriesCountCannotExceedLimit: string;
+              uniqueSeriesRadarCountCannotExceedLimit: string;
+              twoSeriesRadarCountCannotExceedLimit: string;
+              threePlusSeriesRadarCountCannotExceedLimit: string;
+              radarSeriesCountCannotExceedLimit: string;
               uniqueSeriesBoxCountCannotExceedLimit: string;
               twoSeriesBoxCountCannotExceedLimit: string;
               threePlusBoxLineCountCannotExceedLimit: string;
@@ -675,21 +592,158 @@ export abstract class ArcgisChart extends LitElement {
           "Invalid date": string;
       };
   }>;
+  /** @internal */
+  protected _messages: Partial<{ chartNotFoundWarning: string; }> & T9nMeta<{ chartNotFoundWarning: string; }>;
+  /**
+   * Specifies how user interactions on the chart are handled.
+   *
+   * - `monoSelection`: Select one data item at a time. Each new selection replaces the previous selection.
+   * - `multiSelection`: Select multiple data items. Each new selection is added to the existing selection.
+   * - `multiSelectionWithCtrlKey`: Select multiple data items only while holding Ctrl (or Cmd on macOS). Without the key, selection behaves like `monoSelection`.
+   * - `zoom`: Zoom into an area of the chart.
+   * - `none`: Disable interaction-driven selection and zoom actions.
+   *
+   * **Note**: Not applicable to gauges.
+   */
+  accessor actionMode: ActionModes | undefined;
+  /**
+   * When `true`, object ID can be used as a numeric field for aggregated charts (for example, `sum` of `objectId`).
+   *
+   * @default false
+   */
+  accessor allowUsingObjectIdStat: boolean;
+  /**
+   * When `true`, elements such as data items, axes, and legends will animate when the chart is first rendered or when the chart's configuration is updated.
+   *
+   * <video
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/animationEnabled.webm"
+   *   aria-label="animationEnabled"
+   *   width="720"
+   *   autoPlay
+   *   loop
+   *   muted
+   *   playsInline
+   * />
+   *
+   * @default false
+   * @since 5.1
+   */
+  accessor animationEnabled: boolean | undefined;
+  /**
+   * The ARIA attributes for the chart component. Provides accessibility information to assistive technologies such as screen readers. Supports the following properties: [\`label\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), [\`description\`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), [\`describedByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaDescribedByElements), and [\`labelledByElements\`](https://developer.mozilla.org/docs/Web/API/Element/ariaLabelledByElements).
+   *
+   * @example
+   * ```ts
+   * chartElement.aria = {
+   *  label: "Custom chart label",
+   *  description: "Custom chart description",
+   * };
+   * ```
+   * @see [ARIA attributes](https://developers.arcgis.com/javascript/latest/accessibility/#aria-attributes)
+   * @since 5.0
+   */
+  accessor aria: DOMContainerAria | undefined;
+  /**
+   * When `true`, the component is not destroyed automatically when it is disconnected from the document, which is useful when moving or temporarily hiding it.
+   *
+   * > [!CAUTION]
+   * >
+   * > Call the [destroy()](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#destroy) method when you are done to prevent memory leaks.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor autoDestroyDisabled: boolean;
+  /**
+   * Auto disposes the chart when a new one is created in the same container.
+   *
+   * @deprecated since 5.0. Use [autoDestroyDisabled](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#autoDestroyDisabled) instead.
+   * @default false
+   */
+  accessor autoDisposeChart: boolean;
+  /**
+   * When `true`, the data label text color is automatically adjusted for readability based on its background, switching to either the chart background color or white when the contrast is too low.
+   *
+   * | With `autoInverseDataLabelTextColor` | Without `autoInverseDataLabelTextColor` |
+   * | -------- | -------- |
+   * | ![autoInverseDataLabelTextColor true](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/autoInverseDataLabelTextColorTrue.avif) | ![autoInverseDataLabelTextColor false](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/autoInverseDataLabelTextColorFalse.avif) |
+   *
+   * **Note**: Applicable to heat charts only.
+   *
+   * @default false
+   * @since 4.34
+   */
+  accessor autoInverseDataLabelTextColor: boolean;
+  /**
+   * Specifies the Calcite CSS variables to use when applying a Calcite theme.
+   *
+   * By default the following variables are used:
+   * - background: `--calcite-color-foreground-1`
+   * - text: `--calcite-color-text-1`
+   * - line: `--calcite-color-border-1`
+   * - secondary line: `--calcite-color-text-3`
+   * - spinner: `--calcite-color-brand-hover`
+   *
+   * The chart colors are overridden by those associated to those CSS variables, but only if they have not been customized beforehand.
+   *
+   * @see [Charts theming with Calcite CSS variables](https://developers.arcgis.com/javascript/latest/charts/features-and-capabilities/styling-and-theming/#theming-with-css-variables)
+   * @see [Components theming with Calcite](https://developers.arcgis.com/javascript/latest/building-your-ui/#styling-and-theming-with-calcite)
+   * @since 5.1
+   */
+  accessor calciteThemingCSSVariables: CalciteThemeCSSVariables;
+  /**
+   * The index of the chart to be rendered from the layer. Must be used in conjunction with the `layerItemId` or `layer` property.
+   *
+   * If a `layer` or `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
+   *
+   * If the `chartIndex` is out of bounds, the first chart in the layer will be rendered and a warning event will be emitted.
+   *
+   * @example
+   * ```html
+   * <arcgis-chart layer-item-id="8871626e970a4f3e9d6113ec63a92f2f" chart-index="2"></arcgis-chart>
+   * ```
+   */
+  accessor chartIndex: number | undefined;
+  /**
+   * Customize the maximum number of data items allowed on the chart.
+   *
+   * The chart's behavior once that limit is reached can be adjusted through the `behaviorAfterLimit` nested property, to either reject the creation
+   * or update of the chart, or render the elements up to the given limits.
+   *
+   * **Note**: Not applicable to gauges.
+   *
+   * @example
+   * ```ts
+   * chartElement.chartLimits = {
+   *   behaviorAfterLimit: LimitBehavior.RenderUpToTheLimit,
+   *   serialChart: { categories: 15 }
+   * };
+   * ```
+   */
+  accessor chartLimits: ChartElementLimit | undefined;
+  /**
+   * Lifecycle function executed after the data has been processed and before the chart renders.
+   * Can be used to alter the model from information extracted from the data.
+   *
+   * **Note**: Applicable to gauges and pie charts only.
+   */
+  accessor chartWillRender: PreRenderCallback | undefined;
   /**
    * Whether to use features uniquely designed for a chart currently being configured by a user via the UI.
-   * When true, the slotted charts action bar will expose an Edit chart action, surfaces relevant error states,
-   * and can show a helpful in-container placeholder about the chart’s purpose.
+   * When `true` and if the [arcgis-charts-action-bar](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-charts-action-bar/) is slotted in the chart component,
+   * the action bar will expose an "Edit chart" action, surface relevant error states, and show a helpful in-container placeholder about the chart’s purpose.
    *
    * @default false
+   * @since 5.1
    */
   accessor configurationEnabled: boolean;
   /**
-   * Sets the cursor range when `actionMode` is set to `zoom`, `multiSelection` or `multiSelectionWithCtrlKey`.
+   * Defines how the cursor selection rectangle is constrained when [actionMode](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#actionMode) is `zoom`, `multiSelection`, or `multiSelectionWithCtrlKey`.
    *
-   * - `multi-axes`: Allows to draw a free rectangle.
-   * - `x-axis`: Allows to draw a rectangle bound to the x-axis.
-   * - `y-axis`: Allows to draw a rectangle bound to the y-axis.
-   * - `undefined`: Defaults to the preset behavior according to the chart type and action mode.
+   * - `multi-axes`: Allows drawing a free rectangle across both axes.
+   * - `x-axis`: Constrains the rectangle to the x-axis direction.
+   * - `y-axis`: Constrains the rectangle to the y-axis direction.
+   * - `undefined`: Uses the default behavior for the current chart type and action mode.
    *
    * **Note**: Not applicable to gauges.
    */
@@ -697,9 +751,24 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Callback function used to format the data labels. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Not applicable to gauges.
+   * @example
+   * ```ts
+   * // Render custom data labels with the stat value and percentage formatted to 2 decimal places.
+   * chartElement.dataLabelFormatter = (statValue, percent) => {
+   *   return `
+   *     <div>
+   *       Total listings: <strong>${statValue}</strong><br>
+   *       Percentage: <strong>${Number(percent).toFixed(2)}%</strong>
+   *     </div>
+   *   `;
+   * };
+   * ```
+   *
+   * ![dataLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/dataLabelFormatter.avif)
+   *
+   * **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.
    *
@@ -712,7 +781,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;
@@ -740,7 +809,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor enableResponsiveFeatures: boolean;
   /**
-   * Whether to display an error alert and hide the chart when it can't be created or updated.
+   * When set to `ignore`, the chart fails silently without displaying an error or hiding the chart.
+   * By default, it is set to `throw`, which displays an error alert and hides the chart when it can't be created or updated.
    *
    * @default "throw"
    */
@@ -761,7 +831,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor filterByExtent: boolean;
   /**
-   * When `true`, all chart elements are filtered based on the selection.
+   * When `true`, the chart uses the current selection as a data filter and renders only selected elements instead of rendering the full dataset with selection styling.
+   * Axis bounds, time binning intervals will be computed based on the selected elements only.
    *
    * **Note**: Not applicable to gauges or charts configured with imagery layers.
    *
@@ -769,7 +840,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor filterBySelection: boolean;
   /**
-   * When `true`, all chart elements are filtered based on the view extent.
+   * When `true`, chart queries are constrained to the current map view extent. The chart refreshes as the view extent changes, and the axis bounds or other derived values are recalculated from the view extent data.
    *
    * @default false
    */
@@ -777,12 +848,35 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Callback function used to format the gauge inner label. If the returned string contains HTML tags they will be interpreted as such.
    *
+   * @example
+   * ```ts
+   * // Render a centered custom gauge label with the value formatted to 2 decimal places.
+   * chartElement.gaugeInnerLabelFormatter = (value) => {
+   *   return `<div style="text-align: center;"><u>Custom gauge inner label: </u><br /><b>${Number(value).toFixed(2)}</b></div>`;
+   * };
+   * ```
+   *
+   * ![gaugeInnerLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/gaugeInnerLabelFormatter.avif)
+   *
    * **Note**: Applicable to gauges only.
    */
   accessor gaugeInnerLabelFormatter: GaugeInnerLabelFormatCallback | undefined;
   /**
    * Callback function used to format the axes guides tooltip. If the returned string contains HTML tags they will be interpreted as such.
    *
+   * @example
+   * ```ts
+   * // Render a custom tooltip with the guide's start and end values.
+   * chartElement.guideTooltipFormatter = (props) => {
+   *   return `
+   *     <u>Custom guide tooltip</u><br />
+   *     Range: <b>${props.start} - ${props.end}</b>
+   *   `;
+   * };
+   * ```
+   *
+   * ![guideTooltipFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/guideTooltipFormatter.avif)
+   *
    * **Note**: Not applicable to pie charts.
    */
   accessor guideTooltipFormatter: GuideTooltipFormatCallback | undefined;
@@ -804,27 +898,28 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor hideLicenseWatermark: boolean | undefined;
   /**
-   * Hides the loader animation (curtain and spinner), showed by default at every update.
+   * When `true`, the loader animation is hidden when the chart is being created or updated. By default, it is shown at chart creation and each update (if it takes more than 300ms).
+   * | When `hideLoaderAnimation` is `true` | When `hideLoaderAnimation` is `false` |
+   * | -------- | -------- |
+   * | <video src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/hideLoaderAnimationTrue.webm" aria-label="animationEnabled" width="720" autoPlay loop muted playsInline/> | <video src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/hideLoaderAnimationFalse.webm" aria-label="animationEnabled" width="720" autoPlay loop muted playsInline/>
    *
    * @default false
    */
   accessor hideLoaderAnimation: boolean;
   /**
-   * Whether to display or hide all UI messages (e.g. no data warnings, or when the logarithmic scale can't be applied to an axis when the data contains values <= 0).
+   * When set to `true`, UI messages are hidden. These messages can be no data warnings, any placeholder messages set or invalid chart configuration.
+   * By default, its value is `false`, which displays the messages on the chart.
    *
    * @default false
    * @since 5.1
    */
   accessor hideUIMessages: boolean;
   /**
-   * Whether to keep missing categories from a count aggregation as gaps in the chart's data.
+   * When `true`, missing categories from a `Count` aggregation are kept as gaps in the chart's data.
    *
-   * When data is retrieved from the server, the server excludes all features having a count of 0 from the response; hence resulting in missing entries on the charts.
+   * When data is retrieved from the server, features with a count of 0 are excluded from the response, resulting in missing chart entries.
    *
-   * When this property is set to `true`, the dataset will keep these gaps instead of filling them with 0s.
-   *
-   * When left to `false`,  the chart's dataItems associated with empty (no value) categories (from only a `Count` aggregation)
-   * will be populated with 0s.
+   * By default, the chart's [WebChartGenericDataItem](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/data-source/#WebChartGenericDataItem-dataItems) associated with empty categories (from only a `Count` aggregation) are populated with 0s.
    *
    * @default false
    * @since 5.1
@@ -846,27 +941,27 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor ignoreSmoothRenderingLimit: boolean;
   /**
-   * This property will be effective when the component's `view` is provided or when the `layer` is set to a FeatureLayerView.
+   * When `true`, it signals the queries to ignore the view's extent, whether an additional geometry filter is provided or not.
    *
-   * By default the queries made by the chart will consider the view's extent as the unique geometry filter applicable. This implies ignoring any
-   * geometry passed through the model (`component.model.dataFilters`) or the runtime filters (`component.runtimeDataFilters`).
+   * This property will be effective when the component's [view](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#view) property is provided or when the [layer](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layer) property is set to [ChartLayerView](https://developers.arcgis.com/javascript/latest/references/charts-components/interfaces/#ChartLayerView).
    *
-   * Setting this property to `false` signals the queries to ignore the view's extent, whether an additional geometry filter is provided or not.
+   * By default the queries made by the chart will consider the view's extent as the unique geometry filter applicable. This implies ignoring any
+   * geometry filters passed through the [model](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#model) or the [runtimeDataFilters](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#runtimeDataFilters) properties.
    *
    * @default false
    */
   accessor ignoreViewExtent: boolean;
   /**
-   * Disables all interactions on the chart.
+   * When `true`, all interactions such as zooming and selection are disabled on the chart. The chart will be rendered in a read-only state.
    *
    * @default false
    */
   accessor interactionsDisabled: boolean;
   /**
    * Used to perform queries.
-   * If the layer is a `FeatureLayerView` or if the layer and the `view` property are both provided, the queries will be executed client-side.
+   * If the layer is a `ChartLayerView` or if the layer and the `view` property are both provided, the queries will be executed client-side.
    */
-  accessor layer: FeatureLayerView | SupportedLayer | SupportedRasterLayer | undefined;
+  accessor layer: ChartLayerInput | undefined;
   /**
    * Allows the chart to update automatically when the layer's `fields` property changes.
    *
@@ -882,11 +977,12 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor layerFilterChangePolicy: LayerFilterChangePolicy;
   /**
-   * Layer item ID associated with the chart to be rendered. Can be used in conjunction with the `chartIndex` property.
+   * Layer item ID associated with the chart to be rendered. Can be used in conjunction with the `chartIndex` property. If `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
    *
-   * If `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
+   * The layer item ID can be found in the URL of the layer's item page on ArcGIS Online or Enterprise.
+   * For example, in the URL `https://www.arcgis.com/home/item.html?id=8871626e970a4f3e9d6113ec63a92f2f`, the layer item ID is `8871626e970a4f3e9d6113ec63a92f2f`.
    *
-   * Supported layers include: `FeatureLayer`, `SubtypeSublayer`, `ImageryLayer`, `ImageryTileLayer` and `WCSLayer`.
+   * Supported layer types include: [`FeatureLayer`](/references/core/layers/FeatureLayer), [`SubtypeSublayer`](/references/core/layers/support/SubtypeSublayer), [`ImageryLayer`](/references/core/layers/ImageryLayer), [`ImageryTileLayer`](/references/core/layers/ImageryTileLayer) and [`WCSLayer`](/references/core/layers/WCSLayer).
    *
    * @example
    * ```html
@@ -903,6 +999,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.
    *
@@ -912,8 +1017,24 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor legendPosition: WebChartLegendPositions | undefined;
   /**
-   * A callback function used to format the legend value labels. If the returned string contains HTML tags they will be interpreted as such.
-   * If provided, the formatter will be used if at least [displayNumericValue](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChartPieChartLegend-displayNumericValue) or [displayPercentage](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChartPieChartLegend-displayPercentage) is `true`.
+   * When the pie chart label contains either a numeric value or a percentage (which can be set through the
+   * [displayNumericValueOnLegendItems](https://developers.arcgis.com/javascript/latest/references/charts-components/model/pie-chart-model/pie-chart-model/#displayNumericValueOnLegendItems) and
+   * [displayPercentageOnLegendItems](https://developers.arcgis.com/javascript/latest/references/charts-components/model/pie-chart-model/pie-chart-model/#displayPercentageOnLegendItems) properties from the pie chart model), this property
+   * can be used to format the numeric value and/or percentage. If the returned string contains HTML tags they will be interpreted as such.
+   *
+   * @example
+   * ```ts
+   * // Set the pie chart model to display both numeric value and percentage.
+   * pieChartModel.displayNumericValueOnLegendItems = true;
+   * pieChartModel.displayPercentageOnLegendItems = true;
+   *
+   * // Render the numeric value and percentage in bold and italic respectively, with 2 decimal places.
+   * chartElement.legendValueLabelFormatter = (value, percentage) => {
+   *   return `<strong><u>${Number(value).toFixed(2)}</u></strong> (<em>${Number(percentage).toFixed(2)}%</em>)`;
+   * };
+   * ```
+   *
+   * ![legendValueLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/legendValueLabelFormatter.avif)
    *
    * **Note**: Applicable to pie charts only.
    */
@@ -938,8 +1059,30 @@ export abstract class ArcgisChart extends LitElement {
    * ```
    */
   accessor loaderColors: LoaderColors | undefined;
-  /** Custom message overrides for the chart's strings. */
-  accessor messageOverrides: { chartNotFoundWarning?: string | undefined; } & {
+  /**
+   * Custom messages for translated strings on the chart. If the returned string contains HTML tags they will be interpreted as such.
+   *
+   * The customizable messages can be found thru the [`CommonStringsIdentity`](/references/charts-components/utils/localization/interfaces/#CommonStringsIdentity) variable.
+   *
+   * @example
+   * ```ts
+   * // User sets the xAxisField to a field that doesn't exist in the dataset.
+   * barChartModel.xAxisField = "wrong_field_name";
+   *
+   * // Overrides the default message when there's a query error instead of displaying the default "Failure to read input data." message.
+   * chartElement.messageOverrides = {
+   *    errorStrings: {
+   *      errors: {
+   *        queryError:
+   *          "<b><u>The input data provided is invalid, please ensure the xAxisField is correctly specified.</u></b>"
+   *      },
+   *    },
+   *  };
+   * ```
+   *
+   * ![messageOverrides](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/messageOverrides.avif)
+   */
+  accessor messageOverrides: {
       utilsStrings?: {
           chartType?: {
               chart?: string | undefined;
@@ -1077,6 +1220,10 @@ export abstract class ArcgisChart extends LitElement {
               twoTemporalSeriesLineCountCannotExceedLimit?: string | undefined;
               threePlusTemporalSeriesLineCountCannotExceedLimit?: string | undefined;
               lineSeriesCountCannotExceedLimit?: string | undefined;
+              uniqueSeriesRadarCountCannotExceedLimit?: string | undefined;
+              twoSeriesRadarCountCannotExceedLimit?: string | undefined;
+              threePlusSeriesRadarCountCannotExceedLimit?: string | undefined;
+              radarSeriesCountCannotExceedLimit?: string | undefined;
               uniqueSeriesBoxCountCannotExceedLimit?: string | undefined;
               twoSeriesBoxCountCannotExceedLimit?: string | undefined;
               threePlusBoxLineCountCannotExceedLimit?: string | undefined;
@@ -1206,25 +1353,42 @@ export abstract class ArcgisChart extends LitElement {
           "Unable to load file: %1"?: string | undefined;
           "Invalid date"?: string | undefined;
       } | undefined;
-  };
+  } & { chartNotFoundWarning?: string | undefined; };
   /**
    * Provides an API to interact with the chart's configuration.
    *
-   * **Note**: This property has a union type of `ChartModel | WebChart` meaning a raw chart configuration object can be passed to it instead, however it is recommended to use the `ChartModel` instance whenever possible.
+   * `model` accepts either a [ChartModel](https://developers.arcgis.com/javascript/latest/references/charts-components/model/chart-model/chart-model/) instance or a [WebChart](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChart) object.
+   * - `ChartModel`: A chart model class instance, which can be created using the [createModel](https://developers.arcgis.com/javascript/latest/references/charts-components/model/shared/setup-utils/#createModel) function.
+   *   - This is the recommended approach as it ensures the chart configuration is valid and compatible with the component.
+   * - `WebChart`: A plain chart configuration object that follows the [WebChart](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChart) specification.
+   *
+   * @see [Create a new chart with charts model](https://developers.arcgis.com/javascript/latest/charts/#create-a-new-chart-with-charts-model)
    */
   accessor model: ChartModel | WebChart | undefined;
   /**
-   * Whether to consider a `null` statistic as valid. If set to `false` and the data has only null values, the chart's dataset will be considered empty:
-   * - The corresponding warning event will be sent
-   * - The "no data" message will be displayed (unless `hideUIMessages` is set to `true` or `showUIMessages` is set to `false`)
+   * When `true`, null values are considered as valid.
+   *
+   * By default, when the data contains only null values, the chart dataset is considered empty:
+   * - The [@arcgisBadDataWarningRaise](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisBadDataWarningRaise) event will be sent.
+   * - The "No data available to display" warning message will be displayed in the chart container.
    *
    * @default false
    */
   accessor nullAsValid: boolean;
-  /** A placeholder string to provides a brief hint to the user indicating needed information for creating a chart. */
+  /**
+   * Placeholder text displayed in the chart container when no chart is configured.
+   * If the string contains HTML tags they will be interpreted as such.
+   *
+   * @example
+   * ```ts
+   * chartElement.placeholder = "<strong>Welcome!</strong><br/>Read the <a href=\"https://developers.arcgis.com/javascript/latest/charts/charts-intro/\">charts introduction page</a> to get started.";
+   * ```
+   *
+   * ![placeholder](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/placeholder.avif)
+   */
   accessor placeholder: string | undefined;
   /**
-   * Allows the use of the fields alias from the `layer.popupTemplate` when rendering the field names on the chart (e.g. tooltips, axes, legend).
+   * When `true`, field aliases from layer's [popupTemplate](/references/core/layers/FeatureLayer/#popupTemplate) are used to render field names in tooltips, axes and legend on the chart.
    *
    * @default false
    */
@@ -1245,12 +1409,13 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor replaceNoValueCategoryWithZero: boolean | undefined;
   /**
-   * When `true`, the features extent will be returned through the [@arcgisDataProcessComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisDataProcessComplete) and [@arcgisSelectionComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisSelectionComplete) events payload.
+   * When `true`, the feature extent is returned in the payload of [@arcgisDataProcessComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisDataProcessComplete)
+   * and [@arcgisSelectionComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisSelectionComplete) events.
    * Applies only to:
    * - Charts using an aggregation.
-   * - Data source using a feature layer compatible with envelope aggregation.
+   * - Data sources using a feature layer compatible with envelope aggregation.
    *
-   * The extent (IExtent) is returned through the property [featuresExtentField](https://developers.arcgis.com/javascript/latest/references/charts-components/utils/defaults/index/#featuresExtentField).
+   * The extent is returned through the [featuresExtentField](https://developers.arcgis.com/javascript/latest/references/charts-components/utils/defaults/index/#featuresExtentField) variable.
    *
    * **Note**: Not applicable to gauges.
    *
@@ -1258,7 +1423,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor returnFeaturesExtent: boolean;
   /**
-   * When `true`, the selection indexes will be computed whenever a selection is made on or passed to the chart.
+   * When `true`, selection indexes are computed and returned whenever a selection is made on or passed to the chart.
    *
    * **Note**: Not applicable to gauges.
    *
@@ -1266,10 +1431,10 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor returnSelectionIndexes: boolean;
   /**
-   * When `true`, the object ids will be computed whenever a selection is made on or passed to the chart.
-   * Only considered for a data source using a feature layer.
+   * When `true`, object ids are computed and returned whenever a selection is made on or passed to the chart.
+   * Only considered for data sources using a [feature layer](/references/core/layers/FeatureLayer).
    *
-   * **Note**: Not applicable to gauges or charts configured with imagery layers. It's always `false` for imagery layers. No object ids will be computed.
+   * **Note**: Not applicable to gauges or charts configured with imagery layers.
    *
    * @default false
    */
@@ -1277,7 +1442,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * When `true`, the chart is rotated 90 degrees so that the x-axis becomes vertical and the y-axis becomes horizontal.
    *
-   * **Note**: Applicable to bar chart, line chart, combo bar line chart and box plot.
+   * **Note**: Applicable to bar charts, box plots, combo bar line charts and line charts.
    *
    * @default false
    */
@@ -1292,12 +1457,29 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor rotation: boolean;
   /**
-   * Applies runtime data filters to the chart.
+   * Applies runtime data filters to the chart, features will be filtered based on the provided key value pairs.
+   *
+   * Supported keys are `where`, `objectIds`, `geometry`, `spatialRelationship`, `distance`, `units`, `timeExtent`, and `gdbVersion`.
    *
    * @example
    * ```ts
+   * // This example filters the chart to show only features with the name "Katrina", object IDs 12, 19, and 27, within a specified geometry, within 10 miles and a specific time extent.
+   * const start = new Date(2005, 8, 23).getTime();
+   * const end = new Date(2005, 8, 28).getTime();
+   *
    * chartComponent.runtimeDataFilters = {
-   *   where: "FieldValue = 9",
+   *   where: "Name = 'Katrina'",
+   *   objectIds: [12, 19, 27],
+   *   geometry: {
+   *     xmin: -130,
+   *     ymin: 20,
+   *     xmax: -60,
+   *     ymax: 55,
+   *   },
+   *   spatialRelationship: "contains",
+   *   distance: 10,
+   *   units: "miles",
+   *   timeExtent: [start, end]
    * };
    * ```
    */
@@ -1305,11 +1487,60 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Callback function used to format the secondary y-axis labels. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Appliable to bar charts, line charts, combo bar line charts with dual axes.
+   * @example
+   * ```ts
+   * // Render a custom secondary y-axis label with the value formatted as a compact currency.
+   * chartElement.secondaryYAxisLabelFormatter = (value) => {
+   *   const formattedValue = new Intl.NumberFormat("en-US", {
+   *     style: "currency",
+   *     currency: "USD",
+   *     notation: "compact",
+   *     maximumFractionDigits: 1,
+   *   }).format(value);
+   *   return `<strong>${formattedValue}</strong>`;
+   * };
+   * ```
+   *
+   * ![secondaryYAxisLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/secondaryYAxisLabelFormatter.avif)
+   *
+   * **Note**: Applicable to bar, line, and combo bar line charts configured with dual axes through the [setSeriesToSecondaryYAxis](https://developers.arcgis.com/javascript/latest/references/charts-components/model/bar-chart-model/bar-chart-model/#setSeriesToSecondaryYAxis) method.
    */
   accessor secondaryYAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
-   * When this property is set, it will apply a selection on the chart matching the provided selection.
+   * Applies a programmatic selection to the chart. The payload can target chart elements by object IDs (`selectionOIDs`), by indexes (`selectionIndexes`), or by items (`selectionItems`).
+   *
+   * ##### Selection by object IDs
+   * When passing in a `selectionOIDs` array, the chart will match the provided object IDs with the chart's data items and apply the selection.
+   *
+   * @example
+   * ```ts
+   * // This selects the chart data items (`Mid East` and `Great Lakes`) that contains the object IDs "3118" and "6544".
+   * chartElement.selectionData = {
+   *   selectionOIDs: [3118, 6544],
+   * };
+   * ```
+   *
+   * ![selectionOIDs](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionData_selectionOIDs.avif)
+   *
+   *
+   * ##### Selection by items
+   * When passing in a `selectionItems` array, the chart will match the provided items with the chart's data items and apply the selection.
+   * @example
+   * ```ts
+   * // This selects the first chart data item with the matching items.
+   * chartElement.selectionData = {
+   *    selectionItems: [
+   *      {
+   *        // The field name and value
+   *        neighbourhood_group: "Manhattan",
+   *        // The y-series field name and value, 0 indicates the first series.
+   *        COUNT_OBJECTID_0: "",
+   *      },
+   *    ],
+   * };
+   * ```
+   *
+   * ![selectionItems](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionData_selectionItems.avif)
    *
    * **Note**: Not applicable to gauges.
    */
@@ -1322,77 +1553,108 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor selectionManager: SelectionManager | undefined;
   /**
-   * Used to provide a customized theme for the selected and non selected elements.
-   * - If no style is provided for the selected elements, a default selection is applied.
-   * - If no style is provided for the non selected elements, the chart's style is applied.
+   * Customizes the visual style applied to selected and non-selected chart data items (bars, slices, markers, boxes etc.).
    *
-   * **Note**: Not applicable to gauges.
+   * - The [`selectedElementsTheme`](/references/charts-components/utils/misc/interfaces/#SelectionTheme-selectedElementsTheme) property controls the appearance of selected elements.
+   * - The [`nonSelectedElementsTheme`](/references/charts-components/utils/misc/interfaces/#SelectionTheme-nonSelectedElementsTheme) property controls the appearance of elements that are not selected.
    *
    * @example
    * ```ts
-   * chartComponent.selectionTheme = {
-   *   "selectedElementsTheme": {
-   *     "transformation": {
-   *       "scale": 1.2
-   *     }
+   * chartElement.selectionTheme = {
+   *   // The selected elements will have a magenta outline with a width of 3 pixels and will be scaled up by 10%.
+   *   selectedElementsTheme: {
+   *     elementOutlineColor: [255, 0, 237, 255],
+   *     elementOutlineWidth: 3,
+   *     transformation: {
+   *       scale: 1.1,
+   *     },
    *   },
-   *   "nonSelectedElementsTheme": {
-   *     "transformation": {
-   *       "opacity": 0.5
-   *     }
-   *   }
-   * }
+   *   // The non-selected elements will be scaled down by 20% and have their opacity reduced to 50%.
+   *   nonSelectedElementsTheme: {
+   *     transformation: {
+   *       scale: 0.8,
+   *       opacity: 0.5,
+   *     },
+   *   },
+   * };
    * ```
+   *
+   * ![selectionTheme](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionTheme.avif)
+   *
+   * **Note**: Not applicable to gauges.
    */
   accessor selectionTheme: SelectionTheme | undefined;
   /**
-   * When `true`, the series properties `unit` and `size` become optional and will be automatically set to values that fit the data set. Used when creating or updating a chart compatible with time binning.
+   * When `true`, the time binning unit and size is automatically set when not provided via the [`temporalBinningSize`](/references/charts-components/model/bar-chart-model/bar-chart-model/#temporalBinningSize) or [`temporalBinningUnit`](/references/charts-components/model/line-chart-model/line-chart-model/#temporalBinningUnit) properties of the chart model.
    *
-   * **Note**: Only applicable to charts using the temporal binning feature (bar chart, line chart, combo bar line chart, radar chart).
+   * The time binning unit and size information for the chart will be derived from the dataset's date minimum and maximum values to compute an interval that best fits the date range.
+   *
+   * **Note**: Only applicable to charts with temporal binning enabled (bar chart, combo bar line chart, line chart, radar chart).
    *
    * @default false
    */
   accessor setTimeBinningInfoWhenNotProvided: boolean;
   /**
-   * Show the series on the chart even if it doesn't have data (i.e. empty)
-   *
-   * When `false`, the empty series are completely hidden from the chart and the legend.
-   * For example a series can be empty after applying a data filter, filter by attribute or geometry (as when using the filter by view extent).
+   * When `true`, show the series on the chart and legend even if it doesn't contain any data.
    *
-   * **Note**: Not applicable to gauges.
+   * By default, the empty series are hidden from the chart and the legend.
    *
    * @default false
+   * @example
+   * ```ts
+   * // In this example, we first set a data filter to only include features with a room type of "Entire home/apt" or "Private room".
+   * // The "Shared room" series will be empty after applying the data filter.
+   * chartElement.runtimeDataFilters = {
+   *    where: "room_type = 'Entire home/apt' OR room_type = 'Private room'",
+   * };
+   *
+   * // With the `showEmptySeries` property set to `true`,
+   * // the "Shared room" series will still be displayed on the chart and in the legend, even though it was filtered out.
+   * chartElement.showEmptySeries = true;
+   * ```
+   *
+   * ![showEmptySeries](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/showEmptySeries.avif)
+   *
+   * **Note**: Not applicable to gauges.
    * @since 5.1
    */
   accessor showEmptySeries: boolean;
   /**
-   * Shows the license watermark.
+   * When `true`, the license watermark is displayed on the lower left corner of the chart.
    *
+   * @deprecated since 5.2. Won't be replaced.
    * @default false
    * @since 5.1
    */
   accessor showLicenseWatermark: boolean;
   /**
-   * Whether to display or hide all UI messages (e.g. no data warnings, or when the logarithmic scale can't be applied to an axis when the data contains values <= 0).
+   * Whether to display or hide all UI messages (e.g. no data warnings, any placeholder messages set or invalid chart configuration).
    *
    * @deprecated since 5.1. Use [hideUIMessages](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#hideUIMessages) instead.
    * @default false
    */
   accessor showUIMessages: boolean | undefined;
   /**
-   * Whether to skip the chart rendering queue.
-   *
    * When `true`, charts will render immediately without waiting for other charts to finish rendering.
-   * When `false` (default), charts are queued so that only one chart renders at a time.
+   * By default, charts are queued so that only one chart renders at a time.
    *
    * @default false
    * @since 5.1
    */
   accessor skipChartCreationQueue: boolean;
   /**
-   * Whether to synchronize the selection between chart components from the same layer.
+   * When `true`, the selection will be synchronized between charts configured with the same layer.
    *
    * @default false
+   * @example
+   * ```ts
+   * // Both charts are configured with the same layer.
+   * // The "Private room" slice is selected on the pie chart and the selection is reflected on the bar chart.
+   * chartElement1.syncChartsSelection = true;
+   * chartElement2.syncChartsSelection = true;
+   * ```
+   *
+   * ![syncChartsSelection](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/syncChartsSelection.avif)
    * @since 5.1
    */
   accessor syncChartsSelection: boolean;
@@ -1455,33 +1717,41 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor timeZone: MapView["timeZone"] | undefined;
   /**
-   * Disables the toggling of series via the legend items.
+   * 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 multi-series charts.
+   * **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;
   /**
-   * Callback function used to format the tooltips. If the returned string contains HTML tags they will be interpreted as such.
+   * Callback function used to format the tooltips when hovering over a chart element. If the returned string contains HTML tags they will be interpreted as such.
    *
    * @example
    * ```ts
-   * chartComponent.tooltipFormatter = ({ statValue }) => {
-   *   return `<b>Custom tooltip</b> for ${statValue}`;
-   * };
+   * // Render a custom tooltip with the series name, x-value, and stat value.
+   * chartElement.tooltipFormatter = (props) => `
+   *   <div>
+   *     <div><strong>${props.seriesName}</strong> in <strong>${props.xValue}</strong></div>
+   *     <div>Total listings: <strong>${props.statValue}</strong></div>
+   *   </div>
+   * `;
    * ```
    *
+   * ![tooltipFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/tooltipFormatter.avif)
+   *
    * **Note**: Not applicable to gauges.
    */
-  accessor tooltipFormatter: ChartOptions["tooltipFormatter"] | undefined;
+  accessor tooltipFormatter: TooltipFormatters | undefined;
   /**
-   * Whether to update the series when the data updates while the chart uses a split-by field configuration.
-   *
-   * If `addMissingSeries` is set to `true` the missing series will be added to cover the split-by values not referenced by the model.
-   * The default information from the property `updateSplitBySeries.seriesTemplate` will be applied to the new series.
+   * 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.
+   *   - When [`addMissingSeries`](/references/charts-components/utils/components/interfaces/#MissingSplitBySeriesProps-addMissingSeries) is set to `true`, the missing series will be added.
+   *   - When [`seriesTemplate`](/references/charts-components/utils/components/interfaces/#MissingSplitBySeriesProps-seriesTemplate) is omitted, the first existing series from the configuration will be copied to be used as a model for the missing ones. The chart won't render if the series template is not set and there's no series in the configuration.
+   * - If a chart is configured using a chart model, this property is not necessary as the split-by series will be updated automatically when the model's properties are changed.
    *
-   * **Note**: Applicable only to bar chart, line chart and box plot when a split-by field is used.
+   * **Note**: Applicable only to bar chart, box plot, line chart and radar chart when a split-by field is used.
    */
   accessor updateSplitBySeries: MissingSplitBySeriesProps | undefined;
   /**
@@ -1513,15 +1783,47 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Callback function used to format the x-axis labels. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Not applicable to pie charts.
+   * @example
+   * ```ts
+   * // Render a custom x-axis label with underlined string and bolded value.
+   * chartElement.xAxisLabelFormatter = (value) => {
+   *    return `<u>Neighbourhood Group:</u> <strong>${value}</strong>`;
+   * };
+   * ```
+   *
+   * ![xAxisLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/xAxisLabelFormatter.avif)
+   *
+   * **Note**: Only applicable to charts with x-axis labels displayed.
    */
   accessor xAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
    * Callback function used to format the y-axis labels. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Not applicable to pie charts or gauges.
+   * @example
+   * ```ts
+   * // Render a custom y-axis label with underlined string and bolded value.
+   * chartElement.yAxisLabelFormatter = (value) => {
+   *   return `<u>Rental Listings:</u> <strong>${value}</strong>`;
+   * };
+   * ```
+   *
+   * ![yAxisLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/yAxisLabelFormatter.avif)
+   *
+   * **Note**: Only applicable to charts with y-axis labels displayed.
    */
   accessor yAxisLabelFormatter: AxisLabelFormatCallback | undefined;
+  /**
+   * When `true`, count=0 is considered a valid statistic.
+   *
+   * By default, when the aggregation type is "count" and the data contains only values equal to 0, the chart dataset
+   * is considered empty:
+   * - The [@arcgisBadDataWarningRaise](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisBadDataWarningRaise) event will be sent.
+   * - The "No data available to display" warning message will be displayed in the chart container.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor zeroCountAsValid: boolean;
   /**
    * Apply the selection from the selection manager to the chart.
    *
@@ -1535,7 +1837,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   clearSelection(): Promise<void>;
   /**
-   * Destroys the chart instance and removes it from the DOM.
+   * Destroys the chart instance.
    *
    * @since 5.1
    */
@@ -1550,110 +1852,280 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Export the current chart's data as a CSV file.
    *
-   * The `Options` object can contain the following properties:
-   * - `columns`: An array of column to include in the CSV file.
-   * - `delimiter`: The delimiter to use in the CSV file. Default is `,`.
-   * - `includeHeader`: Whether to include the header row in the CSV file. Default is `true`.
-   * - `quoteAll`: Whether to quote all values in the CSV file. Default is `false`.
-   * - `locale`: The locale to use when formatting the CSV file. Default is `en`.
-   *    - Locale supported are: "ar", "ar-u-nu-latn", "bs", "bg", "ca", "cs", "da", "de", "el", "en", "en-US", "es", "et", "fi", "fr", "he", "hr", "hu", "id", "it", "ja", "ko", "lt", "lv", "no", "nl", "pl", "pt-BR", "pt-PT", "ro", "ru", "sr", "sl", "sk", "sv", "th", "tr", "uk", "vi", "zh-CN", "zh-HK", "zh-TW"
-   *
-   * **Note**: The chart types supported by this method are:
-   * - Bar chart
-   * - Box plot
-   * - Combo bar line chart
-   * - Heat chart
-   * - Histogram
-   * - Line chart
-   * - Pie chart
-   *
-   * @param options
+   * @param options - The options to customize the exported CSV file.
+   * @example
+   * ```ts
+   * // Export the chart's data as a CSV file with custom options.
+   * await chartElement.exportAsCSV({
+   *   columns: ["neighbourhood_group", "room_type", "Count"],
+   *   delimiter: "|",
+   *   includeHeader: false,
+   *   quoteAll: true,
+   *   locale: "fr"
+   * });
+   * ```
+   *
+   * ```csv
+   * // The exported CSV file will contain the following data:
+   * sep=|
+   * "Bronx"|"Entire home/apt"|"379"
+   * "Bronx"|"Private room"|"652"
+   * "Bronx"|"Shared room"|"60"
+   * "Brooklyn"|"Entire home/apt"|"9 559"
+   * ...
+   * ```
+   *
+   * **Note**: Not supported for gauges, scatterplots and radar charts.
    */
   exportAsCSV(options?: CSVOptions): Promise<void>;
   /**
-   * Exports the current chart as an image. Default format is `png`.
-   * - Alternative formats supported are: `jpeg` and `svg`.
+   * Exports and downloads the current chart as an image.
+   * - Supported formats: `png` (default), `jpeg`, `jpg`, `webp`, and `svg`.
+   *   - When `webp` format is used on Safari, it will fallback to `png`.
    *
-   * @param format
+   * @param format - The image format to export the chart as. Default: `png`.
    */
   exportAsImage(format?: DownloadableChartImagesTypes): Promise<void>;
-  /** Returns a promise that resolves when the chart model is fully loaded. */
+  /**
+   * Returns a promise that resolves when the chart model is fully loaded.
+   *
+   * This method should be used when loading a chart with [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId) and [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex), and further customization of the chart model is needed.
+   *
+   * @example
+   * ```html
+   * // Load a chart from a layer item
+   * <arcgis-chart layer-item-id="8871626e970a4f3e9d6113ec63a92f2f" chart-index="2" />
+   * ```
+   * ```ts
+   * // Get a reference to the chart element in the DOM
+   * const chartElement = document.querySelector("arcgis-chart");
+   *
+   * // Call the method to ensure the model is fully loaded before making changes
+   * await chartElement.loadModel();
+   *
+   * // Once the model is loaded, use the model's properties/methods to customize
+   * chartElement.model.titleText = "New Title";
+   * ```
+   * @see [Load from layer item and customize with charts model](https://developers.arcgis.com/javascript/latest/charts/#load-from-layer-item-and-customize-with-charts-model)
+   */
   loadModel(): Promise<void>;
   /**
-   * Notify method allows passing external messages to the chart component.
-   * It can be used to pass validation or information messages.
-   * In a situation where a model update is overriding the notification modal, consider waiting for the [@arcgisUpdateComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisUpdateComplete) event.
+   * Passes external messages to the chart component and displays them in the chart's container.
+   * When a model update is overriding the notification modal, consider waiting for the [@arcgisRenderingComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisRenderingComplete) event.
    *
-   * @param message - The message to display in the chart's info modal.
-   * @param heading - The heading to display in the chart's info modal.
+   * @param message - The message to display in the chart's container.
+   * @param heading - The heading to display in the chart's container.
+   * @example
+   * ```html
+   * <button id="show-notification" type="button">Show notification</button>
+   * <button id="clear-notification" type="button">Clear notification</button>
+   * ```
+   *
+   * ```ts
+   * // When the "Show notification" button is clicked, the chart's container will display a custom message and heading.
+   * document.querySelector("#show-notification").addEventListener("click", () => {
+   *   chartElement.notify(
+   *     "This is a notification message.",
+   *     "Notification heading",
+   *   );
+   * });
+   *
+   * // When the "Clear notification" button is clicked, the chart's container will be cleared and hidden.
+   * document.querySelector("#clear-notification").addEventListener("click", () => {
+   *   chartElement.notify();
+   * });
+   * ```
    */
   notify(message?: string, heading?: string): Promise<void>;
   /**
    * Re-render the chart.
    *
-   * @param props - Indicates whether to fetch new data. Default: `true`.
+   * @param props - Properties to control the refresh behavior: `updateData` indicates whether to fetch new data (default: `true`), and `resetAxesBounds` indicates whether to reset the axes bounds along with the refresh (default: `false`).
    */
   refresh(props?: {
       updateData?: boolean;
       resetAxesBounds?: boolean;
   }): Promise<void>;
   /**
-   * Resets the chart zoom to bring it back to full extent.
+   * Resets the chart's zoom and brings it back to full zoom extent.
    *
-   * **Note**: Applicable to XY charts only.
+   * **Note**: Not applicable to gauges, heat charts, pie charts and radar charts.
    */
   resetZoom(): Promise<void>;
   /**
    * Switches the selection on the chart.
    *
-   * **Note**: Not applicable to gauge.
+   * **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"];