@arcgis/charts-components 5.2.0-next.7 → 5.2.0-next.71

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

@@ -22,125 +22,53 @@ 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.
+ * There are different ways to render a chart with the ArcGIS Chart component:
  *
- * Supported chart types include bar charts, box plots, line charts, combo bar-line charts, gauges, heat charts, histograms, pie charts, scatterplots, and radar charts.
+ * ##### Load from a layer item
  *
- * @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/)
+ * To load a chart from a layer item, first the chart needs to be [configured in Map Viewer](https://doc.arcgis.com/en/arcgis-online/create-maps/configure-charts-mv.htm) and [saved to the layer item](https://doc.arcgis.com/en/arcgis-online/create-maps/duplicate-save-layers.htm#ESRI_SECTION1_2AE9121DFA5D4E099F0D434EBA7D9365).
+ * Then set the [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId) property to the item's ID and the [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) property to the index of the chart within the item.
  *
- * **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.
+ * ```html
+ * <arcgis-chart layer-item-id="..." chart-index="0"></arcgis-chart>
+ * ```
+ *
+ * ##### Create a new chart with charts model
+ *
+ * To create a new chart, use the [createModel](https://developers.arcgis.com/javascript/latest/references/charts-components/model/shared/setup-utils/#createModel) method with a layer and a chart type, then configure the chart using the model's properties and methods.
+ *
+ * ```js
+ * import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
+ * import { createModel } from "@arcgis/charts-components/model/shared/setup-utils.js";
+ *
+ * const myLayer = new FeatureLayer({ portalItem: { id: "..." } });
+ *
+ * const chartElement = document.querySelector("arcgis-chart");
+ * const barChartModel = await createModel({ layer: myLayer, chartType: "barChart" });
+ * barChartModel.xAxisField = "field";
+ * ```
+ *
+ * Each supported [chart type](https://developers.arcgis.com/javascript/latest/charts/chart-types/) has its own configuration properties and methods with their corresponding models.
+ *
+ * ##### See also:
+ * - [Introduction to charts](https://developers.arcgis.com/javascript/latest/charts-components-intro/)
+ * - [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/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), [\`description\`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), [\`describedByElements\`](https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaDescribedByElements), and [\`labelledByElements\`](https://developer.mozilla.org/en-US/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;
@@ -675,21 +603,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,
+   *   maxCategoryCountTotal: 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,7 +762,25 @@ 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>
+   *   `;
+   * };
+   * ```
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/dataLabelFormatter.avif"
+   *   alt="dataLabelFormatter true"
+   *   style="max-width: 700px; width: 100%; height: auto;"
+   * />
+   *
+   * **Note**: Not applicable to gauges and radar charts.
    */
   accessor dataLabelFormatter: ChartOptions["dataLabelFormatter"] | undefined;
   /**
@@ -740,7 +823,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"
    */
@@ -748,7 +832,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * The index of the feature to render when using a feature based gauge.
    *
-   * **Note**: Only applicable to gauges.
+   * **Note**: Applicable to gauges only.
    *
    * @deprecated since 5.0. Use charts model's [featureIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/model/gauge-model/gauge-model/#featureIndex) prop instead.
    */
@@ -761,7 +845,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 +854,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,18 +862,49 @@ 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>`;
+   * };
+   * ```
+   *
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/gaugeInnerLabelFormatter.avif"
+   *   alt="gaugeInnerLabelFormatter"
+   *   style="max-width: 700px; width: 100%; height: auto;"
+   * />
+   *
    * **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>
+   *   `;
+   * };
+   * ```
+   *
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/guideTooltipFormatter.avif"
+   *   alt="guideTooltipFormatter"
+   *   style="max-width: 700px; width: 100%; height: auto;"
+   * />
+   *
    * **Note**: Not applicable to pie charts.
    */
   accessor guideTooltipFormatter: GuideTooltipFormatCallback | undefined;
   /**
    * When `true`, the empty series are completely hidden from the chart and the legend.
-   * For example, a series may become empty after applying a data filter, filter by attribute or geometry (as when using the filter by extent).
+   * For example, a series may become empty after applying a data filter, filter by attribute or geometry (as when using the filter by view extent).
    *
    * **Note**: Not applicable to gauges.
    *
@@ -804,27 +920,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 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 `true`, missing categories from a `Count` aggregation are kept as gaps in the chart's data.
    *
-   * When this property is set to `true`, the dataset will keep these gaps instead of filling them with 0s.
+   * When data is retrieved from the server, features with a count of 0 are excluded from the response, resulting in missing chart entries.
    *
-   * When left to `false`,  the chart's dataItems associated with empty (no value) categories (from only a `Count` aggregation)
-   * will be populated with 0s, via the`completeDataForEmptyCategoriesWithZeros` method.
+   * 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,18 +963,18 @@ 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 [`FeatureLayerView`](/references/core/views/layers/FeatureLayerView/).
    *
-   * 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
    */
@@ -882,9 +999,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 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
@@ -893,13 +1013,11 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor layerItemId: string | undefined;
   /**
-   * Allows the chart to update automatically when the layer's renderer changes.
-   * Applies when the color match is enabled.
-   *
-   * @deprecated
-   * since 5.1. Won't be replaced.
+   * Allows the chart to update automatically when the layer's renderer changes. Applies when the color match is enabled.
    *
    * **Note**: If the property is set to `ignore` the chart will still use the layer's renderer information when the data is updated.
+   *
+   * @deprecated since 5.1. Won't be replaced.
    * @default "refresh"
    */
   accessor layerRendererChangePolicy: LayerRendererChangePolicy;
@@ -912,8 +1030,28 @@ 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 `WebChartPieChartLegend.displayNumericValue` or `WebChartPieChartLegend.displayPercentage` is true.
+   * When the pie chart label contains either a numeric value or a percentage (which can be set through the
+   * [setDisplayNumericValue](https://developers.arcgis.com/javascript/latest/references/charts-components/model/pie-chart-model/pie-chart-model/#setDisplayNumericValue) and
+   * [setDisplayPercentage](https://developers.arcgis.com/javascript/latest/references/charts-components/model/pie-chart-model/pie-chart-model/#setDisplayPercentage) methods 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.setDisplayNumericValue(true);
+   * pieChartModel.setDisplayPercentage(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>)`;
+   * };
+   * ```
+   *
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/legendValueLabelFormatter.avif"
+   *   alt="legendValueLabelFormatter"
+   *   style="max-width: 400px; width: 100%; height: auto;"
+   * />
    *
    * **Note**: Applicable to pie charts only.
    */
@@ -934,12 +1072,34 @@ export abstract class ArcgisChart extends LitElement {
    * @example
    * ```ts
    * // Set a blue curtain and a red spinner for the loader animation
-   * myChart.loaderColors = { curtainColor: [30, 144, 255, 255], spinnerColor: [255, 0, 0, 255] };
+   * chartComponent.loaderColors = { curtainColor: [30, 144, 255, 255], spinnerColor: [255, 0, 0, 255] };
    * ```
    */
   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;
@@ -1206,25 +1366,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
    */
@@ -1238,19 +1415,20 @@ export abstract class ArcgisChart extends LitElement {
   accessor queueChartCreation: boolean | undefined;
   /**
    * When `true`, the chart's `dataItems` associated with empty (no value) categories (from only a `Count` aggregation)
-   * will be populated with 0s, via the `completeDataForEmptyCategoriesWithZeros` method.
+   * will be populated with 0s.
    *
    * @deprecated since 5.0. Use [hideZeroCountCategories](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#hideZeroCountCategories) instead.
    * @default false
    */
   accessor replaceNoValueCategoryWithZero: boolean | undefined;
   /**
-   * When `true`, the features extent will be returned through the `arcgisDataProcessComplete` and `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 a property called `arcgis_charts_features_extent`.
+   * 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 +1436,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 +1444,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 +1455,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 and line chart and box plot.
+   * **Note**: Applicable to bar charts, box plots, combo bar line charts and line charts.
    *
    * @default false
    */
@@ -1285,115 +1463,230 @@ 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 and line chart and box plot.
+   * **Note**: Applicable to bar chart, line chart, combo bar line chart and box plot.
    *
    * @deprecated since 5.0. Use either [rotated](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#rotated) or the charts model's [rotated](https://developers.arcgis.com/javascript/latest/references/charts-components/model/bar-chart-model/bar-chart-model/#rotated) prop instead.
    * @default false
    */
   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
-   * myChart.runtimeDataFilters = {
-   *   where: "FieldValue = 9",
+   * // 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: "Name = 'Katrina'",
+   *   objectIds: [12, 19, 27],
+   *   geometry: {
+   *     xmin: -130,
+   *     ymin: 20,
+   *     xmax: -60,
+   *     ymax: 55,
+   *   },
+   *   spatialRelationship: "contains",
+   *   distance: 10,
+   *   units: "miles",
+   *   timeExtent: [start, end]
    * };
    * ```
    */
   accessor runtimeDataFilters: WebChartDataFilters | undefined;
   /**
    * Callback function used to format the secondary y-axis labels. If the returned string contains HTML tags they will be interpreted as such.
-   * The property will be effective only if 3 axes are defined (dual axis chart).
    *
-   * **Note**: Appliable to bar charts, line charts, combo bar line charts and radar charts.
+   * @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],
+   * };
+   * ```
+   *
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionData_selectionOIDs.avif"
+   *   alt="selectionOIDs"
+   *   style="max-width: 600px; width: 100%; height: auto;"
+   * />
+   *
+   * ##### 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: "",
+   *      },
+   *    ],
+   * };
+   * ```
+   *
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionData_selectionItems.avif"
+   *   alt="selectionItems"
+   *   style="max-width: 600px; width: 100%; height: auto;"
+   * />
    *
    * **Note**: Not applicable to gauges.
    */
   accessor selectionData: SelectionData | undefined;
   /**
-   * Selection manager object used to synchronize the selections with the chart when `syncViewSelection` is `true`.
-   * It has precedence over the layer view's [SelectionManager](https://developers.arcgis.com/javascript/latest/references/core/views/SelectionManager/) when both are available.
+   * Selection manager object used to synchronize the selections with the chart when [syncViewSelection](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#syncViewSelection) is `true`.
+   * It has precedence over the layer view's [SelectionManager](/references/core/views/SelectionManager/) when both are available.
    *
    * @since 5.1
    */
   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
+   * @example
    * ```ts
