@disy/cadenza.js 2.2.2 → 2.3.0

package/cadenza.js

@@ -9,6 +9,7 @@
  * @param {ExternalLinkKey} [options.webApplication] - An external link that Cadenza uses to resolve the
  *   [target origin](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#targetorigin) when posting events.
  *   This is required if Cadenza and your application are not running on the same origin.
+ *   Please ensure that the user has view privilege for that link!
  * @param {boolean} [options.debug] - Whether to enable debug logging
  * @throws For invalid arguments
  */
@@ -23,13 +24,42 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
         return cadenza;
     },
 });
-/** @typedef {string} EmbeddingTargetId - The ID of an embedding target */
-/** @typedef {string} GlobalId - The ID of a navigator item */
+/**
+ * @template {string} T
+ * @typedef {string & {__type: T}} OpaqueString - A specific `string` type that is not assignable from another string
+ *
+ * The idea is to have a specific type e.g. for the {@link EmbeddingTargetId} instead of a plain `string`.
+ * You don't need to _actually_ add that `__type` property. In TS code, just use a
+ * [type assertion](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions)
+ * (e.g. `cadenzaClient.show('{embeddingTargetId}' as EmbeddingTargetId)`).
+ */
+/**
+ * @typedef {OpaqueString<'EmbeddingTargetId'>} EmbeddingTargetId - The ID of a Cadenza embedding target
+ *
+ * Embedding targets are called 🇩🇪 "Einbettbarer Inhalt" / 🇺🇸 "Embeddable content" throughout the Cadenza UI and help.
+ * They're managed within the respective workbook:
+ *
+ * - 🇩🇪 "Mehr" > "Arbeitsmappe verwalten" > "Einbettung"
+ * - 🇺🇸 "More" > "Manage workbook" > "Embedding"
+ *
+ * The name of an embedding target (as entered in the UI) is its ID.
+ */
+/** @typedef {OpaqueString<'GlobalId'>} GlobalId - The ID of a navigator item */
 /**
  * @typedef ExternalLinkKey - A tuple qualifying a Cadenza external link
+ *
+ * You get the `repositoryName` and `externalLinkId` from the URL of the external link's page in the Cadenza management center:
+ * ```
+ * {baseUrl}/admin/repositories/{repositoryName}/external-links/{externalLinkId}?...
+ * ```
+ *
  * @property {string} repositoryName - The name of the link's repository
  * @property {string} externalLinkId - The ID of the external link
  */
+/**
+ * @typedef {string[]} WorkbookLayerPath - Identifies a layer within a workbook map view
+ *   using the print names of the layer and - if the layer is grouped - its ancestors
+ */
 /**
  * @typedef PageSource - A well-known Cadenza page
  * @property {'welcome'} page - The name of the page (Only `"welcome"` is currently supported.)
@@ -39,8 +69,8 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * @typedef {'workbook-design'|'workbook-view-management'} UiFeature - The name of a Cadenza UI feature
  *
  * _Note:_ Supported features are:
- * * 'workbook-design' - The workbook designer
- * * 'workbook-view-management' - Add/Edit/Remove workbook views (Is included in 'workbook-design'.)
+ * * `"workbook-design"` - The workbook designer
+ * * `"workbook-view-management"` - Add/Edit/Remove workbook views (Is included in 'workbook-design'.)
  * */
 /**
  * @typedef Geometry - A [GeoJSON](https://geojson.org/) geometry object
@@ -52,9 +82,20 @@ 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 {'csv' | 'excel' | 'json' | 'pdf'} DataType - A data type */
+/**
+ * @typedef {'csv' | 'excel' | 'json' | 'pdf' | 'png'} DataType - A data type
+ *
+ * See [JSON Representation of Cadenza Object Data](../index.html#md:json-representation-of-cadenza-object-data) for JSON data.
+ */
 /** @typedef {'columns' | 'values' | 'totals'} TablePart - A part of a table to export */
-/** @typedef {Record<string, string | number | Date>} FilterVariables - Filter variable names and values */
+/**
+ * @typedef {Record<string, string | string[] | number | Date | null>} FilterVariables - Filter variable names and values
+ *
+ * Variables of type String, Integer, Long, Double and Date can be set.
+ *
+ * _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.
+ */
 /**
  * _Notes:_
  * * Most public methods can be aborted using an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
@@ -77,7 +118,7 @@ export class CadenzaClient {
     #iframeElement;
     /** @readonly */
     #debug;
