@arcgis/charts-components 5.1.0-next.85 → 5.1.0-next.86

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

@@ -45,23 +45,23 @@ export abstract class ArcgisChart extends LitElement {
    * - `none`: No action is performed on user interaction.
    * - `zoom`: Zoom into a specific area of the chart.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    */
   accessor actionMode: ActionModes | undefined;
   /**
-   * Whether to allow the object id to be used as a statistic other than `COUNT`.
+   * Whether to allow the object id to be used as a statistic other than `Count`.
    *
    * @default false
    */
   accessor allowUsingObjectIdStat: boolean;
   /**
-   * The ARIA attributes for the chart.
+   * 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;
   /**
-   * When `true`, the chart will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the chart to a different place on the page, or temporarily hide it.
+   * 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
@@ -78,6 +78,8 @@ export abstract class ArcgisChart extends LitElement {
    * 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;
@@ -95,19 +97,19 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor chartIndex: number | undefined;
   /**
-   * Used to customize the number maximum of bars allowed on the chart.
+   * 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 gauge.
+   * **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 config from information extracted from the data for instance.
+   * Can be used to alter the model from information extracted from the data.
    *
-   * **Note**: Applicable to gauge and pie chart only.
+   * **Note**: Applicable to gauges and pie charts only.
    */
   accessor chartWillRender: PreRenderCallback | undefined;
   /**
@@ -640,13 +642,13 @@ export abstract class ArcgisChart extends LitElement {
    * - `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.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    */
   accessor cursorRange: CursorRange | undefined;
   /**
-   * A callback function used to format the data labels. If the returned string contains HTML tags they will be interpreted as such.
+   * 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 gauge.
+   * **Note**: Not applicable to gauges.
    */
   accessor dataLabelFormatter: ChartOptions["dataLabelFormatter"] | undefined;
   /**
@@ -656,7 +658,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor disableInteractions: boolean;
   /**
-   * Disables the toggling of series via the legend items.
+   * Disables the toggling of series from the legend items.
    *
    * **Note**: Only applicable to multi-series charts.
    *
@@ -711,7 +713,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * The index of the feature to render when using a feature based gauge.
    *
-   * **Note**: Only applicable to gauge.
+   * **Note**: Only applicable to gauges.
    *
    * @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.
    */
@@ -725,29 +727,28 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * When `true`, all chart elements are filtered based on the selection.
    *
-   * **Note**: Not applicable to gauge.
-   *           Not applicable to imagery layer charts.
+   * **Note**: Not applicable to gauges or charts configured with imagery layers.
    *
    * @default false
    */
   accessor filterBySelection: boolean;
   /**
-   * A callback function used to format the gauge inner label. If the returned string contains HTML tags they will be interpreted as such.
+   * Callback function used to format the gauge inner label. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Applicable to gauge only.
+   * **Note**: Applicable to gauges only.
    */
   accessor gaugeInnerLabelFormatter: GaugeInnerLabelFormatCallback | undefined;
   /**
-   * A callback function used to format the axes guides tooltip. If the returned string contains HTML tags they will be interpreted as such.
+   * Callback function used to format the axes guides tooltip. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Not applicable to pie chart.
+   * **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).
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    *
    * @deprecated since 5.1. Use [showEmptySeries](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#showEmptySeries) instead.
    * @default false
@@ -796,7 +797,7 @@ export abstract class ArcgisChart extends LitElement {
    * It's recommended that this property should only be set to `true` for small datasets.
    * When left `undefined`, will be treated as `false`.
    *
-   * **Note**: Applicable to line chart only.
+   * **Note**: Applicable to line charts only.
    *
    * @deprecated since 5.1. Won't be replaced.
    * @default false
@@ -806,7 +807,7 @@ export abstract class ArcgisChart extends LitElement {
    * This property will be effective when the component's `view` is provided or when the `layer` is set to a FeatureLayerView.
    *
    * 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 config (`component.config.dataFilters`) or the runtime filters (`component.runtimeDataFilters`).
+   * geometry passed through the model (`component.model.dataFilters`) or the runtime filters (`component.runtimeDataFilters`).
    *
    * Setting this property to `false` signals the queries to ignore the view's extent, whether an additional geometry filter is provided or not.
    *
@@ -846,7 +847,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Allows the chart to update automatically when the layer's renderer changes.
    *
-   * Applies when the color match feature is enabled.
+   * Applies when the color match is enabled.
    *
    * **Note**: If the property is set to `ignore` the chart will use the layer's renderer information when the data is updated.
    *
@@ -856,7 +857,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Sets the legend's position on the chart.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    *
    * @deprecated since 5.0. Use charts model's [legendPosition](https://developers.arcgis.com/javascript/latest/references/charts-components/model/bar-chart-model/bar-chart-model/#legendPosition) prop instead.
    */
@@ -865,19 +866,27 @@ export abstract class ArcgisChart extends LitElement {
    * 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.
    *
-   * **Note**: Applicable to pie chart only.
+   * **Note**: Applicable to pie charts only.
    */
   accessor legendValueLabelFormatter: PieChartLegendValueLabelFormatCallback | undefined;
   /**
    * When `true`, the legend is visible on the chart.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    *
    * @deprecated since 5.0. Use charts model's [legendVisibility](https://developers.arcgis.com/javascript/latest/references/charts-components/model/bar-chart-model/bar-chart-model/#legendVisibility) prop instead.
    * @default false
    */
   accessor legendVisibility: boolean;
-  /** Defines the colors for the loader animation. */
+  /**
+   * Defines the colors for the loader animation.
+   *
+   * @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] };
+   * ```
+   */
   accessor loaderColors: LoaderColors | undefined;
   /** Custom message overrides for the chart's strings. */
   accessor messageOverrides: { chartNotFoundWarning?: string | undefined; } & {
@@ -1142,7 +1151,7 @@ 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 config object can be passed to it instead, however it is recommended to use a `ChartModel` instance whenever possible.
+   * **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.
    */
   accessor model: ChartModel | WebChart | undefined;
   /**
@@ -1156,14 +1165,14 @@ export abstract class ArcgisChart extends LitElement {
   /** A placeholder string to provides a brief hint to the user indicating needed information for creating a chart. */
   accessor placeholder: string | undefined;
   /**
-   * Builds charts sequentially instead of rendering them all at once
+   * Builds charts sequentially instead of rendering them all at once.
    *
    * @deprecated since 5.1. Use [skipChartCreationQueue](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#skipChartCreationQueue) instead.
    * @default false
    */
   accessor queueChartCreation: boolean | undefined;
   /**
-   * When `true`, the chart's dataItems associated with empty (no value) categories (from only a `Count` aggregation)
+   * 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.
    *
    * @deprecated since 5.0. Use [hideZeroCountCategories](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#hideZeroCountCategories) instead.
@@ -1178,7 +1187,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * The extent (`IExtent`) is returned through a property called `arcgis_charts_features_extent`.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    *
    * @default false
    */
@@ -1186,7 +1195,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * When `true`, the selection indexes will be computed whenever a selection is made on or passed to the chart.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    *
    * @default false
    */
@@ -1195,8 +1204,7 @@ export abstract class ArcgisChart extends LitElement {
    * 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.
    *
-   * **Note**: Not applicable to gauge.
-   *           Not applicable to imagery layer charts. It's always `false` for imagery layers. No object ids will be computed.
+   * **Note**: Not applicable to gauges or charts configured with imagery layers. It's always `false` for imagery layers. No object ids will be computed.
    *
    * @default false
    */
@@ -1210,19 +1218,28 @@ export abstract class ArcgisChart extends LitElement {
    * @default false
    */
   accessor rotation: boolean;
-  /** Applies runtime data filters to the chart. */
+  /**
+   * Applies runtime data filters to the chart.
+   *
+   * @example
+   * ```ts
+   * myChart.runtimeDataFilters = {
+   *   where: "FieldValue = 9",
+   * };
+   * ```
+   */
   accessor runtimeDataFilters: WebChartDataFilters | undefined;
   /**
-   * A callback function used to format the secondary y-axis labels. If the returned string contains HTML tags they will be interpreted as such.
+   * 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**: Not applicable to pie chart or gauge.
+   * **Note**: Appliable to bar charts, line charts, combo bar line charts and radar charts.
    */
   accessor secondaryYAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
    * When this property is set, it will apply a selection on the chart matching the provided selection.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
    */
   accessor selectionData: SelectionData | undefined;
   /**
@@ -1237,7 +1254,23 @@ export abstract class ArcgisChart extends LitElement {
    * - 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.
    *
-   * **Note**: Not applicable to gauge.
+   * **Note**: Not applicable to gauges.
+   *
+   * * \@example
+   * ```ts
+   * myChart.selectionTheme = {
+   *   "selectedElementsTheme": {
+   *     "transformation": {
+   *       "scale": 1.2
+   *     }
+   *   },
+   *   "nonSelectedElementsTheme": {
+   *     "transformation": {
+   *       "opacity": 0.5
+   *     }
+   *   }
+   * }
+   * ```
    */
   accessor selectionTheme: SelectionTheme | undefined;
   /**
@@ -1254,7 +1287,7 @@ export abstract class ArcgisChart extends LitElement {
    * 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 gauge.
+   * **Note**: Not applicable to gauges.
    *
    * @default false
    * @since 5.1
@@ -1277,9 +1310,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Whether to skip the chart rendering queue.
    *
-   * When `true`, charts will render immediately without waiting for other charts
-   * to finish rendering. This bypasses the queuing mechanism used by `amChartsOptions.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.
    *
    * @default false
@@ -1309,15 +1340,22 @@ export abstract class ArcgisChart extends LitElement {
   /** Used to set a custom time zone for the chart. */
   accessor timeZone: MapView["timeZone"] | undefined;
   /**
-   * A 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. If the returned string contains HTML tags they will be interpreted as such.
    *
-   * **Note**: Not applicable to gauge.
+   * @example
+   * ```ts
+   * myChart.tooltipFormatter = ({ statValue }) => {
+   *   return `<b>Custom tooltip</b> for ${statValue}`;
+   * };
+   * ```
+   *
+   * **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 config.
+   * 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.
    *
    * **Note**: Applicable only to bar chart, line chart and box plot when a split-by field is used.
@@ -1340,21 +1378,21 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Whether the chart should be refreshed when the view's time extent changes.
    *
-   * **Note**: Not supported for histogram.
+   * **Note**: Not applicable for histograms.
    *
    * @default "ignore"
    */
   accessor viewTimeExtentChangePolicy: ViewTimeExtentChangePolicy;
   /**
-   * A callback function used to format the x-axis labels. If the returned string contains HTML tags they will be interpreted as such.
+   * 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 chart.
+   * **Note**: Not applicable to pie charts.
    */
   accessor xAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
-   * A callback function used to format the y-axis labels. If the returned string contains HTML tags they will be interpreted as such.
+   * 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 chart or gauge.
+   * **Note**: Not applicable to pie charts or gauges.
    */
   accessor yAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
@@ -1409,7 +1447,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Notify method allows passing external messages to the chart component.
    * It can be used to pass validation or information messages.
-   * In a situation where a config update is overriding your notification modal, consider waiting for the `arcgisUpdateComplete` event.
+   * In a situation where a model update is overriding the notification modal, consider waiting for the [@arcgisUpdateComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisUpdateComplete) event.
    *
    * @param message - The message to display in the chart's info modal.
    * @param heading - The heading to display in the chart's info modal.
@@ -1425,7 +1463,7 @@ export abstract class ArcgisChart extends LitElement {
       resetAxesBounds?: boolean;
   }): Promise<void>;
   /**
-   * Resets the chart zoom to bring it back to full extent
+   * Resets the chart zoom to bring it back to full extent.
    *
    * **Note**: Applicable to XY charts only.
    */
@@ -1440,7 +1478,7 @@ export abstract class ArcgisChart extends LitElement {
   readonly arcgisAxesMinMaxChange: import("@arcgis/lumina").TargetedEvent<this, AxesMinMaxChangePayload>;
   /** Event triggered when an error is detected with the data set. */
   readonly arcgisBadDataWarningRaise: import("@arcgis/lumina").TargetedEvent<this, DataWarningObject>;
-  /** Event triggered when the chart is not found for the given `chartIndex` property. */
+  /** Event triggered when the chart is not found for the given [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) property. */
   readonly arcgisChartNotFoundWarning: import("@arcgis/lumina").TargetedEvent<this, string>;
   /** Event triggered when the chart config is changed. */
   readonly arcgisConfigChange: import("@arcgis/lumina").TargetedEvent<this, {
@@ -1453,7 +1491,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * For instance it can be useful to see all the slices before they get grouped into an 'other' slice during the post-processing step.
    *
-   * **Note**: Applicable to pie chart only.
+   * **Note**: Applicable to pie charts only.
    */
   readonly arcgisDataFetchComplete: import("@arcgis/lumina").TargetedEvent<this, WebChartDataTypes>;
   /** Event triggered once the chart data has been processed. */