@geoscene/charts-components 5.0.19

package/dist/utils/layer/query-features/index.d.ts

@@ -0,0 +1,192 @@
+import type AttributeBinsGraphic from "@geoscene/core/AttributeBinsGraphic.js";
+import type AttributeBinsFeatureSet from "@geoscene/core/rest/support/AttributeBinsFeatureSet.js";
+import type { ErrorStrings } from "../../localization/interfaces.js";
+import type { ChartSubType } from "../../misc/interfaces.js";
+import type { QueryObject } from "../interfaces.js";
+import type { AbortControllerKeyType, Features } from "./interfaces.js";
+import type {
+  WebChartQuery,
+  WebChartTemporalBinning,
+  WebHeatChart,
+} from "../../../spec/web-chart.js";
+import type { WebChartDataItem } from "../../../spec/data-source.js";
+import type { ChartOptions } from "../../../chart-rendering/common/interfaces.js";
+
+/**
+ * Performs a query analytic.
+ *
+ * @param props - The object used to query (FL or FLV)
+ * @internal
+ */
+export function queryAnalytic(props: {
+  queryObject: QueryObject;
+  queryConfig: WebChartQuery;
+  outAnalytics: string;
+  outputFormat: string;
+  dataFormat: string;
+}): Promise<WebChartDataItem | undefined>;
+
+/**
+ * Generates the aliases to use in the queryAttributeBins query to name the stacks and boundaries for the x field
+ *
+ * @param x - The x field used for the stack alias
+ * @param y - The y field used by the stacks
+ * @internal
+ */
+export function getQueryAttributeBinsForScatterplotFieldsAlias(
+  x: string,
+  y: string
+): {
+  lowerBoundaryAlias: string;
+  upperBoundaryAlias: string;
+  stackAlias: string;
+};
+
+/**
+ * Fetches and returns the heat chart data using query(Attribute)Bins
+ *
+ * @param props - The chart configuration
+ * @internal
+ */
+export function queryAttributeBinsForHeatChart(props: {
+  chartConfig: WebHeatChart;
+  queryObject: QueryObject;
+  queryConfig: WebChartQuery;
+  options?: ChartOptions;
+  errorStrings: ErrorStrings;
+}): Promise<AttributeBinsFeatureSet | undefined>;
+
+/**
+ * Query the features for the matrix heat chart.
+ *
+ * @param props - The chart configuration
+ * @internal
+ */
+export function queryFeaturesForMatrixHeatChart(props: {
+  chartConfig: WebHeatChart;
+  queryObject: QueryObject;
+  queryConfig: WebChartQuery;
+  returnFeaturesExtent?: boolean;
+  errorStrings: ErrorStrings;
+  abortKey?: AbortControllerKeyType;
+}): Promise<Features | undefined>;
+
+/**
+ * Uses query(Attribute)Bins to fetch the aggregated scatterplot data
+ *
+ * @param props - The object used to query (FL or FLV)
+ * @internal
+ */
+export function queryAttributeBinsForScatterplot(props: {
+  queryObject: QueryObject;
+  queryConfig: WebChartQuery;
+  xStep: number;
+  yStep: number;
+  xMin: number;
+  xMax: number;
+  x: string;
+  y: string;
+  errorStrings: ErrorStrings;
+}): Promise<AttributeBinsFeatureSet | undefined>;
+
+/**
+ * Performs a query feature count based on the provided parameters.
+ *
+ * @param props - The object used to query (FL or FLV)
+ * @internal
+ */
+export function queryFeatureCount(props: {
+  queryObject: QueryObject;
+  queryConfig: WebChartQuery;
+  chartSubType: ChartSubType;
+  x: string;
+  isGaugeByFeature?: boolean;
+}): Promise<number | undefined>;
+
+/**
+ * Fetches multiple statistics (min, max, count...).
+ * Returns an object mapping the outStatisticFieldName with its value
+ *
+ * @param props - The object used to query (FL or FLV)
+ * @internal
+ */
+export function queryStatistics<T extends Date | number | string>(props: {
+  queryObject: QueryObject;
+  queryConfig: WebChartQuery;
+  abortKey?: AbortControllerKeyType;
+}): Promise<Map<string, T>>;
+
+/**
+ * @param props
+ * @internal
+ */
+export function queryFeatures(props: {
+  queryObject?: QueryObject;
+  queryConfig?: WebChartQuery;
+  returnUniqueIdsOnly?: boolean;
+  abortKey?: AbortControllerKeyType;
+}): Promise<Features>;
+
+/**
+ * Fetches all the features from the input QueryObject, according to the other specified input settings (query, outFields...).
+ * Handles the paging.
+ *
+ * @param props - The object used to query (FL or FLV)
+ * @internal
+ */
+export function queryAllFeatures(props: {
+  queryObject?: QueryObject;
+  queryConfig?: WebChartQuery;
+  returnUniqueIdsOnly?: boolean;
+  featureCount?: number;
+  noBatch?: boolean;
+  abortKey?: AbortControllerKeyType;
+}): Promise<Features>;
+
+/**
+ * Fetches the extent of all the features that are represented by their object ids
+ *
+ * @param props - The object used to query (FL or FLV)
+ * @internal
+ */
+export function queryUniqueIDs(props: {
+  queryObject?: QueryObject;
+  queryConfig: WebChartQuery;
+  uniqueFeature?: boolean;
+  abortKey?: AbortControllerKeyType;
+}): Promise<(number | string)[]>;
+
+/**
+ * Aborts all existing queries and initializes a controller for new ones. The queries are associated
+ * to a unique key to avoid cancelling queries for other charts.
+ *
+ * @param key - The key pointing to the abort controller to execute
+ * @internal
+ */
+export function abortPendingQueries(key?: AbortControllerKeyType): void;
+
+/**
+ * @param x
+ * @internal
+ */
+export function getQueryAttributeBinsForTemporalDataAliases(x: string): {
+  lowerBoundaryAlias: string;
+  upperBoundaryAlias: string;
+};
+
+/**
+ * Fetches binned temporal data using queryAttributeBins().
+ * TODO: support for offset
+ * TODO: support for abortKey input parameter
+ *
+ * @param props - The object used to query (FL or FLV)
+ * @internal
+ */
+export function queryAttributeBinsForTemporalData(props: {
+  queryObject?: QueryObject;
+  queryConfig: WebChartQuery;
+  temporalBinning?: WebChartTemporalBinning;
+  dateField: string;
+  splitByField?: string;
+  abortKey?: AbortControllerKeyType;
+}): Promise<AttributeBinsGraphic[]>;

