@arcgis/charts-components 6.0.0-next.1 → 6.0.0-next.11

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

@@ -703,11 +703,11 @@ export abstract class ArcgisChart extends LitElement {
    */
   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.
+   * The index of the chart to be rendered from the layer. Must be used in conjunction with the [layer](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layer), [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId),  or [mapLayerId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#mapLayerId) property.
    *
-   * If a `layer` or `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
+   * If [layer](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layer), [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId),  or [mapLayerId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#mapLayerId) 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.
+   * If `chartIndex` is out of bounds, the first chart in the layer will be rendered and a warning event will be emitted.
    *
    * @example
    * ```html
@@ -718,17 +718,43 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * 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.
+   * 1. The chart's behavior once that limit is reached can be adjusted through the [`behaviorAfterLimit`](/references/charts-components/utils/defaults/interfaces/#ChartElementLimit-behaviorAfterLimit) nested property.
+   *     - `reject`: Reject the creation or update of the chart when the limit is reached.
+   *     - `renderUpToTheLimit`: Render the elements up to the given limits.
+   * 2. Specific limits for each chart type can be defined with the following nested properties.
+   *     - [`serialChart`](/references/charts-components/utils/defaults/interfaces/#ChartElementLimit-serialChart): Bar chart, line chart, combo bar line chart and radar chart.
+   *       - [`series`](/references/charts-components/utils/defaults/interfaces/#SerialChartLimit-series), [`elements`](/references/charts-components/utils/defaults/interfaces/#SerialChartLimit-elements) and [`categories`](/references/charts-components/utils/defaults/interfaces/#SerialChartLimit-categories) limits can be specified.
+   *     - [`boxPlot`](/references/charts-components/utils/defaults/interfaces/#ChartElementLimit-boxPlot): [`series`](/references/charts-components/utils/defaults/interfaces/#SerialChartLimit-series), [`elements`](/references/charts-components/utils/defaults/interfaces/#SerialChartLimit-elements), [`categories`](/references/charts-components/utils/defaults/interfaces/#SerialChartLimit-categories) and `outliers` limits can be specified.
+   *     - [`heatChart`](/references/charts-components/utils/defaults/interfaces/#ChartElementLimit-heatChart): `cells` limits can be specified.
+   *     - [`scatterplot`](/references/charts-components/utils/defaults/interfaces/#ChartElementLimit-scatterplot): `aggregationThreshold` and `markersAfterAggregation` limits can be specified.
+   *     - [`pieChart`](/references/charts-components/utils/defaults/interfaces/#ChartElementLimit-pieChart): `slices` limits can be specified.
+   *     - [`gauge`](/references/charts-components/utils/defaults/interfaces/#ChartElementLimit-gauge): `features` limits can be specified.
+   *
+   * Default limits when `chartLimits` is not set:
+   * - Except for scatterplots, limits are enforced by rejecting chart creation or updates. No maximum category count is set by default.
+   *   - The [@arcgisBadDataWarningRaise](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisBadDataWarningRaise) event is emitted and, by default, a "Too many features" or "No data available to display" warning message is displayed in the chart container. Set [hideUIMessages](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#hideUIMessages) to `true` to hide the warning.
+   * - Specific limits for each chart type are as follows:
+   *   - Bar chart, box plot: Up to 100 series. With one series, up to 10,000 elements total; with two series, up to 1,000 per series and 2,000 total; with three or more series, up to 100 per series and 2,000 total. Box plots also allow up to 10,000 outliers.
+   *   - Line chart, radar chart: Up to 100 series. With one series, up to 10,000 markers total; with two series, up to 5,000 per series and 10,000 total; with three or more series, up to 1,000 per series and 10,000 total.
+   *   - Histogram: Up to 64 bins, the default is 32 bins.
+   *   - Pie chart: Up to 300 slices.
+   *   - Heat chart: Up to 10,000 cells.
+   *   - Scatterplot: Aggregation starts after 10,000 markers; displays up to 10,000 aggregated markers.
+   *   - Gauge by feature: Up to 50 features.
    *
    * @example
    * ```ts
+   * // Set the maximum number of categories to 15 for the bar chart (part of the serial chart).
    * chartElement.chartLimits = {
-   *   behaviorAfterLimit: LimitBehavior.RenderUpToTheLimit,
+   *   behaviorAfterLimit: "renderUpToTheLimit",
    *   serialChart: { categories: 15 }
    * };
+   *
+   * // Reject the creation or update of the pie chart when the slices count exceeds 10.
+   * chartElement.chartLimits = {
+   *   behaviorAfterLimit: "reject",
+   *   pieChart: { slices: 10 }
+   * };
    * ```
    */
   accessor chartLimits: ChartElementLimit | undefined;
@@ -918,7 +944,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor hideLoaderAnimation: boolean;
   /**
-   * When set to `true`, UI messages are hidden. These messages can be no data warnings, any placeholder messages set or invalid chart configuration.
+   * When `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
@@ -970,7 +996,12 @@ export abstract class ArcgisChart extends LitElement {
   accessor interactionsDisabled: boolean;
   /**
    * Used to perform queries.
-   * If the layer is a `ChartLayerView` or if the layer and the `view` property are both provided, the queries will be executed client-side.
+   *
+   * Charts supports feature-like and imagery layers. Feature-like layers must implement the properties and methods defined by [`ChartLayer`](/references/charts-components/interfaces/#ChartLayer).
+   * - Feature-like layers: [`CatalogLayer`](/references/core/layers/CatalogLayer/), [`CSVLayer`](/references/core/layers/CSVLayer/), [`FeatureLayer`](/references/core/layers/FeatureLayer/), [`GeoJSONLayer`](/references/core/layers/GeoJSONLayer/), [`ParquetLayer`](/references/core/layers/ParquetLayer/), [`WFSLayer`](/references/core/layers/WFSLayer/)
+   * - Imagery layers: [`ImageryLayer`](/references/core/layers/ImageryLayer/), [`ImageryTileLayer`](/references/core/layers/ImageryTileLayer/), [`OrientedImageryLayer`](/references/core/layers/OrientedImageryLayer/), [`WCSLayer`](/references/core/layers/WCSLayer/)
+   *
+   * **Note**: Queries run client-side when [layer](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layer) is a [`ChartLayerView`](/references/charts-components/interfaces/#ChartLayerView), or when both [layer](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layer) and [view](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#view) are provided.
    */
   accessor layer: ChartLayerInput | undefined;
   /**
@@ -988,12 +1019,13 @@ 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. If `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
+   * Layer item ID associated with the chart to be rendered. Can be used in conjunction with the [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) property.
+   * If `layerItemId` is set without [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex), the first chart in the layer will be rendered.
    *
-   * The layer item ID can be found in the URL of the layer's item page on ArcGIS Online or Enterprise.
-   * For example, in the URL `https://www.arcgis.com/home/item.html?id=8871626e970a4f3e9d6113ec63a92f2f`, the layer item ID is `8871626e970a4f3e9d6113ec63a92f2f`.
+   * Supported layer types include: [`FeatureLayer`](/references/core/layers/FeatureLayer), [`ParquetLayer`](/references/core/layers/ParquetLayer),[`ImageryLayer`](/references/core/layers/ImageryLayer), [`ImageryTileLayer`](/references/core/layers/ImageryTileLayer), [`WCSLayer`](/references/core/layers/WCSLayer) and [`OrientedImageryLayer`](/references/core/layers/OrientedImageryLayer).
    *
-   * 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).
+   * > 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`.
    *
    * @example
    * ```html
@@ -1070,6 +1102,21 @@ export abstract class ArcgisChart extends LitElement {
    * ```
    */
   accessor loaderColors: LoaderColors | undefined;
+  /**
+   * The ID of the map layer containing the chart. Can be used in conjunction with the [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex) property. The [map layer ID](/references/core/layers/Layer/#id) can be found by inspecting the layer's properties.
+   * If `mapLayerId` is set without [chartIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#chartIndex), the first chart in the layer will be rendered.
+   *
+   * > [!WARNING]
+   * > Use [layer](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layer), [mapLayerId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#mapLayerId), and [layerItemId](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#layerItemId) independently; only one should be set at a time.
+   *
+   * @see [Tutorial: Chart and map interactions](https://developers.arcgis.com/javascript/latest/tutorials/chart-and-map-interactions/)
+   * @example
+   * ```ts
+   * <arcgis-chart map-layer-id="1a116fff2bf-layer-2" chart-index="2"></arcgis-chart>
+   * ```
+   * @since 5.2
+   */
+  accessor mapLayerId: string | undefined;
   /**
    * Custom messages for translated strings on the chart. If the returned string contains HTML tags they will be interpreted as such.
    *
@@ -1387,8 +1434,8 @@ export abstract class ArcgisChart extends LitElement {
    * 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.
+   * 1. The [@arcgisBadDataWarningRaise](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisBadDataWarningRaise) event will be sent.
+   * 2. The "No data available to display" warning message will be displayed in the chart container.
    *
    * @default false
    */
@@ -1418,6 +1465,17 @@ export abstract class ArcgisChart extends LitElement {
    * @default false
    */
   accessor queueChartCreation: boolean | undefined;
+  /**
+   * By assigning the `id` attribute of the [Map component](/references/map-components/components/arcgis-map/) to this property, you can position the chart component anywhere in the DOM while still maintaining a connection to the Map.
+   *
+   * @example
+   * ```html
+   * <arcgis-map id="my-map"></arcgis-map>
+   * <arcgis-chart reference-element="my-map"></arcgis-chart>
+   * ```
+   * @since 5.2
+   */
+  accessor referenceElement: HTMLElement | string | undefined;
   /**
    * When `true`, the chart's `dataItems` associated with empty (no value) categories (from only a `Count` aggregation)
    * will be populated with 0s.
@@ -1477,11 +1535,14 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * 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`.
+   * Supported keys are [`where`](/references/charts-components/spec/web-chart/#WebChartQuery-where), [`objectIds`](/references/charts-components/spec/web-chart/#WebChartQuery-objectIds), [`geometry`](/references/charts-components/spec/web-chart/#WebChartQuery-geometry),
+   * [`spatialRelationship`](/references/charts-components/spec/web-chart/#WebChartQuery-spatialRelationship), [`distance`](/references/charts-components/spec/web-chart/#WebChartQuery-distance),
+   * [`units`](/references/charts-components/spec/web-chart/#WebChartQuery-units), [`timeExtent`](/references/charts-components/spec/web-chart/#WebChartQuery-timeExtent), and [`gdbVersion`](/references/charts-components/spec/web-chart/#WebChartQuery-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.
+   * // 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();
    *
@@ -1525,10 +1586,11 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor secondaryYAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
-   * Applies a programmatic selection to the chart. The payload can target chart elements by object IDs (`selectionOIDs`), by indexes (`selectionIndexes`), or by items (`selectionItems`).
+   * Applies a programmatic selection to the chart. The payload can target chart elements by [`selectionOIDs`](/references/charts-components/utils/misc/interfaces/#SelectionData-selectionOIDs),
+   * by [`selectionIndexes`](/references/charts-components/utils/misc/interfaces/#SelectionData-selectionIndexes), or by [`selectionItems`](/references/charts-components/utils/misc/interfaces/#SelectionData-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.
+   * When passing in a [`selectionOIDs`](/references/charts-components/utils/misc/interfaces/#SelectionData-selectionOIDs) array, the chart will match the provided object IDs with the chart's data items and apply the selection.
    *
    * @example
    * ```ts
@@ -1541,7 +1603,7 @@ export abstract class ArcgisChart extends LitElement {
    * ![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.
+   * When passing in a [`selectionIndexes`](/references/charts-components/utils/misc/interfaces/#SelectionData-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.
@@ -1560,7 +1622,7 @@ export abstract class ArcgisChart extends LitElement {
    * ![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.
+   * When passing in a [`selectionItems`](/references/charts-components/utils/misc/interfaces/#SelectionData-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.
@@ -1717,6 +1779,19 @@ export abstract class ArcgisChart extends LitElement {
    * When `true`, chart selections will be synchronized with the view's [SelectionManager](/references/core/views/SelectionManager/).
    *
    * @default false
+   * @example
+   * ```html
+   * <!-- Selecting the `Asia` slice on the chart will select the corresponding features on the map. -->
+   * <arcgis-map item-id="87936e6706144627b7c067ebd515da0c">
+   *   <arcgis-chart
+   *     map-layer-id="1a116fff2bf-layer-2"
+   *     chart-index="3"
+   *     slot="bottom-right"
+   *     sync-view-selection
+   *   ></arcgis-chart>
+   * </arcgis-map>
+   * ```
+   * ![syncViewSelection](https://developers.arcgis.com/javascript/latest/assets/references/components/chart/syncViewSelection.avif)
    * @since 5.1
    */
   accessor syncViewSelection: boolean;
@@ -1833,7 +1908,14 @@ export abstract class ArcgisChart extends LitElement {
    * @default false
    */
   accessor usePopupTemplateFieldsInfo: boolean;
-  /** Used to access the feature layer view instance in order to perform client side queries. */
+  /**
+   * Used to access the feature layer view instance in order to perform client side queries.
+   *
+   * An explicitly assigned view takes precedence over the view inferred from
+   * [referenceElement](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#referenceElement) or an ancestor map component.
+   * Set this property to `undefined` to resume using the inferred view.
+   * Reading this property returns the effective view.
+   */
   accessor view: MapView | SceneView | undefined;
   /**
    * Whether the chart should be refreshed when the view's time extent changes.
@@ -1878,12 +1960,11 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor yAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
-   * When `true`, count=0 is considered a valid statistic.
+   * When `true`, `count=0` is considered a valid statistic.
    *
-   * By default, when the aggregation type is "count" and the data contains only values equal to 0, 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.
+   * By default, when the aggregation type is "count" and the data contains only values equal to 0, the chart dataset is considered empty:
+   * 1. The [@arcgisBadDataWarningRaise](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisBadDataWarningRaise) event will be sent.
+   * 2. The "No data available to display" warning message will be displayed in the chart container.
    *
    * @default false
    * @since 5.2
@@ -1930,8 +2011,8 @@ export abstract class ArcgisChart extends LitElement {
    * });
    * ```
    *
+   * The exported CSV file will contain the following data:
    * ```csv
-   * // The exported CSV file will contain the following data:
    * sep=|
    * "Bronx"|"Entire home/apt"|"379"
    * "Bronx"|"Private room"|"652"
@@ -1958,7 +2039,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * @example
    * ```html
-   * // Load a chart from a layer item
+   * <!-- Load a chart from a layer item -->
    * <arcgis-chart layer-item-id="8871626e970a4f3e9d6113ec63a92f2f" chart-index="2" />
    * ```
    * ```ts
@@ -1982,6 +2063,7 @@ export abstract class ArcgisChart extends LitElement {
    * @param heading - The heading to display in the chart's container.
    * @example
    * ```html
+   * <!-- Buttons to show and clear notifications -->
    * <button id="show-notification" type="button">Show notification</button>
    * <button id="clear-notification" type="button">Clear notification</button>
    * ```