@arcgis/charts-components 5.2.0-next.6 → 5.2.0-next.61

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()`](/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 has its own configuration properties and methods, which are covered with examples in the [chart types documentation](https://developers.arcgis.com/javascript/latest/charts/chart-types/chart-types-intro).
+ *
+ * ##### 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,150 @@ 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 point or series at a time. Each new selection replaces the previous selection.
+   * - `multiSelection`: Select multiple data points or series. Each new selection is added to the existing selection.
+   * - `multiSelectionWithCtrlKey`: Select multiple data points or series 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 series, 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 contrast with the series area 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 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;
   /**
    * 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 [`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 +754,19 @@ 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
+   * chartElement.dataLabelFormatter = (value) => {
+   *   return `<b>${value}</b><br /><u>Custom label</u>`;
+   * };
+   * ```
+   * <img
+   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/dataLabelFormatter.avif"
+   *   alt="dataLabelFormatter true"
+   *   style="max-width: 900px; width: 100%; height: auto;"
+   * />
+   *
+   * **Note**: Not applicable to gauges and radar charts.
    */
   accessor dataLabelFormatter: ChartOptions["dataLabelFormatter"] | undefined;
   /**
@@ -748,7 +817,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 +830,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 +839,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 +847,41 @@ 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 = (guide) => {
+   *   return `
+   *     <u>Custom guide tooltip</u><br />
+   *     Range: <b>${guide.start} - ${guide.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;
   /**
    * 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.
    *
@@ -824,7 +917,7 @@ export abstract class ArcgisChart extends LitElement {
    * 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, via the`completeDataForEmptyCategoriesWithZeros` method.
+   * will be populated with 0s.
    *
    * @default false
    * @since 5.1
@@ -846,18 +939,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 +975,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.
+   *
+   * 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`.
    *
-   * If `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
+   * 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 +989,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 +1006,25 @@ 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) => {
+   *   const formatTo2Decimals = (input) => Number(input).toFixed(2);
+   *   return `<strong><u>${formatTo2Decimals(value)}</u></strong> (<em>${formatTo2Decimals(percentage)}%</em>)`;
+   * };
+   * ```
+   *
+   * ![legendValueLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/legendValueLabelFormatter.avif)
    *
    * **Note**: Applicable to pie charts only.
    */
@@ -934,12 +1045,12 @@ 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; } & {
+  accessor messageOverrides: {
       utilsStrings?: {
           chartType?: {
               chart?: string | undefined;
@@ -1206,7 +1317,7 @@ 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.
    *
@@ -1238,19 +1349,19 @@ 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 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.
    * Applies only to:
    * - Charts using an aggregation.
    * - Data source using a feature layer compatible with envelope aggregation.
    *
-   * The extent (`IExtent`) is returned through a property called `arcgis_charts_features_extent`.
+   * The extent (IExtent) is returned through the property [featuresExtentField](https://developers.arcgis.com/javascript/latest/references/charts-components/utils/defaults/index/#featuresExtentField).
    *
    * **Note**: Not applicable to gauges.
    *
@@ -1277,7 +1388,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 chart, line chart, combo bar line chart and box plot.
    *
    * @default false
    */
@@ -1285,7 +1396,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 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
@@ -1296,7 +1407,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * @example
    * ```ts
-   * myChart.runtimeDataFilters = {
+   * chartComponent.runtimeDataFilters = {
    *   where: "FieldValue = 9",
    * };
    * ```
@@ -1304,9 +1415,8 @@ export abstract class ArcgisChart extends LitElement {
   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.
+   * **Note**: Appliable to bar charts, line charts, combo bar line charts with dual axes.
    */
   accessor secondaryYAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
@@ -1316,8 +1426,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   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
    */
@@ -1329,9 +1439,9 @@ export abstract class ArcgisChart extends LitElement {
    *
    * **Note**: Not applicable to gauges.
    *
-   * * \@example
+   * @example
    * ```ts
-   * myChart.selectionTheme = {
+   * chartComponent.selectionTheme = {
    *   "selectedElementsTheme": {
    *     "transformation": {
    *       "scale": 1.2
@@ -1349,7 +1459,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * 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.
    *
-   * **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 using the temporal binning feature (bar chart, line chart, combo bar line chart, radar chart).
    *
    * @default false
    */
@@ -1358,7 +1468,7 @@ export abstract class ArcgisChart extends LitElement {
    * 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 extent).
+   * 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).
    *
    * **Note**: Not applicable to gauges.
    *
@@ -1405,14 +1515,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 +1538,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 +1548,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,10 +1563,6 @@ 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;
   /**
@@ -1470,7 +1578,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * @example
    * ```ts
-   * myChart.tooltipFormatter = ({ statValue }) => {
+   * chartComponent.tooltipFormatter = ({ statValue }) => {
    *   return `<b>Custom tooltip</b> for ${statValue}`;
    * };
    * ```
@@ -1564,7 +1672,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 +1683,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 +1745,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>;