@arcgis/charts-components 5.0.0-next.16 → 5.0.0-next.161

package/dist/utils/chart-config/utils/index.d.ts

@@ -1,6 +1,13 @@
-import { WebChart, WebChartSeriesType, RESTSymbolType, WebChartTypes, WebChartVersionStatus } from '../../../spec';
-import { ChartSubType } from '../../misc/interfaces';
-import { WebChartSeriesSupportingTemporalBinning } from './interfaces';
+import type { ChartOptions } from "../../../chart-rendering/common/interfaces.js";
+import type { DataUpdateDetails } from "../../data/interfaces.js";
+import type { ChartSubType } from "../../misc/interfaces.js";
+import type { WebChartSeriesSupportingTemporalBinning } from "./interfaces.js";
+import type { WebChartTypes, WebChartVersionStatus } from "../../../spec/chart-object-literals.js";
+import type { WebBoxPlot, WebChart, WebChartLegend, WebChartSeriesType, WebHeatChart } from "../../../spec/web-chart.js";
+import type { RESTSymbolType } from "../../../spec/rest-js-object-literals.js";
+import type { TimeIntervalInfo } from "../../../spec/data-source.js";
+import type { IField } from "../../../spec/rest-js-types.js";
+
 /**
  * Retrieve and construct chart version information based on the input version and the currently supported ArcGIS Chart versions
  * defined in `chartConfigVersions`.  Returned information includes:
@@ -16,24 +23,33 @@ import { WebChartSeriesSupportingTemporalBinning } from './interfaces';
  *
  * Note: The input chart version needs to conform to the format defined by sematic versioning spec; otherwise it will be treated as unrecognized.
  *
- * @param configVersion The input config version.
+ * @param configVersion - The input config version.
+ * @internal
  */
