@disy/cadenza.js 2.2.2 → 2.3.0

package/cadenza.d.ts

@@ -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
  */
@@ -17,13 +18,42 @@ export function cadenza(baseUrl: string, options?: {
     webApplication?: ExternalLinkKey | undefined;
     debug?: boolean | undefined;
 } | undefined): CadenzaClient;
-/** @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.)
@@ -33,8 +63,8 @@ export function cadenza(baseUrl: string, options?: {
  * @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
@@ -46,9 +76,20 @@ export function cadenza(baseUrl: string, options?: {
  * _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).
@@ -91,12 +132,9 @@ 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: PageSource | EmbeddingTargetId, { dataType, disabledUiFeatures, expandNavigator, filter, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, operationMode, signal, }?: {
         dataType?: DataType | undefined;
@@ -105,11 +143,11 @@ export class CadenzaClient {
         filter?: FilterVariables | undefined;
         hideMainHeaderAndFooter?: boolean | undefined;
         hideWorkbookToolBar?: boolean | undefined;
-        highlightGlobalId?: string | undefined;
+        highlightGlobalId?: GlobalId | undefined;
         labelSet?: string | undefined;
         operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
-    } | undefined): Promise<void>;
+    } | undefined, ...args: any[]): Promise<void>;
     /**
      * Show a workbook map view in an iframe.
      *
@@ -127,11 +165,9 @@ 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}
      */
     showMap(mapView: EmbeddingTargetId, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, }?: {
         disabledUiFeatures?: UiFeature[] | undefined;
@@ -140,19 +176,78 @@ export class CadenzaClient {
         geometry?: Geometry | undefined;
         hideMainHeaderAndFooter?: boolean | undefined;
         hideWorkbookToolBar?: boolean | undefined;
-        highlightGlobalId?: string | undefined;
+        highlightGlobalId?: GlobalId | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
         operationMode?: OperationMode | undefined;
         useMapSrs?: boolean | undefined;
         signal?: AbortSignal | undefined;
-    } | undefined): Promise<void>;
+    } | undefined, ...args: any[]): Promise<void>;
     /**
      * Expand/collapse the navigator.
      *
      * @param {boolean} expanded - The expansion state of the navigator
      */
-    expandNavigator(expanded?: boolean): void;
+    expandNavigator(expanded?: boolean, ...args: any[]): void;
+    /**
+     * 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>}
+     */
+    getData<T extends DataType>(dataType: T, ...args: any[]): Promise<T extends "png" ? Blob : never>;
+    /**
+     * 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: FilterVariables, ...args: any[]): Promise<void>;
+    /**
+     * 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: WorkbookLayerPath | string, visible: boolean, ...args: any[]): Promise<void>;
+    /**
+     * 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: WorkbookLayerPath | string, values: unknown[], ...args: any[]): Promise<void>;
+    /**
+     * 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: WorkbookLayerPath | string, values: unknown[], ...args: any[]): Promise<void>;
+    /**
+     * 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: WorkbookLayerPath | string, values: unknown[], ...args: any[]): Promise<void>;
     /**
      * Create a geometry.
      *
@@ -167,11 +262,12 @@ 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: EmbeddingTargetId, geometryType: GeometryType, { locationFinder, mapExtent, minScale, useMapSrs, signal }?: {
         locationFinder?: string | undefined;
@@ -179,7 +275,7 @@ export class CadenzaClient {
         minScale?: number | undefined;
         useMapSrs?: boolean | undefined;
         signal?: AbortSignal | undefined;
-    } | undefined): Promise<void>;
+    } | undefined, ...args: any[]): Promise<void>;
     /**
      * Edit a geometry.
      *
@@ -191,11 +287,12 @@ 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}
      */
     editGeometry(backgroundMapView: EmbeddingTargetId, geometry: Geometry, { locationFinder, mapExtent, minScale, useMapSrs, signal }?: {
         locationFinder?: string | undefined;
@@ -203,38 +300,68 @@ export class CadenzaClient {
         minScale?: number | undefined;
         useMapSrs?: boolean | undefined;
         signal?: AbortSignal | undefined;
-    } | undefined): Promise<void>;
+    } | undefined, ...args: any[]): Promise<void>;
+    /**
+     * 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: EmbeddingTargetId, { layers, locationFinder, mapExtent, useMapSrs, signal }?: {
+        layers?: (string | WorkbookLayerPath)[] | undefined;
+        locationFinder?: string | undefined;
+        mapExtent?: Extent | undefined;
+        useMapSrs?: boolean | undefined;
+        signal?: AbortSignal | undefined;
+    } | undefined, ...args: any[]): Promise<void>;
     /**
      * 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<T = unknown>(type: string, subscriber: (event: CadenzaEvent<T>) => void): () => void;
+    on<TYPE extends CadenzaEventType>(type: TYPE, subscriber: (event: CadenzaEvent<TYPE, CadenzaEventByType<TYPE>["detail"]>) => void): () => void;
     /**
      * 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: EmbeddingTargetId, dataType: DataType, { parts, signal }?: {
         parts?: TablePart[] | undefined;
         signal?: AbortSignal | undefined;
-    }): Promise<Response>;
+    }, ...args: any[]): Promise<Response>;
     /**
      * Download data from a workbook view.
      *
      * _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.
@@ -243,16 +370,57 @@ export class CadenzaClient {
     downloadData(source: EmbeddingTargetId, dataType: DataType, { fileName, parts }: {
         fileName?: string | undefined;
         parts?: TablePart[] | undefined;
-    }): void;
+    }, ...args: any[]): void;
     #private;
 }
 /**
- * @template [T=unknown]
+ * @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 {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)
+ */
+/** @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();
 }
@@ -271,15 +439,39 @@ export class CadenzaError extends Error {
     #private;
 }
 /**
- * - The ID of an embedding target
+ * - 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)`).
+ */
+export type OpaqueString<T extends string> = string & {
+    __type: T;
+};
+/**
+ * - 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.
  */
