@arcgis/charts-components 5.1.0-next.99 → 5.1.0

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

@@ -14,6 +14,7 @@ import type { WebChart, WebChartDataFilters } from "../../spec/web-chart.js";
 import type { DataWarningObject, ValidationStatus } from "../../utils/chart-config/validator/interfaces.js";
 import type { AxesMinMaxChangePayload, DataProcessCompletePayload, LegendItemVisibilityChangePayload, NoRenderPropChangePayload, SelectionCompletePayload, SeriesColorChangePayload } from "../../utils/components/event-payloads.js";
 import type { MissingSplitBySeriesProps, DownloadableChartImagesTypes } from "../../utils/components/interfaces.js";
+import type { CalciteThemeCSSVariables } from "../../utils/components/themes.js";
 import type { ActionModes, CursorRange } from "../../utils/cursor/interfaces.js";
 import type { ChartElementLimit } from "../../utils/defaults/interfaces.js";
 import type { LoaderColors, SelectionData, SelectionTheme } from "../../utils/misc/interfaces.js";
@@ -61,7 +62,7 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor animationEnabled: boolean | undefined;
   /**
-   * The ARIA attributes for the chart. Provides accessibility information to assistive technologies such as screen readers. Supports the following properties: [\`label\`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), [\`description\`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), [\`describedByElements\`](https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaDescribedByElements), and [\`labelledByElements\`](https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements).
+   * 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/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), [`description`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), [`describedByElements`](https://developer.mozilla.org/docs/Web/API/Element/ariaDescribedByElements), and [`labelledByElements`](https://developer.mozilla.org/docs/Web/API/Element/ariaLabelledByElements).
    *
    * @since 5.0
    */
