@disy/cadenza.js 2.11.0 → 2.13.0

package/cadenza.js

@@ -96,6 +96,14 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * * `"workbook-design"` - The workbook designer
  * * `"workbook-view-management"` - Add/Edit/Remove workbook views (Is included in 'workbook-design'.)
  * */
+/**
+ * @typedef Distance
+ * @property {number} value
+ * @property {LengthUnit} lengthUnit
+ */
+/**
+ * @typedef {'m'|'km'} LengthUnit
+ */
 /**
  * @typedef Geometry - A [GeoJSON](https://geojson.org/) geometry object
  * @property {GeometryType} type - The type of the geometry
@@ -106,6 +114,13 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * _Note:_ The GeoJSON geometry type "GeometryCollection" is currently not supported.
  */
 /** @typedef {[number,number,number,number]} Extent - An array of numbers representing an extent: [minx, miny, maxx, maxy] */
+/**
+ * @typedef {GeometryZoomTarget} ZoomTarget - An object describing a target to zoom to
+ */
+/**
+ * @typedef GeometryZoomTarget - Instructs Cadenza to zoom to a provided {@Link Geometry}
+ * @property {'geometry'} type The type of the zoom target
+ */
 /**
  * @typedef {'csv' | 'excel' | 'json' | 'pdf' | 'png'} DataType - A data type
  *
@@ -120,6 +135,18 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * _Note:_ Since numbers in JavaScript are Double values ([more info on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_encoding)),
  * for Long variables, the API is currently limited to the Double value range.
  */
+/**
+ * @typedef Feature - A adapted [GeoJSON](https://geojson.org/) feature object.
+ * @property {any[]} objectId - The id of the feature
+ * @property {Geometry} geometry - The geometry
+ * @property {Record<string, string>} properties - The formated properties
+ * @property {number} [area] - The area of a `Polygon` feature
+ * @property {number} [length] - The area of a `LineString` feature
+ */
+/**
+ * @typedef FeatureCollection - A adapted [GeoJSON](https://geojson.org/) feature collection object
+ * @property {Feature[]} features - The features within this collection
+ */
 let hasCadenzaSession = false;
 /** @type {Promise<void> | undefined} */
 let firstEmbeddingTargetShown;