package/dist/utils/layer/query-features/interfaces.d.ts

@@ -0,0 +1,10 @@
+import type Graphic from "@geoscene/core/Graphic.js";
+
+/** @internal */
+export type AbortControllerKeyType = Date | number | string;
+
+/** @internal */
+export const abortControllerMap: Map<AbortControllerKeyType, AbortController>;
+
+/** @internal */
+export type Features = (number | string)[] | Graphic[];

package/dist/utils/layer/query-parser/index.d.ts

@@ -0,0 +1,183 @@
+import type Geometry from "@geoscene/core/geometry/Geometry.js";
+import type FeatureLayer from "@geoscene/core/layers/FeatureLayer.js";
+import type SubtypeSublayer from "@geoscene/core/layers/support/SubtypeSublayer.js";
+import type AttributeBinsQuery from "@geoscene/core/rest/support/AttributeBinsQuery.js";
+import type Query from "@geoscene/core/rest/support/Query.js";
+import type TimeExtent from "@geoscene/core/time/TimeExtent.js";
+import type { QueryProperties } from "@geoscene/core/rest/support/Query.js";
+import type { RESTFieldType } from "../../../spec/rest-js-object-literals.js";
+import type {
+  WebChartHeatChartSeries,
+  WebChartQuery,
+  WebChartTemporalBinning,
+} from "../../../spec/web-chart.js";
+import type { QueryObject } from "../interfaces.js";
+import type { ChartOptions } from "../../../chart-rendering/common/interfaces.js";
+
+/**
+ * Indicates whether a query can be cached. It is not when:
+ * - a geometry is set (unless it's an extent)
+ * - a date filter is set
+ *
+ * @param query - The query object or query parameters
+ * @internal
+ */
+export function isQueryCacheable(
+  query: AttributeBinsQuery | Query | QueryProperties
+): boolean;
+
+/**
+ * @param layer
+ * @internal
+ */
+export function getMaxRecords(
+  layer?: Pick<FeatureLayer, "sourceJSON"> | SubtypeSublayer
+): number;
+
+/**
+ * Function building a where clause by concatenating a list of filters by using the AND operator.
+ *
+ * @param filterList - The list of filters to combine
+ * @param operand - The operand to use to combine the filters (OR, AND...)
+ * @internal
+ */
+export function combineFilters(
+  filterList: (string | null | undefined)[],
+  operand?: string
+): string;
+
+/**
+ * Computes the time extent to be used by the query.
+ *
+ * @param queryObject - The layer or feature layer view
+ * @param defaultTimeExtent - The time extent defined at the series config level or provided at runtime
+ * @internal
+ */
+export function getQueryTimeExtent(
+  queryObject: QueryObject,
+  defaultTimeExtent?: WebChartQuery["timeExtent"]
+): WebChartQuery["timeExtent"] | undefined;
+
+/**
+ * Computes the extent to be used by the query. We prioritize the feature layer view extent
+ * over the series config extent, unless `ignoreViewExtent` is set to true.
+ *
+ * @param props - The layer or feature layer view
+ * @internal
+ */
+export function getQueryGeometry(props: {
+  queryObject: QueryObject;
+  defaultGeometry?: WebChartQuery["geometry"];
+  ignoreViewExtent?: boolean;
+}): WebChartQuery["geometry"] | undefined;
+
+/**
+ * Transforms a [timestamp, timestamp] to a JSAPI TimeExtent object
+ *
+ * @param timeExtentConfig - The time extent filter from the config
+ * @internal
+ */
+export function mapQueryTimeExtent(
+  timeExtentConfig?: WebChartQuery["timeExtent"]
+): TimeExtent | undefined;
+
+/**
+ * Transforms a IGeometry to a JSAPI Geometry
+ *
+ * @param geometryConfig - The geometry from the config
+ * @internal
+ */
+export function mapQueryGeometry(
+  geometryConfig?: WebChartQuery["geometry"]
+): Geometry | null | undefined;
+
+/**
+ * Maps properties from a WebChartQuery and properties specific to temporal binning into an AttributeBinsQuery object.
+ *
+ * @param props - The layer or feature layer view
+ * @internal
+ */
+export function mapAttributeBinsQueryForTemporalData(props: {
+  queryObject?: QueryObject;
+  queryConfig?: WebChartQuery;
+  temporalBinning: WebChartTemporalBinning;
+  dateField: string;
+  splitByField?: string;
+}): Promise<AttributeBinsQuery>;
+
+/**
+ * Builds a SQL expression as well as the start and end values necessary for the calendar date parts binning.
+ *
+ * @param props - The field used by the heat chart
+ * @internal
+ */
+export function getCalendarDatePartsParameters(props: {
+  field: string;
+  fieldType?: RESTFieldType;
+  unit?: string;
+  addIntervalStatement: boolean;
+  outTimeZone?: string;
+  dataTimeZone?: string | null;
+  runsOnClientQueryEngine?: boolean;
+  addLeapDayExpression?: boolean;
+}): {
+  expression?: string;
+  start?: number;
+  end?: number;
+};
+
+/**
+ * Maps properties from a WebChartQuery and properties specific to heat chart into an AttributeBinsQuery object.
+ *
+ * @param props - The layer or feature layer view
+ * @internal
+ */
+export function mapAttributeBinsQueryForHeatChart(props: {
+  queryObject?: QueryObject;
+  queryConfig?: WebChartQuery;
+  x: string;
+  y: string;
+  xTemporalBinning?: WebChartHeatChartSeries["xTemporalBinning"];
+  yTemporalBinning?: WebChartHeatChartSeries["yTemporalBinning"];
+  firstDayOfWeek?: number;
+  configTimeZone?: string;
+  includeLeapDay?: boolean;
+  options?: ChartOptions;
+}): Promise<AttributeBinsQuery>;
+
+/**
+ * Maps properties from a WebChartQuery and properties specific to temporal binning into an AttributeBinsQuery object.
+ *
+ * @param props - The layer or feature layer view
+ * @internal
+ */
+export function mapAttributeBinsQueryForScatterplot(props: {
+  queryObject?: QueryObject;
+  queryConfig?: WebChartQuery;
+  xStep: number;
+  yStep: number;
+  xMin: number;
+  xMax: number;
+  x: string;
+  y: string;
+}): AttributeBinsQuery;
+
+/**
+ * Maps properties from a WebChartQuery into a Query object.
+ *
+ * @param props - The layer or feature layer view
+ * @internal
+ */
+export function mapQuery(props: {
+  queryObject?: QueryObject;
+  queryConfig?: WebChartQuery;
+  maxRecordCountFactor?: number;
+}): Query;
+
+/**
+ * @param layer
+ * @internal
+ */
+export function getMaxRecordCountFactor(
+  layer?: Pick<FeatureLayer, "sourceJSON"> | SubtypeSublayer
+): number | undefined;

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

