@geospatial-sdk/core 0.0.5-alpha.9 → 0.0.5-dev.0.sha-bfaf14b

package/lib/model/events.ts

@@ -0,0 +1,113 @@
+import { EndpointError } from "@camptocamp/ogc-client";
+import { Feature } from "geojson";
+import BaseEvent from "ol/events/Event.js";
+import type { Extent } from "ol/extent.js";
+import {
+  ResolvedMapLayerState,
+  ResolvedMapState,
+  ResolvedMapViewState,
+} from "./resolved-map-state.js";
+
+export type FeaturesByLayerIndex = Map<number, Feature[]>;
+
+export const FeaturesClickEventType = "features-click";
+export interface FeaturesClickEvent {
+  type: typeof FeaturesClickEventType;
+  features: Feature[];
+  featuresByLayer: FeaturesByLayerIndex;
+}
+
+export const FeaturesHoverEventType = "features-hover";
+export interface FeaturesHoverEvent {
+  type: typeof FeaturesHoverEventType;
+  features: Feature[];
+  featuresByLayer: FeaturesByLayerIndex;
+}
+
+export const MapClickEventType = "map-click";
+export interface MapClickEvent {
+  type: typeof MapClickEventType;
+  coordinate: [number, number]; // expressed in lon/lat
+}
+
+export const MapViewStateChangeEventType = "map-view-state-change";
+export interface MapViewStateChangeEvent {
+  type: typeof MapViewStateChangeEventType;
+  viewState: ResolvedMapViewState;
+}
+
+export const MapLayerStateChangeEventType = "map-layer-state-change";
+export interface MapLayerStateChangeEvent {
+  type: typeof MapLayerStateChangeEventType;
+  layerState: ResolvedMapLayerState;
+  layerIndex: number;
+  layerId?: string | number;
+}
+
+export const MapStateChangeEventType = "map-state-change";
+export interface MapStateChangeEvent {
+  type: typeof MapStateChangeEventType;
+  mapState: ResolvedMapState;
+}
+
+export const LayerCreationErrorEventType = "layer-creation-error";
+export interface LayerCreationErrorEvent {
+  type: typeof LayerCreationErrorEventType;
+  error: Error;
+}
+
+export const LayerLoadingErrorEventType = "layer-loading-error";
+export interface LayerLoadingErrorEvent {
+  type: typeof LayerLoadingErrorEventType;
+  error: Error;
+  httpStatus?: number;
+}
+
+/**
+ * DEPRECATED
+ * Use the MapViewStateChangeEvent instead
+ */
+export const MapExtentChangeEventType = "map-extent-change";
+export interface MapExtentChangeEvent {
+  type: typeof MapExtentChangeEventType;
+  extent: Extent;
+}
+
+/**
+ * DEPRECATED
+ * Use the MapLayerStateChangeEvent and LayerLoadingErrorEvent instead
+ */
+export const SourceLoadErrorType = "source-load-error";
+export class SourceLoadErrorEvent extends BaseEvent {
+  message: string;
+  httpStatus?: number;
+  constructor(error: EndpointError | Error | Response) {
+    super(SourceLoadErrorType);
+    if (error instanceof Response) {
+      this.message = error.statusText;
+      this.httpStatus = error.status;
+    } else if (error instanceof EndpointError) {
+      const e = error as EndpointError;
+      this.message = e.message;
+      this.httpStatus = e.httpStatus;
+    } else {
+      this.message = error.message;
+    }
+  }
+}
+
+export interface MapEventsByType {
+  [FeaturesClickEventType]: FeaturesClickEvent;
+  [FeaturesHoverEventType]: FeaturesHoverEvent;
+  [MapClickEventType]: MapClickEvent;
+  [MapViewStateChangeEventType]: MapViewStateChangeEvent;
+  [MapLayerStateChangeEventType]: MapLayerStateChangeEvent;
+  [MapStateChangeEventType]: MapStateChangeEvent;
+  [LayerCreationErrorEventType]: LayerCreationErrorEvent;
+  [LayerLoadingErrorEventType]: LayerLoadingErrorEvent;
+  /**
+   * DEPRECATED
+   */
+  [MapExtentChangeEventType]: MapExtentChangeEvent;
+  [SourceLoadErrorType]: SourceLoadErrorEvent;
+}

package/lib/model/index.ts

@@ -1,2 +1,10 @@
-export * from "./map-context";
-export * from "./map-context-diff";
+/**
+ * @group Types
+ * @packageDocumentation
+ */
+
+export * from "./map-context.js";
+export * from "./map-context-diff.js";
+export * from "./events.js";
+export * from "./resolved-map-state.js";
+export * from "./style.js";