@@ -226,7 +253,9 @@ export class CadenzaClient {
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
-     * @fires {@link CadenzaDrillThroughEvent}
+     * @fires
+     * - {@link CadenzaDrillThroughEvent}
+     * - {@link CadenzaActionEvent}
      * @embed
      */
     show(source, { dataType, disabledUiFeatures, expandNavigator, filter, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, operationMode, signal, } = {}) {
@@ -288,17 +317,21 @@ export class CadenzaClient {
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
      * @param {boolean} [options.useMapSrs] -  Whether the geometry and the extent are in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {ZoomTarget} [options.zoomTarget] - A target Cadenza should zoom to
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
-     * @fires {@link CadenzaDrillThroughEvent}
+     * @fires
+     * - {@link CadenzaDrillThroughEvent}
+     * - {@link CadenzaActionEvent}
      * @embed
      */
-    async showMap(mapView, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, } = {}) {
+    async showMap(mapView, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, zoomTarget, signal, } = {}) {
         this.#log('CadenzaClient#showMap', ...arguments);
         if (geometry) {
             assertValidGeometryType(geometry.type);
         }
+        const zoomToGeometry = geometry && zoomTarget?.type === 'geometry';
         const params = createParams({
             disabledUiFeatures,
             expandNavigator,
@@ -306,7 +339,9 @@ export class CadenzaClient {
             hideMainHeaderAndFooter,
             hideWorkbookToolBar,
             highlightGlobalId,
-            locationFinder,
+            // only use locationFinder if zoom to geometry is not set, to avoid
+            // zooming race condition for Cadenza versions below 10.1
+            locationFinder: zoomToGeometry ? undefined : locationFinder,
             mapExtent,
             operationMode,
             targetType: 'MAP',
@@ -314,7 +349,10 @@ export class CadenzaClient {
         });
         await this.#show(resolvePath(mapView), params, signal);
         if (geometry) {
-            this.#postEvent('setGeometry', { geometry });
+            this.#postEvent('setGeometry', {
+                geometry,
+                zoomToGeometry,
+            });
         }
     }
     /**
@@ -380,7 +418,7 @@ export class CadenzaClient {
      *
      * @hidden
      * @param {WorkbookLayerPath | string} layer - The data view layer to set the selection in
-     * @param {unknown[]} values - The IDs of the objects to select
+     * @param {unknown[][]} values - The IDs of the objects to select
      * @return {Promise<void>} A `Promise` for when the selection was set.
      * @postMessage
      */
@@ -393,7 +431,7 @@ export class CadenzaClient {
      *
      * @hidden
      * @param {WorkbookLayerPath | string} layer - The data view layer to change the selection in
-     * @param {unknown[]} values - The IDs of the objects to select
+     * @param {unknown[][]} values - The IDs of the objects to select
      * @return {Promise<void>} A `Promise` for when the selection was changed.
      * @postMessage
      */
@@ -406,7 +444,7 @@ export class CadenzaClient {
      *
      * @hidden
      * @param {WorkbookLayerPath | string} layer - The data view layer to change the selection in
-     * @param {unknown[]} values - The IDs of the objects to unselect
+     * @param {unknown[][]} values - The IDs of the objects to unselect
      * @return {Promise<void>} A `Promise` for when the selection was changed.
      * @postMessage
      */
@@ -464,6 +502,7 @@ export class CadenzaClient {
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {number} [options.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
      * @param {boolean} [options.useMapSrs] - Whether the geometry is in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {ZoomTarget} [options.zoomTarget] - A target Cadenza should zoom to
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
@@ -473,20 +512,26 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    async editGeometry(backgroundMapView, geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, signal } = {}) {
+    async editGeometry(backgroundMapView, geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, signal, } = {}) {
         this.#log('CadenzaClient#editGeometry', ...arguments);
         assertValidGeometryType(geometry.type);
+        const zoomToGeometry = geometry && zoomTarget?.type === 'geometry';
         const params = createParams({
             action: 'editGeometry',
             filter,
-            locationFinder,
+            // only use locationFinder if zoom to geometry is not set, to avoid
+            // zooming race condition for Cadenza versions below 10.1
+            locationFinder: zoomToGeometry ? undefined : locationFinder,
             mapExtent,
             minScale,
             useMapSrs,
         });
         await this.#show(resolvePath(backgroundMapView), params, signal);
         if (geometry) {
-            this.#postEvent('setGeometry', { geometry });
+            this.#postEvent('setGeometry', {
+                geometry,
+                zoomToGeometry,
+            });
         }
     }
     /**
@@ -719,18 +764,75 @@ export class CadenzaClient {
         const params = createParams({ dataType, filter, parts });
         return this.#fetch(resolvePath(source), params, signal);
     }
+    /**
+     * Fetch object info from a workbook map view.
+     *
+     * @param {EmbeddingTargetId} source - The workbook view to fetch object info from.
+     * @param {(WorkbookLayerPath | string)[]} layerPath - Layer path to identify the layer
+     *  (identified using layer paths or print names)
+     * @param {unknown[][]} objectIds - The IDs of the objects to select
+     * @param {object} [options] - Options
+     * @param {FilterVariables} [options.filter] - Filter variables
+     * @param {AbortSignal} [options.signal] - A signal to abort the data fetching
+     * @param {Boolean} [options.useMapSrs] - Use the map SRS instead of WGS84
+     * @param {Boolean} [options.fullGeometries] - Return non-simplified geometries
+     * @return {Promise<FeatureCollection>} A `Promise` for the fetch response
+     * @throws For invalid arguments
+     */
+    fetchObjectInfo(source, layerPath, objectIds, { filter, signal, useMapSrs, fullGeometries } = {}) {
+        this.#log('CadenzaClient#fetchObjectInfo', ...arguments);
+        const params = createParams({
+            filter,
+        });
+        return this.#fetch(resolvePath(source) + '/objectinfo', params, signal, JSON.stringify({
+            objectIds,
+            layerPath: array(layerPath),
+            useMapSrs,
+            fullGeometries,
+        })).then((response) => response.json());
+    }
+    /**
+     *  Fetch the intersection areas from a workbook map view layer in JSON format for a given area.
+     *
+     * @param {EmbeddingTargetId} source - The workbook view to fetch object info from.
+     * @param {(WorkbookLayerPath | string)[]} layerPath - Layer path to identify the layer
+     *  (identified using layer paths or print names)
+     * @param {Geometry} geometry - The intersection geometry
+     * @param {object} [options] - Options
+     * @param {boolean} [options.useMapSrs]  - The intersection geometry and the result geometries are in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {Distance} [options.buffer] - Buffer size for geometry of the transition
+     * @param {AbortSignal} [options.signal] - A signal to abort the data fetching
+     * @return {Promise<FeatureCollection>} A `Promise` for the fetch response
+     * @server
+     */
+    fetchAreaIntersections(source, layerPath, geometry, { useMapSrs, buffer, signal } = {}) {
+        this.#log('CadenzaClient#areaIntersections', ...arguments);
+        const params = createParams({});
+        return this.#fetch(resolvePath(source) + '/area-intersections', params, signal, JSON.stringify({
+            layerPath: array(layerPath),
+            geometry: geometry,
+            useMapSrs: useMapSrs,
+            buffer: buffer,
+        })).then((response) => response.json());
+    }
     async #fetch(
     /** @type string */ path, 
     /** @type URLSearchParams */ params, 
