@disy/cadenza.js 10.2.3 → 10.2.5

package/cadenza.js

@@ -97,6 +97,12 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * * `"workbook-map-add-layer"`- Add layers to the map
  * * `"workbook-view-management"` - Add/Edit/Remove workbook views (Is included in 'workbook-design'.)
  * */
+/**
+ * @typedef LayerDefinition
+ * @property {string} name - The layer's name.
+ * @property {'geojson'} type - The layer's type.
+ * @property {FeatureCollection} content - The layer's content in geojson format.
+ */
 /**
  * @typedef Distance
  * @property {number} value
@@ -118,11 +124,34 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  */
 /** @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 {GeometryExtentStrategy|
+ * LayerDataExtentStrategy|
+ * LocationFinderExtentStrategy|
+ * StaticExtentStrategy} ExtentStrategy - Options for defining the initial extent of a workbook map view;
+ *   If the options do not result in a defined extent, Cadenza's default logic is used:
+ *   The map will zoom in the way the underlying workbook map view was configured to initially zoom including all auto
+ *   zooming configurations.
+ */
+/**
+ * @typedef GeometryExtentStrategy - The given {@link Geometry} defines the initial map extent.
+ * @property {'geometry'} type - The extent strategy type
+ * @property {Geometry} [geometry] - This geometry takes precedence over another geometry that might be given in an API call.
+ */
+/**
+ * @typedef LayerDataExtentStrategy - The given layers define the initial map extent.
+ * @property {'layerData'} type - The extent strategy type
+ * @property {(WorkbookLayerPath | string)[]} [layers] - A layer is ignored if either the layer or its extent is not known to Cadenza.
+ *   If no layers are given, __all__ map layers are used.
+ */
+/**
+ * @typedef LocationFinderExtentStrategy - The first result of a location finder query defines the initial map extent.
+ * @property {'locationFinder'} type - The extent strategy type
+ * @property {string} query - This query takes precedence over another query that might be given in an API call.
  */
 /**
- * @typedef GeometryZoomTarget - Instructs Cadenza to zoom to a provided {@Link Geometry}
- * @property {'geometry'} type The type of the zoom target
+ * @typedef StaticExtentStrategy - The given extent is used as the initial map extent.
+ * @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 {'csv' | 'excel' | 'json' | 'pdf' | 'png'} DataType - A data type
@@ -168,7 +197,8 @@ 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 `locationFinder` and `mapExtent` parameters - when both are given, the `mapExtent` takes precedence.
+ * * 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 {
@@ -189,7 +219,7 @@ export class CadenzaClient {
     /**
      *
      * @hidden
-     * @param {CadenzaClientOptions} [options]
+     * @param {CadenzaClientOptions} [__namedParameters]
      */
     constructor({ baseUrl, debug = false, iframe, webApplication } = {}) {
         if (webApplication) {
@@ -246,19 +276,19 @@ export class CadenzaClient {
      * Show a page, workbook, worksheet or workbook view in an iframe.
      *
      * @param {PageSource | EmbeddingTargetId} source - The source to show
-     * @param {object} [options]
-     * @param {DataType} [options.dataType] - Set to 'pdf' for embedding targets of type report and of views with view
+     * @param {object} [__namedParameters]
+     * @param {DataType} [__namedParameters.dataType] - Set to 'pdf' for embedding targets of type report and of views with view
      *     type of "JasperReports report" to show the generated report PDF directly (without any Cadenza headers or
      *     footers).
-     * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
-     * @param {boolean} [options.expandNavigator] - Indicates if the navigator should be expanded.
-     * @param {FilterVariables} [options.filter] - Filter variables
-     * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer
-     * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar
-     * @param {GlobalId} [options.highlightGlobalId] - The ID of an item to highlight / expand in the navigator
-     * @param {String} [options.labelSet] - The name of a label set defined in the `basicweb-config.xml` (only supported for the welcome page)
-     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
-     * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
+     * @param {UiFeature[]} [__namedParameters.disabledUiFeatures] - Cadenza UI features to disable
+     * @param {boolean} [__namedParameters.expandNavigator] - Indicates if the navigator should be expanded.
+     * @param {FilterVariables} [__namedParameters.filter] - Filter variables
+     * @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.labelSet] - The name of a label set defined in the `basicweb-config.xml` (only supported for the welcome page)
+     * @param {OperationMode} [__namedParameters.operationMode] - The mode in which a workbook should be operated
+     * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -291,8 +321,8 @@ export class CadenzaClient {
     }
     /**
      * Reload the views of a worksheet.
-     * @param {object} [options] - Options
-     * @param {boolean} [options.invalidateCaches] - When true, caches will be invalidated for objecttypes used
+     * @param {object} [__namedParameters] - Options
+     * @param {boolean} [__namedParameters.invalidateCaches] - When true, caches will be invalidated for objecttypes used
      *   in the worksheet
      * @postMessage
      */
@@ -313,20 +343,21 @@ export class CadenzaClient {
      * Show a workbook map view in an iframe.
      *
      * @param {EmbeddingTargetId} mapView - The workbook map view to show
-     * @param {object} [options] - Options
-     * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
-     * @param {boolean} [options.expandNavigator] - Indicates if the navigator should be expanded.
-     * @param {FilterVariables} [options.filter] - Filter variables
-     * @param {Geometry} [options.geometry] - A geometry to show on the map
-     * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer
-     * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar
-     * @param {GlobalId} [options.highlightGlobalId] - The ID of an item to highlight / expand in the navigator
-     * @param {string} [options.locationFinder] - A search query for the location finder
-     * @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
+     * @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 {boolean} [__namedParameters.expandNavigator] - Indicates if the navigator should be expanded.
+     * @param {FilterVariables} [__namedParameters.filter] - Filter variables
+     * @param {Geometry} [__namedParameters.geometry] - A geometry to show on the map
+     * @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)
+     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -334,12 +365,17 @@ export class CadenzaClient {
      * - {@link CadenzaActionEvent}
      * @embed
      */
-    async showMap(mapView, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, zoomTarget, signal, } = {}) {
+    async showMap(mapView, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, extentStrategy, signal, additionalLayers, } = {}) {
         this.#log('CadenzaClient#showMap', ...arguments);
         if (geometry) {
             assertValidGeometryType(geometry.type);
         }
-        const zoomToGeometry = geometry && zoomTarget?.type === 'geometry';
+        const validExtentStrategy = sanitizeExtentStrategy({
+            geometry,
+            locationFinder,
+            mapExtent,
+            extentStrategy,
+        });
         const params = createParams({
             disabledUiFeatures,
             expandNavigator,
@@ -347,21 +383,23 @@ export class CadenzaClient {
             hideMainHeaderAndFooter,
             hideWorkbookToolBar,
             highlightGlobalId,
-            // 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',
             useMapSrs,
+            validExtentStrategy,
         });
         await this.#show(resolvePath(mapView), params, signal);
         if (geometry) {
             this.#postEvent('setGeometry', {
                 geometry,
-                zoomToGeometry,
             });
         }
+        if (additionalLayers) {
+            for (const layer of additionalLayers) {
+                await this.#postRequest('importLayer', layer);
+            }
+        }
+        this.#setExtentStrategy(validExtentStrategy);
     }
     /**
      * Expand/collapse the navigator.
@@ -463,12 +501,6 @@ export class CadenzaClient {
             values,
         });
     }
-    /**
-     * @typedef LayerDefinition
-     * @property {string} name - The layer's name.
-     * @property {'geojson'} type - The layer's type.
-     * @property {FeatureCollection} content - The layer's content in geojson format.
-     */
     /**
      * Create a geometry.
      *
@@ -477,16 +509,17 @@ export class CadenzaClient {
      *
      * @param {EmbeddingTargetId} backgroundMapView - The workbook map view in the background
      * @param {GeometryType} geometryType - The geometry type
-     * @param {object} [options] - Options
-     * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
-     * @param {FilterVariables} [options.filter] - Filter variables
-     * @param {string} [options.locationFinder] - A search query for the location finder
-     * @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 created geometry should use the map's SRS (otherwise EPSG:4326 will be used)
-     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
-     * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
-     * @param {LayerDefinition[]} [options.additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing.
+     * @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 {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 {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)
+     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -495,40 +528,47 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    async createGeometry(backgroundMapView, geometryType, { disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, additionalLayers, } = {}) {
+    async createGeometry(backgroundMapView, geometryType, { additionalLayers, disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, extentStrategy, } = {}) {
         this.#log('CadenzaClient#createGeometry', ...arguments);
+        const validExtentStrategy = sanitizeExtentStrategy({
+            locationFinder,
+            mapExtent,
+            extentStrategy,
+        });
         const params = createParams({
             action: 'editGeometry',
             disabledUiFeatures,
             filter,
             geometryType,
-            locationFinder,
-            mapExtent,
             minScale,
-            useMapSrs,
             operationMode,
+            useMapSrs,
+            validExtentStrategy,
         });
         await this.#show(resolvePath(backgroundMapView), params, signal);
         if (additionalLayers) {
-            additionalLayers.forEach((layer) => this.#postEvent('importLayer', layer));
+            for (const layer of additionalLayers) {
+                await this.#postRequest('importLayer', layer);
+            }
         }
+        this.#setExtentStrategy(validExtentStrategy);
     }
     /**
      * Edit a geometry.
      *
      * @param {EmbeddingTargetId} backgroundMapView - The workbook map view in the background
      * @param {Geometry} geometry - The geometry
-     * @param {object} [options] - Options
-     * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
-     * @param {FilterVariables} [options.filter] - Filter variables
-     * @param {string} [options.locationFinder] - A search query for the location finder
-     * @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 {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
-     * @param {ZoomTarget} [options.zoomTarget] - A target Cadenza should zoom to
-     * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
-     * @param {LayerDefinition[]} [options.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 {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 {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 {boolean} [__namedParameters.useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -537,32 +577,36 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    async editGeometry(backgroundMapView, geometry, { disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, operationMode, signal, additionalLayers, } = {}) {
+    async editGeometry(backgroundMapView, geometry, { additionalLayers, disabledUiFeatures, filter, locationFinder, mapExtent, minScale, operationMode, signal, useMapSrs, extentStrategy, } = {}) {
         this.#log('CadenzaClient#editGeometry', ...arguments);
         assertValidGeometryType(geometry.type);
-        const zoomToGeometry = geometry && zoomTarget?.type === 'geometry';
+        const validExtentStrategy = sanitizeExtentStrategy({
+            geometry,
+            locationFinder,
+            mapExtent,
+            extentStrategy,
+        });
         const params = createParams({
             action: 'editGeometry',
             disabledUiFeatures,
             filter,
-            // 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,
             operationMode,
+            useMapSrs,
+            validExtentStrategy,
         });
         await this.#show(resolvePath(backgroundMapView), params, signal);
         if (geometry) {
             this.#postEvent('setGeometry', {
                 geometry,
-                zoomToGeometry,
             });
         }
         if (additionalLayers) {
-            additionalLayers.forEach((layer) => this.#postEvent('importLayer', layer));
+            for (const layer of additionalLayers) {
+                await this.#postRequest('importLayer', layer);
+            }
         }
+        this.#setExtentStrategy(validExtentStrategy);
     }
     /**
      * Set custom validity state of the geometry editor in addition to the default validation state (including errors and
@@ -581,15 +625,16 @@ export class CadenzaClient {
      * Select objects in a workbook map.
      *
      * @param {EmbeddingTargetId} backgroundMapView - The workbook map view
-     * @param {object} [options] - Options
-     * @param {FilterVariables} [options.filter] - Filter variables
-     * @param {(WorkbookLayerPath | string)[]} [options.layers] - Layers to restrict the selection to
+     * @param {object} [__namedParameters] - Options
+     * @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} [options.locationFinder] - A search query for the location finder
-     * @param {Extent} [options.mapExtent] - A map extent to set
-     * @param {boolean} [options.useMapSrs] - Whether the geometry is in the map's SRS (otherwise EPSG:4326 is assumed)
-     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
-     * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
+     * @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
+     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -599,18 +644,31 @@ export class CadenzaClient {
      * - {@link CadenzaSelectObjectsCancelEvent}
      * @embed
      */
-    selectObjects(backgroundMapView, { filter, layers, locationFinder, mapExtent, useMapSrs, operationMode, signal, } = {}) {
+    async selectObjects(backgroundMapView, { filter, layers, locationFinder, mapExtent, useMapSrs, operationMode, signal, extentStrategy, } = {}) {
         this.#log('CadenzaClient#selectObjects', ...arguments);
+        const validExtentStrategy = sanitizeExtentStrategy({
+            geometry: undefined,
+            locationFinder,
+            mapExtent,
+            extentStrategy,
+        });
         const params = createParams({
             action: 'selectObjects',
             filter,
             layers: layers?.map(array),
-            locationFinder,
-            mapExtent,
             useMapSrs,
             operationMode,
+            validExtentStrategy,
         });
-        return this.#show(resolvePath(backgroundMapView), params, signal);
+        await this.#show(resolvePath(backgroundMapView), params, signal);
+        this.#setExtentStrategy(validExtentStrategy);
+    }
+    #setExtentStrategy(/** @type {ExtentStrategy | undefined} */ extentStrategy) {
+        const type = extentStrategy?.type;
+        // Other extent strategies are handled via URL parameters.
+        if (type === 'geometry' || type === 'layerData') {
+            this.#postEvent('setExtentStrategy', extentStrategy);
+        }
     }
     /**
      * @param {string} path
@@ -793,13 +851,13 @@ export class CadenzaClient {
      *
      * @param {EmbeddingTargetId} source - The workbook view to fetch data from.
      * @param {DataType} dataType - The data type you want to get back from the server.
-     *   Currently, `"csv"`, `"excel"` and `"json"` are supported for embedding targets of type view with a view type of
+     *  Currently, `"csv"`, `"excel"` and `"json"` are supported for embedding targets of type view with a view type of
      *   table and indicator. `"pdf"` is supported for embedding targets of type report and of type view with a view type
      *   of "JasperReports report".
-     * @param {object} [options] - Options
-     * @param {FilterVariables} [options.filter] - Filter variables
-     * @param {TablePart[]} [options.parts] - Table parts to export; If not specified, all parts are exported.
-     * @param {AbortSignal} [options.signal] - A signal to abort the data fetching
+     * @param {object} [__namedParameters] - Options
+     * @param {FilterVariables} [__namedParameters.filter] - Filter variables
+     * @param {TablePart[]} [__namedParameters.parts] - Table parts to export; If not specified, all parts are exported.
+     * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the data fetching
      * @return {Promise<Response>} A `Promise` for the fetch response
      * @throws For invalid arguments
      * @server
@@ -817,11 +875,11 @@ export class CadenzaClient {
      * @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
+     * @param {object} [__namedParameters] - Options
+     * @param {FilterVariables} [__namedParameters.filter] - Filter variables
+     * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the data fetching
+     * @param {Boolean} [__namedParameters.useMapSrs] - Use the map SRS instead of WGS84
+     * @param {Boolean} [__namedParameters.fullGeometries] - Return non-simplified geometries
      * @return {Promise<FeatureCollection>} A `Promise` for the fetch response
      * @throws For invalid arguments
      */
@@ -844,10 +902,10 @@ export class CadenzaClient {
      * @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
+     * @param {object} [__namedParameters] - Options
+     * @param {boolean} [__namedParameters.useMapSrs]  - The intersection geometry and the result geometries are in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {Distance} [__namedParameters.buffer] - Buffer size for geometry of the transition
+     * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the data fetching
      * @return {Promise<FeatureCollection>} A `Promise` for the fetch response
      * @server
      */
@@ -897,13 +955,13 @@ export class CadenzaClient {
      *
      * @param {EmbeddingTargetId} source - The workbook view to fetch data from.
      * @param {DataType} dataType - The data type you want to get back from the server.
-     *   Currently, `"csv"`, `"excel"` and `"json"` are supported for embedding targets of type view with a view type of
+     *  Currently, `"csv"`, `"excel"` and `"json"` are supported for embedding targets of type view with a view type of
      *   table and indicator. `"pdf"` is supported for embedding targets of type report and of type view with a view type
      *   of "JasperReports report".
-     * @param {object} [options] - Options
-     * @param {string} [options.fileName] - The file name to use; The file extension is appended by Cadenza.
-     * @param {FilterVariables} [options.filter] - Filter variables
-     * @param {TablePart[]} [options.parts] - Table parts to export; If not specified, all parts are exported.
+     * @param {object} [__namedParameters] - Options
+     * @param {string} [__namedParameters.fileName] - The file name to use; The file extension is appended by Cadenza.
+     * @param {FilterVariables} [__namedParameters.filter] - Filter variables
+     * @param {TablePart[]} [__namedParameters.parts] - Table parts to export; If not specified, all parts are exported.
      * @throws For invalid arguments
      * @server
      */
@@ -1047,16 +1105,15 @@ function assertSupportedDataType(
  * @param {GlobalId} [params.highlightGlobalId]
  * @param {string} [params.labelSet]
  * @param {WorkbookLayerPath[]} [params.layers]
- * @param {string} [params.locationFinder]
- * @param {Extent} [params.mapExtent]
  * @param {number} [params.minScale]
  * @param {OperationMode} [params.operationMode]
  * @param {TablePart[]} [params.parts]
  * @param {'MAP'} [params.targetType]
  * @param {boolean} [params.useMapSrs]
+ * @param {ExtentStrategy | undefined} [params.validExtentStrategy]
  * @return {URLSearchParams}
  */
-function createParams({ action, dataType, disabledUiFeatures, expandNavigator, fileName, filter, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, layers, locationFinder, mapExtent, minScale, operationMode, parts, targetType, useMapSrs, }) {
+function createParams({ action, dataType, disabledUiFeatures, expandNavigator, fileName, filter, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, layers, minScale, operationMode, parts, targetType, useMapSrs, validExtentStrategy, }) {
     if (disabledUiFeatures) {
         disabledUiFeatures.forEach((feature) => assert(validUiFeature(feature), `Invalid UI feature: ${feature}`));
     }
@@ -1072,6 +1129,16 @@ function createParams({ action, dataType, disabledUiFeatures, expandNavigator, f
     if (parts) {
         parts.forEach((part) => assert(validTablePart(part), `Invalid table part: ${part}`));
     }
+    let locationFinder;
+    let mapExtent;
+    if (validExtentStrategy) {
+        if (validExtentStrategy.type === 'static') {
+            mapExtent = validExtentStrategy.extent;
+        }
+        else if (validExtentStrategy.type === 'locationFinder') {
+            locationFinder = validExtentStrategy.query;
+        }
+    }
     return new URLSearchParams({
         ...(action && { action }),
         ...(dataType && { dataType }),
@@ -1106,6 +1173,54 @@ function createParams({ action, dataType, disabledUiFeatures, expandNavigator, f
 function array(/** @type unknown */ value) {
     return Array.isArray(value) ? value : [value];
 }
+/**
+ * Creates a valid extent strategy based on these rules:
+ * - `extentStrategy` 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.
+ *
+ * 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, } = {}) {
+    if (extentStrategy) {
+        switch (extentStrategy.type) {
+            case 'static':
+                const extent = extentStrategy.extent ?? mapExtent;
+                if (extent) {
+                    return { type: 'static', extent };
+                }
+                break;
+            case 'locationFinder':
+                const query = extentStrategy.query ?? locationFinder;
+                if (query) {
+                    return { type: 'locationFinder', query };
+                }
+                break;
+            case 'geometry':
+                geometry = extentStrategy.geometry ?? geometry;
+                if (geometry) {
+                    return { type: 'geometry', geometry };
+                }
+                break;
+            default:
+                return extentStrategy;
+        }
+    }
+    if (mapExtent) {
+        return { type: 'static', extent: mapExtent };
+    }
+    if (locationFinder) {
+        return { type: 'locationFinder', query: locationFinder };
+    }
+}
 // Please do not add internal event types like 'ready' here.
 /**
  * @typedef {'action'

package/package.json

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