@geospatial-sdk/core 0.0.5-dev.44 → 0.0.5-dev.45

package/README.md

@@ -1,11 +1,44 @@
-# `core`
+# `@geospatial-sdk/core`
 
-> TODO: description
+<!-- #region body -->
 
-## Usage
+This package provides the foundation for the Geospatial SDK.
+
+It includes:
+
+- **Map Context model**: TypeScript types and interfaces for declaratively defining maps, layers, and views
+- **Diff algorithms**: Utilities to compute differences between Map Context objects (`computeMapContextDiff`)
+- **Validation utilities**: Tools for working with and validating geospatial data
+- **Shared constants**: Common definitions used across all packages
+
+The `@geospatial-sdk/core` package is framework-agnostic and does not depend on any specific mapping library. It's required by all other packages in the SDK.
 
+## Installation
+
+```sh
+npm install @geospatial-sdk/core
 ```
-const core = require('core');
 
-// TODO: DEMONSTRATE API
+## Usage
+
+```typescript
+import { computeMapContextDiff, type MapContext } from "@geospatial-sdk/core";
+
+const oldContext: MapContext = {
+  layers: [{ type: "xyz", url: "https://example.com/{z}/{x}/{y}.png" }],
+  view: { center: [0, 0], zoom: 2 },
+};
+
+const newContext: MapContext = {
+  layers: [{ type: "xyz", url: "https://example.com/{z}/{x}/{y}.png" }],
+  view: { center: [5, 45], zoom: 5 },
+};
+
+const diff = computeMapContextDiff(newContext, oldContext);
 ```