-    /** @type AbortSignal | undefined */ signal) {
+    /** @type AbortSignal | undefined */ signal, 
+    /** @type String | undefined If body is set, the fetch will be a post.*/ body) {
         const url = this.#createUrl(path, params);
         this.#log('Fetch', url.toString());
+        const method = body ? 'POST' : undefined;
+        const headers = new Headers();
+        headers.set('X-Requested-With', 'XMLHttpRequest');
+        if (body) {
+            headers.set('Content-Type', 'application/json');
+        }
         const res = await fetch(url, {
             signal,
-            headers: {
-                // Make Cadenza return an error instead of showing an error page.
-                'X-Requested-With': 'XMLHttpRequest',
-            },
+            method,
+            headers,
+            body,
         });
         if (!res.ok) {
             const errorType = {
@@ -955,7 +1057,8 @@ function array(/** @type unknown */ value) {
 }
 // Please do not add internal event types like 'ready' here.
 /**
- * @typedef {'change:selection'
+ * @typedef {'action'
+ * | 'change:selection'
  * | 'drillThrough'
  * | 'editGeometry:ok'
  * | 'editGeometry:update'
@@ -967,7 +1070,8 @@ function array(/** @type unknown */ value) {
  */
 /**
  * @template {CadenzaEventType} T
- * @typedef {T extends 'change:selection' ? CadenzaChangeSelectionEvent
+ * @typedef {T extends 'action' ? CadenzaActionEvent
+ *  : T extends 'change:selection' ? CadenzaChangeSelectionEvent
  *  : T extends 'drillThrough' ? CadenzaDrillThroughEvent
  *  : T extends 'editGeometry:update' ? CadenzaEditGeometryUpdateEvent
  *  : T extends 'editGeometry:ok' ? CadenzaEditGeometryOkEvent
@@ -985,6 +1089,9 @@ function array(/** @type unknown */ value) {
  * @property {TYPE} type - The event type
  * @property {DETAIL} detail - Optional event details (depending on the event type)
  */
+/**
+ * @typedef {CadenzaEvent<'action', {context: string}>} CadenzaActionEvent - When the user executed a POST message action, which is defined on an external link in the Cadenza management center.
+ */
 /*
  * @hidden
  * @typedef {CadenzaEvent<'change:extent', {extent: Extent}>} CadenzaChangeExtentEvent - When the user moved the map.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@disy/cadenza.js",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "license": "Apache-2.0",
   "repository": "github:DisyInformationssysteme/cadenza.js",
   "type": "module",

package/sandbox.cjs

@@ -6,8 +6,8 @@ const DEFAULT_CADENZA_URL = 'http://localhost:8080/cadenza';
 
 const index = process.argv.indexOf(CADENZA_URL_PARAM);
 const cadenzaUrlFromArgs = index !== -1
-    ? process.argv[index + 1]
-    : process.argv.find(arg => arg.startsWith(CADENZA_URL_PARAM + '='))?.slice(CADENZA_URL_PARAM.length + 1);
+  ? process.argv[index + 1]
+  : process.argv.find(arg => arg.startsWith(CADENZA_URL_PARAM + '='))?.slice(CADENZA_URL_PARAM.length + 1);
 const cadenzaUrl = new URL(cadenzaUrlFromArgs || process.env.CADENZA_URL || DEFAULT_CADENZA_URL);
 
 execSync(`npx --yes http-server -a localhost -c-1 -d false --proxy ${cadenzaUrl.origin} --proxy-options.headers.Origin ${cadenzaUrl.origin} -o /sandbox.html${cadenzaUrl.pathname !== '/' ? `?contextPath=${cadenzaUrl.pathname}` : ''}`, { stdio: 'inherit' });

package/sandbox.html

@@ -161,9 +161,9 @@
       },
       setFilter: data => cadenzaClient.setFilter(parseFilterVariables(data.filter)),
       setLayerVisibility: data => cadenzaClient.setLayerVisibility(JSON.parse(data.layer), data.visibility === 'on'),
-      setSelection: data => cadenzaClient.setSelection(JSON.parse(data.layer), JSON.parse(data.values)),
-      addSelection: data => cadenzaClient.addSelection(JSON.parse(data.layer), JSON.parse(data.values)),
-      removeSelection: data => cadenzaClient.removeSelection(JSON.parse(data.layer), JSON.parse(data.values)),
+      setSelection: data => cadenzaClient.setSelection(JSON.parse(data.layer), JSON.parse(data.objectIds)),
+      addSelection: data => cadenzaClient.addSelection(JSON.parse(data.layer), JSON.parse(data.objectIds)),
+      removeSelection: data => cadenzaClient.removeSelection(JSON.parse(data.layer), JSON.parse(data.objectIds)),
       createGeometry: data => cadenzaClient.createGeometry(data.embeddingTargetId, data.geometryType, getOptions(data)),
       editGeometry: ({ geometry, ...data }) => cadenzaClient.editGeometry(data.embeddingTargetId, JSON.parse(geometry), getOptions(data)),
       selectObjects: data => cadenzaClient.selectObjects(data.embeddingTargetId, getOptions(data)),
@@ -171,6 +171,16 @@
         console.log('Inspect the fetchData() request in the devtools.');
         cadenzaClient.fetchData(data.embeddingTargetId, data.dataType, getOptions(data));
       },
+      fetchObjectInfo: data => {
+        console.log('Inspect the fetchObjectInfo() request in the devtools.');
+        cadenzaClient.fetchObjectInfo(data.embeddingTargetId, JSON.parse(data.layer), JSON.parse(data.objectIds), getOptions(data))
+          .then(console.log);
+      },
+      fetchAreaIntersections: data => {
+        console.log('Inspect the fetchAreaIntersections() request in the devtools.');
+        cadenzaClient.fetchAreaIntersections(data.embeddingTargetId, JSON.parse(data.layer), JSON.parse(data.geometry), getOptions(data))
+          .then(console.log);
+      },
       downloadData: data => cadenzaClient.downloadData(data.embeddingTargetId, data.dataType, getOptions(data))
     };
 
@@ -216,7 +226,11 @@
       parts,
       layers,
       simplifiedOperationMode,
-      useMapSrs
+      useMapSrs,
+      fullGeometries,
+      zoomToGeometry,
+      distance,
+      lengthUnit
     }) {
       return {
         disabledUiFeatures: disabledUiFeatures && disabledUiFeatures.split(','),
@@ -235,7 +249,10 @@
         parts: parts && parts.split(','),
         ...(simplifiedOperationMode === 'on' && { operationMode: 'simplified' }),
         layers: layers ? JSON.parse(layers) : undefined,
-        useMapSrs: useMapSrs === 'on'
+        useMapSrs: useMapSrs === 'on',
+        fullGeometries: fullGeometries === 'on',
+        zoomTarget: zoomToGeometry === 'on' ? { type: 'geometry' } : undefined,
+        buffer: distance ? { value: Number(distance), lengthUnit: lengthUnit ? lengthUnit : 'm' } : undefined
       };
     }
 
@@ -284,6 +301,8 @@
           <optgroup label="Without Iframe">
             <option value="downloadData">Download data</option>
             <option value="fetchData">Fetch data</option>
+            <option value="fetchObjectInfo">Fetch Object Info</option>
+            <option value="fetchAreaIntersections">Fetch Area Intersections</option>
           </optgroup>
         </select>
       </div>
@@ -442,7 +461,7 @@
   </div>
 </template>
 
-<template data-action="showMap" data-common="map,showWorkbook,filter,show">
+<template data-action="showMap" data-common="zoomTo,map,showWorkbook,filter,show">
   <div>
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
@@ -477,7 +496,7 @@
   </div>
 </template>
 
-<template data-action="editGeometry" data-common="map,filter">
+<template data-action="editGeometry" data-common="zoomTo,map,filter">
   <div>
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
@@ -518,9 +537,9 @@
   </div>
 </template>
 
-<template data-action="setSelection" data-common="layer,layer-selection"></template>
-<template data-action="addSelection" data-common="layer,layer-selection"></template>
-<template data-action="removeSelection" data-common="layer,layer-selection"></template>
+<template data-action="setSelection" data-common="layer,object-ids"></template>
+<template data-action="addSelection" data-common="layer,object-ids"></template>
+<template data-action="removeSelection" data-common="layer,object-ids"></template>
 
 <template data-action="reload">
   <div>
@@ -532,12 +551,12 @@
 </template>
 <template data-action="closeMe">No Parameters needed.</template>
 
-<template id="common-layer-selection">
+<template id="common-object-ids">
   <div>
-    <label for="values">List of Object IDs *</label>
-    <textarea name="values" id="values" rows="5" required></textarea>
+    <label for="objectids">List of object ID value lists *</label>
+    <textarea name="objectIds" id="objectids" rows="5" required></textarea>
     <small>
-      <p>A JSON value like <code>["object1","object2"]</code></p>
+      <p>A JSON value like <code>[["&lt;object1-id&gt;"],["&lt;object2-id&gt;"]]</code></p>
     </small>
   </div>
 </template>
@@ -555,6 +574,15 @@
   </div>
 </template>
 
+<template id="common-zoomTo">
+  <div>
+    <label>
+      <input type="checkbox" name="zoomToGeometry">
+      Zoom to geometry
+    </label>
+  </div>
+</template>
+
 <template data-action="downloadData" data-common="data,filter">
   <div>
     <label for="embeddingTargetId">Embedding target ID *</label>
@@ -573,6 +601,61 @@
   </div>
 </template>
 
+<template data-action="fetchObjectInfo" data-common="layer,object-ids,filter">
+  <div>
+    <label for="embeddingTargetId">Embedding target ID *</label>
+    <input name="embeddingTargetId" id="embeddingTargetId" required>
+  </div>
+  <div>
+    <label>
+      <input type="checkbox" name="useMapSrs">
+      Use map SRS
+    </label>
+  </div>
+  <div>
+    <label>
+      <input type="checkbox" name="fullGeometries">
+      Return the non-simplified geometries
+    </label>
+  </div>
+</template>
+
+<template data-action="fetchAreaIntersections" data-common="layer">
+  <div>
+    <label for="embeddingTargetId">Embedding target ID *</label>
+    <input name="embeddingTargetId" id="embeddingTargetId" required>
+  </div>
+  <div>
+    <label for="geometry">Intersection Geometry (GeoJSON) *</label>
+    <textarea name="geometry" id="geometry" rows="5" required></textarea>
+    <small>
+      <p>
+        The geometry must result in an area in combination with the buffer specification.
+      </p>
+    </small>
+  </div>
+  <div>
+    <label>
+      <input type="checkbox" name="useMapSrs">
+      Use map SRS
+    </label>
+  </div>
+  <div>
+    <label for="distance">Buffer size</label>
+    <input name="distance" id="distance" type="number" min="0">
+    <label for="lengthUnit">Length unit</label>
+    <select name="lengthUnit" id="lengthUnit">
+      <option>m</option>
+      <option>km</option>
+    </select>
+    <small>
+      <p>
+        A positive buffer size is needed for point or line intersection geometries.
+      </p>
+    </small>
+  </div>
+</template>
+
 <template data-action="getData">
   <div>
     <label for="dataType">Data type</label>