package/lib/model/map-context-diff.ts

@@ -1,4 +1,4 @@
-import { MapContextLayer, MapContextView } from "./map-context";
+import { MapContextLayer, MapContextView } from "./map-context.js";
 
 /**
  * Associates a position to a layer; the position is the index of
@@ -18,6 +18,15 @@ export interface MapContextLayerReordered {
   previousPosition: number;
 }
 
+/**
+ * Describes a layer that was changed: both states before and after change are included
+ */
+export interface MapContextLayerChanged {
+  layer: MapContextLayer;
+  previousLayer: MapContextLayer;
+  position: number;
+}
+
 /**
  * Describes a delta between two contexts, in order to be
  * applied to an existing map.
@@ -29,9 +38,9 @@ export interface MapContextLayerReordered {
  * 4. change layers
  */
 export interface MapContextDiff {
-  layersChanged: MapContextLayerPositioned[];
+  layersChanged: MapContextLayerChanged[];
   layersReordered: MapContextLayerReordered[];
   layersRemoved: MapContextLayerPositioned[];
   layersAdded: MapContextLayerPositioned[];
-  viewChanges: MapContextView;
+  viewChanges?: MapContextView | null; // this is both optional (meaning no view change) and nullable (meaning reset to default view)
 }

package/lib/model/map-context.ts

@@ -1,11 +1,21 @@
 import { FeatureCollection, Geometry } from "geojson";
+import { VectorStyle } from "./style.js";
+import { WmsLayerDimensionValue } from "@camptocamp/ogc-client";
 
-export type LayerDimensions = Record<string, string>;
-
+/**
+ * @private
+ * @inline
+ */
 export type LayerExtras = Record<string, unknown>;
 
 export interface MapContextBaseLayer {
+  /**
+   * An optional identifier for the layer; if provided, will improve performance when the layers is updated through a context diff.
+   */
   id?: string | number;
+  /**
+   * Optional version indicator; if provided, must be increased by the application for the change detection to trigger, otherwise the SDK will consider that the layer is unchanged.
+   */
   version?: number;
 
   /**
@@ -14,87 +24,270 @@ export interface MapContextBaseLayer {
    * non-serializable entities
    */
   extras?: LayerExtras;
+
+  /**
+   * Whether the layer is visible or not on the map. A non-visible layer will still have its data queried and kept in memory, so switching this on/off shows immediately on the map.
+   *
+   * Default value is `true` (visible).
+   */
   visibility?: boolean;
+
+  /**
+   * Opacity level; between 0 and 1.
+   *
+   * Default value is 1 (fully opaque).
+   */
   opacity?: number;
+
+  /**
+   * Optional label for the layer, typically used to represent the layer in a layer list or when showing a popup above a feature.
+   */
   label?: string;
+
+  /**
+   * Attributions for the layer. Optional but strongly recommended: remember to attribute your map!
+   */
   attributions?: string;
+
+  /**
+   * Whether data on the layer can be picked up using the `feature-click` event.
+   *
+   * Default value is `true`. Set to `false` to save performance.
+   */
+  clickable?: boolean;
+
+  /**
+   * Whether features on the layer can be picked up using the `feature-hover` event. Mostly has an effect only for vector layers.
+   *
+   * Default value is `false`.
+   */
+  hoverable?: boolean;
+
+  /**
+   * Controls the `Referer` header sent with tile/image requests.
+   * See the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Request/referrerPolicy) for possible values.
+   *
+   * Support depends on the layer type and the map library used.
+   */
+  referrerPolicy?: ReferrerPolicy;
+}
+
+/**
+ * Dates are expressed as ISO8601 strings, e.g. "2023-01-01T00:00:00Z" or "2023-01-01"
+ */
+export type DateString = string;
+
+export interface TimeInterval {
+  begin: DateString;
+  end: DateString;
 }