-   * myChart.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,
+   *     },
+   *   },
+   *   // 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,
+   *     },
    *   },
-   *   "nonSelectedElementsTheme": {
-   *     "transformation": {
-   *       "opacity": 0.5
-   *     }
-   *   }
-   * }
+   * };
    * ```
+   *
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionTheme.avif"
+   *   alt="selectionTheme"
+   *   style="max-width: 700px; width: 100%; height: auto;"
+   * />
+   *
+   * **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.
+   *
+   * 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 using the temporal binning feature (bar chart, line chart, combo bar and line chart, radar chart).
+   * **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 `true`, show the series on the chart and legend even if it doesn't contain any data.
    *
-   * 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 extent).
-   *
-   * **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;
+   * ```
+   *
+   * <img
+   *  src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/showEmptySeries.avif"
+   *  alt="showEmptySeries"
+   *  style="max-width: 700px; width: 100%; height: auto;"
+   * />
+   *
+   * **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;
+   * ```
+   *
+   * <img
+   *  src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/syncChartsSelection.avif"
+   *  alt="syncChartsSelection"
+   *  style="max-width: 700px; width: 100%; height: auto;"
+   * />
    * @since 5.1
    */
   accessor syncChartsSelection: boolean;
@@ -1405,14 +1698,14 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncSelection: boolean;
   /**
-   * Determines whether the chart's selection should be synchronized with either the chart's `selectionManager` or the layer view's.
+   * Determines whether the chart's selection should be synchronized with either the chart's [selectionManager](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#selectionManager) or the layer view's.
    *
    * @deprecated since 5.1. Use [syncViewSelection](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#syncViewSelection) prop instead.
    * @default "disabled"
    */
   accessor syncSelectionsBetweenChartAndLayerViewPolicy: SyncSelectionsBetweenChartAndLayerViewPolicy;
   /**
-   * Determines whether the chart's selection should be synchronized with either the chart's `selectionManager` or the layer view's.
+   * Determines whether the chart's selection should be synchronized with either the chart's [selectionManager](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#selectionManager) or the layer view's.
    *
    * @default false
    * @since 5.1
@@ -1428,7 +1721,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncViewTimeExtent: boolean;
   /**
-   * Whether the chart's data should be in sync with the view's time zone (`timeZone`).
+   * Whether the chart's data should be in sync with the view's [timeZone](/references/core/views/MapView/#timeZone).
+   *
    * **Note**: This applies only to charts supporting temporal data. Additionally if the data is binned, it applies only if the layer has the
    * capacity to handle the `/queryBins` operation. For any other case the chart will ignore the view's time zone regardless of the value of this property.
    *
@@ -1437,7 +1731,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncViewTimeZone: boolean;
   /**
-   * List of chart types to include from syncing the view's time zone (`timeZone`) with the data. Currently heat charts are included by default.
+   * List of chart types to include from syncing the view's [`timeZone`](/references/core/views/MapView/#timeZone) with the data. Currently heat charts are included by default.
+   *
    * **Note**: This applies only to charts supporting temporal data. Additionally if the data is binned, it applies only if the layer has the
    * capacity to handle the `/queryBins` operation. For any other case the chart will ignore the view's time zone regardless of the content of this list.
    *
@@ -1451,40 +1746,43 @@ export abstract class ArcgisChart extends LitElement {
    * ```ts
    * chartComponent.timeZone = "America/Los_Angeles";
    * ```
-   * @example
-   * ```html
-   * <arcgis-chart time-zone="America/Los_Angeles"></arcgis-chart>
-   * ```
    */
   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.
    *
    * @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
-   * myChart.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;
   /**
-   * 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 not provided, 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;
   /**
@@ -1516,13 +1814,33 @@ 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;
   /**
@@ -1564,7 +1882,7 @@ export abstract class ArcgisChart extends LitElement {
    * **Note**: The chart types supported by this method are:
    * - Bar chart
    * - Box plot
-   * - Combo bar and line chart
+   * - Combo bar line chart
    * - Heat chart
    * - Histogram
    * - Line chart
@@ -1575,7 +1893,8 @@ export abstract class ArcgisChart extends LitElement {
   exportAsCSV(options?: CSVOptions): Promise<void>;
   /**
    * Exports the current chart as an image. Default format is `png`.
-   * - Alternative formats supported are: `jpeg` and `svg`.
+   * - Alternative formats supported are: `jpeg`, `jpg`, `webp`, and `svg`.
+   * - When WebP format is used on Safari, it will fallback to PNG rendering.
    *
    * @param format
    */
@@ -1636,7 +1955,11 @@ export abstract class ArcgisChart extends LitElement {
   readonly arcgisDataProcessComplete: import("@arcgis/lumina").TargetedEvent<this, DataProcessCompletePayload>;
   /** Event triggered when an error occurred while fetching of processing the data for the chart. */
   readonly arcgisDataProcessError: import("@arcgis/lumina").TargetedEvent<this, void>;
-  /** Event triggered when an invalid configuration is detected. */
+  /**
+   * Event triggered 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. */
   readonly arcgisLegendItemVisibilityChange: import("@arcgis/lumina").TargetedEvent<this, LegendItemVisibilityChangePayload>;