@disy/cadenza.js 10.4.1 → 10.4.2

package/cadenza.js

@@ -12,7 +12,7 @@
  */
 // This placeholder is replaced when Cadenza JS is released,
 // i.e. during development, the version is not available.
-const CADENZAJS_VERSION = '10.4.1';
+const CADENZAJS_VERSION = '10.4.2';
 /**
  * Creates an instance of the Cadenza JS client.
  *
@@ -158,6 +158,18 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * @property {'static'} type - The extent strategy type
  * @property {Extent} extent - This extent takes precedence over another extent that might be given in an API call.
  */
+/**
+ * @typedef CommonEditGeometryOptions - Common options for the initialization of the geometry editor.
+ * @property {LayerDefinition[]} [additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing.
+ * @property {UiFeature[]} [disabledUiFeatures] - Cadenza UI features to disable
+ * @property {ExtentStrategy} [extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
+ * @property {FilterVariables} [filter] - Filter variables
+ * @property {number} [minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
+ * @property {OperationMode} [operationMode] - The mode in which a workbook should be operated
+ * @property {AbortSignal} [signal] - A signal to abort the iframe loading
+ * @property {SnappingOptions} [snapping] - Passing these options enables snapping
+ * @property {boolean} [useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS and the created geometry should use the map's SRS (otherwise EPSG:4326 is assumed)
+ */
 /**
  * @typedef {'csv' | 'excel' | 'json' | 'pdf' | 'png'} DataType - A data type
  *
@@ -223,8 +235,6 @@ let firstEmbeddingTargetShown;
  *   When aborted, the result Promise is rejected with an {@link AbortError}.
  * * If there's another error, the result Promise is rejected with a {@link CadenzaError}.
  * * For methods that support the `hideMainHeaderAndFooter` and `hideWorkbookToolBar` parameters - the parameters cannot override the configuration of an embedding target.
- * * For methods that support the _deprecated_ `locationFinder` and `mapExtent` parameters - when both are given, the `mapExtent` takes precedence.
- *   * Both `locationFinder` and `mapExtent` parameters are _deprecated_ - Use {@link LocationFinderExtentStrategy} or {@link StaticExtentStrategy} instead.
  */
 // Must be exported to be included in the docs.
 export class CadenzaClient {
@@ -382,8 +392,6 @@ export class CadenzaClient {
      * @param {boolean} [__namedParameters.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer
      * @param {boolean} [__namedParameters.hideWorkbookToolBar] - Whether to hide the workbook toolbar
      * @param {GlobalId} [__namedParameters.highlightGlobalId] - The ID of an item to highlight / expand in the navigator
-     * @param {string} [__namedParameters.locationFinder] - A search query for the location finder - _Deprecated_: Use {@link LocationFinderExtentStrategy} instead.
-     * @param {Extent} [__namedParameters.mapExtent] - A map extent to set - _Deprecated_: Use {@link StaticExtentStrategy} instead.
      * @param {OperationMode} [__namedParameters.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the iframe loading
      * @param {boolean} [__namedParameters.useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS (otherwise EPSG:4326 is assumed)
@@ -394,7 +402,7 @@ export class CadenzaClient {
      * - {@link CadenzaActionEvent}
      * @embed
      */
-    async showMap(mapView, { additionalLayers, disabledUiFeatures, expandNavigator, extentStrategy, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, } = {}) {
+    async showMap(mapView, { additionalLayers, disabledUiFeatures, expandNavigator, extentStrategy, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, operationMode, useMapSrs, signal, } = {}) {
         this.#log('CadenzaClient#showMap', ...arguments);
         if (geometry) {
             assertValidGeometryType(geometry.type);
@@ -402,8 +410,6 @@ export class CadenzaClient {
         const validExtentStrategy = sanitizeExtentStrategy({
             extentStrategy,
             geometry,
-            locationFinder,
-            mapExtent,
         });
         const params = createParams({
             disabledUiFeatures,
@@ -445,16 +451,19 @@ export class CadenzaClient {
      *
      * Currently, only map views are supported.
      *
-     * @hidden
      * @template {DataType} T
-     * @param {T} dataType - The requested data type. Currently, only `"png"` is supported.
+     * @param {DataType} dataType - The requested data type. Currently, only `"png"` is
+     * @param {object} [__namedParameters] - Options
+     * @param {number} [__namedParameters.width] - The width of the resulting map image in px.
+     * @param {number} [__namedParameters.height] - The height of the resulting map image in px.
+     * @param {boolean} [__namedParameters.withScale] - Whether to show the scale line and the scale on the map image.
      * @return {Promise<T extends 'png' ? Blob : never>}
      * @postMessage
      */
-    async getData(dataType) {
+    async getData(dataType, { width, height, withScale } = {}) {
         this.#log('CadenzaClient#getData', ...arguments);
         assertSupportedDataType(dataType, ['png']);
-        return this.#postRequest('getData', { dataType });
+        return this.#postRequest('getData', { dataType, width, height, withScale });
     }
     /**
      * Set filter variables in the currently shown workbook.
@@ -557,19 +566,7 @@ export class CadenzaClient {
      *
      * @param {EmbeddingTargetId} backgroundMapView - The workbook map view in the background
      * @param {GeometryType} geometryType - The geometry type
-     * @param {object} [__namedParameters] - Options
-     * @param {LayerDefinition[]} [__namedParameters.additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing.
-     * @param {UiFeature[]} [__namedParameters.disabledUiFeatures] - Cadenza UI features to disable
-     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
-     * @param {FilterVariables} [__namedParameters.filter] - Filter variables
-     * @param {string} [__namedParameters.locationFinder] - A search query for the location finder - _Deprecated_: Use {@link LocationFinderExtentStrategy} instead.
-     * @param {Extent} [__namedParameters.mapExtent] - A map extent to set - _Deprecated_: Use {@link StaticExtentStrategy} instead.
-     * @param {number} [__namedParameters.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
-     * @param {OperationMode} [__namedParameters.operationMode] - The mode in which a workbook should be operated
-     * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the iframe loading
-     * @param {SnappingOptions} [__namedParameters.snapping] - Passing these options enables snapping
-     * @param {boolean} [__namedParameters.useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS and the created geometry should use the map's SRS (otherwise EPSG:4326 is assumed)
-     * @return {Promise<void>} A `Promise` for when the iframe is loaded
+     * @param {CommonEditGeometryOptions} [editGeometryOptions] - Options for the initialization of the geometry editor.
      * @throws For invalid arguments
      * @fires
      * - {@link CadenzaEditGeometryUpdateEvent}
@@ -577,12 +574,10 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    async createGeometry(backgroundMapView, geometryType, { additionalLayers, disabledUiFeatures, extentStrategy, filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, snapping, } = {}) {
+    async createGeometry(backgroundMapView, geometryType, { additionalLayers, disabledUiFeatures, extentStrategy, filter, minScale, useMapSrs, operationMode, signal, snapping, } = {}) {
         this.#log('CadenzaClient#createGeometry', ...arguments);
         const validExtentStrategy = sanitizeExtentStrategy({
             extentStrategy,
-            locationFinder,
-            mapExtent,
         });
         const params = createParams({
             action: 'editGeometry',
@@ -596,30 +591,18 @@ export class CadenzaClient {
             validExtentStrategy,
         });
         await this.#show(resolvePath(backgroundMapView), params, signal);
-        if (additionalLayers) {
-            for (const layer of additionalLayers) {
-                await this.#postRequest('importLayer', layer);
-            }
-        }
-        this.#setExtentStrategy(validExtentStrategy);
+        await this.#setupEditorViaPostRequests({
+            additionalLayers,
+            validExtentStrategy,
+        });
+        await this.#setEditorStateToReady();
     }
     /**
      * Edit a geometry.
      *
      * @param {EmbeddingTargetId} backgroundMapView - The workbook map view in the background
-     * @param {Geometry} geometry - The geometry
-     * @param {object} [__namedParameters] - Options
-     * @param {LayerDefinition[]} [__namedParameters.additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing. Each is a layer definition, with name, type and content (a Geojson featureCollection).
-     * @param {UiFeature[]} [__namedParameters.disabledUiFeatures] - Cadenza UI features to disable
-     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
-     * @param {FilterVariables} [__namedParameters.filter] - Filter variables
-     * @param {string} [__namedParameters.locationFinder] - A search query for the location finder - _Deprecated_: Use {@link LocationFinderExtentStrategy} instead.
-     * @param {Extent} [__namedParameters.mapExtent] - A map extent to set - _Deprecated_: Use {@link StaticExtentStrategy} instead.
-     * @param {number} [__namedParameters.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
-     * @param {OperationMode} [__namedParameters.operationMode] - The mode in which a workbook should be operated
-     * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the iframe loading
-     * @param {SnappingOptions} [__namedParameters.snapping] - Passing these options enables snapping
-     * @param {boolean} [__namedParameters.useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {Geometry} geometry - The geometry to edit
+     * @param {CommonEditGeometryOptions} [editGeometryOptions] - Options for the initialization of the geometry editor.
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -628,19 +611,99 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    async editGeometry(backgroundMapView, geometry, { additionalLayers, disabledUiFeatures, extentStrategy, filter, locationFinder, mapExtent, minScale, operationMode, signal, snapping, useMapSrs, } = {}) {
+    async editGeometry(backgroundMapView, geometry, { additionalLayers, disabledUiFeatures, extentStrategy, filter, minScale, operationMode, signal, snapping, useMapSrs, } = {}) {
         this.#log('CadenzaClient#editGeometry', ...arguments);
-        assertValidGeometryType(geometry.type);
+        const geometryType = geometry.type;
+        assertValidGeometryType(geometryType);
         const validExtentStrategy = sanitizeExtentStrategy({
             extentStrategy,
             geometry,
-            locationFinder,
-            mapExtent,
         });
         const params = createParams({
             action: 'editGeometry',
             disabledUiFeatures,
             filter,
+            geometryType,
+            minScale,
+            operationMode,
+            snapping,
+            useMapSrs,
+            validExtentStrategy,
+        });
+        await this.#show(resolvePath(backgroundMapView), params, signal);
+        await this.#setupEditorViaPostRequests({
+            additionalLayers,
+            validExtentStrategy,
+            geometry,
+        });
+        await this.#setEditorStateToReady();
+    }
+    /**
+     * Create multiple geometries.
+     *
+     * @param {EmbeddingTargetId} backgroundMapView - The workbook map view in the background
+     * @param {GeometryType} geometryType - The type of geometries to create
+     * @param {CommonEditGeometryOptions} [editGeometryOptions] - Options for the initialization of the geometry editor.
+     * @return {Promise<void>} A `Promise` for when the iframe is loaded
+     * @throws For invalid arguments
+     * @fires
+     * - {@link CadenzaEditGeometryUpdateEvent}
+     * - {@link CadenzaEditGeometryOkEvent}
+     * - {@link CadenzaEditGeometryCancelEvent}
+     * @embed
+     */
+    async batchCreateGeometry(backgroundMapView, geometryType, { additionalLayers, disabledUiFeatures, extentStrategy, filter, minScale, operationMode, signal, snapping, useMapSrs, } = {}) {
+        this.#log('CadenzaClient#editGeometry', ...arguments);
+        assertValidGeometryType(geometryType);
+        const validExtentStrategy = sanitizeExtentStrategy({
+            extentStrategy,
+        });
+        const params = createParams({
+            action: 'editGeometry',
+            batchModeEnabled: true,
+            disabledUiFeatures,
+            filter,
+            geometryType,
+            minScale,
+            operationMode,
+            snapping,
+            useMapSrs,
+            validExtentStrategy,
+        });
+        await this.#show(resolvePath(backgroundMapView), params, signal);
+        await this.#setupEditorViaPostRequests({
+            additionalLayers,
+            validExtentStrategy,
+        });
+        await this.#setEditorStateToReady();
+    }
+    /**
+     * Edit multiple geometries.
+     *
+     * @param {EmbeddingTargetId} backgroundMapView - The workbook map view in the background
+     * @param {FeatureCollection} features - The features to edit. The last feature in this collection is directly set up for editing.
+     * @param {CommonEditGeometryOptions} [editGeometryOptions] - Options for the initialization of the geometry editor.
+     * @return {Promise<void>} A `Promise` for when the iframe is loaded
+     * @throws For invalid arguments
+     * @fires
+     * - {@link CadenzaEditGeometryUpdateEvent}
+     * - {@link CadenzaEditGeometryOkEvent}
+     * - {@link CadenzaEditGeometryCancelEvent}
+     * @embed
+     */
+    async batchEditGeometry(backgroundMapView, features, { additionalLayers, disabledUiFeatures, extentStrategy, filter, minScale, operationMode, signal, snapping, useMapSrs, } = {}) {
+        this.#log('CadenzaClient#editGeometry', ...arguments);
+        const geometryType = getGeometryTypeFromFeatureCollection(features);
+        const validExtentStrategy = sanitizeExtentStrategy({
+            extentStrategy,
+            geometry: features.features[features.features.length - 1].geometry,
+        });
+        const params = createParams({
+            action: 'editGeometry',
+            batchModeEnabled: true,
+            disabledUiFeatures,
+            filter,
+            geometryType,
             minScale,
             operationMode,
             snapping,
@@ -648,17 +711,41 @@ export class CadenzaClient {
             validExtentStrategy,
         });
         await this.#show(resolvePath(backgroundMapView), params, signal);
+        await this.#setupEditorViaPostRequests({
+            additionalLayers,
+            validExtentStrategy,
+            features,
+        });
+        await this.#setEditorStateToReady();
+    }
+    /**
+     * @param {object} __namedParameters - Options
+     * @param [__namedParameters.geometry] {Geometry} - The geometry to edit
+     * @param [__namedParameters.additionalLayers] {LayerDefinition[]} - Layer definitions to be imported and shown in the background, as a basis for the drawing.
+     * @param [__namedParameters.validExtentStrategy] {ExtentStrategy} - Defines the initial map extent; If not given, Cadenza's default logic is used.
+     * @param [__namedParameters.features] {FeatureCollection} - The features to edit. The last feature in this collection is directly set up for editing.
+     * @returns {Promise<Awaited<unknown>[]>}
+     */
+    #setupEditorViaPostRequests({ geometry, additionalLayers, validExtentStrategy, features, }) {
+        const postRequests = [];
+        postRequests.push(this.#setExtentStrategy(validExtentStrategy));
         if (geometry) {
-            this.#postEvent('setGeometry', {
+            postRequests.push(this.#postRequest('setGeometry', {
                 geometry,
-            });
+            }));
         }
         if (additionalLayers) {
             for (const layer of additionalLayers) {
-                await this.#postRequest('importLayer', layer);
+                postRequests.push(this.#postRequest('importLayer', layer));
             }
         }
-        this.#setExtentStrategy(validExtentStrategy);
+        if (features) {
+            postRequests.push(this.#postRequest('addFeatures', features));
+        }
+        return Promise.all(postRequests);
+    }
+    #setEditorStateToReady() {
+        return this.#postRequest('setEditorState', 'READY');
     }
     /**
      * Set custom validity state of the geometry editor in addition to the default validation state (including errors and
@@ -682,8 +769,6 @@ export class CadenzaClient {
      * @param {FilterVariables} [__namedParameters.filter] - Filter variables
      * @param {(WorkbookLayerPath | string)[]} [__namedParameters.layers] - Layers to restrict the selection to
      *  (identified using layer paths or print names)
-     * @param {string} [__namedParameters.locationFinder] - A search query for the location finder - _Deprecated_: Use {@link LocationFinderExtentStrategy} instead.
-     * @param {Extent} [__namedParameters.mapExtent] - A map extent to set - _Deprecated_: Use {@link StaticExtentStrategy} instead.
      * @param {boolean} [__namedParameters.useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS (otherwise EPSG:4326 is assumed)
      * @param {OperationMode} [__namedParameters.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the iframe loading
@@ -696,12 +781,9 @@ export class CadenzaClient {
      * - {@link CadenzaSelectObjectsCancelEvent}
      * @embed
      */
-    async selectObjects(backgroundMapView, { extentStrategy, filter, layers, locationFinder, mapExtent, useMapSrs, operationMode, signal, } = {}) {
+    async selectObjects(backgroundMapView, { extentStrategy, filter, layers, useMapSrs, operationMode, signal } = {}) {
         this.#log('CadenzaClient#selectObjects', ...arguments);
         const validExtentStrategy = sanitizeExtentStrategy({
-            geometry: undefined,
-            locationFinder,
-            mapExtent,
             extentStrategy,
         });
         const params = createParams({
@@ -719,7 +801,7 @@ export class CadenzaClient {
         const type = extentStrategy?.type;
         // Other extent strategies are handled via URL parameters.
         if (type === 'geometry' || type === 'layerData') {
-            this.#postEvent('setExtentStrategy', extentStrategy);
+            return this.#postRequest('setExtentStrategy', extentStrategy);
         }
     }
     /**
@@ -1173,6 +1255,7 @@ function assertValidFilterVariables(/** @type {FilterVariables} */ filter) {
 /**
  * @param {object} params
  * @param {string} [params.action]
+ * @param {boolean} [params.batchModeEnabled]
  * @param {DataType} [params.dataType]
  * @param {UiFeature[]} [params.disabledUiFeatures]
  * @param {boolean} [params.expandNavigator]
@@ -1194,7 +1277,7 @@ function assertValidFilterVariables(/** @type {FilterVariables} */ filter) {
  * @param {Layout | undefined} [params.layout]
  * @return {URLSearchParams}
  */
-function createParams({ action, dataType, disabledUiFeatures, expandNavigator, fileName, filter, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, layers, minScale, operationMode, parts, targetType, snapping, useMapSrs, validExtentStrategy, layout, }) {
+function createParams({ action, batchModeEnabled, dataType, disabledUiFeatures, expandNavigator, fileName, filter, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, layers, minScale, operationMode, parts, targetType, snapping, useMapSrs, validExtentStrategy, layout, }) {
     if (disabledUiFeatures) {
         disabledUiFeatures.forEach((feature) => assert(validUiFeature(feature), `Invalid UI feature: ${feature}`));
     }
@@ -1225,6 +1308,7 @@ function createParams({ action, dataType, disabledUiFeatures, expandNavigator, f
     }
     return new URLSearchParams({
         ...(action && { action }),
+        ...(batchModeEnabled && { batchModeEnabled: 'true' }),
         ...(dataType && { dataType }),
         ...(disabledUiFeatures && {
             disabledUiFeatures: disabledUiFeatures.join(),
@@ -1259,31 +1343,27 @@ function array(/** @type unknown */ value) {
 }
 /**
  * Creates a valid extent strategy based on these rules:
- * - `extentStrategy` trumps `geometry`, `geometry` trumps `mapExtent`, `mapExtent` trumps `locationFinder`.
- * - `mapExtent`, `locationFinder`, and `geometry` are used as fallback for
- *   {@link StaticExtentStrategy#extent}, {@link LocationFinderExtentStrategy#query},
- *   and {@link GeometryExtentStrategy#geometry} respectively.
+ * - `extentStrategy` trumps `geometry`.
+ * - `geometry` is used as fallback for {@link GeometryExtentStrategy#geometry}.
  *
  * If the result is not a valid extent strategy, the return value is undefined.
  *
  * @param {object} __namedParameters
  * @param {Geometry} [__namedParameters.geometry]
- * @param {string} [__namedParameters.locationFinder]
- * @param {Extent} [__namedParameters.mapExtent]
  * @param {ExtentStrategy} [__namedParameters.extentStrategy]
  * @return {ExtentStrategy | undefined}
  */
-function sanitizeExtentStrategy({ extentStrategy, mapExtent, locationFinder, geometry, } = {}) {
+function sanitizeExtentStrategy({ extentStrategy, geometry } = {}) {
     if (extentStrategy) {
         switch (extentStrategy.type) {
             case 'static':
-                const extent = extentStrategy.extent ?? mapExtent;
+                const extent = extentStrategy.extent;
                 if (extent) {
                     return { type: 'static', extent };
                 }
                 break;
             case 'locationFinder':
-                const query = extentStrategy.query ?? locationFinder;
+                const query = extentStrategy.query;
                 if (query) {
                     return { type: 'locationFinder', query };
                 }
@@ -1301,12 +1381,20 @@ function sanitizeExtentStrategy({ extentStrategy, mapExtent, locationFinder, geo
     if (geometry) {
         return { type: 'geometry', geometry };
     }
-    if (mapExtent) {
-        return { type: 'static', extent: mapExtent };
-    }
-    if (locationFinder) {
-        return { type: 'locationFinder', query: locationFinder };
-    }
+}
+/**
+ * Retrieves the {@link GeometryType} of the provided feature collection.
+ * All provided features must have geometries of the same type.
+ *
+ * @param {FeatureCollection} featureCollection - The feature collection to validate.
+ */
+function getGeometryTypeFromFeatureCollection(featureCollection) {
+    const features = featureCollection.features;
+    assert(features.length > 0, 'Feature collection is empty');
+    const geometryType = features[0].geometry.type;
+    assertValidGeometryType(geometryType);
+    assert(features.every((feature) => feature.geometry.type === geometryType), 'Geometries are not of the same type');
+    return geometryType;
 }
 // Please do not add internal event types like 'ready' here.
 /**

package/package.json

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