@arcgis/charts-components 5.2.0-next.99 → 6.0.0-next.0

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

@@ -2,7 +2,6 @@
 import type MapView from "@arcgis/core/views/MapView.js";
 import type SceneView from "@arcgis/core/views/SceneView.js";
 import type SelectionManager from "@arcgis/core/views/SelectionManager.js";
-import type FeatureLayerView from "@arcgis/core/views/layers/FeatureLayerView.js";
 import type { DOMContainerAria } from "@arcgis/core/views/DOMContainer.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { AxisLabelFormatCallback, BarAndLineDataLabelFormatCallback, GaugeInnerLabelFormatCallback, GuideTooltipFormatCallback, HistogramLabelFormatCallback, PieChartLabelFormatCallback, PieChartLegendValueLabelFormatCallback, PreRenderCallback, ScatterplotLabelFormatCallback, TooltipFormatters } from "../../chart-rendering/common/interfaces.js";
@@ -22,19 +21,16 @@ import type { ErrorPolicy, LayerFieldsChangePolicy, LayerFilterChangePolicy, Lay
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
 /**
- * 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.
+ * The ArcGIS Chart component renders a chart from a [model](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#model) object that defines the chart's configuration and data.
  *
- * You can render a chart either by:
- * - Setting [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId) and [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) to load a saved chart from a layer item.
- * - Create a new chart by using the [`createModel()`](/references/charts-components/model/shared/setup-utils/#createModel) function to create a chart model and set it to the [model](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#model) property.
- *
- * > [!IMPORTANT]
- * >
- * > See the [Introduction to charts](https://developers.arcgis.com/javascript/latest/charts-components-intro/) guide for detailed examples on how to render a chart using the above patterns.
- *
- * There are 10 supported chart types, each with its own model properties and methods. Refer to the [chart types documentation](https://developers.arcgis.com/javascript/latest/charts/chart-types/) for more information on each chart type.
+ * Depending on your use case, you can:
+ * - Load a saved chart from a layer item by setting [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId) and [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex).
+ * - Create a new model with [`createModel()`](/references/charts-components/model/shared/setup-utils/#createModel), then set it to the [model](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#model) property.
+ * - Load a saved chart from a layer item and customize it by calling [loadModel()](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#loadModel) before making changes to the model.
  *
  * ##### See also:
+ * - [Charts introduction page](https://developers.arcgis.com/javascript/latest/charts/): For an overview of charts and their capabilities.
+ * - [Chart types guide page](https://developers.arcgis.com/javascript/latest/charts/chart-types/): For a complete list of supported chart types and detailed guides.
  * - [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/)
  *
@@ -321,6 +317,13 @@ export abstract class ArcgisChart extends LitElement {
           "Unable to load file: %1": string;
           "Invalid date": string;
       };
+      imageryAoiToolsStrings: {
+          polyline: string;
+          circle: string;
+          rectangle: string;
+          polygon: string;
+          freehandPolygon: string;
+      };
   } & T9nMeta<{
       utilsStrings: {
           chartType: {
@@ -592,6 +595,13 @@ export abstract class ArcgisChart extends LitElement {
           "Unable to load file: %1": string;
           "Invalid date": string;
       };
+      imageryAoiToolsStrings: {
+          polyline: string;
+          circle: string;
+          rectangle: string;
+          polygon: string;
+          freehandPolygon: string;
+      };
   }>;
   /** @internal */
   protected _messages: Partial<{ chartNotFoundWarning: string; }> & T9nMeta<{ chartNotFoundWarning: string; }>;
@@ -764,11 +774,8 @@ 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: 700px; width: 100%; height: auto;"
-   * />
+   *
+   * ![dataLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/dataLabelFormatter.avif)
    *
    * **Note**: Not applicable to gauges and radar charts.
    */
@@ -860,11 +867,7 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * <img
-   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/gaugeInnerLabelFormatter.avif"
-   *   alt="gaugeInnerLabelFormatter"
-   *   style="max-width: 700px; width: 100%; height: auto;"
-   * />
+   * ![gaugeInnerLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/gaugeInnerLabelFormatter.avif)
    *
    * **Note**: Applicable to gauges only.
    */
@@ -883,11 +886,7 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * <img
-   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/guideTooltipFormatter.avif"
-   *   alt="guideTooltipFormatter"
-   *   style="max-width: 700px; width: 100%; height: auto;"
-   * />
+   * ![guideTooltipFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/guideTooltipFormatter.avif)
    *
    * **Note**: Not applicable to pie charts.
    */
@@ -953,11 +952,11 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor ignoreSmoothRenderingLimit: boolean;
   /**
-   * When `true`, it signals the queries to ignore the view's extent, whether an additional geometry filter is provided or not.
+   * When `true`, it signals the queries to ignore the view's [`extent`](/references/core/views/MapView/#extent), whether an additional geometry filter is provided or not.
    *
-   * 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/).
+   * This property will be effective when the component's [view](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#view) property is provided or when the [layer](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layer) property is set to [ChartLayerView](https://developers.arcgis.com/javascript/latest/references/charts-components/interfaces/#ChartLayerView).
    *
-   * By default the queries made by the chart will consider the view's extent as the unique geometry filter applicable. This implies ignoring any
+   * By default the queries made by the chart will consider the view's [`extent`](/references/core/views/MapView/#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
@@ -971,9 +970,9 @@ export abstract class ArcgisChart extends LitElement {
   accessor interactionsDisabled: boolean;
   /**
    * Used to perform queries.
-   * If the layer is a `FeatureLayerView` or if the layer and the `view` property are both provided, the queries will be executed client-side.
+   * If the layer is a `ChartLayerView` or if the layer and the `view` property are both provided, the queries will be executed client-side.
    */
-  accessor layer: ChartLayerInput | FeatureLayerView | undefined;
+  accessor layer: ChartLayerInput | undefined;
   /**
    * Allows the chart to update automatically when the layer's `fields` property changes.
    *
@@ -1046,11 +1045,7 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * <img
-   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/legendValueLabelFormatter.avif"
-   *   alt="legendValueLabelFormatter"
-   *   style="max-width: 400px; width: 100%; height: auto;"
-   * />
+   * ![legendValueLabelFormatter](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/legendValueLabelFormatter.avif)
    *
    * **Note**: Applicable to pie charts only.
    */
@@ -1369,6 +1364,13 @@ export abstract class ArcgisChart extends LitElement {
           "Unable to load file: %1"?: string | undefined;
           "Invalid date"?: string | undefined;
       } | undefined;
+      imageryAoiToolsStrings?: {
+          polyline?: string | undefined;
+          circle?: string | undefined;
+          rectangle?: string | undefined;
+          polygon?: string | undefined;
+          freehandPolygon?: string | undefined;
+      } | undefined;
   } & { chartNotFoundWarning?: string | undefined; };
   /**
    * Provides an API to interact with the chart's configuration.
@@ -1536,11 +1538,26 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * <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;"
-   * />
+   * ![selectionOIDs](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionData_selectionOIDs.avif)
+   *
+   * ##### Selection by indexes
+   * When passing in a `selectionIndexes` map, the chart will match the provided indexes with the chart's data items and apply the selection.
+   * @example
+   * ```ts
+   * // This selects the first and third chart data items.
+   * chartElement.selectionData = {
+   *   selectionIndexes: new Map([
+   *     // Selects the first and third data items ("Bronx" and "Manhattan") for the first series ("Entire home/apt").
+   *     [0, { indexesToSelect: [0, 2] }],
+   *     // Selects the second data item ("Brooklyn") for the second series ("Private room").
+   *     [1, { indexesToSelect: [1] }],
+   *     // With no indexesToSelect provided, all data items for the third series ("Shared room") are selected.
+   *     [2, {}],
+   *   ]),
+   * };
+   * ```
+   *
+   * ![selectionIndexes](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionData_selectionIndexes.avif)
    *
    * ##### Selection by items
    * When passing in a `selectionItems` array, the chart will match the provided items with the chart's data items and apply the selection.
@@ -1559,19 +1576,20 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * <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;"
-   * />
+   * ![selectionItems](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionData_selectionItems.avif)
    *
    * **Note**: Not applicable to gauges.
    */
   accessor selectionData: SelectionData | undefined;
   /**
-   * 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.
+   * Use this property to supply a custom selection manager for charts.
+   * This is useful when applications want to share selection sets between components, without relying on the view's [SelectionManager](/references/core/views/SelectionManager/).
    *
+   * @example
+   * ```ts
+   * // Sync chart's selection manager with another component's selection manager (e.g. feature table)
+   * chartElement.selectionManager = featureTableElement.selectionManager;
+   * ```
    * @since 5.1
    */
   accessor selectionManager: SelectionManager | undefined;
