@disy/cadenza.js 1.0.0 → 1.1.0

package/cadenza.d.ts

@@ -4,14 +4,22 @@
  * @param {string} baseUrl - The base URL of the Cadenza server
  * @param {object} [options] - Options
  * @param {HTMLIFrameElement | string} [options.iframe] - An iframe for embedding Cadenza or the iframe's ID
+ * @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.
  * @param {boolean} [options.debug] - Whether to enable debug logging
- * @throws For invalid base URL
+ * @throws For invalid arguments
  */
 export function cadenza(baseUrl: string, options?: {
     iframe?: string | HTMLIFrameElement | undefined;
+    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 */
+/**
+ * @typedef ExternalLinkKey - A tuple qualifying a Cadenza external link
+ * @property {string} repositoryName - The name of the link's repository
+ * @property {string} externalLinkId - The ID of the external link
+ */
 /**
  * @typedef WorkbookKey - A tuple qualifying a workbook
  * @property {string} repositoryName - The name of the workbook's repository
@@ -32,6 +40,14 @@ export function cadenza(baseUrl: string, options?: {
 /** @typedef {EmbeddingTargetId | WorkbookKey} WorkbookSource - A workbook source */
 /** @typedef {EmbeddingTargetId | WorksheetKey} WorksheetSource - A worksheet source */
 /** @typedef {EmbeddingTargetId | WorkbookViewKey} WorkbookViewSource - A workbook view source */
+/** @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
+ *
+ * _Note:_ Supported features are:
+ * * '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
  * @property {GeometryType} type - The type of the geometry
@@ -56,10 +72,12 @@ export class CadenzaClient {
      * @param {string} baseUrl
      * @param {object} [options]
      * @param {HTMLIFrameElement | string} [options.iframe]
+     * @param {ExternalLinkKey} [options.webApplication]
      * @param {boolean} [options.debug]
      */
-    constructor(baseUrl: string, { debug, iframe }?: {
+    constructor(baseUrl: string, { debug, iframe, webApplication }?: {
         iframe?: string | HTMLIFrameElement | undefined;
+        webApplication?: ExternalLinkKey | undefined;
         debug?: boolean | undefined;
     } | undefined);
     /** The base URL of the Cadenza server this client is requesting */
@@ -71,15 +89,24 @@ export class CadenzaClient {
      *
      * @param {WorkbookSource | WorksheetSource | WorkbookViewSource} source - The source to show
      * @param {object} [options]
-     * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer.
-     * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar.
+     * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
+     * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer
+     * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar
+     * @param {GlobalId} [options.highlightGlobalId] - The ID of an item to highlight / expand in the navigator
+     * @param {string} [options.mediaType] - Set to 'application/pdf' for views of type "JasperReports report"
+     *     to show the report PDF directly, without any Cadenza headers or footers.
+     * @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 an invalid source
+     * @throws For invalid arguments
      */
-    show(source: WorkbookSource | WorksheetSource | WorkbookViewSource, { hideMainHeaderAndFooter, hideWorkbookToolBar, signal }?: {
+    show(source: WorkbookSource | WorksheetSource | WorkbookViewSource, { disabledUiFeatures, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, mediaType, operationMode, signal, }?: {
+        disabledUiFeatures?: UiFeature[] | undefined;
         hideMainHeaderAndFooter?: boolean | undefined;
         hideWorkbookToolBar?: boolean | undefined;
+        highlightGlobalId?: string | undefined;
+        mediaType?: string | undefined;
+        operationMode?: OperationMode | undefined;
         signal?: AbortSignal | undefined;
     } | undefined): Promise<void>;
     /**
@@ -87,22 +114,28 @@ export class CadenzaClient {
      *
      * @param {WorkbookViewSource} mapView - The workbook map view to show
      * @param {object} [options] - Options
+     * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
      * @param {Geometry} [options.geometry] - A geometry to show on the map
-     * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer.
-     * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar.
+     * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer
+     * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar
+     * @param {GlobalId} [options.highlightGlobalId] - The ID of an item to highlight / expand in the navigator
      * @param {string} [options.locationFinder] - A search query for the location finder
      * @param {Extent} [options.mapExtent] - A map extent to set
+     * @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
-     * @throws For an invalid workbook view source or geometry type
+     * @throws For invalid arguments
      */
-    showMap(mapView: WorkbookViewSource, { geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, locationFinder, mapExtent, useMapSrs, signal, }?: {
+    showMap(mapView: WorkbookViewSource, { disabledUiFeatures, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, }?: {
+        disabledUiFeatures?: UiFeature[] | undefined;
         geometry?: Geometry | undefined;
         hideMainHeaderAndFooter?: boolean | undefined;
         hideWorkbookToolBar?: boolean | undefined;
+        highlightGlobalId?: string | undefined;
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
+        operationMode?: OperationMode | undefined;
         useMapSrs?: boolean | undefined;
         signal?: AbortSignal | undefined;
     } | undefined): Promise<void>;
@@ -115,22 +148,22 @@ export class CadenzaClient {
      * @param {WorkbookViewSource} backgroundMapView - The workbook map view in the background
      * @param {GeometryType} geometryType - The geometry type
      * @param {object} [options] - Options
-     * @param {Extent} [options.mapExtent] - A map extent to set
      * @param {string} [options.locationFinder] - A search query for the location finder
-     * @param {boolean} [options.useMapSrs] - Whether the created geometry should use the map's SRS (otherwise EPSG:4326 will be used)
+     * @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 {AbortSignal} [options.signal] - A signal to abort the iframe loading
      * @return {Promise<void>} A Promise for when the iframe is loaded
-     * @throws For an invalid workbook view source or geometry type
+     * @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.
      */
-    createGeometry(backgroundMapView: WorkbookViewSource, geometryType: GeometryType, { mapExtent, locationFinder, useMapSrs, minScale, signal }?: {
-        mapExtent?: Extent | undefined;
+    createGeometry(backgroundMapView: WorkbookViewSource, geometryType: GeometryType, { locationFinder, mapExtent, minScale, useMapSrs, signal }?: {
         locationFinder?: string | undefined;
-        useMapSrs?: boolean | undefined;
+        mapExtent?: Extent | undefined;
         minScale?: number | undefined;
+        useMapSrs?: boolean | undefined;
         signal?: AbortSignal | undefined;
     } | undefined): Promise<void>;
     /**
@@ -141,20 +174,20 @@ export class CadenzaClient {
      * @param {object} [options] - Options
      * @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 {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
-     * @throws For an invalid workbook view source
+     * @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.
      */
-    editGeometry(backgroundMapView: WorkbookViewSource, geometry: Geometry, { mapExtent, locationFinder, useMapSrs, minScale, signal }?: {
+    editGeometry(backgroundMapView: WorkbookViewSource, geometry: Geometry, { locationFinder, mapExtent, minScale, useMapSrs, signal }?: {
         locationFinder?: string | undefined;
         mapExtent?: Extent | undefined;
-        useMapSrs?: boolean | undefined;
         minScale?: number | undefined;
+        useMapSrs?: boolean | undefined;
         signal?: AbortSignal | undefined;
     } | undefined): Promise<void>;
     /**
@@ -166,6 +199,41 @@ export class CadenzaClient {
      * @return {() => void} An unsubscribe function
      */
     on<T = unknown>(type: string, subscriber: (event: CadenzaEvent<T>) => void): () => void;
+    /**
+     * Fetch data from a workbook view.
+     *
+     * @param {WorkbookViewSource} source - The workbook view to fetch data from
+     * @param {MediaType} mediaType - The media type to use for the data. Allowed are:
+     * * 'application/json'
+     * * 'application/pdf' (for Jasper Report views)
+     * * 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' (Excel)
+     * * 'text/csv'
+     * @param {object} options - Options
+     * @param {AbortSignal} [options.signal] - A signal to abort the data fetching
+     * @return {Promise<Response>} A Promise for the fetch response
+     * @throws For invalid arguments
+     */
+    fetchData(source: WorkbookViewSource, mediaType: MediaType, { signal }?: {
+        signal?: AbortSignal | undefined;
+    }): 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 {WorkbookViewSource} source - The workbook view to download data from
+     * @param {MediaType} mediaType - The media type to use for the data. Allowed are:
+     * * 'application/json'
+     * * 'application/pdf' (for Jasper Report views)
+     * * 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' (Excel)
+     * * 'text/csv'
+     * @param {object} options - Options
+     * @param {string} [options.fileName] - The file name to use; The file extension is appended by Cadenza.
+     * @throws For invalid arguments
+     */
+    downloadData(source: WorkbookViewSource, mediaType: MediaType, { fileName }: {
+        fileName?: string | undefined;
+    }): void;
     #private;
 }
 /**
@@ -196,6 +264,23 @@ export class CadenzaError extends Error {
  * - The ID of an embedding target
  */
 export type EmbeddingTargetId = string;
+/**
+ * - The ID of a navigator item
+ */
+export type GlobalId = string;
+/**
+ * - A tuple qualifying a Cadenza external link
+ */
+export type ExternalLinkKey = {
+    /**
+     * - The name of the link's repository
+     */
+    repositoryName: string;
+    /**
+     * - The ID of the external link
+     */
+    externalLinkId: string;
+};
 /**
  * - A tuple qualifying a workbook
  */
@@ -255,6 +340,18 @@ export type WorksheetSource = EmbeddingTargetId | WorksheetKey;
  * - A workbook view source
  */
 export type WorkbookViewSource = EmbeddingTargetId | WorkbookViewKey;
+/**
+ * - The mode in which a workbook should be operated
+ */
+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'.)
+ */
+export type UiFeature = 'workbook-design' | 'workbook-view-management';
 /**
  * - A [GeoJSON](https://geojson.org/) geometry object
  */
@@ -274,6 +371,12 @@ export type GeometryType = 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineStr
  * - An array of numbers representing an extent: [minx, miny, maxx, maxy]
  */
 export type Extent = [number, number, number, number];
+/**
+ * - A media type
+ *
+ * See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types}
+ */
+export type MediaType = string;
 /**
  * - A Cadenza `postMessage()` event
  */
@@ -294,3 +397,10 @@ export type CadenzaErrorEvent = CadenzaEvent<{
     type: string;
     message?: string;
 }>;
+declare namespace MediaType {
+    let CSV: string;
+    let EXCEL: string;
+    let JSON: string;
+    let PDF: string;
+}
+export {};