@@ -0,0 +1,202 @@
+import type FeatureLayer from "@geoscene/core/layers/FeatureLayer.js";
+import type SubtypeGroupLayer from "@geoscene/core/layers/SubtypeGroupLayer.js";
+import type SubtypeSublayer from "@geoscene/core/layers/support/SubtypeSublayer.js";
+import type FeatureLayerView from "@geoscene/core/views/layers/FeatureLayerView.js";
+import type { QueryObject } from "../interfaces.js";
+import type { SupportedLayer } from "../../../interfaces.js";
+import type { WebChart } from "../../../spec/web-chart.js";
+
+/**
+ * Indicates whether the input object is a feature collection.
+ *
+ * @param queryObject
+ * @internal
+ */
+export function isFeatureCollectionLayer(
+  queryObject: QueryObject
+): queryObject is FeatureLayerView;
+
+/**
+ * Indicates whether the input object is an instance of `FeatureLayerView`.
+ *
+ * @param queryObject
+ * @internal
+ */
+export function isFeatureLayerView(
+  queryObject: QueryObject | SubtypeGroupLayer
+): queryObject is FeatureLayerView;
+
+/**
+ * Indicates whether the input object is an instance of `FeatureLayer`.
+ *
+ * @param queryObject
+ * @internal
+ */
+export function isFeatureLayer(
+  queryObject: QueryObject
+): queryObject is FeatureLayer;
+
+/**
+ * Indicates whether the input object is an instance of `SubtypeGroupLayer`.
+ *
+ * @param queryObject
+ * @internal
+ */
+export function isSubtypeGroupLayer(
+  queryObject: QueryObject | SubtypeGroupLayer
+): queryObject is SubtypeGroupLayer;
+
+/**
+ * Indicates whether the input object is an instance of `SubtypeSublayer`.
+ *
+ * @param queryObject
+ * @internal
+ */
+export function isSubtypeSublayer(
+  queryObject: Pick<SubtypeSublayer, "type"> | QueryObject
+): queryObject is SubtypeSublayer;
+
+/**
+ * Indicates whether the input object is an instance of `SupportedLayer` (`FeatureLayer` or `SubtypeSublayer`).
+ *
+ * @param queryObject
+ * @internal
+ */
+export function isSupportedLayer(
+  queryObject: QueryObject
+): queryObject is SupportedLayer;
+
+/**
+ * Returns the main `Layer` instance associated with the layer being used.
+ *
+ * Only needed for the case where the layer is a `SubtypeSublayer`, in which case we use the parent layer which is a `SubtypeGroupLayer`.
+ *
+ * @param layer
+ * @internal
+ */
+export function getMainLayer(
+  layer: FeatureLayer | Pick<SubtypeSublayer, "parent" | "type">
+): FeatureLayer | SubtypeGroupLayer;
+
+/**
+ * @param layer
+ * @internal
+ */
+export function getMainLayer(
+  layer: FeatureLayer | Pick<SubtypeSublayer, "parent" | "type"> | undefined
+): FeatureLayer | SubtypeGroupLayer | null | undefined;
+
+/**
+ * @param layer
+ * @internal
+ */
+export function getMainLayer(
+  layer: FeatureLayer | Pick<SubtypeSublayer, "parent" | "type"> | undefined
+): FeatureLayer | SubtypeGroupLayer | null | undefined;
+
+/**
+ * Indicates whether a layer supports queries with a `distance` parameter
+ *
+ * @param layer - The layer to test
+ * @returns A boolean
+ * @internal
+ */
+export function doesLayerSupportQueryWithDistance(
+  layer: SupportedLayer
+): boolean;
+
+/**
+ * Indicates whether a layer supports the queryBins operation for the heat chart use case.
+ *
+ * @param layer - The layer to test
+ * @returns A boolean indicating whether the operation is supported
+ * @internal
+ */
+export function doesLayerSupportsQueryBinsForHeatChart(
+  layer: SupportedLayer
+): boolean;
+
+/**
+ * Indicates whether a layer supports the queryBins operation for the temporal data use case.
+ * We currently only use the "date" operation.
+ * If a split-by field is provided we verify whether `stackBy` parameter is supported (refer to `mapAttributeBinsQuery()`).
+ *
+ * @param layer - The layer to test
+ * @param splitByField - The split-by field
+ * @returns A boolean indicating whether the operation is supported
+ * @internal
+ */
+export function doesLayerSupportsQueryBinsForTemporalData(
+  layer?: FeatureLayerView | SubtypeGroupLayer | SupportedLayer,
+  splitByField?: string
+): boolean;
+
+/**
+ * Indicates whether the layer supports the cacheHint parameter for the queryBins operation
+ *
+ * @param queryObject - The layer or feature layer view
+ * @internal
+ */
+export function doesLayerSupportsCacheHintForQueryBins(
+  queryObject: QueryObject
+): boolean;
+
+/**
+ * Indicates whether the layer supports the query bins operation for scatterplot:
+ * - supports queryBins
+ * - supports the type `fixedIntervalBin`
+ * - statistics: supports MAX and COUNT
+ *
+ * @param queryObject - The layer or feature layer view
+ * @internal
+ */
+export function doesLayerSupportsQueryBinsForScatterplot(
+  queryObject: QueryObject
+): boolean;
+
+/**
+ * Returns a feature layer from a QueryObject instance.
+ * It will use the QueryObject itself if it's a Feature Layer, or the `layer` property from it if it's a Feature Layer View.
+ *
+ * @param layerOrLayerView
+ * @internal
+ */
+export function getLayerFromLayerOrLayerView(
+  layerOrLayerView: FeatureLayerView | SupportedLayer
+): SupportedLayer;
+
+/**
+ * Returns a feature layer from a QueryObject instance.
+ * It will use the QueryObject itself if it's a Feature Layer, or the `layer` property from it if it's a Feature Layer View.
+ *
+ * @param queryObject
+ * @internal
+ */
+export function getLayerFromQueryObject(
+  queryObject: QueryObject
+): SupportedLayer;
+
+/**
+ * Computes a feature layer capabilities regarding its spatial aggregation statistics.
+ * Only considers the 'EnvelopeAggregate' for now.
+ *
+ * @param layer - The layer instance
+ * @returns A sum up of the capabilities
+ * @internal
+ */
+export function getLayerSpatialAggregationStatisticsCapabilities(
+  layer: SupportedLayer
+): boolean;
+
+/**
+ * Adds a iLayer to a WebChart.
+ * If the `queryObject` prop is provided an `iLayer` is added to the config.
+ *
+ * @param props - The chart config with no iLayer
+ * @returns The update chart config with a `iLayer` property
+ * @internal
+ */
+export function addILayer<T extends WebChart>(props: {
+  chartConfig: T;
+  queryObject?: FeatureLayerView | SupportedLayer;
+}): T & WebChart;

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