@@ -1602,11 +1620,7 @@ export abstract class ArcgisChart extends LitElement {
    * };
    * ```
    *
-   * <img
-   *   src="https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionTheme.avif"
-   *   alt="selectionTheme"
-   *   style="max-width: 700px; width: 100%; height: auto;"
-   * />
+   * ![selectionTheme](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/selectionTheme.avif)
    *
    * **Note**: Not applicable to gauges.
    */
@@ -1640,11 +1654,7 @@ export abstract class ArcgisChart extends LitElement {
    * 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;"
-   * />
+   * ![showEmptySeries](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/showEmptySeries.avif)
    *
    * **Note**: Not applicable to gauges.
    * @since 5.1
@@ -1685,11 +1695,7 @@ export abstract class ArcgisChart extends LitElement {
    * 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;"
-   * />
+   * ![syncChartsSelection](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/syncChartsSelection.avif)
    * @since 5.1
    */
   accessor syncChartsSelection: boolean;
@@ -1701,21 +1707,21 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncSelection: boolean;
   /**
-   * 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.
+   * When `true`, chart selections will be synchronized with the view's [SelectionManager](/references/core/views/SelectionManager/).
    *
    * @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](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#selectionManager) or the layer view's.
+   * When `true`, chart selections will be synchronized with the view's [SelectionManager](/references/core/views/SelectionManager/).
    *
    * @default false
    * @since 5.1
    */
   accessor syncViewSelection: boolean;
   /**
-   * Whether the chart should be refreshed when the view's time extent changes.
+   * When `true`, the chart will be refreshed when the view's [`timeExtent`](/references/core/views/MapView/#timeExtent) changes.
    *
    * **Note**: Not supported for histogram.
    *
@@ -1724,10 +1730,10 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncViewTimeExtent: boolean;
   /**
-   * Whether the chart's data should be in sync with the view's [timeZone](/references/core/views/MapView/#timeZone).
+   * When `true`, the chart's data will 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.
+   * **Note**: Applicable only to bar, line, combo bar-line, heat and radar charts that use temporal data.
+   * For binned data, the layer must support the `/queryBins` operation. Otherwise, the chart ignores the view's time zone.
    *
    * @default false
    * @since 5.1
@@ -1743,11 +1749,21 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncViewTimeZoneInclusionList: (typeof WebChartTypes.BarSeries | typeof WebChartTypes.ComboLineAndBarSeries | typeof WebChartTypes.HeatSeries | typeof WebChartTypes.LineSeries | typeof WebChartTypes.RadarSeries)[];
   /**
-   * Used to set a custom time zone for the chart.
+   * Defines the time zone used to display date and time values in the chart. The underlying data is not modified.
+   *
+   * | America/New_York | Europe/Helsinki |
+   * |---|---|
+   * |![timeZone_NewYork](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/timeZone_newYork.avif) | ![timeZone_Helsinki](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/timeZone_helsinki.avif) |
    *
+   * **Note**: Applicable only to bar, line, combo bar-line, and heat and radar charts that use temporal data.
+   * For binned data, the layer must support the `/queryBins` operation. Otherwise, the chart ignores
+   * the view's time zone.
+   *
+   * @see [Wikipedia - List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
    * @example
    * ```ts
