@arcgis/charts-components 5.2.0-next.65 → 5.2.0-next.66

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

@@ -36,7 +36,7 @@ import type { T9nMeta } from "@arcgis/lumina/controllers";
  *
  * ##### 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.
+ * 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";
@@ -49,7 +49,7 @@ import type { T9nMeta } from "@arcgis/lumina/controllers";
  * 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).
+ * 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/)
@@ -608,9 +608,9 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * 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`.
+   * - `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.
    *
@@ -624,7 +624,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   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.
+   * 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"
@@ -673,7 +673,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   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.
+   * 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` |
    * | -------- | -------- |
@@ -716,12 +716,20 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor chartIndex: number | undefined;
   /**
-   * Customize the maximum number of series allowed on the chart.
+   * 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;
   /**
@@ -733,7 +741,7 @@ export abstract class ArcgisChart extends LitElement {
   accessor chartWillRender: PreRenderCallback | undefined;
   /**
    * Whether to use features uniquely designed for a chart currently being configured by a user via the UI.
-   * 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,
+   * 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
@@ -763,7 +771,7 @@ export abstract class ArcgisChart extends LitElement {
    * <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;"
+   *   style="max-width: 700px; width: 100%; height: auto;"
    * />
    *
    * **Note**: Not applicable to gauges and radar charts.
@@ -809,7 +817,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"
    */
@@ -855,7 +864,11 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * ![gaugeInnerLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/gaugeInnerLabelFormatter.avif)
+   * <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.
    */
@@ -874,7 +887,11 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * ![guideTooltipFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/guideTooltipFormatter.avif)
+   * <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.
    */
@@ -897,27 +914,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.
+   * 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
@@ -1024,7 +1042,11 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * ![legendValueLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/legendValueLabelFormatter.avif)
+   * <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.
    */
@@ -1049,7 +1071,29 @@ export abstract class ArcgisChart extends LitElement {
    * ```
    */
   accessor loaderColors: LoaderColors | undefined;
-  /** Custom message overrides for the chart's strings. */
+  /**
+   * 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?: {
@@ -1321,21 +1365,38 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * 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
    */
@@ -1356,12 +1417,13 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor replaceNoValueCategoryWithZero: boolean | undefined;
   /**
-   * When `true`, the features extent will be returned through the [@arcgisDataProcessComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisDataProcessComplete) and [@arcgisSelectionComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisSelectionComplete) events payload.
+   * When `true`, the feature extent is returned in the payload of [@arcgisDataProcessComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisDataProcessComplete)
+   * and [@arcgisSelectionComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisSelectionComplete) events.
    * Applies only to:
    * - Charts using an aggregation.
-   * - Data source using a feature layer compatible with envelope aggregation.
+   * - Data sources using a feature layer compatible with envelope aggregation.
    *
-   * The extent (IExtent) is returned through the property [featuresExtentField](https://developers.arcgis.com/javascript/latest/references/charts-components/utils/defaults/index/#featuresExtentField).
+   * The extent is returned through the [featuresExtentField](https://developers.arcgis.com/javascript/latest/references/charts-components/utils/defaults/index/#featuresExtentField) variable.
    *
    * **Note**: Not applicable to gauges.
    *
@@ -1369,7 +1431,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.
    *
@@ -1377,10 +1439,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
    */
@@ -1388,7 +1450,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * When `true`, the chart is rotated 90 degrees so that the x-axis becomes vertical and the y-axis becomes horizontal.
    *
-   * **Note**: Applicable to bar chart, line chart, combo bar line chart and box plot.
+   * **Note**: Applicable to bar charts, box plots, combo bar line charts and line charts.
    *
    * @default false
    */
@@ -1403,12 +1465,29 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor rotation: boolean;
   /**
-   * Applies runtime data filters to the chart.
+   * Applies runtime data filters to the chart, features will be filtered based on the provided key value pairs.
+   *
+   * Supported keys are `where`, `objectIds`, `geometry`, `spatialRelationship`, `distance`, `units`, `timeExtent`, and `gdbVersion`.
    *
    * @example
    * ```ts
+   * // This example filters the chart to show only features with the name "Katrina", object IDs 12, 19, and 27, within a specified geometry, within 10 miles and a specific time extent.
+   * const start = new Date(2005, 8, 23).getTime();
+   * const end = new Date(2005, 8, 28).getTime();
+   *
    * chartComponent.runtimeDataFilters = {
-   *   where: "FieldValue = 9",
+   *   where: "Name = 'Katrina'",
+   *   objectIds: [12, 19, 27],
+   *   geometry: {
+   *     xmin: -130,
+   *     ymin: 20,
+   *     xmax: -60,
+   *     ymax: 55,
+   *   },
+   *   spatialRelationship: "contains",
+   *   distance: 10,
+   *   units: "miles",
+   *   timeExtent: [start, end]
    * };
    * ```
    */