+
+<!-- #endregion body -->
+
+## Documentation
+
+For more detailed API documentation, see the [documentation website](https://camptocamp.github.io/geospatial-sdk/docs/).

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * {@include ../README.md#body}
+ *
+ * @module 📦 core
+ */
 export * from "./utils/index.js";
 export * from "./model/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AACA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,3 +1,7 @@
-// PUBLIC API
+/**
+ * {@include ../README.md#body}
+ *
+ * @module 📦 core
+ */
 export * from "./utils/index.js";
 export * from "./model/index.js";

package/dist/model/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @group Types
+ * @packageDocumentation
+ */
 export * from "./map-context.js";
 export * from "./map-context-diff.js";
 export * from "./events.js";

package/dist/model/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/model/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/model/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC"}

package/dist/model/index.js

@@ -1,3 +1,7 @@
+/**
+ * @group Types
+ * @packageDocumentation
+ */
 export * from "./map-context.js";
 export * from "./map-context-diff.js";
 export * from "./events.js";

package/dist/model/map-context.d.ts

@@ -1,6 +1,14 @@
 import { FeatureCollection, Geometry } from "geojson";
 import { VectorStyle } from "./style.js";
+/**
+ * @private
+ * @inline
+ */
 export type LayerDimensions = Record<string, string>;
+/**
+ * @private
+ * @inline
+ */
 export type LayerExtras = Record<string, unknown>;
 export interface MapContextBaseLayer {
     id?: string | number;
@@ -67,17 +75,14 @@ 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 | MapContextLayerOgcApi | MapContextLayerMapLibreStyle;
 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];
 /**
@@ -95,15 +100,28 @@ export interface ViewByExtent {
     extent: Extent;
 }
 /**
- * @property geometry Expressed in longitude/latitude
+ * @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 | null;

package/dist/model/map-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map-context.d.ts","sourceRoot":"","sources":["../../lib/model/map-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"map-context.d.ts","sourceRoot":"","sources":["../../lib/model/map-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAGD,MAAM,WAAW,4BAA6B,SAAQ,mBAAmB;IACvE,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,oCAAoC,CAAC;CACnD;AAED,UAAU,YAAa,SAAQ,mBAAmB;IAChD,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AACD,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,KAAK,CAAC;CACd;AACD,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,IAAI,EAAE,iBAAiB,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;IAClD,GAAG,CAAC,EAAE,KAAK,CAAC;CACb;AACD,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAEhF;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,GAClB,sBAAsB,GACtB,qBAAqB,GACrB,4BAA4B,CAAC;AAEjC,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,CACzB,mBAAmB,GACnB,YAAY,GACZ,cAAc,CACjB,GAAG;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B"}

package/dist/utils/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @group Utils
+ * @packageDocumentation
+ */
 export * from "./url.js";
 export * from "./freeze.js";
 export * from "./hash.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC"}

package/dist/utils/index.js

@@ -1,3 +1,7 @@
+/**
+ * @group Utils
+ * @packageDocumentation
+ */
 export * from "./url.js";
 export * from "./freeze.js";
 export * from "./hash.js";

package/dist/utils/map-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map-context.d.ts","sourceRoot":"","sources":["../../lib/utils/map-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGhE,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,aAAa,UAAQ,GACpB,MAAM,CAER;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,eAAe,GACtB,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,eAAe,GACtB,OAAO,CAKT;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,GAC1B,MAAM,CAER;AAED;;;;;;;GAOG;AAEH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,CAQZ;AAED;;;;;;GAMG;AAEH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,GAC1B,UAAU,CAOZ;AAED;;;;;;;GAOG;AAEH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,EAC3B,WAAW,EAAE,eAAe,GAC3B,UAAU,CAOZ;AAED;;;;;;;GAOG;AAEH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,EAC3B,QAAQ,EAAE,MAAM,GACf,UAAU,CAGZ"}
+{"version":3,"file":"map-context.d.ts","sourceRoot":"","sources":["../../lib/utils/map-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGhE,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,aAAa,UAAQ,GACpB,MAAM,CAER;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,eAAe,GACtB,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,eAAe,GACtB,OAAO,CAST;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,GAC1B,MAAM,CAER;AAED;;;;;;;GAOG;AAEH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,CAQZ;AAED;;;;;;GAMG;AAEH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,GAC1B,UAAU,CAOZ;AAED;;;;;;;GAOG;AAEH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,EAC3B,WAAW,EAAE,eAAe,GAC3B,UAAU,CAOZ;AAED;;;;;;;GAOG;AAEH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,eAAe,EAC3B,QAAQ,EAAE,MAAM,GACf,UAAU,CAGZ"}

package/dist/utils/map-context.js

@@ -9,7 +9,9 @@ export function isLayerSame(layerA, layerB) {
     return getLayerHash(layerA) === getLayerHash(layerB);
 }
 export function isLayerSameAndUnchanged(layerA, layerB) {
-    if ("id" in layerA && "id" in layerB) {
+    if ("id" in layerA &&
+        "id" in layerB &&
+        ("version" in layerA || "version" in layerB)) {
         return layerA.id == layerB.id && layerA.version == layerB.version;
     }
     return getLayerHash(layerA, true) === getLayerHash(layerB, true);

package/dist/utils/view.d.ts

@@ -1,3 +1,25 @@
 import { MapContextLayer, MapContextView } from "../model/index.js";
+/**
+ * Creates a view from a layer by extracting its geographic extent. The returned extent is
+ * always expressed in EPSG:4326 (longitude/latitude) coordinates.
+ *
+ * @param layer - The map context layer to extract the extent from
+ * @returns A Promise resolving to a `ViewByExtent` object, or `null` if the extent cannot be determined
+ * @throws {Error} If the layer type is not supported
+ *
+ * @example
+ * ```typescript
+ * const wmsLayer: MapContextLayerWms = {
+ *   type: 'wms',
+ *   url: 'https://example.com/wms',
+ *   name: 'myLayer'
+ * };
+ *
+ * const view = await createViewFromLayer(wmsLayer);
+ * if (view) {
+ *   console.log('Extent:', view.extent); // [minX, minY, maxX, maxY] in EPSG:4326
+ * }
+ * ```
+ */
 export declare function createViewFromLayer(layer: MapContextLayer): Promise<MapContextView | null>;
 //# sourceMappingURL=view.d.ts.map

package/dist/utils/view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../lib/utils/view.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,eAAe,EAIf,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAK3B,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAYhC"}
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../lib/utils/view.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,eAAe,EAIf,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAYhC"}

package/dist/utils/view.js

@@ -6,6 +6,28 @@ import GeoJSON from "ol/format/GeoJSON.js";
 import { extend } from "ol/extent.js";
 import proj4 from "proj4";
 const GEOJSON = new GeoJSON();
+/**
+ * Creates a view from a layer by extracting its geographic extent. The returned extent is
+ * always expressed in EPSG:4326 (longitude/latitude) coordinates.
+ *
+ * @param layer - The map context layer to extract the extent from
+ * @returns A Promise resolving to a `ViewByExtent` object, or `null` if the extent cannot be determined
+ * @throws {Error} If the layer type is not supported
+ *
+ * @example
+ * ```typescript
+ * const wmsLayer: MapContextLayerWms = {
+ *   type: 'wms',
+ *   url: 'https://example.com/wms',
+ *   name: 'myLayer'
+ * };
+ *
+ * const view = await createViewFromLayer(wmsLayer);
+ * if (view) {
+ *   console.log('Extent:', view.extent); // [minX, minY, maxX, maxY] in EPSG:4326
+ * }
+ * ```
+ */
 export async function createViewFromLayer(layer) {
     if (layer.type === "wms") {
         return await getWmsLayerExtent(layer);

package/lib/index.ts

@@ -1,3 +1,8 @@
-// PUBLIC API
+/**
+ * {@include ../README.md#body}
+ *
+ * @module 📦 core
+ */
+
 export * from "./utils/index.js";
 export * from "./model/index.js";

package/lib/model/index.ts

@@ -1,3 +1,8 @@
+/**
+ * @group Types
+ * @packageDocumentation
+ */
+
 export * from "./map-context.js";
 export * from "./map-context-diff.js";
 export * from "./events.js";

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

@@ -33,5 +33,5 @@ export interface MapContextDiff {
   layersReordered: MapContextLayerReordered[];
   layersRemoved: MapContextLayerPositioned[];
   layersAdded: MapContextLayerPositioned[];
-  viewChanges?: MapContextView | null;
+  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,8 +1,16 @@
 import { FeatureCollection, Geometry } from "geojson";
 import { VectorStyle } from "./style.js";
 
+/**
+ * @private
+ * @inline
+ */
 export type LayerDimensions = Record<string, string>;
 
+/**
+ * @private
+ * @inline
+ */
 export type LayerExtras = Record<string, unknown>;
 
 export interface MapContextBaseLayer {
@@ -79,14 +87,10 @@ 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
@@ -100,7 +104,7 @@ export type MapContextLayer =
 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];
 
@@ -121,12 +125,20 @@ export interface ViewByExtent {
 }
 
 /**
- * @property geometry Expressed in longitude/latitude
+ * @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
@@ -136,7 +148,12 @@ export type MapContextView = (
   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 | null; // a view of "null" means the map will show a default view;
+  view: MapContextView | null;
 }

package/lib/utils/index.ts

@@ -1,3 +1,8 @@
+/**
+ * @group Utils
+ * @packageDocumentation
+ */
+
 export * from "./url.js";
 export * from "./freeze.js";
 export * from "./hash.js";

package/lib/utils/map-context.test.ts

@@ -99,8 +99,30 @@ describe("Map context utils", () => {
   });
 
   describe("isLayerSameAndUnchanged", () => {
-    describe("layers with id", () => {
+    describe("layers with id and version", () => {
       it("compares non-strictly by id and version field", () => {
+        expect(
+          isLayerSameAndUnchanged(
+            { ...SAMPLE_LAYER1, id: "ab", version: 2 },
+            { ...SAMPLE_LAYER2, id: "ab", version: 2 },
+          ),
+        ).toBe(true);
+        expect(
+          isLayerSameAndUnchanged(
+            { ...SAMPLE_LAYER1, id: "ab", version: 2 },
+            { ...SAMPLE_LAYER1, id: "ab", version: 1 },
+          ),
+        ).toBe(false);
+        expect(
+          isLayerSameAndUnchanged(
+            { ...SAMPLE_LAYER1, id: 1 },
+            { ...SAMPLE_LAYER1, id: "01", version: 3 },
+          ),
+        ).toBe(false);
+      });
+    });
+    describe("layers with id and both without version", () => {
+      it("compares by properties, including extras", () => {
         expect(
           isLayerSameAndUnchanged(
             { ...SAMPLE_LAYER1, id: "a" },
@@ -112,23 +134,23 @@ describe("Map context utils", () => {
             { ...SAMPLE_LAYER1, id: "a" },
             { ...SAMPLE_LAYER2, id: "a" },
           ),
-        ).toBe(true);
+        ).toBe(false);
         expect(
           isLayerSameAndUnchanged(
-            { ...SAMPLE_LAYER1, id: "ab", version: 2 },
-            { ...SAMPLE_LAYER2, id: "ab", version: 2 },
+            { ...SAMPLE_LAYER1, id: "a" },
+            { ...SAMPLE_LAYER1, id: "a" },
           ),
         ).toBe(true);
         expect(
           isLayerSameAndUnchanged(
-            { ...SAMPLE_LAYER1, id: "ab", version: 2 },
-            { ...SAMPLE_LAYER1, id: "ab", version: 1 },
+            { ...SAMPLE_LAYER2, id: "b", extras: { hello: "world" } },
+            { ...SAMPLE_LAYER2, id: "b", extras: { hello: "world" } },
           ),
-        ).toBe(false);
+        ).toBe(true);
         expect(
           isLayerSameAndUnchanged(
-            { ...SAMPLE_LAYER1, id: 1 },
-            { ...SAMPLE_LAYER1, id: "01", version: 3 },
+            { ...SAMPLE_LAYER2, id: "b", extras: { hello: "world" } },
+            { ...SAMPLE_LAYER2, id: "b", extras: { foo: "bar" } },
           ),
         ).toBe(false);
       });

package/lib/utils/map-context.ts

@@ -22,7 +22,11 @@ export function isLayerSameAndUnchanged(
   layerA: MapContextLayer,
   layerB: MapContextLayer,
 ): boolean {
-  if ("id" in layerA && "id" in layerB) {
+  if (
+    "id" in layerA &&
+    "id" in layerB &&
+    ("version" in layerA || "version" in layerB)
+  ) {
     return layerA.id == layerB.id && layerA.version == layerB.version;
   }
   return getLayerHash(layerA, true) === getLayerHash(layerB, true);

package/lib/utils/view.ts

@@ -19,6 +19,28 @@ import { FeatureCollection, Geometry } from "geojson";
 
 const GEOJSON = new GeoJSON();
 
+/**
+ * Creates a view from a layer by extracting its geographic extent. The returned extent is
+ * always expressed in EPSG:4326 (longitude/latitude) coordinates.
+ *
+ * @param layer - The map context layer to extract the extent from
+ * @returns A Promise resolving to a `ViewByExtent` object, or `null` if the extent cannot be determined
+ * @throws {Error} If the layer type is not supported
+ *
+ * @example
+ * ```typescript
+ * const wmsLayer: MapContextLayerWms = {
+ *   type: 'wms',
+ *   url: 'https://example.com/wms',
+ *   name: 'myLayer'
+ * };
+ *
+ * const view = await createViewFromLayer(wmsLayer);
+ * if (view) {
+ *   console.log('Extent:', view.extent); // [minX, minY, maxX, maxY] in EPSG:4326
+ * }
+ * ```
+ */
 export async function createViewFromLayer(
   layer: MapContextLayer,
 ): Promise<MapContextView | null> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geospatial-sdk/core",
-  "version": "0.0.5-dev.44+44c94a2",
+  "version": "0.0.5-dev.45+a90fe28",
   "description": "Core functions and models for the SDK",
   "author": "Olivia <olivia.guyot@camptocamp.com>",
   "homepage": "",
@@ -22,7 +22,7 @@
     "test": "vitest",
     "build": "tsc"
   },
-  "gitHead": "44c94a2e3458beb7e3f3ffc98ed170c21a0fc460",
+  "gitHead": "a90fe28ac749e1d35a976bdcfd02cb47357e8955",
   "dependencies": {
     "proj4": "^2.9.2"
   },