-   * chartComponent.timeZone = "America/Los_Angeles";
+   * // Display date and time values in the specified time zone.
+   * chartElement.timeZone = "Europe/Helsinki";
    * ```
    */
   accessor timeZone: MapView["timeZone"] | undefined;
@@ -1779,6 +1795,20 @@ export abstract class ArcgisChart extends LitElement {
    * **Note**: Not applicable to gauges.
    */
   accessor tooltipFormatter: TooltipFormatters | undefined;
+  /**
+   * When `true`, the chart title, subtitle, and footer are limited to two lines. Text that exceeds the available space is
+   * truncated with an ellipsis, helping reserve more space for the chart itself. Axis titles are not affected.
+   *
+   * By default, these labels wrap according to the available space without a two-line limit.
+   *
+   * | With `truncateLongTitles` | Without `truncateLongTitles` |
+   * | -------- | -------- |
+   * | ![truncateLongTitles true](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/truncateLongTitlesTrue.avif) | ![truncateLongTitles false](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/truncateLongTitlesFalse.avif) |
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor truncateLongTitles: boolean;
   /**
    * Whether to automatically add the missing series to cover the split-by values not referenced in the configuration.
    * - This property only applies to plain chart configuration object that's constructed following the [WebChart](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChart) specification.
@@ -1946,7 +1976,7 @@ export abstract class ArcgisChart extends LitElement {
   loadModel(): Promise<void>;
   /**
    * Passes external messages to the chart component and displays them in the chart's container.
-   * When a model update is overriding the notification modal, consider waiting for the [@arcgisUpdateComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisUpdateComplete) event.
+   * When a model update is overriding the notification modal, consider waiting for the [@arcgisRenderingComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisRenderingComplete) event.
    *
    * @param message - The message to display in the chart's container.
    * @param heading - The heading to display in the chart's container.