@@ -1416,11 +1495,67 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Callback function used to format the secondary y-axis labels. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Appliable to bar charts, line charts, combo bar line charts with dual axes.
+   * @example
+   * ```ts
+   * // Render a custom secondary y-axis label with the value formatted as a compact currency.
+   * chartElement.secondaryYAxisLabelFormatter = (value) => {
+   *   const formattedValue = new Intl.NumberFormat("en-US", {
+   *     style: "currency",
+   *     currency: "USD",
+   *     notation: "compact",
+   *     maximumFractionDigits: 1,
+   *   }).format(value);
+   *   return `<strong>${formattedValue}</strong>`;
+   * };
+   * ```
+   *
+   * ![secondaryYAxisLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/secondaryYAxisLabelFormatter.avif)
+   *
+   * **Note**: Applicable to bar, line, and combo bar line charts configured with dual axes through the [setSeriesToSecondaryYAxis](https://developers.arcgis.com/javascript/latest/references/charts-components/model/bar-chart-model/bar-chart-model/#setSeriesToSecondaryYAxis) method.
    */
   accessor secondaryYAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
-   * When this property is set, it will apply a selection on the chart matching the provided selection.
+   * Applies a programmatic selection to the chart. The payload can target chart elements by object IDs (`selectionOIDs`), by indexes (`selectionIndexes`), or by items (`selectionItems`).
+   *
+   * ##### Selection by object IDs
+   * When passing in a `selectionOIDs` array, the chart will match the provided object IDs with the chart's data items and apply the selection.
+   *
+   * @example
+   * ```ts
+   * // This selects the chart data items (`Mid East` and `Great Lakes`) that contains the object IDs "3118" and "6544".
+   * chartElement.selectionData = {
+   *   selectionOIDs: [3118, 6544],
+   * };
+   * ```
+   *
+   * <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.
    */
@@ -1433,77 +1568,120 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor selectionManager: SelectionManager | undefined;
   /**
-   * Used to provide a customized theme for the selected and non selected elements.
-   * - If no style is provided for the selected elements, a default selection is applied.
-   * - If no style is provided for the non selected elements, the chart's style is applied.
+   * Customizes the visual style applied to selected and non-selected chart data items (bars, slices, markers, boxes etc.).
    *
-   * **Note**: Not applicable to gauges.
+   * - The [`selectedElementsTheme`](/references/charts-components/utils/misc/interfaces/#SelectionTheme-selectedElementsTheme) property controls the appearance of selected elements.
+   * - The [`nonSelectedElementsTheme`](/references/charts-components/utils/misc/interfaces/#SelectionTheme-nonSelectedElementsTheme) property controls the appearance of elements that are not selected.
    *
    * @example
    * ```ts
-   * chartComponent.selectionTheme = {
-   *   "selectedElementsTheme": {
-   *     "transformation": {
-   *       "scale": 1.2
-   *     }
+   * chartElement.selectionTheme = {
+   *   // The selected elements will have a magenta outline with a width of 3 pixels and will be scaled up by 10%.
+   *   selectedElementsTheme: {
+   *     elementOutlineColor: [255, 0, 237, 255],
+   *     elementOutlineWidth: 3,
+   *     transformation: {
+   *       scale: 1.1,
+   *     },
+   *   },
+   *   // 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 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 `false`, the empty series are completely hidden from the chart and the legend.
-   * For example a series can be empty after applying a data filter, filter by attribute or geometry (as when using the filter by view extent).
+   * When `true`, show the series on the chart and legend even if it doesn't contain any data.
    *
-   * **Note**: Not applicable to gauges.
+   * By default, the empty series are hidden from the chart and the legend.
    *
    * @default false
+   * @example
+   * ```ts
+   * // In this example, we first set a data filter to only include features with a room type of "Entire home/apt" or "Private room".
+   * // The "Shared room" series will be empty after applying the data filter.
+   * chartElement.runtimeDataFilters = {
+   *    where: "room_type = 'Entire home/apt' OR room_type = 'Private room'",
+   * };
+   *
+   * // With the `showEmptySeries` property set to `true`,
+   * // the "Shared room" series will still be displayed on the chart and in the legend, even though it was filtered out.
+   * chartElement.showEmptySeries = true;
+   * ```
+   *
+   * <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;