@disy/cadenza.js 10.2.1 → 10.2.2

package/cadenza.d.ts

@@ -205,6 +205,12 @@ export class CadenzaClient {
      * @postMessage
      */
     removeSelection(layer: WorkbookLayerPath | string, values: unknown[][], ...args: any[]): Promise<void>;
+    /**
+     * @typedef {Object} 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.
      *
@@ -214,6 +220,7 @@ 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
@@ -221,6 +228,7 @@ export class CadenzaClient {
      * @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.
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -229,7 +237,8 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    createGeometry(backgroundMapView: EmbeddingTargetId, geometryType: GeometryType, { filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, }?: {
+    createGeometry(backgroundMapView: EmbeddingTargetId, geometryType: GeometryType, { disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, additionalLayers, }?: {
+        disabledUiFeatures?: UiFeature[] | undefined;
         filter?: FilterVariables | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
@@ -237,6 +246,20 @@ export class CadenzaClient {
         useMapSrs?: boolean | undefined;
         operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
+        additionalLayers?: {
+            /**
+             * - The layer's name.
+             */
+            name: string;
+            /**
+             * - The layer's type.
+             */
+            type: 'geojson';
+            /**
+             * - The layer's content in geojson format.
+             */
+            content: FeatureCollection;
+        }[] | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
      * Edit a geometry.