+export interface ValueInterval {
+  begin: WmsLayerDimensionValue;
+  end: WmsLayerDimensionValue;
+}
+export type LayerDimensionValue =
+  WmsLayerDimensionValue | WmsLayerDimensionValue[] | ValueInterval;
+
+export type LayerTimeDimensionValue =
+  DateString | DateString[] | TimeInterval | "current";
 
 export interface MapContextLayerWms extends MapContextBaseLayer {
   type: "wms";
   url: string;
   name: string;
-  dimensions?: LayerDimensions;
+
+  /**
+   * value of the built-in TIME dimension to request; can be a single date, a list of dates, a temporal interval, or a list of intervals
+   */
+  timeValue?: LayerTimeDimensionValue;
+
+  /**
+   * value of the built-in ELEVATION dimension to request; can be a single value, a list of discrete values, an interval, or a list of intervals
+   */
+  elevationValue?: LayerDimensionValue;
+
+  /**
+   * value of any other dimension to request (either scalar or temporal); key is the dimension name, it will be prefixed by DIM_ in the request
+   */
+  otherDimensionValues?: Record<
+    string,
+    LayerDimensionValue | LayerTimeDimensionValue
+  >;
+
+  /**
+   * If unspecified, will use the default one
+   */
   style?: string;
+
+  /**
+   * Vendor-specific WMS parameters that are appended as-is to every GetMap request.
+   * Use this for non-standard server extensions such as NcWMS (`COLORSCALERANGE`, `LOGSCALE`).
+   * Keys are case-sensitive; they are passed without transformation.
+   */
+  customParams?: Record<string, string>;
+
+  /**
+   * Whether to use tiled WMS requests. Tiled requests include a `TILED=true` parameter as per https://wiki.osgeo.org/wiki/WMS_Tiling_Client_Recommendation
+   *
+   * Using tiled requests allow tiles to be cached and thus the server load to potentially be reduced; on the other hand,
+   * it can increase the time to show the layer and degrade the quality of the rendering (e.g. with labels).
+   *
+   * Note: untiled requests are not supported by MapLibre-GL-JS
+   *
+   * Default value: `true` (use tiled requests)
+   */
+  useTiles?: boolean;
+
+  /**
+   * The image format MIME type to use for WMS requests, e.g. `"image/png"` or `"image/jpeg"`.
+   *
+   * If not specified, the WMS server's default format will be used.
+   */
+  format?: string;
+
+  /**
+   * An OGC encoded filter (e.g. an OGC `<Filter>` document) applied verbatim to the WMS
+   * GetMap `FILTER` parameter. Use it to restrict the features rendered by the layer.
+   *
+   * The value is passed through as-is; the SDK does not validate or transform it.
+   */
+  filter?: string;
 }
 
+/**
+ * @private
+ * @inline
+ */
+export type LayerDimensionSimpleValue =
+  string | number | DateString | "current";
+
 export interface MapContextLayerWmts extends MapContextBaseLayer {
   type: "wmts";
   url: string;
   name: string;
-  dimensions?: LayerDimensions;
+  // TODO: add support for these
+  dimensionValues?: Record<string, LayerDimensionSimpleValue>;
   style?: string;
 }
 