-export declare function getChartVersionInfo(configVersion?: string): {
+export function getChartVersionInfo(configVersion?: string): {
     versionStatus: WebChartVersionStatus;
     versions: string[];
 };
+
 /**
  * Get the series to use as a reference for the chart. That's the one containing important common information like the query,
  * the split-by field, etc.
  * For box plot we need to handle the specific case of the mean line series.
- * @param chartConfig The chart config
+ *
+ * @param chartConfig - The chart config
+ * @internal
  */
-export declare function getSeriesReference(chartConfig: WebChart): WebChartSeriesType;
+export function getSeriesReference(chartConfig: WebChart): WebChartSeriesType;
+
 /**
  * Find the expected symbol type for a guide given the start and end values.
- * @param guide The guide to analyze
+ *
+ * @param start - The guide to analyze
+ * @param end
+ * @internal
  */
-export declare function findExpectedGuideSymbol(start: Date | number | string | null, end: Date | number | string | null | undefined): RESTSymbolType;
+export function findExpectedGuideSymbol(start: Date | number | string | null, end: Date | number | string | null | undefined): RESTSymbolType;
+
 /**
  * Extract the field name from equality-where clauses like `field = 'some_value'`.
  * This field is actually stored in each series where clause.
@@ -41,61 +57,61 @@ export declare function findExpectedGuideSymbol(start: Date | number | string |
  * E.g.:
  * "field = 'some_value'" => "field"
  * "field > 'some_value'" => ""
- * @param where the where clause to extract the field from
- * @param normalize whether to normalize the extracted field; by default it's true
+ *
+ * @param where - the where clause to extract the field from
+ * @param normalize - whether to normalize the extracted field; by default it's true
+ * @internal
  */
-export declare function getSplitByField(where: string | undefined, normalize?: boolean): string;
+export function getSplitByField(where: string | undefined, normalize?: boolean): string;
+
 /**
  * Extract the value from equality-where clauses like `field = 'some_value'`.
  * Optionally normalize or escape single quotes in the returned value according to the `normalize` param value.
  * If normalize is undefined then normalize the returned value.
  * For string value, if normalize is set to false and escape is set to false or undefined, the value is returned as is.
- * @param props.where the where clause to extract the value from
- * @param props.normalize whether to normalize the extracted value; default is true
- * @param props.keepSurroundingQuotes whether to keep the surrounding quotes; default is false
- * @param props.escape whether to escape the extracted value; default is false
+ *
+ * @param props - the where clause to extract the value from
+ * @internal
  */
-export declare function getSplitByValue(props: {
+export function getSplitByValue(props: {
     where: string | undefined;
     normalize?: boolean;
     keepSurroundingQuotes?: boolean;
     escape?: boolean;
 }): number | string | null;
+
 /**
  * Detects a where clause being always true, as in 1=1, 2 = 2, 'some_value'='some_value'
+ *
  * @param where
+ * @internal
  */
-export declare function isAbsoluteTruthWhereClause(where?: string): boolean;
+export function isAbsoluteTruthWhereClause(where?: string): boolean;
+
 /**
  * Normalizes a where clause, by escaping the "'" character and other special characters if needed.
  * Ex:
  *   - where = "field = 5" => returns "field = 5"
  *   - where = "field = 'value'" => returns "field = 'value'"
  *   - where = "field = 'va'lue'" => returns "field = 'va''lue'"
- * @param props.where the where clause to normalize
- * @param props.normalize whether to normalize the where clause
- * @param props.escape whether to escape the where clause
+ *
+ * @param props - the where clause to normalize
+ * @internal
  */
-export declare function normalizeWhereClause(props: {
+export function normalizeWhereClause(props: {
     where: string;
     normalize?: boolean;
     escape?: boolean;
 }): string;
-/**
- * Gets the query type for the pie.
- * @param series the pie series
- */
-declare function getPieChartChartSubType(series: WebChartSeriesType[]): ChartSubType;
-/**
- * Gets the query type for bar/line chart.
- * @param series the bar/line series
- */
-declare function getBarLineChartSubType(series: WebChartSeriesType[]): ChartSubType;
+
 /**
  * Gets the query type for box plot chart.
- * @param seriesConfig the box plot series config
+ *
+ * @param seriesConfig - the box plot series config
+ * @internal
  */
-export declare function getBoxPlotChartSubType(seriesConfig: WebChartSeriesType[]): ChartSubType;
+export function getBoxPlotChartSubType(seriesConfig: WebChartSeriesType[]): ChartSubType;
+
 /**
  * Returns the type of query we're dealing with. The actual values are:
  * a. Simple (0): single query using an aggregation
@@ -104,35 +120,302 @@ export declare function getBoxPlotChartSubType(seriesConfig: WebChartSeriesType[
  * d. SplitByNumericalFields (3): multiple queries using multiple numerical fields as a split-by
  * e. PieFromFields (4): single query using more than one statistics fields
  * f. For Box-plot: one of the 7 combinations.
- * @param series The config series. Refrain from using `[firstSeries]` in place of `config.series` to avoid incorrect result,
+ *
+ * @param series - The config series. Refrain from using `[firstSeries]` in place of `config.series` to avoid incorrect result,
  * especially for box-plot, bar and line charts.
+ * @internal
  */
-export declare function getChartSubType(series?: WebChartSeriesType[]): ChartSubType;
+export function getChartSubType(series?: WebChartSeriesType[]): ChartSubType;
+
 /**
  * Indicates whether the bar or line series is configured to use time binning.
- * @param props.seriesConfig The series configuration
- * @param props.xAxisValueFormatType The x-axis value format type
- * @param props.setTimeBinningInfoWhenNotProvided Boolean indicating whether we want to set the time binning info when not provided
+ *
+ * @param props - The series configuration
+ * @internal
  */
-export declare function isSeriesUsingTimeBinning(props: {
+export function isSeriesUsingTimeBinning(props: {
     seriesConfig: WebChartSeriesType;
     xAxisValueFormatType?: WebChartTypes;
     setTimeBinningInfoWhenNotProvided?: boolean;
 }): boolean;
+
 /**
  * Indicates whether a series supports temporal binning.
- * @param series The series to test
+ *
+ * @param series - The series to test
+ * @internal
  */
-export declare function doesSeriesSupportTemporalBinning(series: WebChartSeriesType): series is WebChartSeriesSupportingTemporalBinning;
+export function doesSeriesSupportTemporalBinning(series: WebChartSeriesType): series is WebChartSeriesSupportingTemporalBinning;
+
 /**
  * Compares two config data filters and returns true if they are identical, false otherwise
  *
- * @param oldConfig
+ * @param previousConfig
  * @param newConfig
+ * @internal
+ */
+export function hasConfigFilterChanged(previousConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Compares two heat chart configs and indicates whether the hide empty rows and columns option changed
+ *
+ * @param previousConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasHeatChartHideEmptyRowsAndColumnsChanged(previousConfig: WebHeatChart, newConfig: WebHeatChart): boolean;
+
+/**
+ * Compares two heat chart configs and indicates whether to include leap day
+ *
+ * @param previousConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasHeatChartIncludeLeapDayChanged(previousConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Compares two configs and indicates whether additional tooltip fields (only non-numeric) changed
+ *
+ * **NOTE**: Only applicable to scatterplot
+ *
+ * @param props - The previous config
+ * @internal
+ */
+export function hasAdditionalTooltipFieldsChanged(props: {
+    previousConfig: WebChart;
+    newConfig: WebChart;
+    fieldList?: IField[];
+}): boolean;
+
+/**
+ * Compares two configs and indicates whether the color type change
+ *
+ * @param oldConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasColorMatchChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Compares two configs and indicates whether the stacked type changed
+ *
+ * @param oldConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasStackedTypeChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Normalizes the legend position
+ *
+ * @param legend - The legend
+ * @returns The normalized legend
+ * @internal
+ */
+export function normalizeLegendPosition(legend: WebChartLegend): WebChartLegend;
+
+/**
+ * Compares two configs and indicates whether the legend visibility changed
+ *
+ * @param oldConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasHeatLegendConfigChanged(oldConfig: WebHeatChart, newConfig: WebHeatChart): boolean;
+
+/**
+ * Compates two configs and indicates whether the heat legend position changed
+ *
+ * @param oldConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasHeatLegendPositionChanged(oldConfig: WebHeatChart, newConfig: WebHeatChart): boolean;
+
+/**
+ * Compares two configs and indicates whether the gradient rules changed
+ *
+ * @param oldConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasGradientRulesChanged(oldConfig: WebHeatChart, newConfig: WebHeatChart): boolean;
+
+/**
+ * Compares two configs and indicates whether the heat rules type changed
+ *
+ * @param oldConfig - The previous config
+ * @param newConfig - The updated config
+ * @internal
+ */
+export function hasHeatRulesTypeChanged(oldConfig: WebHeatChart, newConfig: WebHeatChart): boolean;
+
+/**
+ * Compares the 'slices' array from the pie series, and indicates whether they are different.
+ * Compare only the slices id and label to avoid false positives.
+ *
+ * @param props - The previous chart config
+ * @internal
  */
-export declare function hasConfigFilterChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
-export declare const chartConfigUtilsPrivateFunctions: {
-    getPieChartChartSubType: typeof getPieChartChartSubType;
-    getBarLineChartSubType: typeof getBarLineChartSubType;
+export function hasSlicesConfigChanged(props: {
+    oldConfig: WebChart;
+    newConfig: WebChart;
+}): boolean;
+
+/**
+ * @param props
+ * @internal
+ */
+export function hasDataForFilterBySelectionChanged(props: {
+    previousSelectionOIDs?: (number | string)[];
+    options?: ChartOptions;
+}): boolean;
+
+/**
+ * Compares the split by value for each series element in the box plot config and returns true if the series has different split by value between new and old box plot config, false otherwise.
+ *
+ * @param oldSeries - The former series config
+ * @param newSeries - The new series config
+ * @internal
+ */
+export function hasSplitByValueChanged(oldSeries: WebChart["series"], newSeries: WebChart["series"]): boolean;
+
+/**
+ * Verify if the order of the numeric fields has changed
+ *
+ * @param oldSeries - The previous series config
+ * @param newSeries - The new series config
+ * @internal
+ */
+export function hasNumericFieldsChanged(oldSeries: WebChart["series"], newSeries: WebChart["series"]): boolean;
+
+/**
+ * Returns true when the time interval info was set previously and are not in the new config
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasTimeIntervalInfoBeenReset(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Returns true when the dual axis feature was enabled or disabled (number of axes changed)
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasDualAxisChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Returns true when the series are not associated to the same axis anymore
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasSeriesAxisChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Returns true when at least one guide's 'above' property changed from an update to another.
+ *
+ * @param oldConfig - The old chart config
+ * @param newConfig - The new chart config
+ * @internal
+ */
+export function hasAnyGuideAboveChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Returns true if the rotated property changed since the previous update.
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasRotationChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Returns true if the rotated property changed since the previous update.
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasOutliersVisibilityChanged(oldConfig: WebBoxPlot, newConfig: WebBoxPlot): boolean;
+
+/**
+ * Returns true if the 'standardizeValues' property changed in the chart config since the previous update.
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasStandardizeValuesVisibilityChanged(oldConfig: WebBoxPlot, newConfig: WebBoxPlot): boolean;
+
+/**
+ * Returns true if the 'chartRenderer' property changed in the chart config since the previous update.
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasChartRendererChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Returns true if the 'timeZone' property from the axis value format changed in the chart config since the previous update.
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasIntlTimeZoneChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Indicates whether the size policy changed from the previous update
+ *
+ * @param oldConfig - the old chart config
+ * @param newConfig - the new chart config
+ * @internal
+ */
+export function hasSizePolicyChanged(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Indicates whether a series reinitialization is necessary due to size policy changes
+ *
+ * @param oldConfig - The old chart config
+ * @param newConfig - The new chart config
+ * @internal
+ */
+export function doSizePolicyChangesRequireSeriesReinit(oldConfig: WebChart, newConfig: WebChart): boolean;
+
+/**
+ * Function saying if a data update is needed. We compare different properties from the former config and the new one
+ * in order to decide if the update is needed.
+ *
+ * @param props
+ * @internal
+ */
+export function doesConfigChangeRequireNewData(props: {
+    previousConfig: WebBoxPlot | WebChart;
+    newConfig: WebBoxPlot | WebChart;
+    options?: ChartOptions;
+    previousFilterBySelection?: boolean;
+    previousTimeIntervalInfo?: TimeIntervalInfo;
+    previousSelectionOIDs?: (number | string)[];
+    fieldList?: IField[];
+}): {
+    dataUpdateNeeded: boolean;
+    dataUpdateDetails: DataUpdateDetails;
 };
-export {};
+
+/**
+ * Sorts the series in the config based on the series sort options.
+ * When no sort option is provide, no sorting is performed.
+ *
+ * @param chartConfig - The optional chart config to sort the series
+ * @param chartContainer - The HTML chart container
+ * @returns The updated chart config with the series sorted, or undefined if the input config is undefined
+ * @internal
+ */
+export function sortConfigSeries<T extends WebChart | undefined>(chartConfig: T, chartContainer?: HTMLElement): T;

package/dist/utils/chart-config/utils/interfaces.d.ts

@@ -1,3 +1,8 @@
-import { WebChartBarChartSeries, WebChartLineChartSeries, WebChartRadarChartSeries, WebChartTypes } from '../../../spec';
+import type { WebChartTypes } from "../../../spec/chart-object-literals.js";
+import type { WebChartBarChartSeries, WebChartLineChartSeries, WebChartRadarChartSeries } from "../../../spec/web-chart.js";
+
+/** @internal */
 export type WebChartSeriesSupportingTemporalBinning = WebChartBarChartSeries | WebChartLineChartSeries | WebChartRadarChartSeries;
-export declare const webChartTypesSupportingTemporalBinning: (WebChartTypes | undefined)[];
+
+/** @internal */
+export const webChartTypesSupportingTemporalBinning: (WebChartTypes | undefined)[];

package/dist/utils/chart-config/validator/index.d.ts

@@ -1,93 +1,25 @@
-import { WebChart, WebGaugeChart } from '../../../spec';
-import { WebChartJSONSchemas } from '../../../json-schema';
-import { ErrorObject } from 'ajv';
-import { QueryObject } from '../../layer/interfaces';
-import { ConfigWarningObject, CustomErrorObject, ValidationStatus } from './interfaces';
-/**
- * Extracts schema name from the schema `$ref` path
- * For e.g.:
- *   - "#/definitions/WebChartInlineDataSource" => "WebChartInlineDataSource"
- *   - "#/definitions/WebChartBarChartSeries" => "WebChartBarChartSeries"
- * @param schemaRefPath
- */
-declare function extractSchemaNameFromRefPath(schemaRefPath: string): string;
-/**
- * Formats specific error messages based on the error keyword.
- * @param errors Array storing the errors met during the validation
- */
-declare function customizeValidationErrors(errors: ErrorObject[]): Promise<ErrorObject[]>;
-/**
- * By default, the JSON schema created by ac-spec is suitable for WebChart validation.
- * If we want to validate any other object, an appropriate schema can be generated via this function.
- * @param schema
- * @param schemaKey
- */
-declare function createStartingSchema(schema: typeof WebChartJSONSchemas, schemaKey: keyof typeof WebChartJSONSchemas.definitions): typeof WebChartJSONSchemas;
-/**
- * Tests whether a layer can be loaded.
- * @param queryObject The query object (layer or feature layer view)
- */
-declare function findLayerLoadError(queryObject: QueryObject): Promise<CustomErrorObject | undefined>;
-/**
- * Check whether there exists a `StatisticDefinition` in any series' `Query` where non-count aggregation is applied to a non-numeric field
- * @param props.seriesConfigs The series config list
- * @param props.queryObject The query object
- * @param props.allowUsingObjectIdStat Whether to allow using the object id field as a statistic field
- */
-declare function findNumericAggregationWarnings(props: {
-    seriesConfigs: WebChart["series"];
-    queryObject: QueryObject;
-    allowUsingObjectIdStat?: boolean;
-}): Promise<ConfigWarningObject[]>;
-/**
- * Verifies that the chart series are unique. Sets a message to display if not.
- * @param chartConfig The chart config
- */
-declare function findDuplicateSeriesIDWarnings(chartConfig?: WebChart): Promise<ConfigWarningObject[]>;
-/**
- * Look for issues of level 'warning' in the chart config.
- * @param props.input The input config
- * @param props.queryObject The query object
- * @param props.allowUsingObjectIdStat Whether to allow using the object id field as a statistic field
- */
-declare function findWarnings(props: {
-    input: WebChart;
-    queryObject: QueryObject;
-    allowUsingObjectIdStat?: boolean;
-}): Promise<ConfigWarningObject[]>;
-/**
- * Look for specific errors independent from the JSON schema.
- * @param queryObject The query object
- * @param chartConfig The chart config
- */
-declare function findCustomErrors(queryObject?: QueryObject, chartConfig?: WebChart | WebGaugeChart): Promise<CustomErrorObject[]>;
+import type { QueryObject } from "../../layer/interfaces.js";
+import type { ValidationStatus } from "./interfaces.js";
+import type { WebChart, WebGaugeChart } from "../../../spec/web-chart.js";
+
 /**
  * Validates the `WebChart` config by checking for  and displays `Errors` and `Warnings`.
  * - `Errors` are violations in the config w.r.t the JSON schema.
  * - `Warnings` are undesired combinations in the config which don't violate the JSON schema but should still be blocked.
- * @param props.input The input config
- * @param props.queryObject The query object
- * @param props.allowUsingObjectIdStat Whether to allow using the object id field as a statistic field
+ *
+ * @param props - The input config
  */
-export declare function validateWebChart(props: {
+export function validateWebChart(props: {
     input?: WebChart | WebGaugeChart;
     queryObject?: QueryObject;
     allowUsingObjectIdStat?: boolean;
 }): Promise<ValidationStatus>;
+
 /**
  * Checks whether the config is "partial", meaning it has been initialized for a given chart type
  * but has not been provided the minimum required prop(s) yet.
- * @param config The config to analyze
+ *
+ * @param config - The config to analyze
+ * @internal
  */
-export declare function isPartialConfig(config?: WebChart): boolean;
-export declare const chartConfigValidatorPrivateFunctions: {
-    findCustomErrors: typeof findCustomErrors;
-    findWarnings: typeof findWarnings;
-    findNumericAggregationWarnings: typeof findNumericAggregationWarnings;
-    findDuplicateSeriesIDWarnings: typeof findDuplicateSeriesIDWarnings;
-    findLayerLoadError: typeof findLayerLoadError;
-    createStartingSchema: typeof createStartingSchema;
-    extractSchemaNameFromRefPath: typeof extractSchemaNameFromRefPath;
-    customizeValidationErrors: typeof customizeValidationErrors;
-};
-export {};
+export function isPartialConfig(config?: WebChart): boolean;