@@ -89,6 +90,22 @@ export abstract class ArcgisChart extends LitElement {
    * @default false
    */
   accessor autoInverseDataLabelTextColor: boolean;
+  /**
+   * Allows picking the Calcite CSS variables to use when applying a Calcite theme.
+   *
+   * By default the following variables are used:
+   * - background: `--calcite-color-foreground-1`
+   * - text: `--calcite-color-text-1`
+   * - line: `--calcite-color-border-1`
+   * - secondary line: `--calcite-color-text-3`
+   * - spinner: `--calcite-color-brand-hover`
+   *
+   * The charts colors are overridden by those associated to those CSS variables, but only if they have not been
+   * customized beforehand.
+   *
+   * @since 5.1
+   */
+  accessor calciteThemingCSSVariables: CalciteThemeCSSVariables;
   /**
    * The index of the chart to be rendered from the layer. Must be used in conjunction with the `layerItemId` or `layer` property.
    *
@@ -183,6 +200,12 @@ export abstract class ArcgisChart extends LitElement {
               quarterOfYear: string;
           };
           null: string;
+          accessibility: { gauge: {
+              innerLabel: string;
+              maximumValue: string;
+              minimumValue: string;
+              gauge: string;
+          }; };
       };
       errorStrings: {
           errorHeading: string;
@@ -200,6 +223,8 @@ export abstract class ArcgisChart extends LitElement {
           };
           notifications: {
               invalidConfig: string;
+              invalidConfigForRaster: string;
+              invalidConfigTitle: string;
               invalidSeriesConfig: string;
               invalidSeriesConfigTitle: string;
               validateAggregationTypeMsg: string;
@@ -270,6 +295,7 @@ export abstract class ArcgisChart extends LitElement {
               noDataMessage: string;
               noDataFBSMessage: string;
               noDataFBEMessage: string;
+              noValue: string;
               exportImageChartNotReady: string;
               exportImage: string;
               defaultError: string;
@@ -441,6 +467,12 @@ export abstract class ArcgisChart extends LitElement {
               quarterOfYear: string;
           };
           null: string;
+          accessibility: { gauge: {
+              innerLabel: string;
+              maximumValue: string;
+              minimumValue: string;
+              gauge: string;
+          }; };
       };
       errorStrings: {
           errorHeading: string;
@@ -458,6 +490,8 @@ export abstract class ArcgisChart extends LitElement {
           };
           notifications: {
               invalidConfig: string;
+              invalidConfigForRaster: string;
+              invalidConfigTitle: string;
               invalidSeriesConfig: string;
               invalidSeriesConfigTitle: string;
               validateAggregationTypeMsg: string;
@@ -528,6 +562,7 @@ export abstract class ArcgisChart extends LitElement {
               noDataMessage: string;
               noDataFBSMessage: string;
               noDataFBEMessage: string;
+              noValue: string;
               exportImageChartNotReady: string;
               exportImage: string;
               defaultError: string;
@@ -681,25 +716,6 @@ export abstract class ArcgisChart extends LitElement {
    * @default false
    */
   accessor disableTogglingLegendItems: boolean;
-  /**
-   * Whether to enable automatic chart theming based on Calcite theme detection.
-   *
-   * **Note**: Currently, only the `calcite-mode-dark` theme is supported. When this theme
-   * is applied, all chart colors are automatically adjusted for dark mode and
-   * any custom chart colors will be overridden. This includes series, axes, grid and other elements.
-   *
-   * When `true`, the chart component will automatically apply the
-   * supported Calcite theme if it is detected on the chart container or any
-   * parent element.
-   *
-   * When `false` (default), the chart component will not apply any Calcite-based theming,
-   * even if a supported Calcite theme is detected.
-   *
-   * @default false
-   * @since 5.0
-   * @internal
-   */
-  accessor enableAutoTheming: boolean;
   /**
    * Whether to enable the beta features from the chart component.
    *
@@ -732,7 +748,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * The index of the feature to render when using a feature based gauge.
    *
-   * **Note**: Only applicable to gauges.
+   * **Note**: Applicable to gauges only.
    *
    * @deprecated since 5.0. Use charts model's [featureIndex](https://developers.arcgis.com/javascript/latest/references/charts-components/model/gauge-model/gauge-model/#featureIndex) prop instead.
    */
@@ -772,7 +788,7 @@ export abstract class ArcgisChart extends LitElement {
   accessor guideTooltipFormatter: GuideTooltipFormatCallback | undefined;
   /**
    * When `true`, the empty series are completely hidden from the chart and the legend.
-   * For example, a series may become empty after applying a data filter, filter by attribute or geometry (as when using the filter by extent).
+   * For example, a series may become empty after applying a data filter, filter by attribute or geometry (as when using the filter by view extent).
    *
    * **Note**: Not applicable to gauges.
    *
@@ -808,7 +824,7 @@ export abstract class ArcgisChart extends LitElement {
    * When this property is set to `true`, the dataset will keep these gaps instead of filling them with 0s.
    *
    * When left to `false`,  the chart's dataItems associated with empty (no value) categories (from only a `Count` aggregation)
-   * will be populated with 0s, via the`completeDataForEmptyCategoriesWithZeros` method.
+   * will be populated with 0s.
    *
    * @default false
    * @since 5.1
@@ -870,6 +886,8 @@ export abstract class ArcgisChart extends LitElement {
    *
    * If `layerItemId` is set without `chartIndex`, the first chart in the layer will be rendered.
    *
+   * Supported layers include: `FeatureLayer`, `SubtypeSublayer`, `ImageryLayer`, `ImageryTileLayer` and `WCSLayer`.
+   *
    * @example
    * ```html
    * <arcgis-chart layer-item-id="8871626e970a4f3e9d6113ec63a92f2f" chart-index="2"></arcgis-chart>
@@ -877,13 +895,11 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor layerItemId: string | undefined;
   /**
-   * Allows the chart to update automatically when the layer's renderer changes.
-   * Applies when the color match is enabled.
-   *
-   * @deprecated
-   * since 5.1. Won't be replaced.
+   * Allows the chart to update automatically when the layer's renderer changes. Applies when the color match is enabled.
    *
    * **Note**: If the property is set to `ignore` the chart will still use the layer's renderer information when the data is updated.
+   *
+   * @deprecated since 5.1. Won't be replaced.
    * @default "refresh"
    */
   accessor layerRendererChangePolicy: LayerRendererChangePolicy;
@@ -897,7 +913,7 @@ export abstract class ArcgisChart extends LitElement {
   accessor legendPosition: WebChartLegendPositions | undefined;
   /**
    * A callback function used to format the legend value labels. If the returned string contains HTML tags they will be interpreted as such.
-   * If provided, the formatter will be used if at least `WebChartPieChartLegend.displayNumericValue` or `WebChartPieChartLegend.displayPercentage` is true.
+   * If provided, the formatter will be used if at least [displayNumericValue](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChartPieChartLegend-displayNumericValue) or [displayPercentage](https://developers.arcgis.com/javascript/latest/references/charts-components/spec/web-chart/#WebChartPieChartLegend-displayPercentage) is `true`.
    *
    * **Note**: Applicable to pie charts only.
    */
@@ -914,10 +930,11 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * Defines the colors for the loader animation.
    *
+   * @deprecated since 5.1. Customize the Calcite CSS variables defined by [calciteThemingCSSVariables](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#calciteThemingCSSVariables) instead.
    * @example
    * ```ts
    * // Set a blue curtain and a red spinner for the loader animation
-   * myChart.loaderColors = { curtainColor: [30, 144, 255, 255], spinnerColor: [255, 0, 0, 255] };
+   * chartComponent.loaderColors = { curtainColor: [30, 144, 255, 255], spinnerColor: [255, 0, 0, 255] };
    * ```
    */
   accessor loaderColors: LoaderColors | undefined;
@@ -982,6 +999,12 @@ export abstract class ArcgisChart extends LitElement {
               quarterOfYear?: string | undefined;
           } | undefined;
           null?: string | undefined;
+          accessibility?: { gauge?: {
+              innerLabel?: string | undefined;
+              maximumValue?: string | undefined;
+              minimumValue?: string | undefined;
+              gauge?: string | undefined;
+          } | undefined; } | undefined;
       } | undefined;
       errorStrings?: {
           errorHeading?: string | undefined;
@@ -999,6 +1022,8 @@ export abstract class ArcgisChart extends LitElement {
           } | undefined;
           notifications?: {
               invalidConfig?: string | undefined;
+              invalidConfigForRaster?: string | undefined;
+              invalidConfigTitle?: string | undefined;
               invalidSeriesConfig?: string | undefined;
               invalidSeriesConfigTitle?: string | undefined;
               validateAggregationTypeMsg?: string | undefined;
@@ -1069,6 +1094,7 @@ export abstract class ArcgisChart extends LitElement {
               noDataMessage?: string | undefined;
               noDataFBSMessage?: string | undefined;
               noDataFBEMessage?: string | undefined;
+              noValue?: string | undefined;
               exportImageChartNotReady?: string | undefined;
               exportImage?: string | undefined;
               defaultError?: string | undefined;
@@ -1212,19 +1238,19 @@ export abstract class ArcgisChart extends LitElement {
   accessor queueChartCreation: boolean | undefined;
   /**
    * When `true`, the chart's `dataItems` associated with empty (no value) categories (from only a `Count` aggregation)
-   * will be populated with 0s, via the `completeDataForEmptyCategoriesWithZeros` method.
+   * will be populated with 0s.
    *
    * @deprecated since 5.0. Use [hideZeroCountCategories](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#hideZeroCountCategories) instead.
    * @default false
    */
   accessor replaceNoValueCategoryWithZero: boolean | undefined;
   /**
-   * When `true`, the features extent will be returned through the `arcgisDataProcessComplete` and `arcgisSelectionComplete` events payload.
+   * When `true`, the features extent will be returned through the [@arcgisDataProcessComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisDataProcessComplete) and [@arcgisSelectionComplete](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#event-arcgisSelectionComplete) events payload.
    * Applies only to:
    * - Charts using an aggregation.
    * - Data source using a feature layer compatible with envelope aggregation.
    *
-   * The extent (`IExtent`) is returned through a property called `arcgis_charts_features_extent`.
+   * The extent (IExtent) is returned through the property [featuresExtentField](https://developers.arcgis.com/javascript/latest/references/charts-components/utils/defaults/index/#featuresExtentField).
    *
    * **Note**: Not applicable to gauges.
    *
@@ -1251,7 +1277,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * When `true`, the chart is rotated 90 degrees so that the x-axis becomes vertical and the y-axis becomes horizontal.
    *
-   * **Note**: Applicable to bar chart, line chart, combo bar and line chart and box plot.
+   * **Note**: Applicable to bar chart, line chart, combo bar line chart and box plot.
    *
    * @default false
    */
@@ -1259,7 +1285,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * When `true`, the chart is rotated 90 degrees so that the x-axis becomes vertical and the y-axis becomes horizontal.
    *
-   * **Note**: Applicable to bar chart, line chart, combo bar and line chart and box plot.
+   * **Note**: Applicable to bar chart, line chart, combo bar line chart and box plot.
    *
    * @deprecated since 5.0. Use either [rotated](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#rotated) or the charts model's [rotated](https://developers.arcgis.com/javascript/latest/references/charts-components/model/bar-chart-model/bar-chart-model/#rotated) prop instead.
    * @default false
@@ -1270,7 +1296,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * @example
    * ```ts
-   * myChart.runtimeDataFilters = {
+   * chartComponent.runtimeDataFilters = {
    *   where: "FieldValue = 9",
    * };
    * ```
@@ -1278,9 +1304,8 @@ export abstract class ArcgisChart extends LitElement {
   accessor runtimeDataFilters: WebChartDataFilters | undefined;
   /**
    * Callback function used to format the secondary y-axis labels. If the returned string contains HTML tags they will be interpreted as such.
-   * The property will be effective only if 3 axes are defined (dual axis chart).
    *
-   * **Note**: Appliable to bar charts, line charts, combo bar line charts and radar charts.
+   * **Note**: Appliable to bar charts, line charts, combo bar line charts with dual axes.
    */
   accessor secondaryYAxisLabelFormatter: AxisLabelFormatCallback | undefined;
   /**
@@ -1290,8 +1315,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor selectionData: SelectionData | undefined;
   /**
-   * Selection manager object used to synchronize the selections with the chart when `syncViewSelection` is `true`.
-   * It has precedence over the layer view's [SelectionManager](https://developers.arcgis.com/javascript/latest/references/core/views/SelectionManager/) when both are available.
+   * Selection manager object used to synchronize the selections with the chart when [syncViewSelection](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#syncViewSelection) is `true`.
+   * It has precedence over the layer view's [SelectionManager](/references/core/views/SelectionManager/) when both are available.
    *
    * @since 5.1
    */
@@ -1303,9 +1328,9 @@ export abstract class ArcgisChart extends LitElement {
    *
    * **Note**: Not applicable to gauges.
    *
-   * * \@example
+   * @example
    * ```ts
-   * myChart.selectionTheme = {
+   * chartComponent.selectionTheme = {
    *   "selectedElementsTheme": {
    *     "transformation": {
    *       "scale": 1.2
@@ -1323,7 +1348,7 @@ export abstract class ArcgisChart extends LitElement {
   /**
    * When `true`, the series properties `unit` and `size` become optional and will be automatically set to values that fit the data set. Used when creating or updating a chart compatible with time binning.
    *
-   * **Note**: Only applicable to charts using the temporal binning feature (bar chart, line chart, combo bar and line chart, radar chart).
+   * **Note**: Only applicable to charts using the temporal binning feature (bar chart, line chart, combo bar line chart, radar chart).
    *
    * @default false
    */
@@ -1332,7 +1357,7 @@ export abstract class ArcgisChart extends LitElement {
    * Show the series on the chart even if it doesn't have data (i.e. empty)
    *
    * When `false`, the empty series are completely hidden from the chart and the legend.
-   * For example a series can be empty after applying a data filter, filter by attribute or geometry (as when using the filter by extent).
+   * For example a series can be empty after applying a data filter, filter by attribute or geometry (as when using the filter by view extent).
    *
    * **Note**: Not applicable to gauges.
    *
@@ -1379,14 +1404,14 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncSelection: boolean;
   /**
-   * Determines whether the chart's selection should be synchronized with either the chart's `selectionManager` or the layer view's.
+   * Determines whether the chart's selection should be synchronized with either the chart's [selectionManager](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#selectionManager) or the layer view's.
    *
    * @deprecated since 5.1. Use [syncViewSelection](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#syncViewSelection) prop instead.
    * @default "disabled"
    */
   accessor syncSelectionsBetweenChartAndLayerViewPolicy: SyncSelectionsBetweenChartAndLayerViewPolicy;
   /**
-   * Determines whether the chart's selection should be synchronized with either the chart's `selectionManager` or the layer view's.
+   * Determines whether the chart's selection should be synchronized with either the chart's [selectionManager](https://developers.arcgis.com/javascript/latest/references/charts-components/components/arcgis-chart/#selectionManager) or the layer view's.
    *
    * @default false
    * @since 5.1
@@ -1402,7 +1427,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncViewTimeExtent: boolean;
   /**
-   * Whether the chart's data should be in sync with the view's time zone (`timeZone`).
+   * Whether the chart's data should be in sync with the view's [timeZone](/references/core/views/MapView/#timeZone).
+   *
    * **Note**: This applies only to charts supporting temporal data. Additionally if the data is binned, it applies only if the layer has the
    * capacity to handle the `/queryBins` operation. For any other case the chart will ignore the view's time zone regardless of the value of this property.
    *
@@ -1411,7 +1437,8 @@ export abstract class ArcgisChart extends LitElement {
    */
   accessor syncViewTimeZone: boolean;
   /**
-   * List of chart types to include from syncing the view's time zone (`timeZone`) with the data. Currently heat charts are included by default.
+   * List of chart types to include from syncing the view's [`timeZone`](/references/core/views/MapView/#timeZone) with the data. Currently heat charts are included by default.
+   *
    * **Note**: This applies only to charts supporting temporal data. Additionally if the data is binned, it applies only if the layer has the
    * capacity to handle the `/queryBins` operation. For any other case the chart will ignore the view's time zone regardless of the content of this list.
    *
@@ -1425,10 +1452,6 @@ export abstract class ArcgisChart extends LitElement {
    * ```ts
    * chartComponent.timeZone = "America/Los_Angeles";
    * ```
-   * @example
-   * ```html
-   * <arcgis-chart time-zone="America/Los_Angeles"></arcgis-chart>
-   * ```
    */
   accessor timeZone: MapView["timeZone"] | undefined;
   /**
@@ -1444,7 +1467,7 @@ export abstract class ArcgisChart extends LitElement {
    *
    * @example
    * ```ts
-   * myChart.tooltipFormatter = ({ statValue }) => {
+   * chartComponent.tooltipFormatter = ({ statValue }) => {
    *   return `<b>Custom tooltip</b> for ${statValue}`;
    * };
    * ```
@@ -1538,7 +1561,8 @@ export abstract class ArcgisChart extends LitElement {
    * **Note**: The chart types supported by this method are:
    * - Bar chart
    * - Box plot
-   * - Combo bar and line chart
+   * - Combo bar line chart
+   * - Heat chart
    * - Histogram
    * - Line chart
    * - Pie chart
@@ -1609,7 +1633,11 @@ export abstract class ArcgisChart extends LitElement {
   readonly arcgisDataProcessComplete: import("@arcgis/lumina").TargetedEvent<this, DataProcessCompletePayload>;
   /** Event triggered when an error occurred while fetching of processing the data for the chart. */
   readonly arcgisDataProcessError: import("@arcgis/lumina").TargetedEvent<this, void>;
-  /** Event triggered when an invalid configuration is detected. */
+  /**
+   * Event triggered when an invalid configuration is detected.
+   *
+   * @deprecated since 5.1. Won't be replaced.
+   */
   readonly arcgisInvalidConfigWarningRaise: import("@arcgis/lumina").TargetedEvent<this, DataWarningObject>;
   /** Event triggered once a legend item visibility has been changed. */
   readonly arcgisLegendItemVisibilityChange: import("@arcgis/lumina").TargetedEvent<this, LegendItemVisibilityChangePayload>;