@@ -244,6 +267,7 @@ export class CadenzaClient {
      * @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
@@ -252,6 +276,7 @@ export class CadenzaClient {
      * @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 {Object[]} [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).
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -260,7 +285,8 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    editGeometry(backgroundMapView: EmbeddingTargetId, geometry: Geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, operationMode, signal, }?: {
+    editGeometry(backgroundMapView: EmbeddingTargetId, geometry: Geometry, { disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, operationMode, signal, additionalLayers, }?: {
+        disabledUiFeatures?: UiFeature[] | undefined;
         filter?: FilterVariables | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
@@ -269,6 +295,7 @@ export class CadenzaClient {
         operationMode?: OperationMode | undefined;
         zoomTarget?: GeometryZoomTarget | undefined;
         signal?: AbortSignal | undefined;
+        additionalLayers?: Object[] | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
      * Set custom validity state of the geometry editor in addition to the default validation state (including errors and
@@ -419,6 +446,7 @@ export class CadenzaClient {
  * | 'objectInfo'
  * | 'selectObjects:ok'
  * | 'selectObjects:cancel'
+ * | 'reload'
  * } CadenzaEventType - An event type to subscribe to using {@link CadenzaClient#on}
  */
 /**
@@ -432,6 +460,7 @@ export class CadenzaClient {
  *  : T extends 'objectInfo' ? CadenzaObjectInfoEvent
  *  : T extends 'selectObjects:ok' ? CadenzaSelectObjectsOkEvent
  *  : T extends 'selectObjects:cancel' ? CadenzaSelectObjectsCancelEvent
+ *  : T extends 'reload' ? CadenzaReloadEvent
  *  : never
  * } CadenzaEventByType
  */
@@ -470,6 +499,13 @@ export class CadenzaClient {
  * For a selection in a workbook map view with activated feature info, the values also include the simplified geometries of the selected objects.
  */
 /** @typedef {CadenzaEvent<'selectObjects:cancel'>} CadenzaSelectObjectsCancelEvent - When the user cancelled the selection. */
+/**
+ * @typedef {CadenzaEvent<'reload'>} CadenzaReloadEvent - When the user clicked on the 'reload' button in the embedding standby page
+ *
+ * If a user does not interact with the iframe displaying the Cadenza content for a while, a standby embed page is displayed
+ * and the user can click a reload button there. Then the application using Cadenza JS can re-trigger the loading of the iframe
+ * with the correct original URL and parameters and do what was originally done when displaying that iframe.
+ */
 export class AbortError extends DOMException {
     constructor();
 }
@@ -578,9 +614,10 @@ export type OperationMode = 'normal' | 'simplified';
  *
  * _Note:_ Supported features are:
  * * `"workbook-design"` - The workbook designer
+ * * `"workbook-map-add-layer"`- Add layers to the map
  * * `"workbook-view-management"` - Add/Edit/Remove workbook views (Is included in 'workbook-design'.)
  */
-export type UiFeature = 'workbook-design' | 'workbook-view-management';
+export type UiFeature = 'workbook-design' | 'workbook-map-add-layer' | 'workbook-view-management';
 export type Distance = {
     value: number;
     lengthUnit: LengthUnit;
@@ -678,8 +715,8 @@ export type CustomValidityType = 'error' | 'warning' | 'info' | 'success';
 /**
  * - 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';
-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 : never;
+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;
 /**
  * - A Cadenza `postMessage()` event
  */
@@ -770,3 +807,11 @@ export type CadenzaSelectObjectsOkEvent = CadenzaEvent<'selectObjects:ok', {
  * - When the user cancelled the selection.
  */
 export type CadenzaSelectObjectsCancelEvent = CadenzaEvent<'selectObjects:cancel'>;
+/**
+ * - When the user clicked on the 'reload' button in the embedding standby page
+ *
+ * If a user does not interact with the iframe displaying the Cadenza content for a while, a standby embed page is displayed
+ * and the user can click a reload button there. Then the application using Cadenza JS can re-trigger the loading of the iframe
+ * with the correct original URL and parameters and do what was originally done when displaying that iframe.
+ */
+export type CadenzaReloadEvent = CadenzaEvent<'reload'>;

package/cadenza.js

@@ -90,10 +90,11 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  */
 /** @typedef {'normal'|'simplified'} OperationMode - The mode in which a workbook should be operated */
 /**
- * @typedef {'workbook-design'|'workbook-view-management'} UiFeature - The name of a Cadenza UI feature
+ * @typedef {'workbook-design'|'workbook-map-add-layer'|'workbook-view-management'} UiFeature - The name of a Cadenza UI feature
  *
  * _Note:_ Supported features are:
  * * `"workbook-design"` - The workbook designer
+ * * `"workbook-map-add-layer"`- Add layers to the map
  * * `"workbook-view-management"` - Add/Edit/Remove workbook views (Is included in 'workbook-design'.)
  * */
 /**
@@ -456,6 +457,12 @@ export class CadenzaClient {
             values,
         });
     }
+    /**
+     * @typedef {Object} 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.
      *
@@ -465,6 +472,7 @@ 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
@@ -472,6 +480,7 @@ export class CadenzaClient {
      * @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.
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -480,10 +489,11 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    createGeometry(backgroundMapView, geometryType, { filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, } = {}) {
+    async createGeometry(backgroundMapView, geometryType, { disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, additionalLayers, } = {}) {
         this.#log('CadenzaClient#createGeometry', ...arguments);
         const params = createParams({
             action: 'editGeometry',
+            disabledUiFeatures,
             filter,
             geometryType,
             locationFinder,
@@ -492,7 +502,10 @@ export class CadenzaClient {
             useMapSrs,
             operationMode,
         });
-        return this.#show(resolvePath(backgroundMapView), params, signal);
+        await this.#show(resolvePath(backgroundMapView), params, signal);
+        if (additionalLayers) {
+            additionalLayers.forEach((layer) => this.#postEvent('importLayer', layer));
+        }
     }
     /**
      * Edit a geometry.
@@ -500,6 +513,7 @@ export class CadenzaClient {
      * @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
@@ -508,6 +522,7 @@ export class CadenzaClient {
      * @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 {Object[]} [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).
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
      * @fires
@@ -516,12 +531,13 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    async editGeometry(backgroundMapView, geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, operationMode, signal, } = {}) {
+    async editGeometry(backgroundMapView, geometry, { disabledUiFeatures, filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, operationMode, signal, additionalLayers, } = {}) {
         this.#log('CadenzaClient#editGeometry', ...arguments);
         assertValidGeometryType(geometry.type);
         const zoomToGeometry = geometry && zoomTarget?.type === 'geometry';
         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
@@ -538,6 +554,9 @@ export class CadenzaClient {
                 zoomToGeometry,
             });
         }
+        if (additionalLayers) {
+            additionalLayers.forEach((layer) => this.#postEvent('importLayer', layer));
+        }
     }
     /**
      * Set custom validity state of the geometry editor in addition to the default validation state (including errors and
@@ -995,7 +1014,11 @@ function validOperationMode(/** @type string */ value) {
     return ['normal', 'simplified'].includes(value);
 }
 function validUiFeature(/** @type string */ value) {
-    return ['workbook-design', 'workbook-view-management'].includes(value);
+    return [
+        'workbook-design',
+        'workbook-map-add-layer',
+        'workbook-view-management',
+    ].includes(value);
 }
 function assertSupportedDataType(
 /** @type DataType */ type, 
@@ -1086,6 +1109,7 @@ function array(/** @type unknown */ value) {
  * | 'objectInfo'
  * | 'selectObjects:ok'
  * | 'selectObjects:cancel'
+ * | 'reload'
  * } CadenzaEventType - An event type to subscribe to using {@link CadenzaClient#on}
  */
 /**
@@ -1099,6 +1123,7 @@ function array(/** @type unknown */ value) {
  *  : T extends 'objectInfo' ? CadenzaObjectInfoEvent
  *  : T extends 'selectObjects:ok' ? CadenzaSelectObjectsOkEvent
  *  : T extends 'selectObjects:cancel' ? CadenzaSelectObjectsCancelEvent
+ *  : T extends 'reload' ? CadenzaReloadEvent
  *  : never
  * } CadenzaEventByType
  */
@@ -1142,6 +1167,13 @@ function array(/** @type unknown */ value) {
  * For a selection in a workbook map view with activated feature info, the values also include the simplified geometries of the selected objects.
  */
 /** @typedef {CadenzaEvent<'selectObjects:cancel'>} CadenzaSelectObjectsCancelEvent - When the user cancelled the selection. */
+/**
+ * @typedef {CadenzaEvent<'reload'>} CadenzaReloadEvent - When the user clicked on the 'reload' button in the embedding standby page
+ *
+ * If a user does not interact with the iframe displaying the Cadenza content for a while, a standby embed page is displayed
+ * and the user can click a reload button there. Then the application using Cadenza JS can re-trigger the loading of the iframe
+ * with the correct original URL and parameters and do what was originally done when displaying that iframe.
+ */
 export class AbortError extends DOMException {
     constructor() {
         super('Aborted', 'AbortError');

package/package.json

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

package/sandbox.html

@@ -231,7 +231,8 @@
       fullGeometries,
       zoomToGeometry,
       distance,
-      lengthUnit
+      lengthUnit,
+      additionalLayers
     }) {
       return {
         disabledUiFeatures: disabledUiFeatures && disabledUiFeatures.split(','),
@@ -253,7 +254,8 @@
         useMapSrs: useMapSrs === 'on',
         fullGeometries: fullGeometries === 'on',
         zoomTarget: zoomToGeometry === 'on' ? { type: 'geometry' } : undefined,
-        buffer: distance ? { value: Number(distance), lengthUnit: lengthUnit ? lengthUnit : 'm' } : undefined
+        buffer: distance ? { value: Number(distance), lengthUnit: lengthUnit ? lengthUnit : 'm' } : undefined,
+        additionalLayers: additionalLayers && JSON.parse(additionalLayers)
       };
     }
 
@@ -351,6 +353,15 @@
       Simplified operation mode
     </label>
   </div>
+  <div>
+    <label>
+      <input type="checkbox" name="expandNavigator">
+      Expand navigator tree
+    </label>
+  </div>
+</template>
+
+<template id="common-disabledUiFeatures">
   <div>
     <label for="disabledUiFeatures">Disabled UI features</label>
     <input name="disabledUiFeatures" id="disabledUiFeatures" placeholder="feature1,feature2,...">
@@ -361,16 +372,11 @@
       Supported features:
       <ul>
         <li>workbook-design</li>
+        <li>workbook-map-add-layer</li>
         <li>workbook-view-management</li>
       </ul>
     </small>
   </div>
-  <div>
-    <label>
-      <input type="checkbox" name="expandNavigator">
-      Expand navigator tree
-    </label>
-  </div>
 </template>
 
 <template id="common-filter">
@@ -427,7 +433,7 @@
   </div>
 </template>
 
-<template data-action="show" data-common="showWorkbook,filter,show">
+<template data-action="show" data-common="showWorkbook,disabledUiFeatures,filter,show">
   <div>
     <label for="embeddingTargetId">Embedding target ID *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
@@ -463,7 +469,7 @@
   </div>
 </template>
 
-<template data-action="showMap" data-common="zoomTo,map,showWorkbook,filter,show">
+<template data-action="showMap" data-common="zoomTo,map,showWorkbook,disabledUiFeatures,filter,show">
   <div>
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
@@ -490,11 +496,15 @@
 
 <template data-action="setFilter" data-common="filter"></template>
 
-<template data-action="createGeometry" data-common="map,filter">
+<template data-action="createGeometry" data-common="map,disabledUiFeatures,filter">
   <div>
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
   </div>
+  <div>
+    <label for="geometry">Additional layers (GeoJSON)</label>
+    <textarea name="additionalLayers" id="additionalLayers" rows="10"></textarea>
+  </div>
   <div>
     <label for="geometryType">Geometry type</label>
     <select name="geometryType" id="geometryType">
@@ -518,11 +528,15 @@
   </div>
 </template>
 
-<template data-action="editGeometry" data-common="zoomTo,map,filter">
+<template data-action="editGeometry" data-common="zoomTo,map,disabledUiFeatures,filter">
   <div>
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
   </div>
+  <div>
+    <label for="geometry">Additional layers (GeoJSON)</label>
+    <textarea name="additionalLayers" id="additionalLayers" rows="10"></textarea>
+  </div>
   <div>
     <label for="geometry">Geometry (GeoJSON) *</label>
     <textarea name="geometry" id="geometry" rows="5" required></textarea>