@disy/cadenza.js 10.2.8 → 10.2.10

package/cadenza.d.ts

@@ -19,11 +19,14 @@ export function cadenza(options?: CadenzaClientOptions | undefined): CadenzaClie
  * @throws For invalid arguments
  */
 export function cadenza(baseUrl: string, options?: CadenzaClientOptions | undefined): CadenzaClient;
+export namespace cadenza {
+    export { CADENZAJS_VERSION as version };
+}
 /**
  * _Notes:_
  * * Most public methods are tagged with one of these modifiers:
  *   * `Embed`: The method embeds Cadenza in the given iframe.
- *   * `Post Message`: The method communicates with an embedded or parent/opener Cadenza via postMessage.
+ *   * `Post Message`: The method communicates with an embedded Cadenza via postMessage.
  *   * `Post Message Parent`: The method communicates with a parent/opener Cadenza via postMessage.
  *   * `Server`: The method communicates with the Cadenza server via HTTP.
  * * Most public methods can be aborted using an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
@@ -85,11 +88,12 @@ export class CadenzaClient {
      * @param {object} [__namedParameters] - Options
      * @param {boolean} [__namedParameters.invalidateCaches] - When true, caches will be invalidated for objecttypes used
      *   in the worksheet
+     * @return {Promise<void>} A `Promise` which resolves when the views of the worksheet have finished reloading
      * @postMessage
      */
     reload({ invalidateCaches }?: {
         invalidateCaches?: boolean | undefined;
-    } | undefined, ...args: any[]): void;
+    } | undefined, ...args: any[]): Promise<void>;
     /**
      * Sends a message to parent Cadenza window to close the window containing this application
      * @postMessageParent
@@ -103,6 +107,7 @@ export class CadenzaClient {
      * @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 {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @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
@@ -113,7 +118,6 @@ export class CadenzaClient {
      * @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
@@ -121,10 +125,11 @@ export class CadenzaClient {
      * - {@link CadenzaActionEvent}
      * @embed
      */
