@disy/cadenza.js 2.13.1 → 2.14.1

package/cadenza.d.ts

@@ -219,6 +219,7 @@ export class CadenzaClient {
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {number} [options.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
      * @param {boolean} [options.useMapSrs] - Whether the created geometry should use the map's SRS (otherwise EPSG:4326 will be used)
+     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
@@ -228,12 +229,13 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    createGeometry(backgroundMapView: EmbeddingTargetId, geometryType: GeometryType, { filter, locationFinder, mapExtent, minScale, useMapSrs, signal }?: {
+    createGeometry(backgroundMapView: EmbeddingTargetId, geometryType: GeometryType, { filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, }?: {
         filter?: FilterVariables | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
         minScale?: number | undefined;
         useMapSrs?: boolean | undefined;
+        operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
@@ -247,6 +249,7 @@ export class CadenzaClient {
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {number} [options.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
      * @param {boolean} [options.useMapSrs] - Whether the geometry is in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
      * @param {ZoomTarget} [options.zoomTarget] - A target Cadenza should zoom to
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
@@ -257,15 +260,26 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    editGeometry(backgroundMapView: EmbeddingTargetId, geometry: Geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, signal, }?: {
+    editGeometry(backgroundMapView: EmbeddingTargetId, geometry: Geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, operationMode, signal, }?: {
         filter?: FilterVariables | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
         minScale?: number | undefined;
         useMapSrs?: boolean | undefined;
+        operationMode?: OperationMode | undefined;
         zoomTarget?: GeometryZoomTarget | undefined;
         signal?: AbortSignal | undefined;
     } | undefined, ...args: any[]): Promise<void>;
+    /**
+     * Set custom validity state of the geometry editor in addition to the default validation state (including errors and
+     * warnings). When set to error the dialog submission is blocked.
+     * If there already is a custom state set it will override it.
+     * Passing '' will reset the custom state to undefined, meaning no custom state is displayed.
+     * If no geometry editing is started, the method call has no effect.
+     * @param {string} message The message to show in the dialog
+     * @param {CustomValidityType} [type] The type of message (defaults to 'error')
+     */
+    setCustomValidity(message: string, type?: CustomValidityType | undefined): void;
     /**
      * Select objects in a workbook map.
      *
@@ -277,6 +291,7 @@ export class CadenzaClient {
      * @param {string} [options.locationFinder] - A search query for the location finder
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {boolean} [options.useMapSrs] - Whether the geometry is in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
@@ -287,12 +302,13 @@ export class CadenzaClient {
      * - {@link CadenzaSelectObjectsCancelEvent}
      * @embed
      */
-    selectObjects(backgroundMapView: EmbeddingTargetId, { filter, layers, locationFinder, mapExtent, useMapSrs, signal }?: {
+    selectObjects(backgroundMapView: EmbeddingTargetId, { filter, layers, locationFinder, mapExtent, useMapSrs, operationMode, signal, }?: {
         filter?: FilterVariables | undefined;
         layers?: (string | WorkbookLayerPath)[] | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
         useMapSrs?: boolean | undefined;
+        operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
     } | undefined, ...args: any[]): Promise<void>;
     /**
@@ -403,6 +419,7 @@ export class CadenzaClient {
  * | 'objectInfo'
  * | 'selectObjects:ok'
  * | 'selectObjects:cancel'
+ * | 'reload'
  * } CadenzaEventType - An event type to subscribe to using {@link CadenzaClient#on}
  */
 /**
@@ -416,6 +433,7 @@ export class CadenzaClient {
  *  : T extends 'objectInfo' ? CadenzaObjectInfoEvent
  *  : T extends 'selectObjects:ok' ? CadenzaSelectObjectsOkEvent
  *  : T extends 'selectObjects:cancel' ? CadenzaSelectObjectsCancelEvent
+ *  : T extends 'reload' ? CadenzaReloadEvent
  *  : never
  * } CadenzaEventByType
  */
@@ -454,6 +472,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();
 }
@@ -655,11 +680,15 @@ export type FeatureCollection = {
      */
     features: Feature[];
 };
+/**
+ * - The type of custom validity used for disclose on visual presentation and form submission behavior
+ */
+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
  */
@@ -750,3 +779,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

@@ -147,6 +147,7 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * @typedef FeatureCollection - A adapted [GeoJSON](https://geojson.org/) feature collection object
  * @property {Feature[]} features - The features within this collection
  */
+/** @typedef {'error'|'warning'|'info'|'success'} CustomValidityType - The type of custom validity used for disclose on visual presentation and form submission behavior */
 let hasCadenzaSession = false;
 /** @type {Promise<void> | undefined} */
 let firstEmbeddingTargetShown;
@@ -469,6 +470,7 @@ export class CadenzaClient {
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {number} [options.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
      * @param {boolean} [options.useMapSrs] - Whether the created geometry should use the map's SRS (otherwise EPSG:4326 will be used)
+     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
@@ -478,7 +480,7 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    createGeometry(backgroundMapView, geometryType, { filter, locationFinder, mapExtent, minScale, useMapSrs, signal } = {}) {
+    createGeometry(backgroundMapView, geometryType, { filter, locationFinder, mapExtent, minScale, useMapSrs, operationMode, signal, } = {}) {
         this.#log('CadenzaClient#createGeometry', ...arguments);
         const params = createParams({
             action: 'editGeometry',
@@ -488,6 +490,7 @@ export class CadenzaClient {
             mapExtent,
             minScale,
             useMapSrs,
+            operationMode,
         });
         return this.#show(resolvePath(backgroundMapView), params, signal);
     }
@@ -502,6 +505,7 @@ export class CadenzaClient {
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {number} [options.minScale] - The minimum scale where the user should work on. A warning is shown when the map is zoomed out above the threshold.
      * @param {boolean} [options.useMapSrs] - Whether the geometry is in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
      * @param {ZoomTarget} [options.zoomTarget] - A target Cadenza should zoom to
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
@@ -512,7 +516,7 @@ export class CadenzaClient {
      * - {@link CadenzaEditGeometryCancelEvent}
      * @embed
      */
-    async editGeometry(backgroundMapView, geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, signal, } = {}) {
+    async editGeometry(backgroundMapView, geometry, { filter, locationFinder, mapExtent, minScale, useMapSrs, zoomTarget, operationMode, signal, } = {}) {
         this.#log('CadenzaClient#editGeometry', ...arguments);
         assertValidGeometryType(geometry.type);
         const zoomToGeometry = geometry && zoomTarget?.type === 'geometry';
@@ -525,6 +529,7 @@ export class CadenzaClient {
             mapExtent,
             minScale,
             useMapSrs,
+            operationMode,
         });
         await this.#show(resolvePath(backgroundMapView), params, signal);
         if (geometry) {
@@ -534,6 +539,19 @@ export class CadenzaClient {
             });
         }
     }
+    /**
+     * Set custom validity state of the geometry editor in addition to the default validation state (including errors and
+     * warnings). When set to error the dialog submission is blocked.
+     * If there already is a custom state set it will override it.
+     * Passing '' will reset the custom state to undefined, meaning no custom state is displayed.
+     * If no geometry editing is started, the method call has no effect.
+     * @param {string} message The message to show in the dialog
+     * @param {CustomValidityType} [type] The type of message (defaults to 'error')
+     */
+    setCustomValidity(message, type = 'error') {
+        assert(['error', 'warning', 'info', 'success'].includes(type), `Invalid validity type: ${type}`);
+        this.#postEvent('setCustomValidity', { message, type });
+    }
     /**
      * Select objects in a workbook map.
      *
@@ -545,6 +563,7 @@ export class CadenzaClient {
      * @param {string} [options.locationFinder] - A search query for the location finder
      * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {boolean} [options.useMapSrs] - Whether the geometry is in the map's SRS (otherwise EPSG:4326 is assumed)
+     * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
      * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A `Promise` for when the iframe is loaded
      * @throws For invalid arguments
@@ -555,7 +574,7 @@ export class CadenzaClient {
      * - {@link CadenzaSelectObjectsCancelEvent}
      * @embed
      */
-    selectObjects(backgroundMapView, { filter, layers, locationFinder, mapExtent, useMapSrs, signal } = {}) {
+    selectObjects(backgroundMapView, { filter, layers, locationFinder, mapExtent, useMapSrs, operationMode, signal, } = {}) {
         this.#log('CadenzaClient#selectObjects', ...arguments);
         const params = createParams({
             action: 'selectObjects',
@@ -564,6 +583,7 @@ export class CadenzaClient {
             locationFinder,
             mapExtent,
             useMapSrs,
+            operationMode,
         });
         return this.#show(resolvePath(backgroundMapView), params, signal);
     }
@@ -1046,7 +1066,7 @@ function createParams({ action, dataType, disabledUiFeatures, expandNavigator, f
         ...(locationFinder && { locationFinder }),
         ...(mapExtent && { mapExtent: mapExtent.join() }),
         ...(minScale && { minScale: String(minScale) }),
-        ...(operationMode && operationMode !== 'normal' && { operationMode }),
+        ...(operationMode && { operationMode }),
         ...(parts && { parts: parts.join() }),
         ...(targetType && { targetType }),
         ...(useMapSrs && { useMapSrs: 'true' }),
@@ -1066,6 +1086,7 @@ function array(/** @type unknown */ value) {
  * | 'objectInfo'
  * | 'selectObjects:ok'
  * | 'selectObjects:cancel'
+ * | 'reload'
  * } CadenzaEventType - An event type to subscribe to using {@link CadenzaClient#on}
  */
 /**
@@ -1079,6 +1100,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
  */
@@ -1122,6 +1144,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": "2.13.1",
+  "version": "2.14.1",
   "license": "Apache-2.0",
   "repository": "github:DisyInformationssysteme/cadenza.js",
   "type": "module",

package/sandbox.html

@@ -181,7 +181,8 @@
         cadenzaClient.fetchAreaIntersections(data.embeddingTargetId, JSON.parse(data.layer), JSON.parse(data.geometry), getOptions(data))
           .then(console.log);
       },
-      downloadData: data => cadenzaClient.downloadData(data.embeddingTargetId, data.dataType, getOptions(data))
+      downloadData: data => cadenzaClient.downloadData(data.embeddingTargetId, data.dataType, getOptions(data)),
+      setCustomValidity: data => cadenzaClient.setCustomValidity(data.message, data.type || undefined)
     };
 
     const form = document.getElementById('form');
@@ -247,7 +248,7 @@
         mapExtent: mapExtent && mapExtent.split(',').map(Number),
         minScale: minScale && Number(minScale),
         parts: parts && parts.split(','),
-        ...(simplifiedOperationMode === 'on' && { operationMode: 'simplified' }),
+        operationMode: (simplifiedOperationMode === 'on' ? 'simplified' : 'normal' ),
         layers: layers ? JSON.parse(layers) : undefined,
         useMapSrs: useMapSrs === 'on',
         fullGeometries: fullGeometries === 'on',
@@ -297,6 +298,7 @@
             <option value="createGeometry">Create Geometry</option>
             <option value="editGeometry">Edit Geometry</option>
             <option value="selectObjects">Select Objects</option>
+            <option value="setCustomValidity">Set Custom Validity</option>
           </optgroup>
           <optgroup label="Without Iframe">
             <option value="downloadData">Download data</option>
@@ -472,6 +474,20 @@
   </div>
 </template>
 
+<template data-action="setCustomValidity">
+  <p>Requires a geometry editing UI (Create / Edit Geometry actions) to be opened first.</p>
+  <label for="message">Message</label>
+  <input type="text" name="message" id="message">
+  <label for="type">Type</label>
+  <select name="type" id="type">
+    <option selected></option>
+    <option>success</option>
+    <option>info</option>
+    <option>warning</option>
+    <option>error</option>
+  </select>
+</template>
+
 <template data-action="setFilter" data-common="filter"></template>
 
 <template data-action="createGeometry" data-common="map,filter">
@@ -490,6 +506,12 @@
       <option>MultiPolygon</option>
     </select>
   </div>
+  <div>
+    <label>
+      <input type="checkbox" name="simplifiedOperationMode">
+      Simplified operation mode
+    </label>
+  </div>
   <div>
     <label for="minScale">Minimum Scale</label>
     <input type="number" name="minScale" id="minScale">
@@ -505,6 +527,12 @@
     <label for="geometry">Geometry (GeoJSON) *</label>
     <textarea name="geometry" id="geometry" rows="5" required></textarea>
   </div>
+  <div>
+    <label>
+      <input type="checkbox" name="simplifiedOperationMode">
+      Simplified operation mode
+    </label>
+  </div>
   <div>
     <label for="minScale">Minimum Scale</label>
     <input type="number" name="minScale" id="minScale">
@@ -516,6 +544,12 @@
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
   </div>
+  <div>
+    <label>
+      <input type="checkbox" name="simplifiedOperationMode">
+      Simplified operation mode
+    </label>
+  </div>
   <div>
     <label for="layers">Layers</label>
     <input name="layers" id="layers">