@@ -0,0 +1,87 @@
+import type MapView from "@geoscene/core/views/MapView.js";
+import type {
+  ErrorStrings,
+  LocaleInfo,
+  UtilsStrings,
+  SupportedLocalesForFormats,
+} from "./interfaces.js";
+
+/**
+ * Finds the locale info of the closest element to the given element.
+ *
+ * @param element - The element to get the locale info from.
+ * @internal
+ */
+export function getLocaleInfo(element?: HTMLElement): LocaleInfo;
+
+/**
+ * Converts the given `timeZone` from GeoScene `MapView` to a valid time zone string.
+ *
+ * @param timeZone
+ * @internal
+ */
+export function convertTimeZone(
+  timeZone: MapView["timeZone"] | undefined
+): string | undefined;
+
+/**
+ * Returns the date string in the Calcite date picker's expected format `YYYY-MM-DD` based on the given date and time zone.
+ *
+ * @param date
+ * @param timeZone
+ * @internal
+ */
+export function getDateStringInCalciteDatePickerFormat(
+  date: Date,
+  timeZone: string
+): string;
+
+/**
+ * Returns the time string in the Calcite time picker's expected format `HH:mm` based on the given date and time zone.
+ *
+ * @param date
+ * @param timeZone
+ * @internal
+ */
+export function getTimeStringInCalciteTimePickerFormat(
+  date: Date,
+  timeZone: string
+): string;
+
+/**
+ * Performs locale aware parse float
+ *
+ * @param localizedString - string that has to be parsed
+ * @param locale - locale used for parsing the float
+ * @internal
+ */
+export function localeParseFloat(
+  localizedString: string,
+  locale?: string
+): number;
+
+/**
+ * Gets the format locale from the given element.
+ *
+ * @param element - HTMLElement to get the locale from
+ * @internal
+ */
+export function getElementFormatLocale(
+  element: HTMLElement
+): SupportedLocalesForFormats;
+
+/**
+ * Returns a default `CommonStrings` t9n object.
+ * This is used by the chart components unit tests and the charts-js Storybook demos.
+ *
+ * @internal
+ */
+export function getDefaultErrorsStrings(): Promise<ErrorStrings>;
+
+/**
+ * Returns a default `UtilsStrings` t9n object.
+ * This is used by the chart components unit tests and the charts-js Storybook demos.
+ *
+ * @internal
+ */
+export function getDefaultUtilsStrings(): Promise<UtilsStrings>;