-    /** @type {[ string, (event: CadenzaEvent<never>) => void ][]} */
+    /** @type {[ CadenzaEventType | string, (event: CadenzaEvent<never>) => void ][]} */
     #subscriptions = [];
     /**
      * @hidden
@@ -119,9 +160,11 @@ export class CadenzaClient {
         return this.#iframeElement;
     }
     get #requiredIframe() {
-        const iframe = this.iframe;
+        const iframe = /** @type {HTMLIFrameElement} */ (this.iframe);
         assert(iframe instanceof HTMLIFrameElement, 'Required iframe is not present.');
-        return /** @type {HTMLIFrameElement} */ (iframe);
+        const { width, height } = iframe.getBoundingClientRect();
+        assert(width > 0 && height > 0, 'Iframe must be visible.');
+        return iframe;
     }
     /**
      * Show a page, workbook, worksheet or workbook view in an iframe.
@@ -139,15 +182,12 @@ export class CadenzaClient {
      * @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
-     * @return {Promise<void>} A Promise for when the iframe is loaded
+     * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
-     * @fires `drillThrough` - When the user executed a POST message drill-through.
-     *   The event includes a row of values for each row in the workbook selection, each row consisting of the values of
-     *   the attributes that were selected for the POST message content. If the drill-through was executed from a map
-     *   view, each row includes the geometry of the select object as the last value.
+     * @fires {@link CadenzaDrillThroughEvent}
      */
     show(source, { dataType, disabledUiFeatures, expandNavigator, filter, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, operationMode, signal, } = {}) {
-        this.#log('CadenzaClient#show', source);
+        this.#log('CadenzaClient#show', ...arguments);
         if (dataType) {
             assertSupportedDataType(dataType, ['pdf']);
         }
@@ -166,7 +206,6 @@ export class CadenzaClient {
             labelSet,
             dataType,
             operationMode,
-            webApplication: this.#webApplication,
         });
         return this.#show(resolvePath(source), params, signal);
     }
@@ -187,14 +226,12 @@ export class CadenzaClient {
      * @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 {AbortSignal} [options.signal] - A signal to abort the iframe loading
-     * @return {Promise<void>} A Promise for when the iframe is loaded
+     * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
-     * @fires `drillThrough` - When the user executed a POST message drill-through.
-     *   The event includes a row of values for each row in the workbook selection, each row consisting of the values of
-     *   the attributes that were selected for the POST message content plus the geometry of the select object as the last value.
+     * @fires {@link CadenzaDrillThroughEvent}
      */
     async showMap(mapView, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, } = {}) {
-        this.#log('CadenzaClient#showMap', mapView, geometry);
+        this.#log('CadenzaClient#showMap', ...arguments);
         if (geometry) {
             assertValidGeometryType(geometry.type);
         }
@@ -208,11 +245,13 @@ export class CadenzaClient {
             locationFinder,
             mapExtent,
             operationMode,
+            targetType: 'MAP',
             useMapSrs,
-            webApplication: this.#webApplication,
         });
         await this.#show(resolvePath(mapView), params, signal);
-        this.#postEvent('setGeometry', { geometry });
+        if (geometry) {
+            this.#postEvent('setGeometry', { geometry });
+        }
     }
     /**
      * Expand/collapse the navigator.
@@ -220,9 +259,93 @@ export class CadenzaClient {
      * @param {boolean} expanded - The expansion state of the navigator
      */
     expandNavigator(expanded = true) {
-        this.#log('CadenzaClient#expandNavigator', expanded);
+        this.#log('CadenzaClient#expandNavigator', ...arguments);
         this.#postEvent('expandNavigator', { expandNavigator: Boolean(expanded) });
     }