-    showMap(mapView: EmbeddingTargetId, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, extentStrategy, signal, additionalLayers, }?: {
+    showMap(mapView: EmbeddingTargetId, { additionalLayers, disabledUiFeatures, expandNavigator, extentStrategy, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, }?: {
         additionalLayers?: LayerDefinition[] | undefined;
         disabledUiFeatures?: UiFeature[] | undefined;
         expandNavigator?: boolean | undefined;
+        extentStrategy?: ExtentStrategy | undefined;
         filter?: FilterVariables | undefined;
         geometry?: Geometry | undefined;
         hideMainHeaderAndFooter?: boolean | undefined;
@@ -135,7 +140,6 @@ export class CadenzaClient {
         operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
         useMapSrs?: boolean | undefined;
-        extentStrategy?: ExtentStrategy | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
      * Expand/collapse the navigator.
@@ -185,30 +189,42 @@ export class CadenzaClient {
      * @hidden
      * @param {WorkbookLayerPath | string} layer - The data view layer to set the selection in
      * @param {unknown[][]} values - The IDs of the objects to select
+     * @param {object} [__namedParameters]
+     * @param {GeometryExtentStrategy} [__namedParameters.extentStrategy] - Strategy to define the new map extent
      * @return {Promise<void>} A `Promise` for when the selection was set.
      * @postMessage
      */
-    setSelection(layer: WorkbookLayerPath | string, values: unknown[][], ...args: any[]): Promise<void>;
+    setSelection(layer: WorkbookLayerPath | string, values: unknown[][], { extentStrategy }?: {
+        extentStrategy?: GeometryExtentStrategy | undefined;
+    } | undefined, ...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
+     * @param {object} [__namedParameters]
+     * @param {GeometryExtentStrategy} [__namedParameters.extentStrategy] - Strategy to define the new map extent
      * @return {Promise<void>} A `Promise` for when the selection was changed.
      * @postMessage
      */
-    addSelection(layer: WorkbookLayerPath | string, values: unknown[][], ...args: any[]): Promise<void>;
+    addSelection(layer: WorkbookLayerPath | string, values: unknown[][], { extentStrategy }?: {
+        extentStrategy?: GeometryExtentStrategy | undefined;
+    } | undefined, ...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
+     * @param {object} [__namedParameters]
+     * @param {GeometryExtentStrategy} [__namedParameters.extentStrategy] - Strategy to define the new map extent
      * @return {Promise<void>} A `Promise` for when the selection was changed.
      * @postMessage
      */
-    removeSelection(layer: WorkbookLayerPath | string, values: unknown[][], ...args: any[]): Promise<void>;
+    removeSelection(layer: WorkbookLayerPath | string, values: unknown[][], { extentStrategy }?: {
+        extentStrategy?: GeometryExtentStrategy | undefined;
+    } | undefined, ...args: any[]): Promise<void>;
     /**
      * Create a geometry.
      *
@@ -220,14 +236,15 @@ export class CadenzaClient {
      * @param {object} [__namedParameters] - Options
      * @param {LayerDefinition[]} [__namedParameters.additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing.
      * @param {UiFeature[]} [__namedParameters.disabledUiFeatures] - Cadenza UI features to disable
+     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @param {FilterVariables} [__namedParameters.filter] - Filter variables
      * @param {string} [__namedParameters.locationFinder] - A search query for the location finder - _Deprecated_: Use {@link LocationFinderExtentStrategy} instead.
      * @param {Extent} [__namedParameters.mapExtent] - A map extent to set - _Deprecated_: Use {@link StaticExtentStrategy} instead.
      * @param {number} [__namedParameters.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
      * @param {OperationMode} [__namedParameters.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the iframe loading
+     * @param {SnappingOptions} [__namedParameters.snapping] - Passing these options enables snapping
      * @param {boolean} [__namedParameters.useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS and the created geometry should use the map's SRS (otherwise EPSG:4326 is assumed)
-     * @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
@@ -236,17 +253,18 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    createGeometry(backgroundMapView: EmbeddingTargetId, geometryType: GeometryType, { additionalLayers, disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, extentStrategy, }?: {
+    createGeometry(backgroundMapView: EmbeddingTargetId, geometryType: GeometryType, { additionalLayers, disabledUiFeatures, extentStrategy, filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, snapping, }?: {
         additionalLayers?: LayerDefinition[] | undefined;
         disabledUiFeatures?: UiFeature[] | undefined;
+        extentStrategy?: ExtentStrategy | undefined;
         filter?: FilterVariables | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
         minScale?: number | undefined;
         operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
+        snapping?: SnappingOptions | undefined;
         useMapSrs?: boolean | undefined;
-        extentStrategy?: ExtentStrategy | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
      * Edit a geometry.
@@ -256,14 +274,15 @@ export class CadenzaClient {
      * @param {object} [__namedParameters] - Options
      * @param {LayerDefinition[]} [__namedParameters.additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing. Each is a layer definition, with name, type and content (a Geojson featureCollection).
      * @param {UiFeature[]} [__namedParameters.disabledUiFeatures] - Cadenza UI features to disable
+     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @param {FilterVariables} [__namedParameters.filter] - Filter variables
      * @param {string} [__namedParameters.locationFinder] - A search query for the location finder - _Deprecated_: Use {@link LocationFinderExtentStrategy} instead.
      * @param {Extent} [__namedParameters.mapExtent] - A map extent to set - _Deprecated_: Use {@link StaticExtentStrategy} instead.
      * @param {number} [__namedParameters.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
      * @param {OperationMode} [__namedParameters.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [__namedParameters.signal] - A signal to abort the iframe loading
+     * @param {SnappingOptions} [__namedParameters.snapping] - Passing these options enables snapping
      * @param {boolean} [__namedParameters.useMapSrs] - Whether the coordinates specified in other parameters are specified in the map's SRS (otherwise EPSG:4326 is assumed)
-     * @param {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
@@ -272,17 +291,18 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    editGeometry(backgroundMapView: EmbeddingTargetId, geometry: Geometry, { additionalLayers, disabledUiFeatures, filter, locationFinder, mapExtent, minScale, operationMode, signal, useMapSrs, extentStrategy, }?: {
+    editGeometry(backgroundMapView: EmbeddingTargetId, geometry: Geometry, { additionalLayers, disabledUiFeatures, extentStrategy, filter, locationFinder, mapExtent, minScale, operationMode, signal, snapping, useMapSrs, }?: {
         additionalLayers?: LayerDefinition[] | undefined;
         disabledUiFeatures?: UiFeature[] | undefined;
+        extentStrategy?: ExtentStrategy | undefined;
         filter?: FilterVariables | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
         minScale?: number | undefined;
         operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
+        snapping?: SnappingOptions | undefined;
         useMapSrs?: boolean | undefined;
-        extentStrategy?: ExtentStrategy | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
      * Set custom validity state of the geometry editor in addition to the default validation state (including errors and
@@ -299,6 +319,7 @@ export class CadenzaClient {
      *
      * @param {EmbeddingTargetId} backgroundMapView - The workbook map view
      * @param {object} [__namedParameters] - Options
+     * @param {ExtentStrategy} [__namedParameters.extentStrategy] - Defines the initial map extent; If not given, Cadenza's default logic is used.
      * @param {FilterVariables} [__namedParameters.filter] - Filter variables
      * @param {(WorkbookLayerPath | string)[]} [__namedParameters.layers] - Layers to restrict the selection to
      *  (identified using layer paths or print names)
@@ -307,7 +328,6 @@ export class CadenzaClient {
      * @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
@@ -317,7 +337,8 @@ export class CadenzaClient {
      * - {@link CadenzaSelectObjectsCancelEvent}
      * @embed
      */
-    selectObjects(backgroundMapView: EmbeddingTargetId, { filter, layers, locationFinder, mapExtent, useMapSrs, operationMode, signal, extentStrategy, }?: {
+    selectObjects(backgroundMapView: EmbeddingTargetId, { extentStrategy, filter, layers, locationFinder, mapExtent, useMapSrs, operationMode, signal, }?: {
+        extentStrategy?: ExtentStrategy | undefined;
         filter?: FilterVariables | undefined;
         layers?: (string | WorkbookLayerPath)[] | undefined;
         locationFinder?: string | undefined;
@@ -325,7 +346,6 @@ export class CadenzaClient {
         useMapSrs?: boolean | undefined;
         operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
-        extentStrategy?: ExtentStrategy | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
      * Subscribe to a `postMessage()` event.
@@ -372,17 +392,17 @@ export class CadenzaClient {
      * @param {unknown[][]} objectIds - The IDs of the objects to select
      * @param {object} [__namedParameters] - Options
      * @param {FilterVariables} [__namedParameters.filter] - Filter variables
+     * @param {Boolean} [__namedParameters.fullGeometries] - Return non-simplified geometries
      * @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
      */
-    fetchObjectInfo(source: EmbeddingTargetId, layerPath: (WorkbookLayerPath | string)[], objectIds: unknown[][], { filter, signal, useMapSrs, fullGeometries }?: {
+    fetchObjectInfo(source: EmbeddingTargetId, layerPath: (WorkbookLayerPath | string)[], objectIds: unknown[][], { filter, signal, fullGeometries, useMapSrs }?: {
         filter?: FilterVariables | undefined;
+        fullGeometries?: boolean | undefined;
         signal?: AbortSignal | undefined;
         useMapSrs?: boolean | undefined;
-        fullGeometries?: boolean | undefined;
     } | undefined, ...args: any[]): Promise<FeatureCollection>;
     /**
      *  Fetch the intersection areas from a workbook map view layer in JSON format for a given area.
@@ -392,16 +412,16 @@ export class CadenzaClient {
      *  (identified using layer paths or print names)
      * @param {Geometry} geometry - The intersection geometry
      * @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
+     * @param {boolean} [__namedParameters.useMapSrs]  - The intersection geometry and the result geometries are in the map's SRS (otherwise EPSG:4326 is assumed)
      * @return {Promise<FeatureCollection>} A `Promise` for the fetch response
      * @server
      */
-    fetchAreaIntersections(source: EmbeddingTargetId, layerPath: (WorkbookLayerPath | string)[], geometry: Geometry, { useMapSrs, buffer, signal }?: {
-        useMapSrs?: boolean | undefined;
+    fetchAreaIntersections(source: EmbeddingTargetId, layerPath: (WorkbookLayerPath | string)[], geometry: Geometry, { buffer, signal, useMapSrs }?: {
         buffer?: Distance | undefined;
         signal?: AbortSignal | undefined;
+        useMapSrs?: boolean | undefined;
     } | undefined, ...args: any[]): Promise<FeatureCollection>;
     /**
      * Download data from a workbook view.
@@ -435,9 +455,9 @@ export class CadenzaClient {
  * | 'editGeometry:update'
  * | 'editGeometry:cancel'
  * | 'objectInfo'
+ * | 'reload'
  * | 'selectObjects:ok'
  * | 'selectObjects:cancel'
- * | 'reload'
  * } CadenzaEventType - An event type to subscribe to using {@link CadenzaClient#on}
  */
 /**
@@ -449,9 +469,9 @@ export class CadenzaClient {
  *  : T extends 'editGeometry:ok' ? CadenzaEditGeometryOkEvent
  *  : T extends 'editGeometry:cancel' ? CadenzaEditGeometryCancelEvent
  *  : T extends 'objectInfo' ? CadenzaObjectInfoEvent
+ *  : T extends 'reload' ? CadenzaReloadEvent
  *  : T extends 'selectObjects:ok' ? CadenzaSelectObjectsOkEvent
  *  : T extends 'selectObjects:cancel' ? CadenzaSelectObjectsCancelEvent
- *  : T extends 'reload' ? CadenzaReloadEvent
  *  : never
  * } CadenzaEventByType
  */
@@ -784,11 +804,21 @@ export type FeatureCollection = {
  * - The type of custom validity used for disclose on visual presentation and form submission behavior
  */
 export type CustomValidityType = 'error' | 'warning' | 'info' | 'success';
+export type SnappingOptions = {
+    /**
+     * - The layer to snap to
+     */
+    layer: WorkbookLayerPath | string;
+    /**
+     * - Snapping types; Without this option, the Cadenza default snapping types are used.
+     */
+    types?: ("toVertices" | "toEdges" | "lineTracing")[] | undefined;
+};
 /**
  * - An event type to subscribe to using {@link CadenzaClienton }
  */
-export type CadenzaEventType = 'action' | 'change:selection' | 'drillThrough' | 'editGeometry:ok' | 'editGeometry:update' | 'editGeometry:cancel' | 'objectInfo' | 'selectObjects:ok' | 'selectObjects:cancel' | 'reload';
-export type CadenzaEventByType<T extends CadenzaEventType> = T extends 'action' ? CadenzaActionEvent : 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 : T extends 'reload' ? CadenzaReloadEvent : never;
+export type CadenzaEventType = 'action' | 'change:selection' | 'drillThrough' | 'editGeometry:ok' | 'editGeometry:update' | 'editGeometry:cancel' | 'objectInfo' | 'reload' | 'selectObjects:ok' | 'selectObjects:cancel';
+export type CadenzaEventByType<T extends CadenzaEventType> = T extends 'action' ? CadenzaActionEvent : 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 'reload' ? CadenzaReloadEvent : T extends 'selectObjects:ok' ? CadenzaSelectObjectsOkEvent : T extends 'selectObjects:cancel' ? CadenzaSelectObjectsCancelEvent : never;
 /**
  * - A Cadenza `postMessage()` event
  */
@@ -883,3 +913,17 @@ export type CadenzaSelectObjectsCancelEvent = CadenzaEvent<'selectObjects:cancel
  * with the correct original URL and parameters and do what was originally done when displaying that iframe.
  */
 export type CadenzaReloadEvent = CadenzaEvent<'reload'>;
+/**
+ * @typedef CadenzaClientOptions
+ * @property {string} [baseUrl] - The base URL of the Cadenza server
+ * @property {HTMLIFrameElement | string} [options.iframe] - An iframe for embedding Cadenza or the iframe's ID.
+ *   The iframe is required only for methods that embed Cadenza in an iframe, so e.g. not for {@link CadenzaClient#fetchData}.
+ *   If you want to embed Cadenza in multiple iframes, you need to create an instance of the `CadenzaClient` per iframe.
+ * @property {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!
+ * @property {boolean} [options.debug] - Whether to enable debug logging
+ */
+declare const CADENZAJS_VERSION: "{{version}}";
+export {};