-export interface MapContextLayerWfs extends MapContextBaseLayer {
-  type: "wfs";
+export interface MapContextLayerVector {
+  style?: VectorStyle;
+  hoverStyle?: VectorStyle;
+}
+
+export type MapContextLayerWfs = MapContextBaseLayer &
+  MapContextLayerVector & {
+    type: "wfs";
+    url: string;
+    featureType: string;
+  };
+
+export type MapContextLayerOgcApi = MapContextBaseLayer &
+  MapContextLayerVector & {
+    type: "ogcapi";
+    url: string;
+    collection: string;
+    useTiles?: "vector" | "map";
+    tileMatrixSet?: string;
+    options?: Record<string, string>;
+  };
+
+// Layer pointing to a MapLibre Style spec, see https://maplibre.org/maplibre-style-spec/
+export interface MapContextLayerMapLibreStyle extends MapContextBaseLayer {
+  type: "maplibre-style";
+  styleUrl: string;
+  accessToken?: string;
+}
+
+export interface MapContextLayerGeotiff extends MapContextBaseLayer {
+  type: "geotiff";
   url: string;
-  featureType: string;
 }
 
 export interface MapContextLayerXyz extends MapContextBaseLayer {
   type: "xyz";
   url: string;
+  tileFormat?: "application/vnd.mapbox-vector-tile"; // If not specified, the system will automatically assume tiles are images.
 }
 
-interface LayerGeojson extends MapContextBaseLayer {
-  type: "geojson";
-}
-interface LayerGeojsonWithUrl extends LayerGeojson {
+export type LayerGeojson = MapContextBaseLayer &
+  MapContextLayerVector & {
+    type: "geojson";
+  };
+export interface LayerGeojsonWithUrl extends LayerGeojson {
   url: string;
   data?: never;
 }
-interface LayerGeojsonWithData extends LayerGeojson {
+export interface LayerGeojsonWithData extends LayerGeojson {
   data: FeatureCollection<Geometry | null> | string;
   url?: never;
 }
-
-/**
- * @interface
- */
 export type MapContextLayerGeojson = LayerGeojsonWithUrl | LayerGeojsonWithData;
 
 /**
- * @interface
+ * A layer that can be used in a map context.
  */
 export type MapContextLayer =
   | MapContextLayerWms
   | MapContextLayerWmts
   | MapContextLayerWfs
   | MapContextLayerXyz
-  | MapContextLayerGeojson;
+  | MapContextLayerGeojson
+  | MapContextLayerOgcApi
+  | MapContextLayerMapLibreStyle
+  | MapContextLayerGeotiff;
 
 export type Coordinate = [number, number];
 
 /**
- * Min X, min Y, max X, max Y
+ * Array components are respectively: minX, minY, maxX, maxY
  */
 export type Extent = [number, number, number, number];
 
 /**
  * @property center Expressed in longitude/latitude
+ * @property zoom
+ */
+export interface ViewByZoomAndCenter {
+  center: Coordinate;
+  zoom: number;
+}
+
+/**
  * @property extent Expressed in longitude/latitude
- * @property maxExtent Expressed in longitude/latitude
  */
-export interface MapContextView {
-  center?: Coordinate;
-  zoom?: number;
-  extent?: Extent;
+export interface ViewByExtent {
+  extent: Extent;
+}
+
+/**
+ * @property geometry Expressed in GeoJSON
+ */
+export interface ViewByGeometry {
+  geometry: Geometry;
+}
+
+/**
+ * A description of a map viewport in one of three ways:
+ *  * by center and zoom level,
+ *  * by extent,
+ *  * by geometry (in GeoJSON)
+ *
+ * Also allows specifying constraints for zoom and extent.
+ */
+export type MapContextView = (
+  ViewByZoomAndCenter | ViewByExtent | ViewByGeometry
+) & {
   maxZoom?: number;
   maxExtent?: Extent;
-}
+};
 
+/**
+ * A map context, containing layers and a view.
+ *
+ * Note: setting the `view` property to `null` indicates that the map should use a default global view.
+ */
 export interface MapContext {
   layers: MapContextLayer[];
-  view: MapContextView;
+  view: MapContextView | null;
 }

package/lib/model/resolved-map-state.ts

@@ -0,0 +1,67 @@
+import { Coordinate, Extent } from "./map-context.js";
+
+export type MapLayerCreationStatus =
+  | {
+      created: true;
+    }
+  | {
+      creationError: true;
+      creationErrorMessage: string;
+    };
+
+export type MapLayerLoadingStatus =
+  | {
+      loaded: true;
+    }
+  | {
+      loadingError: true;
+      loadingErrorMessage: string;
+      loadingErrorHttpStatus?: number;
+    }
+  | {
+      loading: true;
+    };
+
+export interface MapLayerDataInfo {
+  featuresCount?: number;
+  geometryTypes?: Array<"Point" | "LineString" | "Polygon">;
+}
+
+export interface ResolvedMapLayerIdentity {
+  id?: string | number;
+}
+
+export type ResolvedMapLayerState = MapLayerCreationStatus &
+  MapLayerLoadingStatus &
+  MapLayerDataInfo &
+  ResolvedMapLayerIdentity;
+
+/**
+ * Describes the actual view state of a map
+ */
+export interface ResolvedMapViewState {
+  /** View center in longitude/latitude */
+  center: Coordinate;
+
+  /** Actual view extent in longitude/latitude */
+  extent: Extent;
+
+  /** Map units per pixel */
+  resolution: number;
+
+  /** Scale denominator (takes into account an estimated DPI) */
+  scaleDenominator: number;
+
+  /** Bearing in degrees; 90 is North (up) */
+  bearing: number;
+}
+
+/**
+ * Describes the actual state of a map after a context or context diff was applied to it.
+ * A `view` of null means the view state hasn't been changed yet.
+ * A `layer` item of null means the layer state hasn't been changed yet.
+ */
+export interface ResolvedMapState {
+  layers: Array<ResolvedMapLayerState | null>;
+  view: ResolvedMapViewState | null;
+}

package/lib/model/style.ts

@@ -0,0 +1,3 @@
+import type { FlatStyleLike } from "ol/style/flat.js";
+
+export type VectorStyle = FlatStyleLike;

package/lib/utils/freeze.test.ts

@@ -1,4 +1,4 @@
-import { deepFreeze } from "./freeze";
+import { deepFreeze } from "./freeze.js";
 
 describe("freeze util", () => {
   describe("deepFreeze", () => {