+    /**
+     * Get data from the currently shown workbook view.
+     *
+     * Currently, only map views are supported.
+     *
+     * @hidden
+     * @template {DataType} T
+     * @param {T} dataType - The requested data type. Currently, only `"png"` is supported.
+     * @return {Promise<T extends 'png' ? Blob : never>}
+     */
+    async getData(dataType) {
+        this.#log('CadenzaClient#getData', ...arguments);
+        assertSupportedDataType(dataType, ['png']);
+        return this.#postRequest('getData', { dataType });
+    }
+    /**
+     * Set filter variables in the currently shown workbook.
+     *
+     * @hidden
+     * @param {FilterVariables} filter - The variable values
+     * @return {Promise<void>} A `Promise` for when the filter variables were set.
+     */
+    setFilter(filter) {
+        this.#log('CadenzaClient#setFilter', ...arguments);
+        return this.#postRequest('setFilter', { filter });
+    }
+    /**
+     * Set the visibility of a layer in the currently shown workbook map view.
+     *
+     * When making a layer visible, its ancestors will be made visible, too.
+     * When hiding a layer, the ancestors are not affected.
+     *
+     * @hidden
+     * @param {WorkbookLayerPath | string} layer - The layer to show or hide
+     *   (identified using a layer path or a print name)
+     * @param {boolean} visible - The visibility state of the layer
+     * @return {Promise<void>} A `Promise` for when the layer visibility was set.
+     */
+    setLayerVisibility(layer, visible) {
+        this.#log('CadenzaClient#setLayerVisibility', ...arguments);
+        return this.#postRequest('setLayerVisibility', {
+            layer: array(layer),
+            visible,
+        });
+    }
+    /**
+     * Set the selection in the currently shown workbook map view.
+     *
+     * @hidden
+     * @param {WorkbookLayerPath | string} layer - The data view layer to set the selection in
+     * @param {unknown[]} values - The IDs of the objects to select
+     * @return {Promise<void>} A `Promise` for when the selection was set.
+     */
+    setSelection(layer, values) {
+        this.#log('CadenzaClient#setSelection', ...arguments);
+        return this.#postRequest('setSelection', { layer: array(layer), values });
+    }
+    /**
+     * Add to the selection in the currently shown workbook map view.
+     *
+     * @hidden
+     * @param {WorkbookLayerPath | string} layer - The data view layer to change the selection in
+     * @param {unknown[]} values - The IDs of the objects to select
+     * @return {Promise<void>} A `Promise` for when the selection was changed.
+     */
+    addSelection(layer, values) {
+        this.#log('CadenzaClient#addSelection', ...arguments);
+        return this.#postRequest('addSelection', { layer: array(layer), values });
+    }
+    /**
+     * Remove from the selection in the currently shown workbook map view.
+     *
+     * @hidden
+     * @param {WorkbookLayerPath | string} layer - The data view layer to change the selection in
+     * @param {unknown[]} values - The IDs of the objects to unselect
+     * @return {Promise<void>} A `Promise` for when the selection was changed.
+     */
+    removeSelection(layer, values) {
+        this.#log('CadenzaClient#removeSelection', ...arguments);
+        return this.#postRequest('removeSelection', {
+            layer: array(layer),
+            values,
+        });
+    }
     /**
      * Create a geometry.
      *
@@ -237,14 +360,15 @@ export class CadenzaClient {
      * @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 {AbortSignal} [options.signal] - A signal to abort the iframe loading
-     * @return {Promise<void>} A Promise for when the iframe is loaded
+     * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
-     * @fires `editGeometry:update` - When the user changed the geometry. The event includes the edited geometry.
-     * @fires `editGeometry:ok` - When the user completed the geometry editing. The event includes the edited geometry.
-     * @fires `editGeometry:cancel` - When the user cancelled the geometry editing in Cadenza.
+     * @fires
+     * - {@link CadenzaEditGeometryUpdateEvent}
+     * - {@link CadenzaEditGeometryOkEvent}
+     * - {@link CadenzaEditGeometryCancelEvent}
      */
     createGeometry(backgroundMapView, geometryType, { locationFinder, mapExtent, minScale, useMapSrs, signal } = {}) {
-        this.#log('CadenzaClient#createGeometry', backgroundMapView, geometryType);
+        this.#log('CadenzaClient#createGeometry', ...arguments);
         const params = createParams({
             action: 'editGeometry',
             geometryType,
@@ -252,7 +376,6 @@ export class CadenzaClient {
             mapExtent,
             minScale,
             useMapSrs,
-            webApplication: this.#webApplication,
         });
         return this.#show(resolvePath(backgroundMapView), params, signal);
     }
@@ -267,14 +390,15 @@ export class CadenzaClient {
      * @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 {AbortSignal} [options.signal] - A signal to abort the iframe loading
-     * @return {Promise<void>} A Promise for when the iframe is loaded
+     * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
-     * @fires `editGeometry:update` - When the user changed the geometry. The event includes the edited geometry.
-     * @fires `editGeometry:ok` - When the user completed the geometry editing. The event includes the edited geometry.
-     * @fires `editGeometry:cancel` - When the user cancelled the geometry editing in Cadenza.
+     * @fires
+     * - {@link CadenzaEditGeometryUpdateEvent}
+     * - {@link CadenzaEditGeometryOkEvent}
+     * - {@link CadenzaEditGeometryCancelEvent}
      */
     async editGeometry(backgroundMapView, geometry, { locationFinder, mapExtent, minScale, useMapSrs, signal } = {}) {
-        this.#log('CadenzaClient#editGeometry', backgroundMapView, geometry);
+        this.#log('CadenzaClient#editGeometry', ...arguments);
         assertValidGeometryType(geometry.type);
         const params = createParams({
             action: 'editGeometry',
@@ -282,15 +406,51 @@ export class CadenzaClient {
             mapExtent,
             minScale,
             useMapSrs,
-            webApplication: this.#webApplication,
         });
         await this.#show(resolvePath(backgroundMapView), params, signal);
-        this.#postEvent('setGeometry', { geometry });
+        if (geometry) {
+            this.#postEvent('setGeometry', { geometry });
+        }
+    }
+    /**
+     * Select objects in a workbook map.
+     *
+     * @param {EmbeddingTargetId} backgroundMapView - The workbook map view
+     * @param {object} [options] - Options
+     * @param {(WorkbookLayerPath | string)[]} [options.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 {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 CadenzaChangeSelectionEvent}
+     * - {@link CadenzaObjectInfoEvent}
+     * - {@link CadenzaSelectObjectsOkEvent}
+     * - {@link CadenzaSelectObjectsCancelEvent}
+     */
+    selectObjects(backgroundMapView, { layers, locationFinder, mapExtent, useMapSrs, signal } = {}) {
+        this.#log('CadenzaClient#selectObjects', ...arguments);
+        const params = createParams({
+            action: 'selectObjects',
+            layers: layers?.map(array),
+            locationFinder,
+            mapExtent,
+            useMapSrs,
+        });
+        return this.#show(resolvePath(backgroundMapView), params, signal);
     }
     #show(
     /** @type string */ path, 
     /** @type URLSearchParams */ params, 
     /** @type AbortSignal | undefined */ signal) {
+        const webApplication = this.#webApplication;
+        if (webApplication) {
+            params.set('webApplicationLink', webApplication.externalLinkId);
+            params.set('webApplicationLinkRepository', webApplication.repositoryName);
+        }
         const url = this.#createUrl(path, params);
         this.#log('Load iframe', url.toString());
         this.#requiredIframe.src = url.toString();
@@ -298,14 +458,14 @@ export class CadenzaClient {
     }
     #getIframePromise(/** @type AbortSignal | undefined */ signal) {
         const iframe = this.#requiredIframe;
-        /** @type {() => void} */
+        /** @type {EventListener} */
         let onerror;
-        /** @type {() => void} */
+        /** @type {EventListener} */
         let onabort;
         /** @type {(() => void)[]} */
         let unsubscribes;
         /** @type {Promise<void>} */
-        let promise = new Promise((resolve, reject) => {
+        const promise = new Promise((resolve, reject) => {
             onerror = () => reject(new CadenzaError('loading-error', 'Loading failed'));
             iframe.addEventListener('error', onerror);
             if (signal) {
@@ -316,8 +476,8 @@ export class CadenzaClient {
                 signal.addEventListener('abort', onabort);
             }
             unsubscribes = [
-                this.on('ready', () => resolve()),
-                this.on('error', (/** @type {CadenzaErrorEvent} */ event) => {
+                this.#on('ready', () => resolve()),
+                this.#on('error', (/** @type {CadenzaErrorEvent} */ event) => {
                     const { type, message } = event.detail;
                     reject(new CadenzaError(type, message ?? 'Loading failed'));
                 }),
@@ -335,17 +495,30 @@ export class CadenzaClient {
     /**
      * Subscribe to a `postMessage()` event.
      *
-     * @template [T=unknown]
-     * @param {string} type - The event type
-     * @param {(event: CadenzaEvent<T>) => void} subscriber - The subscriber function
+     * @template {CadenzaEventType} TYPE
+     * @param {TYPE} type - The event type
+     * @param {(event: CadenzaEvent<TYPE, CadenzaEventByType<TYPE>['detail']>) => void} subscriber - The subscriber function
      * @return {() => void} An unsubscribe function
      */
     on(type, subscriber) {
+        return this.#on(type, subscriber);
+    }
+    /**
+     * @template {CadenzaEventType | string} TYPE
+     * @template [DETAIL=unknown]
+     * @param {TYPE} type
+     * @param {(event: CadenzaEvent<TYPE, DETAIL>) => void} subscriber
+     * @return {() => void} An unsubscribe function
+     */
+    #on(type, subscriber) {
         const subscriptions = this.#subscriptions;
         if (subscriptions.length === 0) {
             window.addEventListener('message', this.#onMessage);
         }
-        subscriptions.push([type, subscriber]);
+        subscriptions.push([
+            type,
+            /** @type {(event: CadenzaEvent<never>) => void} */ (subscriber),
+        ]);
         return () => {
             subscriptions.forEach(([subscriptionType, subscriptionSubscriber], i) => {
                 if (subscriptionType === type &&
@@ -359,7 +532,8 @@ export class CadenzaClient {
         };
     }
     // Use arrow function so that it's bound to this.
-    #onMessage = (/** @type MessageEvent<CadenzaEvent<never>> */ event) => {
+    #onMessage = (
+    /** @type MessageEvent<CadenzaEvent<never, never>> */ event) => {
         if (event.origin !== this.#origin ||
             event.source !== this.#requiredIframe.contentWindow) {
             return;
@@ -372,26 +546,63 @@ export class CadenzaClient {
             }
         });
     };
-    #postEvent(/** @type string */ type, /** @type unknown */ detail) {
+    /**
+     * Posts an event to Cadenza and returns a `Promise` for the response.
+     *
+     * It is guaranteed that a response refers to a specific request,
+     * even if multiple request are executed in parallel.
+     * @template [T=void]
+     * @param {string} type
+     * @param {unknown} [detail]
+     * @returns {Promise<T>}
+     */
+    #postRequest(type, detail) {
+        const { port1, port2 } = new MessageChannel();
+        const promise = new Promise((resolve, reject) => {
+            port1.onmessage = (
+            /** @type MessageEvent<CadenzaEvent<never, never>> */ event) => {
+                const cadenzaEvent = event.data;
+                if (cadenzaEvent.type === `${type}:success`) {
+                    resolve(cadenzaEvent.detail);
+                }
+                else if (cadenzaEvent.type === `${type}:error`) {
+                    reject();
+                }
+            };
+        });
+        this.#postEvent(type, detail, [port2]);
+        return promise;
+    }
+    /**
+     * @param {string} type
+     * @param {unknown} [detail]
+     * @param {Transferable[]} [transfer]
+     */
+    #postEvent(type, detail, transfer) {
         const cadenzaEvent = { type, detail };
         this.#log('postMessage', cadenzaEvent);
         const contentWindow = /** @type {WindowProxy} */ (this.#requiredIframe.contentWindow);
-        contentWindow.postMessage(cadenzaEvent, { targetOrigin: this.#origin });
+        contentWindow.postMessage(cadenzaEvent, {
+            targetOrigin: this.#origin,
+            transfer,
+        });
     }
     /**
      * Fetch data from a workbook view.
      *
-     * @param {EmbeddingTargetId} source - The workbook view to fetch data from
-     * @param {DataType} dataType - The data type you want to get back from the server
+     * @param {EmbeddingTargetId} source - The workbook view to fetch data from.
+     *   Currently only table and indicator views are supported.
+     * @param {DataType} dataType - The data type you want to get back from the server.
+     *   Currently, `"csv"`, `"excel"` and `"json"` are supported.
      * @param {object} options - Options
      * @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
-     * @return {Promise<Response>} A Promise for the fetch response
+     * @return {Promise<Response>} A `Promise` for the fetch response
      * @throws For invalid arguments
      */
     fetchData(source, dataType, { parts, signal } = {}) {
-        this.#log('CadenzaClient#fetchData', source, dataType);
-        assertSupportedDataType(dataType);
+        this.#log('CadenzaClient#fetchData', ...arguments);
+        assertSupportedDataType(dataType, ['csv', 'excel', 'json']);
         const params = createParams({ dataType, parts });
         return this.#fetch(resolvePath(source), params, signal);
     }
@@ -417,16 +628,18 @@ export class CadenzaClient {
      *
      * _Note:_ The file name, if not provided, is generated from the name of the workbook view and the current date.
      *
-     * @param {EmbeddingTargetId} source - The workbook view to download data from
-     * @param {DataType} dataType - The data type you want to get back from the server
+     * @param {EmbeddingTargetId} source - The workbook view to download data from.
+     *   Currently only table and indicator views are supported.
+     * @param {DataType} dataType - The data type you want to get back from the server.
+     *   Currently, `"csv"`, `"excel"` and `"json"` are supported.
      * @param {object} options - Options
      * @param {string} [options.fileName] - The file name to use; The file extension is appended by Cadenza.
      * @param {TablePart[]} [options.parts] - Table parts to export; If not specified, all parts are exported.
      * @throws For invalid arguments
      */
     downloadData(source, dataType, { fileName, parts }) {
-        this.#log('CadenzaClient#downloadData', source, dataType);
-        assertSupportedDataType(dataType);
+        this.#log('CadenzaClient#downloadData', ...arguments);
+        assertSupportedDataType(dataType, ['csv', 'excel', 'json']);
         const params = createParams({ dataType, fileName, parts });
         this.#download(resolvePath(source), params);
     }
@@ -452,7 +665,20 @@ export class CadenzaClient {
     }
     #log(/** @type unknown[] */ ...args) {
         if (this.#debug) {
-            console.log(...args);
+            /** @type {unknown[]} */
+            const redundantValues = [undefined, '', false];
+            /** @type {(value: unknown) => value is object} */
+            const isObject = (/** @type {unknown} */ value) => value != null && typeof value === 'object';
+            const sanitizedArgs = args
+                .map((arg) => {
+                if (isObject(arg)) {
+                    return Object.fromEntries(Object.entries(arg).filter(([, value]) => !redundantValues.includes(value)));
+                }
+                return arg;
+            })
+                .filter((arg) => !redundantValues.includes(arg) &&
+                !(isObject(arg) && Object.keys(arg).length === 0));
+            console.log(...sanitizedArgs);
         }
     }
 }
@@ -529,11 +755,11 @@ function validUiFeature(/** @type string */ value) {
 }
 function assertSupportedDataType(
 /** @type DataType */ type, 
-/** @type DataType[] */ supportedTypes = ['csv', 'excel', 'json', 'pdf']) {
+/** @type DataType[] */ supportedTypes) {
     assert(supportedTypes.includes(type), `Invalid data type: ${type}`);
 }
 /**
- * @param {object} params - Options
+ * @param {object} params
  * @param {string} [params.action]
  * @param {DataType} [params.dataType]
  * @param {UiFeature[]} [params.disabledUiFeatures]
@@ -545,16 +771,17 @@ function assertSupportedDataType(
  * @param {boolean} [params.hideWorkbookToolBar]
  * @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 {ExternalLinkKey} [params.webApplication]
  * @return {URLSearchParams}
  */
-function createParams({ action, dataType, disabledUiFeatures, expandNavigator, fileName, filter, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, locationFinder, mapExtent, minScale, parts, useMapSrs, webApplication, operationMode, }) {
+function createParams({ action, dataType, disabledUiFeatures, expandNavigator, fileName, filter, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, layers, locationFinder, mapExtent, minScale, operationMode, parts, targetType, useMapSrs, }) {
     if (disabledUiFeatures) {
         disabledUiFeatures.forEach((feature) => assert(validUiFeature(feature), `Invalid UI feature: ${feature}`));
     }
@@ -588,25 +815,76 @@ function createParams({ action, dataType, disabledUiFeatures, expandNavigator, f
         ...(hideWorkbookToolBar && { hideWorkbookToolBar: 'true' }),
         ...(highlightGlobalId && { highlightGlobalId }),
         ...(labelSet && { labelSet }),
+        ...(layers &&
+            layers.length && {
+            layers: JSON.stringify(layers),
+        }),
         ...(locationFinder && { locationFinder }),
         ...(mapExtent && { mapExtent: mapExtent.join() }),
         ...(minScale && { minScale: String(minScale) }),
         ...(operationMode && operationMode !== 'normal' && { operationMode }),
         ...(parts && { parts: parts.join() }),
+        ...(targetType && { targetType }),
         ...(useMapSrs && { useMapSrs: 'true' }),
-        ...(webApplication && {
-            webApplicationLink: webApplication.externalLinkId,
-            webApplicationLinkRepository: webApplication.repositoryName,
-        }),
     });
 }
+function array(/** @type unknown */ value) {
+    return Array.isArray(value) ? value : [value];
+}
+// Please do not add internal event types like 'ready' here.
+/**
+ * @typedef {'change:selection'
+ * | 'drillThrough'
+ * | 'editGeometry:ok'
+ * | 'editGeometry:update'
+ * | 'editGeometry:cancel'
+ * | 'objectInfo'
+ * | 'selectObjects:ok'
+ * | 'selectObjects:cancel'
+ * } CadenzaEventType - An event type to subscribe to using {@link CadenzaClient#on}
+ */
+/**
+ * @template {CadenzaEventType} T
+ * @typedef {T extends 'change:selection' ? CadenzaChangeSelectionEvent
+ *  : T extends 'drillThrough' ? CadenzaDrillThroughEvent
+ *  : T extends 'editGeometry:update' ? CadenzaEditGeometryUpdateEvent
+ *  : T extends 'editGeometry:ok' ? CadenzaEditGeometryOkEvent
+ *  : T extends 'editGeometry:cancel' ? CadenzaEditGeometryCancelEvent
+ *  : T extends 'objectInfo' ? CadenzaObjectInfoEvent
+ *  : T extends 'selectObjects:ok' ? CadenzaSelectObjectsOkEvent
+ *  : T extends 'selectObjects:cancel' ? CadenzaSelectObjectsCancelEvent
+ *  : never
+ * } CadenzaEventByType
+ */
 /**
- * @template [T=unknown]
+ * @template {CadenzaEventType | string} TYPE
+ * @template [DETAIL=unknown]
  * @typedef CadenzaEvent - A Cadenza `postMessage()` event
- * @property {string} type - The event type
- * @property {T} detail - Optional event details (depending on the event type)
+ * @property {TYPE} type - The event type
+ * @property {DETAIL} detail - Optional event details (depending on the event type)
+ */
+/*
+ * @hidden
+ * @typedef {CadenzaEvent<'change:extent', {extent: Extent}>} CadenzaChangeExtentEvent - When the user moved the map.
+ *   The extent is transformed according to the `useMapSrs` option.
+ */
+/** @typedef {CadenzaEvent<'change:selection', undefined | {layer: WorkbookLayerPath, values: unknown[][]}>} CadenzaChangeSelectionEvent - When the user changed the selection. */
+/**
+ * @typedef {CadenzaEvent<'drillThrough', {values: unknown[][]}>} CadenzaDrillThroughEvent - When the user executed a POST message drill-through.
+ * <p>
+ * The event includes a data row for every item in the workbook selection, each row consisting of the values of
+ * the attributes that were selected for the POST message content. If the drill-through was executed from a map
+ * view, each row includes the geometry of the selected object as the last value.
+ * <p>
+ * See also: <a href="../index.html#md:json-representation-of-cadenza-object-data">JSON Representation of Cadenza Object Data</a>
  */
-/** @typedef {CadenzaEvent<{type: string, message?: string}>} CadenzaErrorEvent - An error event that is mapped to a {@link CadenzaError} */
+/** @typedef {CadenzaEvent<'editGeometry:update', {geometry: Geometry}>} CadenzaEditGeometryUpdateEvent - When the user changed the geometry. */
+/** @typedef {CadenzaEvent<'editGeometry:ok', {geometry: Geometry}>} CadenzaEditGeometryOkEvent - When the user submitted the geometry. */
+/** @typedef {CadenzaEvent<'editGeometry:cancel'>} CadenzaEditGeometryCancelEvent - When the user cancelled the geometry editing. */
+/** @typedef {CadenzaEvent<'error', {type: string, message?: string}>} CadenzaErrorEvent - An error event that is mapped to a {@link CadenzaError} */
+/** @typedef {CadenzaEvent<'objectInfo', {layer: WorkbookLayerPath, objectInfos: {selectionIndex: number, formattedValues: Record<string, string>}[]}>} CadenzaObjectInfoEvent - When the user opened the object info flyout. */
+/** @typedef {CadenzaEvent<'selectObjects:ok', {layer: WorkbookLayerPath, values: unknown[][]}>} CadenzaSelectObjectsOkEvent - When the user submitted the selection. */
+/** @typedef {CadenzaEvent<'selectObjects:cancel'>} CadenzaSelectObjectsCancelEvent - When the user cancelled the selection. */
 export class AbortError extends DOMException {
     constructor() {
         super('Aborted', 'AbortError');