-export type EmbeddingTargetId = string;
+export type EmbeddingTargetId = OpaqueString<'EmbeddingTargetId'>;
 /**
  * - The ID of a navigator item
  */
-export type GlobalId = string;
+export type GlobalId = OpaqueString<'GlobalId'>;
 /**
  * - 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}?...
+ * ```
  */
 export type ExternalLinkKey = {
     /**
@@ -291,6 +483,11 @@ export type ExternalLinkKey = {
      */
     externalLinkId: string;
 };
+/**
+ * - Identifies a layer within a workbook map view
+ *   using the print names of the layer and - if the layer is grouped - its ancestors
+ */
+export type WorkbookLayerPath = string[];
 /**
  * - A well-known Cadenza page
  */
@@ -308,8 +505,8 @@ export type OperationMode = 'normal' | 'simplified';
  * - 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'.)
  */
 export type UiFeature = 'workbook-design' | 'workbook-view-management';
 /**
@@ -333,33 +530,101 @@ export type GeometryType = 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineStr
 export type Extent = [number, number, number, number];
 /**
  * - A data type
+ *
+ * See [JSON Representation of Cadenza Object Data](../index.html#md:json-representation-of-cadenza-object-data) for JSON data.
  */
-export type DataType = 'csv' | 'excel' | 'json' | 'pdf';
+export type DataType = 'csv' | 'excel' | 'json' | 'pdf' | 'png';
 /**
  * - A part of a table to export
  */
 export type TablePart = 'columns' | 'values' | 'totals';
 /**
  * - 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.
  */
-export type FilterVariables = Record<string, string | number | Date>;
+export type FilterVariables = Record<string, string | string[] | number | Date | null>;
+/**
+ * - An event type to subscribe to using {@link CadenzaClienton }
+ */
+export type CadenzaEventType = 'change:selection' | 'drillThrough' | 'editGeometry:ok' | 'editGeometry:update' | 'editGeometry:cancel' | 'objectInfo' | 'selectObjects:ok' | 'selectObjects:cancel';
+export type CadenzaEventByType<T extends CadenzaEventType> = 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;
 /**
  * - A Cadenza `postMessage()` event
  */
-export type CadenzaEvent<T = unknown> = {
+export type CadenzaEvent<TYPE extends string, DETAIL = unknown> = {
     /**
      * - The event type
      */
-    type: string;
+    type: TYPE;
     /**
      * - Optional event details (depending on the event type)
      */
-    detail: T;
+    detail: DETAIL;
 };
+/**
+ * - When the user changed the selection.
+ */
+export type CadenzaChangeSelectionEvent = CadenzaEvent<'change:selection', undefined | {
+    layer: string[];
+    values: unknown[][];
+}>;
+/**
+ * - 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>
+ */
+export type CadenzaDrillThroughEvent = CadenzaEvent<'drillThrough', {
+    values: unknown[][];
+}>;
+/**
+ * - When the user changed the geometry.
+ */
+export type CadenzaEditGeometryUpdateEvent = CadenzaEvent<'editGeometry:update', {
+    geometry: Geometry;
+}>;
+/**
+ * - When the user submitted the geometry.
+ */
+export type CadenzaEditGeometryOkEvent = CadenzaEvent<'editGeometry:ok', {
+    geometry: Geometry;
+}>;
+/**
+ * - When the user cancelled the geometry editing.
+ */
+export type CadenzaEditGeometryCancelEvent = CadenzaEvent<'editGeometry:cancel'>;
 /**
  * - An error event that is mapped to a {@link CadenzaError }
  */
-export type CadenzaErrorEvent = CadenzaEvent<{
+export type CadenzaErrorEvent = CadenzaEvent<'error', {
     type: string;
     message?: string;
 }>;
+/**
+ * - When the user opened the object info flyout.
+ */
+export type CadenzaObjectInfoEvent = CadenzaEvent<'objectInfo', {
+    layer: string[];
+    objectInfos: {
+        selectionIndex: number;
+        formattedValues: Record<string, string>;
+    }[];
+}>;
+/**
+ * - When the user submitted the selection.
+ */
+export type CadenzaSelectObjectsOkEvent = CadenzaEvent<'selectObjects:ok', {
+    layer: string[];
+    values: unknown[][];
+}>;
+/**
+ * - When the user cancelled the selection.
+ */
+export type CadenzaSelectObjectsCancelEvent = CadenzaEvent<'selectObjects:cancel'>;