@arcgis/charts-components 5.0.0-next.10 → 5.0.0-next.100

package/dist/utils/components/themes.d.ts

@@ -0,0 +1,133 @@
+import { ChartOptions } from '../../chart-rendering/common/interfaces';
+import { EsriColor } from '../../chart-rendering/common/types';
+import { ArcgisChart } from '../../components/arcgis-chart/customElement.js';
+import { Color, WebChartBarChartSeries, WebChartBoxPlotSeries, WebChartHistogramSeries, WebChartLineChartSeries, WebChartOverlay, WebChartPieChartSlice, WebChartRadarChartSeries, WebChartScatterplotSeries } from '../../spec';
+/**
+ * Interface representing the list of colors a theme can provide.
+ */
+export interface ChartThemeColors {
+    backgroundColor?: EsriColor;
+    textColor?: EsriColor;
+    lineColor?: EsriColor;
+    secondLineColor?: EsriColor;
+}
+/**
+ * Indicates whether the Calcite dark mode is enabled on the DOM.
+ * @param chartElement The chart element
+ */
+export declare function isCalciteDarkModeEnabled(chartElement: HTMLElement): boolean;
+/**
+ * Retrieves the Calcite dark theme colors from the css variables.
+ * @param chartElement The chart element
+ */
+declare function getCalciteDarkThemeColors(chartElement: Element): ChartThemeColors;
+/**
+ * Applies the theme colors to the axes.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToAxes(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Applies the theme colors to the background.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToBackground(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Applies the theme colors to the title, footer and subtitle.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToTitleFooterSubtitle(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Updates the overlay symbol color (if the overlay is created and visible).
+ * @param overlayColor The color to set
+ * @param overlay The overlay to update
+ */
+declare function updateOverlaySymbolColor(overlayColor: Color, overlay?: WebChartOverlay): void;
+/**
+ * Updates the marker symbol color.
+ * @param props.configElementWithFillSymbol The config element with marker symbol to update
+ * @param props.markerColor The marker color to set
+ * @param props.lineColor The line color to set (optional)
+ */
+declare function updateMarkerSymbolColor(props: {
+    configElementWithFillSymbol: WebChartLineChartSeries | WebChartRadarChartSeries | WebChartScatterplotSeries;
+    markerColor: Color;
+    lineColor?: Color;
+}): void;
+/**
+ * Updates the fill symbol color.
+ * @param props.configElementWithFillSymbol The config element with fill symbol to update
+ * @param props.fillColor The fill color to set
+ * @param props.lineColor The line color to set (optional)
+ */
+declare function updateFillSymbolColor(props: {
+    configElementWithFillSymbol: WebChartBarChartSeries | WebChartBoxPlotSeries | WebChartHistogramSeries | WebChartPieChartSlice;
+    fillColor: Color;
+    lineColor?: Color;
+}): void;
+/**
+ * Applies the theme colors to the series.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToSeries(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Applies the theme colors to pie chart specific properties.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToPieChartSeries(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Applies the theme colors to the legend.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToLegend(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Applies the theme colors to gauge specific properties.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToGauge(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Applies the theme colors to heat chart specific properties.
+ * @param config The config to alter
+ * @param themeColors The theme colors to apply
+ */
+declare function applyThemeColorsToHeatChart(config: ArcgisChart["config"], themeColors: ChartThemeColors): void;
+/**
+ * Applies the theme to the loader colors in the chart options.
+ * @param props.options The chart options
+ * @param props.calciteThemeApplied The currently applied calcite theme
+ * @param props.config The chart config
+ * @returns The altered chart options
+ */
+export declare function applyThemeToLoaderColors(props: {
+    options: ChartOptions;
+    calciteThemeApplied: ArcgisChart["calciteThemeApplied"];
+    config: ArcgisChart["config"];
+}): ChartOptions;
+/**
+ * Apply a theme colors to the chart config.
+ * The only theme supported currently is the Calcite dark mode.
+ * @param chartElement The chart element
+ * @param config The chart config
+ */
+export declare function applyThemeColors(chartElement: HTMLArcgisChartElement, config: ArcgisChart["config"]): ArcgisChart["config"];
+export declare const commonThemesPrivateFunctions: {
+    applyThemeColorsToAxes: typeof applyThemeColorsToAxes;
+    applyThemeColorsToBackground: typeof applyThemeColorsToBackground;
+    applyThemeColorsToTitleFooterSubtitle: typeof applyThemeColorsToTitleFooterSubtitle;
+    applyThemeColorsToSeries: typeof applyThemeColorsToSeries;
+    applyThemeColorsToPieChartSeries: typeof applyThemeColorsToPieChartSeries;
+    applyThemeColorsToLegend: typeof applyThemeColorsToLegend;
+    applyThemeColorsToGauge: typeof applyThemeColorsToGauge;
+    applyThemeColorsToHeatChart: typeof applyThemeColorsToHeatChart;
+    getCalciteDarkThemeColors: typeof getCalciteDarkThemeColors;
+    updateOverlaySymbolColor: typeof updateOverlaySymbolColor;
+    updateFillSymbolColor: typeof updateFillSymbolColor;
+    updateMarkerSymbolColor: typeof updateMarkerSymbolColor;
+};
+export {};

package/dist/utils/components/watch-handlers.d.ts

@@ -1,37 +1,37 @@
 import { ArcgisChart } from '../../components/arcgis-chart/customElement.js';
 /**
- * Adds a listener on the feature layer, so every time the definition expression (filter) is modified we update
+ * Adds a watch handler on the feature layer, so every time the definition expression (filter) is modified we update
  * the chart.
  *
  * @param component The chart component
  */
-export declare function addLayerFilterListener(component: ArcgisChart): Promise<IHandle | undefined>;
+export declare function watchLayerFilter(component: ArcgisChart): IHandle | undefined;
 /**
- * Adds a listener on the feature layer, so every time the renderer is modified we update the chart.
+ * Adds a watch handler on the feature layer, so every time the renderer is modified we update the chart.
  *
  * @param component The chart component
  */
-export declare function addLayerRendererListener(component: ArcgisChart): Promise<IHandle | undefined>;
+export declare function watchLayerRenderer(component: ArcgisChart): IHandle | undefined;
 /**
- * Adds a listener on the feature layer view, so every time the view's extent is modified we update
+ * Adds a watch handler on the feature layer view, so every time the view's extent is modified we update
  * the chart.
  *
  * @param props.component The chart component
  */
-export declare function addExtentChangeListener(component: ArcgisChart): Promise<IHandle[] | undefined>;
+export declare function watchExtentChange(component: ArcgisChart): Promise<IHandle[] | undefined>;
 /**
- * Adds a listener on the view's time extent, so every time extent is modified we update the chart.
+ * Adds a watch handler on the view's time extent, so every time extent is modified we update the chart.
  * @param component The chart component
  */
-export declare function addViewTimeExtentListener(component: ArcgisChart): Promise<IHandle | undefined>;
+export declare function watchViewTimeExtent(component: ArcgisChart): IHandle | undefined;
 /**
- * Adds a listener on the feature layer, so every time the fields are modified we update the chart.
+ * Adds a watch handler on the feature layer, so every time the fields are modified we update the chart.
  *
  * @param component The chart component
  */
-export declare function addLayerFieldsListener(component: ArcgisChart): Promise<IHandle | undefined>;
+export declare function watchLayerFields(component: ArcgisChart): IHandle | undefined;
 /**
- * Adds a listener on the layer's view; so every time the selection data is modified, we update the chart.
+ * Adds a watch handler on the layer's view; so every time the selection data is modified, we update the chart.
  * @param component The chart component
  */
-export declare function addSelectionsChangeInViewListener(component: ArcgisChart): Promise<IHandle | undefined>;
+export declare function watchSelectionsChangeInView(component: ArcgisChart): IHandle | undefined;

package/dist/utils/components/web-component-utils.d.ts

@@ -1,28 +1,23 @@
-import { CSVOptions } from '../../interfaces';
-import { ModelTypes } from '../../model';
-import { IField, SupportedLayer } from '../../spec';
-import { ChartConfig } from '../types';
 import { default as FeatureLayerView } from '@arcgis/core/views/layers/FeatureLayerView.js';
+import { SupportedLayer, CSVOptions } from '../../interfaces';
+import { ModelTypes } from '../../model';
+import { IField } from '../../spec';
 import { SupportedLocalesForFormats } from '../localization/interfaces';
+import { ChartConfig } from '../types';
 /**
  * A utility function to compare if a value has changed deeply.
- * @param value
- * @param oldValue
  */
 export declare function hasChangedDeep<T>(value: T, oldValue?: T): boolean;
 /**
  * A utility function to compare if a value has changed deeply or shallowly.
- * @param value
- * @param oldValue
  */
 export declare function hasChangedDeepOrShallow<T>(value: T, oldValue?: T): boolean;
 /**
  * Formats a cell value for CSV output.
  * This function handles quoting and escaping of special characters.
- * @param {unknown} value - The value to format.
- * @param {boolean} [quoteAll] - Whether to quote all values.
- *                               If `true`, all values will be quoted.
- *                               If `false` or `undefined`, only values that contain special characters will be quoted.
+ *
+ * @param value - The value to format.
+ * @param quoteAll - Whether to quote all values. If `true`, all values will be quoted. If `false` or `undefined`, only values that contain special characters will be quoted.
  */
 export declare const formatCell: (props: {
     value: unknown;
@@ -31,6 +26,7 @@ export declare const formatCell: (props: {
 }) => string;
 /**
  * Converts an array of objects to a CSV string.
+ *
  * @param data - The data to convert.
  * @param options - Options for CSV conversion.
  * @returns The CSV string.
@@ -39,10 +35,11 @@ export declare function arrayToCSV<T extends Record<string, unknown>>(data: T[],
 /**
  * Transform the raw data to a format that is suitable for exporting to CSV.
  * This function is used to transform the data before it is passed to the CSV export function.
- * @param props.config - [Optional] The chart configuration that defines the chart type and data transformation.
+ *
+ * @param props.config - The chart configuration that defines the chart type and data transformation.
  * @param props.rawData - The raw data to be transformed, which is an array of objects.
- * @param props.layer - [Optional] The layer associated with the chart, used for additional data context.
- * @param props.fieldList - [Optional] The list of fields in the layer, used to determine field types and names.
+ * @param props.layer - The layer associated with the chart, used for additional data context.
+ * @param props.fieldList - The list of fields in the layer, used to determine field types and names.
  */
 export declare function transformChartData<T extends Record<string, unknown>>(props: {
     config?: ChartConfig;
@@ -52,12 +49,14 @@ export declare function transformChartData<T extends Record<string, unknown>>(pr
 }): T[];
 /**
  * Transform the histogram data to a format that is suitable for exporting to CSV.
+ *
  * @param config - The histogram model or config
  * @param rows - The raw data to be transformed.
  */
 export declare function transformHistogramData<T extends Record<string, unknown>>(config: ChartConfig<typeof ModelTypes.Histogram>, rows: T[]): T[];
 /**
  * Processes the chart data for bar and line charts.
+ *
  * @param props.config - The chart model.
  * @param props.rows - The raw data to be transformed.
  * @param props.layer - The layer associated with the chart.
@@ -70,6 +69,7 @@ export declare function transformBarLineChartData<T extends Record<string, unkno
 }): T[];
 /**
  * Transform the pie chart data to a format that is suitable for exporting to CSV.
+ *
  * @param props.model - The pie chart model.
  * @param props.rows - The raw data to be transformed.
  * @param props.layer - The layer associated with the chart.
@@ -82,6 +82,7 @@ export declare function transformPieChartData<T extends Record<string, unknown>>
 }): T[];
 /**
  * Transform the box plot data to a format that is suitable for exporting to CSV.
+ *
  * @param model - The box plot model.
  * @param rows - The raw data to be transformed.
  * @returns The transformed data.
@@ -94,6 +95,14 @@ export declare function transformBoxPlotData<T extends Record<string, unknown>>(
 }): T[];
 /**
  * Check if the provided date is valid.
- * @param {unknown} date - The date to check, should be a string or a number.
+ *
+ * @param date - The date to check, should be a string or a number.
  */
 export declare const isValidDate: (date: unknown) => date is Date | number | string;
+/**
+ * Returns a unique ID.
+ *
+ * @example
+ * 33c2c20e-5a9e-c7be-1b23-b210e6218831
+ */
+export declare function generateGUID(): string;

package/dist/utils/data/categorical-data/index.d.ts

@@ -1,7 +1,7 @@
 import { WebChartQuery } from '../../../spec';
 import { ChartElementLimit } from '../../defaults/interfaces';
-import { AbortControllerKeyType } from '../../layer/query-features/interfaces';
 import { QueryObject } from '../../layer/interfaces';
+import { AbortControllerKeyType } from '../../layer/query-features/interfaces';
 /**
  * Fetches the unique values from a given field.
  * /!\ Currently the results for a same split-by field might differ from a category field to another.

package/dist/utils/data/index.d.ts

@@ -11,30 +11,32 @@ export declare function getBoxPlotStatisticFieldNames(y?: string): Record<BoxPlo
  * Check the `subType` in the chart config to determine whether the chart is a gauge by feature.
  * If `subType` is not defined, the chart is defaulted to be a statistic gauge.
  *
- * @param config the chart config
- * @default false
+ * @param config - the chart config
  */
-export declare function isGaugeByFeature(config: WebGaugeChart): boolean;
+export declare function isGaugeByFeature(config: WebChart): boolean;
 /**
  * From fetched data (type: WebChartDataTypes) returns the part containing the data that
  * is to be assigned to the chart (WebChartDataItem[] | WebChartBin[])
- * @param props.fetchedData The fetched finished data
+ *
+ * @param props.fetchedData - The fetched finished data
  */
 export declare function extractChartDataFromFetchedData(fetchedData?: WebChartDataTypes): WebChartBin[] | WebChartDataItem[] | undefined;
 /**
  * Determine whether the current box plot has multi-fields or not based on its query type
- * @param chartSubType: Box plot sub type
+ *
+ * @param chartSubType - Box plot sub type
  */
 export declare function isMultiFieldsBoxPlot(chartSubType?: ChartSubType): boolean;
 /**
  * Compute Y value for given Box Plot Y field key based on the provided config
- * @param props.key The BoxPlotYFieldKeys related to the stat
- * @param props.y The y field to use to get the y value
- * @param props.chartSubType The box plot sub type
- * @param props.splitBy The where clause used as a split-by value for a given series
- * @param props.splitByValue The split-by value for a given series
- * @param props.showOutliers Whether to show the outliers
- * @param props.standardizeValues Whether to show the standardized values
+ *
+ * @param props.key - The BoxPlotYFieldKeys related to the stat
+ * @param props.y - The y field to use to get the y value
+ * @param props.chartSubType - The box plot sub type
+ * @param props.splitBy - The where clause used as a split-by value for a given series
+ * @param props.splitByValue - The split-by value for a given series
+ * @param props.showOutliers - Whether to show the outliers
+ * @param props.standardizeValues - Whether to show the standardized values
  */
 export declare function getBoxPlotYValue(props: BoxPlotYValueProps): string;
 /**
@@ -99,7 +101,7 @@ export declare function isEmptyDataset(props: {
     dataSet?: WebChartDataItem[];
 }): boolean;
 /**
- * Gets the data min and max values for a stacked series
+ * Gets the data min and max values for a stacked series; also an indicator whether the data has negative values.
  * @param seriesConfig The config for the series
  * @param filteredSeriesIds List of series ids to use as a filter
  * @param filteredData The data to look into
@@ -111,6 +113,7 @@ export declare function getDataMinMaxFromStackedSeries(props: {
 }): {
     stackedMinY: number;
     stackedMaxY: number;
+    dataHasNegativeValues: boolean;
 };
 /**
  * Looks for the min and max values from a data set, considering only the visible series.

package/dist/utils/data/interfaces.d.ts

@@ -1,7 +1,6 @@
 import { WebChartDataTypes, WebChartQuery } from '../../spec';
 import { DataWarningKeywords } from '../chart-config/validator/interfaces';
 import { ChartSubType } from '../misc/interfaces';
-import { BinnedServerData } from './time-binning/interfaces';
 export interface DataMinMax {
     minY: number;
     maxY: number;
@@ -13,7 +12,6 @@ export interface DataInfo {
     invalidType?: DataWarningKeywords;
     count?: number;
     data?: WebChartDataTypes;
-    binnedServerData?: BinnedServerData;
     queryConfig?: WebChartQuery;
 }
 export declare const BoxPlotYFieldKeys: {
@@ -37,3 +35,34 @@ export interface BoxPlotYValueProps {
     showOutliers?: boolean;
     standardizeValues?: boolean;
 }
+export interface DataUpdateDetails {
+    common: {
+        queryChanged: boolean;
+        xOrYChanged: boolean;
+        numberOfSeriesChanged: boolean;
+        configFiltersChanged: boolean;
+        filterBySelectionChanged: boolean;
+        dataForFilterBySelectionChanged: boolean;
+        binTemporalDataChanged: boolean;
+        timeBinningChanged: boolean;
+        timeIntervalUnitChanged: boolean;
+        newTimeBinningWillBeCalculated: boolean;
+        valueFormatChangeRequiresNewData: boolean;
+    };
+    histogram: {
+        dataPropsChanged: boolean;
+    };
+    gauge: {
+        valueConversionChanged: boolean;
+    };
+    boxPlot: {
+        showMeanChanged: boolean;
+    };
+    heatChart: {
+        binningChanged: boolean;
+        hideEmptyRowsAndColumnsChanged: boolean;
+    };
+    scatterPlot: {
+        tooltipFieldsChanged: boolean;
+    };
+}

package/dist/utils/data/time-binning/interfaces.d.ts

@@ -14,10 +14,6 @@ export interface TimeBinningStatistics {
     dateRange: DateRange;
     numberOfFeatures: number;
 }
-export interface BinnedServerData {
-    data: WebChartDataItem[];
-    timeBinningStats: TimeBinningStatistics;
-}
 export interface GroupProps {
     binFirstOrLastIndex: number;
     data: WebChartDataItem[];

package/dist/utils/defaults/index.d.ts

@@ -1,6 +1,6 @@
-import { CategoryFormatOptions, Color, DateTimeFormatOptions, HistogramOverlays, IFont, ISimpleFillSymbol, ISimpleLineSymbol, ISimpleMarkerSymbol, NumberFormatOptions, ScatterplotOverlays, SizePolicy, WebBoxPlot, WebChart, WebChartAxis, WebChartBarChartSeries, WebChartBoxPlotSeries, WebChartCursorCrosshair, WebChartGaugeAxis, WebChartGaugeSeries, WebChartHeatChartSeries, WebChartHistogramSeries, WebChartLegend, WebChartLineChartSeries, WebChartNeedle, WebChartOverlay, WebChartPieChartSeries, WebChartPieChartTick, WebChartRadarChartSeries, WebChartScatterplotSeries, WebChartText, WebChartTextSymbol, WebGaugeChart, WebChartStackedKinds, WebChartTypes } from '../../spec';
-import { ChartElementLimit, ChartElementTechnicalLimit, ChartTextProps, QueryDefaults, TextElements } from './interfaces';
+import { CategoryFormatOptions, Color, DateTimeFormatOptions, HistogramOverlays, IFont, ISimpleFillSymbol, ISimpleLineSymbol, ISimpleMarkerSymbol, NumberFormatOptions, ScatterplotOverlays, SizePolicy, WebBoxPlot, WebChart, WebChartAxis, WebChartBarChartSeries, WebChartBoxPlotSeries, WebChartCursorCrosshair, WebChartGaugeAxis, WebChartGaugeSeries, WebChartHeatChartSeries, WebChartHistogramSeries, WebChartLegend, WebChartLineChartSeries, WebChartNeedle, WebChartOverlay, WebChartPieChartSeries, WebChartPieChartTick, WebChartRadarChartSeries, WebChartScatterplotSeries, WebChartText, WebChartTextSymbol, WebGaugeChart, WebHeatChart, WebChartStackedKinds, WebChartTypes } from '../../spec';
 import { CommonStrings } from '../localization/interfaces';
+import { ChartElementLimit, ChartElementTechnicalLimit, ChartTextProps, QueryDefaults, TextElements } from './interfaces';
 export declare const histogramBinCount = 32;
 export declare const featuresExtentField = "arcgis_charts_features_extent";
 export declare const queryDefaults: QueryDefaults;
@@ -26,6 +26,8 @@ export declare const defaultHeatChartFields: {
     yField: string;
 };
 export declare const ramp: Color[];
+export declare const darkModeRamp: Color[];
+export declare const darkModeOverlayRamp: Color[];
 /**
  * Returns a specific color from the default ramp, given an index. If the index is > than the ramp length,
  * we use modulo to get the corresponding color.
@@ -170,9 +172,9 @@ export declare function getDefaultScatterplot(commonStrings: CommonStrings, id?:
  * Gets default heat chart
  * @param commonStrings
  * @param id
- * @returns WebChart
+ * @returns WebHeatChart
  */
-export declare function getDefaultHeatChart(commonStrings: CommonStrings, objectIDField: string): WebChart;
+export declare function getDefaultHeatChart(commonStrings: CommonStrings, objectIDField: string): WebHeatChart;
 export declare function getDefaultHistogramOverlays(): Required<HistogramOverlays>;
 export declare function getDefaultHistogramSymbol(): ISimpleFillSymbol;
 export declare function getDefaultHistogramSeries(): Omit<Required<WebChartHistogramSeries>, "dataTooltipDateFormat" | "dataTooltipPercentFormat" | "dataTooltipValueFormat" | "query">;

package/dist/utils/defaults/interfaces.d.ts

@@ -44,7 +44,7 @@ export interface QueryDefaults {
     maxParallelRequests: number;
     maxRecords: number;
     outStatistics: Readonly<IStatisticDefinition>;
-    uniqueIdsName: string;
+    uniqueIdsName: number | string;
     orderByJSAPIDelimiter: string;
 }
 export interface ChartTextProps {

package/dist/utils/errors/index.d.ts

@@ -17,11 +17,11 @@ export declare class ArcgisChartsError<T = any> extends Error {
      */
     details?: T;
     /**
-     * Creates a new ArcgisChartsError instance.
+     * Creates a new `ArcgisChartsError` instance.
      *
-     * @param {string} name - A unique error name.
-     * @param {string} [message] - A message describing the details of the error.
-     * @param {Object} [details] - The details object provides additional details specific to the error.
+     * @param name - A unique error name.
+     * @param message - A message describing the details of the error.
+     * @param details - The details object provides additional details specific to the error.
      */
     constructor(name: string, message?: string, details?: T);
 }