camunda-bpmn-js 1.3.1 → 1.5.0

package/dist/camunda-platform-viewer.development.js

@@ -435,6 +435,14 @@
 
   var DEFAULT_RENDER_PRIORITY$1 = 1000;
 
+  /**
+   * @typedef {import('../model').Base} Base
+   * @typedef {import('../model').Connection} Connection
+   * @typedef {import('../model').Shape} Shape
+   *
+   * @typedef {import('../core/EventBus').default} EventBus
+   */
+
   /**
    * The base implementation of shape and connection renderers.
    *
@@ -473,52 +481,51 @@
   }
 
   /**
-   * Should check whether *this* renderer can render
-   * the element/connection.
+   * Checks whether an element can be rendered.
    *
-   * @param {element} element
+   * @param {Base} element The element to be rendered.
    *
-   * @returns {boolean}
+   * @returns {boolean} Whether the element can be rendered.
    */
-  BaseRenderer.prototype.canRender = function() {};
+  BaseRenderer.prototype.canRender = function(element) {};
 
   /**
-   * Provides the shape's snap svg element to be drawn on the `canvas`.
+   * Draws a shape.
    *
-   * @param {djs.Graphics} visuals
-   * @param {Shape} shape
+   * @param {SVGElement} visuals The SVG element to draw the shape into.
+   * @param {Shape} shape The shape to be drawn.
    *
-   * @returns {Snap.svg} [returns a Snap.svg paper element ]
+   * @returns {SVGElement} The SVG element of the shape drawn.
    */
-  BaseRenderer.prototype.drawShape = function() {};
+  BaseRenderer.prototype.drawShape = function(visuals, shape) {};
 
   /**
-   * Provides the shape's snap svg element to be drawn on the `canvas`.
+   * Draws a connection.
    *
-   * @param {djs.Graphics} visuals
-   * @param {Connection} connection
+   * @param {SVGElement} visuals The SVG element to draw the connection into.
+   * @param {Connection} connection The connection to be drawn.
    *
-   * @returns {Snap.svg} [returns a Snap.svg paper element ]
+   * @returns {SVGElement} The SVG element of the connection drawn.
    */
-  BaseRenderer.prototype.drawConnection = function() {};
+  BaseRenderer.prototype.drawConnection = function(visuals, connection) {};
 
   /**
-   * Gets the SVG path of a shape that represents it's visual bounds.
+   * Gets the SVG path of the graphical representation of a shape.
    *
-   * @param {Shape} shape
+   * @param {Shape} shape The shape.
    *
-   * @return {string} svg path
+   * @return {string} The SVG path of the shape.
    */
-  BaseRenderer.prototype.getShapePath = function() {};
+  BaseRenderer.prototype.getShapePath = function(shape) {};
 
   /**
-   * Gets the SVG path of a connection that represents it's visual bounds.
+   * Gets the SVG path of the graphical representation of a connection.
    *
-   * @param {Connection} connection
+   * @param {Connection} connection The connection.
    *
-   * @return {string} svg path
+   * @return {string} The SVG path of the connection.
    */
-  BaseRenderer.prototype.getConnectionPath = function() {};
+  BaseRenderer.prototype.getConnectionPath = function(connection) {};
 
   /**
    * Is an element of the given BPMN type?
@@ -1325,9 +1332,15 @@
   }
 
   /**
-   * @param { [ string, ...any[] ][] } elements
+   * @typedef {(string|number)[]} Component
+   *
+   * @typedef {import('../util/Types').Point} Point
+   */
+
+  /**
+   * @param {Component[]} elements
    *
-   * @return { string }
+   * @return {string}
    */
   function componentsToPath(elements) {
     return elements.flat().join(',').replace(/,?([A-z]),?/g, '$1');
@@ -1407,9 +1420,9 @@
   }
 
   /**
-   * @param { { x: number, y: number }[] } points
-   * @param { any } [attrs]
-   * @param { number } [radius]
+   * @param {Point[]} points
+   * @param {*} [attrs]
+   * @param {number} [radius]
    *
    * @return {SVGElement}
    */
@@ -1434,8 +1447,8 @@
   }
 
   /**
-   * @param { SVGElement } gfx
-   * @param { { x: number, y: number }[]} points
+   * @param {SVGElement} gfx
+   * @param {Point[]} points
    *
    * @return {SVGElement}
    */
@@ -2156,7 +2169,7 @@
   }
 
   /**
-   * @param {<SVGElement>} element
+   * @param {SVGElement} element
    * @param {number} x
    * @param {number} y
    * @param {number} angle
@@ -2481,7 +2494,11 @@
           ...shapeStyle({
             fill: fill,
             stroke: stroke,
-            strokeWidth: 1
+            strokeWidth: 1,
+
+            // fix for safari / chrome / firefox bug not correctly
+            // resetting stroke dash array
+            strokeDasharray: [ 10000, 1 ]
           })
         });
 
@@ -2497,7 +2514,11 @@
           ...shapeStyle({
             fill: fill,
             stroke: stroke,
-            strokeWidth: 1
+            strokeWidth: 1,
+
+            // fix for safari / chrome / firefox bug not correctly
+            // resetting stroke dash array
+            strokeDasharray: [ 10000, 1 ]
           })
         });
 
@@ -2513,7 +2534,11 @@
           ...lineStyle({
             fill: 'none',
             stroke: stroke,
-            strokeWidth: 1.5
+            strokeWidth: 1.5,
+
+            // fix for safari / chrome / firefox bug not correctly
+            // resetting stroke dash array
+            strokeDasharray: [ 10000, 1 ]
           })
         });
 
@@ -2530,7 +2555,11 @@
           ...lineStyle({
             fill: 'none',
             stroke: stroke,
-            strokeWidth: 1.5
+            strokeWidth: 1.5,
+
+            // fix for safari / chrome / firefox bug not correctly
+            // resetting stroke dash array
+            strokeDasharray: [ 10000, 1 ]
           })
         });
 
@@ -4220,6 +4249,10 @@
     return getRectPath(element);
   };
 
+  /**
+   * @typedef {import('../util/Types').Dimensions} Dimensions
+   */
+
   var DEFAULT_BOX_PADDING = 0;
 
   var DEFAULT_LABEL_SIZE$1 = {
@@ -4293,7 +4326,8 @@
    *
    * Alters the lines passed.
    *
-   * @param  {Array<string>} lines
+   * @param {string[]} lines
+   *
    * @return {Object} the line descriptor, an object { width, height, text }
    */
   function layoutNext(lines, maxWidth, fakeText) {
@@ -4338,8 +4372,9 @@
    * Shortens a line based on spacing and hyphens.
    * Returns the shortened result on success.
    *
-   * @param  {string} line
-   * @param  {number} maxLength the maximum characters of the string
+   * @param {string} line
+   * @param {number} maxLength the maximum characters of the string
+   *
    * @return {string} the shortened string
    */
   function semanticShorten(line, maxLength) {
@@ -5179,6 +5214,10 @@
     pathMap: [ 'type', PathMap ]
   };
 
+  /**
+   * @typedef {import('./').Replacements} Replacements
+   */
+
   /**
    * A simple translation stub to be used for multi-language support
    * in diagrams. Can be easily replaced with a more sophisticated
@@ -5193,7 +5232,7 @@
    * }
    *
    * @param {string} template to interpolate
-   * @param {Object} [replacements] a map with substitutes
+   * @param {Replacements} [replacements] a map with substitutes
    *
    * @return {string} the translated string
    */
@@ -5346,8 +5385,6 @@
     }, size);
   }
 
-  var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
-
   function getDefaultExportFromCjs (x) {
   	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
   }
@@ -5364,9 +5401,9 @@
   /**
    * Convert the given bounds to a { top, left, bottom, right } descriptor.
    *
-   * @param {Bounds|Point} bounds
+   * @param {Point|Rect} bounds
    *
-   * @return {Object}
+   * @return {RectTRBL}
    */
   function asTRBL(bounds) {
     return {
@@ -5381,9 +5418,9 @@
   /**
    * Convert a { top, left, bottom, right } to an objects bounds.
    *
-   * @param {Object} trbl
+   * @param {RectTRBL} trbl
    *
-   * @return {Bounds}
+   * @return {Rect}
    */
   function asBounds(trbl) {
     return {
@@ -5398,7 +5435,7 @@
   /**
    * Get the mid of the given bounds or point.
    *
-   * @param {Bounds|Point} bounds
+   * @param {Point|Rect} bounds
    *
    * @return {Point}
    */
@@ -5413,7 +5450,7 @@
   /**
    * Get the mid of the given Connection.
    *
-   * @param {djs.Base.Connection} connection
+   * @param {Connection} connection
    *
    * @return {Point}
    */
@@ -5472,7 +5509,7 @@
   /**
    * Get the mid of the given Element.
    *
-   * @param {djs.Base.Connection} connection
+   * @param {Connection} connection
    *
    * @return {Point}
    */
@@ -5882,6 +5919,14 @@
     return isPrimaryButton(event) && originalEvent.shiftKey;
   }
 
+  /**
+   * @typedef {import('../../model').Base} Base
+   *
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('../../draw/Styles').default} Styles
+   */
+
   function allowAll(event) { return true; }
 
   function allowPrimaryAndAuxiliary(event) {
@@ -5911,6 +5956,8 @@
    * prevents the original DOM operation.
    *
    * @param {EventBus} eventBus
+   * @param {ElementRegistry} elementRegistry
+   * @param {Styles} styles
    */
   function InteractionEvents(eventBus, elementRegistry, styles) {
 
@@ -5920,8 +5967,8 @@
      * Fire an interaction event.
      *
      * @param {string} type local event name, e.g. element.click.
-     * @param {DOMEvent} event native event
-     * @param {djs.model.Base} [element] the diagram element to emit the event on;
+     * @param {MouseEvent|TouchEvent} event native event
+     * @param {Base} [element] the diagram element to emit the event on;
      *                                   defaults to the event target
      */
     function fire(type, event, element) {
@@ -6003,8 +6050,8 @@
      * on the target shape or connection.
      *
      * @param {string} eventName the name of the triggered DOM event
-     * @param {MouseEvent} event
-     * @param {djs.model.Base} targetElement
+     * @param {MouseEvent|TouchEvent} event
+     * @param {Base} targetElement
      */
     function triggerMouseEvent(eventName, event, targetElement) {
 
@@ -6170,7 +6217,7 @@
     /**
      * Create default hit for the given element.
      *
-     * @param {djs.model.Base} element
+     * @param {Base} element
      * @param {SVGElement} gfx
      *
      * @return {SVGElement} created hit
@@ -6242,8 +6289,8 @@
     /**
      * Update default hit of the element.
      *
-     * @param  {djs.model.Base} element
-     * @param  {SVGElement} gfx
+     * @param {Base} element
+     * @param {SVGElement} gfx
      *
      * @return {SVGElement} updated hit
      */
@@ -6291,7 +6338,7 @@
    * @event element.hover
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6302,7 +6349,7 @@
    * @event element.out
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6313,7 +6360,7 @@
    * @event element.click
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6324,7 +6371,7 @@
    * @event element.dblclick
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6335,7 +6382,7 @@
    * @event element.mousedown
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6346,7 +6393,7 @@
    * @event element.mouseup
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6358,7 +6405,7 @@
    * @event element.contextmenu
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6372,10 +6419,10 @@
    * Returns the surrounding bbox for all elements in
    * the array or the element primitive.
    *
-   * @param {Array<djs.model.Shape>|djs.model.Shape} elements
+   * @param {Base|Base[]} elements
    * @param {boolean} [stopRecursion=false]
    *
-   * @return {Bounds}
+   * @return {Rect}
    */
   function getBBox(elements, stopRecursion) {
 
@@ -6446,6 +6493,12 @@
 
   var LOW_PRIORITY$2 = 500;
 
+  /**
+   * @typedef {import('../../model').Base} Base
+   *
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('../../draw/Styles').default} Styles
+   */
 
   /**
    * @class
@@ -6455,9 +6508,8 @@
    *
    * @param {EventBus} eventBus
    * @param {Styles} styles
-   * @param {ElementRegistry} elementRegistry
    */
-  function Outline(eventBus, styles, elementRegistry) {
+  function Outline(eventBus, styles) {
 
     this.offset = 6;
 
@@ -6515,8 +6567,8 @@
    * Updates the outline of a shape respecting the dimension of the
    * element and an outline offset.
    *
-   * @param  {SVGElement} outline
-   * @param  {djs.model.Base} element
+   * @param {SVGElement} outline
+   * @param {Base} element
    */
   Outline.prototype.updateShapeOutline = function(outline, element) {
 
@@ -6534,8 +6586,8 @@
    * Updates the outline of a connection respecting the bounding box of
    * the connection and an outline offset.
    *
-   * @param  {SVGElement} outline
-   * @param  {djs.model.Base} element
+   * @param {SVGElement} outline
+   * @param {Base} element
    */
   Outline.prototype.updateConnectionOutline = function(outline, connection) {
 
@@ -6558,13 +6610,17 @@
     outline: [ 'type', Outline ]
   };
 
+  /**
+   * @typedef {import('../../core/EventBus').default} EventBus
+   */
+
   /**
    * A service that offers the current selection in a diagram.
    * Offers the api to control the selection, too.
    *
    * @class
    *
-   * @param {EventBus} eventBus the event bus
+   * @param {EventBus} eventBus
    */
   function Selection(eventBus, canvas) {
 
@@ -6620,8 +6676,8 @@
    *
    * @method Selection#select
    *
-   * @param  {Object|Object[]} elements element or array of elements to be selected
-   * @param  {boolean} [add] whether the element(s) should be appended to the current selection, defaults to false
+   * @param {Object|Object[]} elements element or array of elements to be selected
+   * @param {boolean} [add] whether the element(s) should be appended to the current selection, defaults to false
    */
   Selection.prototype.select = function(elements, add) {
     var selectedElements = this._selectedElements,
@@ -6660,6 +6716,12 @@
     this._eventBus.fire('selection.changed', { oldSelection: oldSelection, newSelection: selectedElements });
   };
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('./Selection').default} Selection
+   */
+
   var MARKER_HOVER = 'hover',
       MARKER_SELECTED = 'selected';
 
@@ -6676,6 +6738,7 @@
    *
    * @param {Canvas} canvas
    * @param {EventBus} eventBus
+   * @param {Selection} selection
    */
   function SelectionVisuals(canvas, eventBus, selection) {
     this._canvas = canvas;
@@ -6781,6 +6844,19 @@
     };
   }
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('./Selection').default} Selection
+   */
+
+  /**
+   * @param {EventBus} eventBus
+   * @param {Selection} selection
+   * @param {Canvas} canvas
+   * @param {ElementRegistry} elementRegistry
+   */
   function SelectionBehavior(eventBus, selection, canvas, elementRegistry) {
 
     // Select elements on create
@@ -6901,9 +6977,8 @@
   /**
    * Util that provides unique IDs.
    *
-   * @class djs.util.IdGenerator
+   * @class
    * @constructor
-   * @memberOf djs.util
    *
    * The ids can be customized via a given prefix and contain a random value to avoid collisions.
    *
@@ -6918,8 +6993,6 @@
   /**
    * Returns a next unique ID.
    *
-   * @method djs.util.IdGenerator#next
-   *
    * @returns {string} the id
    */
   IdGenerator.prototype.next = function() {
@@ -6931,6 +7004,18 @@
 
   var LOW_PRIORITY$1 = 500;
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   *
+   * @typedef {import('./Overlays').Overlay} Overlay
+   * @typedef {import('./Overlays').OverlayAttrs} OverlayAttrs
+   * @typedef {import('./Overlays').OverlayContainer} OverlayContainer
+   * @typedef {import('./Overlays').OverlaysConfig} OverlaysConfig
+   * @typedef {import('./Overlays').OverlaysConfigDefault} OverlaysConfigDefault
+   * @typedef {import('./Overlays').OverlaysFilter} OverlaysFilter
+   */
 
   /**
    * A service that allows users to attach overlays to diagram elements.
@@ -6940,6 +7025,7 @@
    * @example
    *
    * // add a pink badge on the top left of the shape
+   *
    * overlays.add(someShape, {
    *   position: {
    *     top: -5,
@@ -6991,19 +7077,21 @@
    *     }
    * }
    *
-   * @param {Object} config
+   * @param {OverlaysConfig} config
    * @param {EventBus} eventBus
    * @param {Canvas} canvas
    * @param {ElementRegistry} elementRegistry
    */
   function Overlays(config, eventBus, canvas, elementRegistry) {
-
     this._eventBus = eventBus;
     this._canvas = canvas;
     this._elementRegistry = elementRegistry;
 
     this._ids = ids;
 
+    /**
+     * @type {OverlaysConfigDefault}
+     */
     this._overlayDefaults = assign$1({
 
       // no show constraints
@@ -7014,16 +7102,18 @@
     }, config && config.defaults);
 
     /**
-     * Mapping overlayId -> overlay
+     * @type {Map<string, Overlay>}
      */
     this._overlays = {};
 
     /**
-     * Mapping elementId -> overlay container
+     * @type {OverlayContainer[]}
      */
     this._overlayContainers = [];
 
-    // root html element for all overlays
+    /**
+     * @type {HTMLElement}
+     */
     this._overlayRoot = createRoot(canvas.getContainer());
 
     this._init();
@@ -7039,12 +7129,12 @@
 
 
   /**
-   * Returns the overlay with the specified id or a list of overlays
+   * Returns the overlay with the specified ID or a list of overlays
    * for an element with a given type.
    *
    * @example
    *
-   * // return the single overlay with the given id
+   * // return the single overlay with the given ID
    * overlays.get('some-id');
    *
    * // return all overlays for the shape
@@ -7053,16 +7143,12 @@
    * // return all overlays on shape with type 'badge'
    * overlays.get({ element: someShape, type: 'badge' });
    *
-   * // shape can also be specified as id
+   * // shape can also be specified as ID
    * overlays.get({ element: 'element-id', type: 'badge' });
    *
+   * @param {OverlaysFilter} search The filter to be used to find the overlay(s).
    *
-   * @param {Object} search
-   * @param {string} [search.id]
-   * @param {string|djs.model.Base} [search.element]
-   * @param {string} [search.type]
-   *
-   * @return {Object|Array<Object>} the overlay(s)
+   * @return {Overlay|Overlay[]} The overlay(s).
    */
   Overlays.prototype.get = function(search) {
 
@@ -7094,27 +7180,13 @@
   };
 
   /**
-   * Adds a HTML overlay to an element.
+   * Adds an HTML overlay to an element.
    *
-   * @param {string|djs.model.Base}   element   attach overlay to this shape
-   * @param {string}                  [type]    optional type to assign to the overlay
-   * @param {Object}                  overlay   the overlay configuration
+   * @param {Base|string} element The element to add the overlay to.
+   * @param {string} [type] An optional type that can be used to filter.
+   * @param {OverlayAttrs} overlay The overlay.
    *
-   * @param {string|DOMElement}       overlay.html                 html element to use as an overlay
-   * @param {Object}                  [overlay.show]               show configuration
-   * @param {number}                  [overlay.show.minZoom]       minimal zoom level to show the overlay
-   * @param {number}                  [overlay.show.maxZoom]       maximum zoom level to show the overlay
-   * @param {Object}                  overlay.position             where to attach the overlay
-   * @param {number}                  [overlay.position.left]      relative to element bbox left attachment
-   * @param {number}                  [overlay.position.top]       relative to element bbox top attachment
-   * @param {number}                  [overlay.position.bottom]    relative to element bbox bottom attachment
-   * @param {number}                  [overlay.position.right]     relative to element bbox right attachment
-   * @param {boolean|Object}          [overlay.scale=true]         false to preserve the same size regardless of
-   *                                                               diagram zoom
-   * @param {number}                  [overlay.scale.min]
-   * @param {number}                  [overlay.scale.max]
-   *
-   * @return {string}                 id that may be used to reference the overlay for update or removal
+   * @return {string} The overlay's ID that can be used to get or remove it.
    */
   Overlays.prototype.add = function(element, type, overlay) {
 
@@ -7155,11 +7227,11 @@
 
 
   /**
-   * Remove an overlay with the given id or all overlays matching the given filter.
+   * Remove an overlay with the given ID or all overlays matching the given filter.
    *
    * @see Overlays#get for filter options.
    *
-   * @param {string|object} [filter]
+   * @param {OverlaysFilter} filter The filter to be used to find the overlay.
    */
   Overlays.prototype.remove = function(filter) {
 
@@ -7195,19 +7267,32 @@
 
   };
 
+  /**
+   * Checks whether overlays are shown.
+   *
+   * @returns {boolean} Whether overlays are shown.
+   */
   Overlays.prototype.isShown = function() {
     return this._overlayRoot.style.display !== 'none';
   };
 
+  /**
+   * Show all overlays.
+   */
   Overlays.prototype.show = function() {
     setVisible(this._overlayRoot);
   };
 
-
+  /**
+   * Hide all overlays.
+   */
   Overlays.prototype.hide = function() {
     setVisible(this._overlayRoot, false);
   };
 
+  /**
+   * Remove all overlays and their container.
+   */
   Overlays.prototype.clear = function() {
     this._overlays = {};
 
@@ -7583,6 +7668,13 @@
     overlays: [ 'type', Overlays ]
   };
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('../../core/GraphicsFactory').default} GraphicsFactory
+   */
+
   /**
    * Adds change support to the diagram, including
    *
@@ -7652,32 +7744,41 @@
     changeSupport: [ 'type', ChangeSupport ]
   };
 
+  /**
+   * @typedef {import('../core/EventBus').default} EventBus
+   * @typedef {import(./CommandInterceptor).HandlerFunction} HandlerFunction
+   * @typedef {import(./CommandInterceptor).ComposeHandlerFunction} ComposeHandlerFunction
+   */
+
   var DEFAULT_PRIORITY$1 = 1000;
 
   /**
-   * A utility that can be used to plug-in into the command execution for
+   * A utility that can be used to plug into the command execution for
    * extension and/or validation.
    *
+   * @class
+   * @constructor
+   *
    * @param {EventBus} eventBus
    *
    * @example
    *
-   * import inherits from 'inherits-browser';
-   *
    * import CommandInterceptor from 'diagram-js/lib/command/CommandInterceptor';
    *
-   * function CommandLogger(eventBus) {
-   *   CommandInterceptor.call(this, eventBus);
+   * class CommandLogger extends CommandInterceptor {
+   *   constructor(eventBus) {
+   *     super(eventBus);
    *
-   *   this.preExecute(function(event) {
-   *     console.log('command pre-execute', event);
+   *   this.preExecute('shape.create', (event) => {
+   *     console.log('commandStack.shape-create.preExecute', event);
    *   });
    * }
-   *
-   * inherits(CommandLogger, CommandInterceptor);
-   *
    */
   function CommandInterceptor(eventBus) {
+
+    /**
+     * @type {EventBus}
+     */
     this._eventBus = eventBus;
   }
 
@@ -7690,16 +7791,15 @@
   }
 
   /**
-   * Register an interceptor for a command execution
-   *
-   * @param {string|Array<string>} [events] list of commands to register on
-   * @param {string} [hook] command hook, i.e. preExecute, executed to listen on
-   * @param {number} [priority] the priority on which to hook into the execution
-   * @param {Function} handlerFn interceptor to be invoked with (event)
-   * @param {boolean} unwrap if true, unwrap the event and pass (context, command, event) to the
-   *                          listener instead
-   * @param {Object} [that] Pass context (`this`) to the handler function
-   */
+     * Intercept a command during one of the phases.
+     *
+     * @param {string|string[]} [events] One or more commands to intercept.
+     * @param {string} [hook] Phase during which to intercept command.
+     * @param {number} [priority] Priority with which command will be intercepted.
+     * @param {ComposeHandlerFunction|HandlerFunction} handlerFn Callback.
+     * @param {boolean} [unwrap] Whether the event should be unwrapped.
+     * @param {*} [that] `this` value the callback will be called with.
+     */
   CommandInterceptor.prototype.on = function(events, hook, priority, handlerFn, unwrap, that) {
 
     if (isFunction(hook) || isNumber(hook)) {
@@ -7755,24 +7855,19 @@
   ];
 
   /*
-   * Install hook shortcuts
-   *
-   * This will generate the CommandInterceptor#(preExecute|...|reverted) methods
-   * which will in term forward to CommandInterceptor#on.
+   * Add prototype methods for each phase of command execution (e.g. execute,
+   * revert).
    */
   forEach$1(hooks, function(hook) {
 
     /**
-     * {canExecute|preExecute|preExecuted|execute|executed|postExecute|postExecuted|revert|reverted}
-     *
-     * A named hook for plugging into the command execution
+     * Add prototype method for a specific phase of command execution.
      *
-     * @param {string|Array<string>} [events] list of commands to register on
-     * @param {number} [priority] the priority on which to hook into the execution
-     * @param {Function} handlerFn interceptor to be invoked with (event)
-     * @param {boolean} [unwrap=false] if true, unwrap the event and pass (context, command, event) to the
-     *                          listener instead
-     * @param {Object} [that] Pass context (`this`) to the handler function
+     * @param {string|string[]} [events] One or more commands to intercept.
+     * @param {number} [priority] Priority with which command will be intercepted.
+     * @param {ComposeHandlerFunction|HandlerFunction} handlerFn Callback.
+     * @param {boolean} [unwrap] Whether the event should be unwrapped.
+     * @param {*} [that] `this` value the callback will be called with.
      */
     CommandInterceptor.prototype[hook] = function(events, priority, handlerFn, unwrap, that) {
 
@@ -7788,12 +7883,18 @@
     };
   });
 
+  /**
+   * @typedef {import('didi').Injector} Injector
+   *
+   * @typedef {import('../../core/Canvas').default} Canvas
+   */
+
   /**
    * A modeling behavior that ensures we set the correct root element
    * as we undo and redo commands.
    *
    * @param {Canvas} canvas
-   * @param {didi.Injector} injector
+   * @param {Injector} injector
    */
   function RootElementsBehavior(canvas, injector) {
 
@@ -7827,111 +7928,10 @@
     rootElementsBehavior: [ 'type', RootElementsBehavior ]
   };
 
-  var css_escape = {exports: {}};
-
-  /*! https://mths.be/cssescape v1.5.1 by @mathias | MIT license */
-
-  (function (module, exports) {
-  (function(root, factory) {
-  		// https://github.com/umdjs/umd/blob/master/returnExports.js
-  		{
-  			// For Node.js.
-  			module.exports = factory(root);
-  		}
-  	}(typeof commonjsGlobal != 'undefined' ? commonjsGlobal : commonjsGlobal, function(root) {
-
-  		if (root.CSS && root.CSS.escape) {
-  			return root.CSS.escape;
-  		}
-
-  		// https://drafts.csswg.org/cssom/#serialize-an-identifier
-  		var cssEscape = function(value) {
-  			if (arguments.length == 0) {
-  				throw new TypeError('`CSS.escape` requires an argument.');
-  			}
-  			var string = String(value);
-  			var length = string.length;
-  			var index = -1;
-  			var codeUnit;
-  			var result = '';
-  			var firstCodeUnit = string.charCodeAt(0);
-  			while (++index < length) {
-  				codeUnit = string.charCodeAt(index);
-  				// Note: there’s no need to special-case astral symbols, surrogate
-  				// pairs, or lone surrogates.
-
-  				// If the character is NULL (U+0000), then the REPLACEMENT CHARACTER
-  				// (U+FFFD).
-  				if (codeUnit == 0x0000) {
-  					result += '\uFFFD';
-  					continue;
-  				}
-
-  				if (
-  					// If the character is in the range [\1-\1F] (U+0001 to U+001F) or is
-  					// U+007F, […]
-  					(codeUnit >= 0x0001 && codeUnit <= 0x001F) || codeUnit == 0x007F ||
-  					// If the character is the first character and is in the range [0-9]
-  					// (U+0030 to U+0039), […]
-  					(index == 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
-  					// If the character is the second character and is in the range [0-9]
-  					// (U+0030 to U+0039) and the first character is a `-` (U+002D), […]
-  					(
-  						index == 1 &&
-  						codeUnit >= 0x0030 && codeUnit <= 0x0039 &&
-  						firstCodeUnit == 0x002D
-  					)
-  				) {
-  					// https://drafts.csswg.org/cssom/#escape-a-character-as-code-point
-  					result += '\\' + codeUnit.toString(16) + ' ';
-  					continue;
-  				}
-
-  				if (
-  					// If the character is the first character and is a `-` (U+002D), and
-  					// there is no second character, […]
-  					index == 0 &&
-  					length == 1 &&
-  					codeUnit == 0x002D
-  				) {
-  					result += '\\' + string.charAt(index);
-  					continue;
-  				}
-
-  				// If the character is not handled by one of the above rules and is
-  				// greater than or equal to U+0080, is `-` (U+002D) or `_` (U+005F), or
-  				// is in one of the ranges [0-9] (U+0030 to U+0039), [A-Z] (U+0041 to
-  				// U+005A), or [a-z] (U+0061 to U+007A), […]
-  				if (
-  					codeUnit >= 0x0080 ||
-  					codeUnit == 0x002D ||
-  					codeUnit == 0x005F ||
-  					codeUnit >= 0x0030 && codeUnit <= 0x0039 ||
-  					codeUnit >= 0x0041 && codeUnit <= 0x005A ||
-  					codeUnit >= 0x0061 && codeUnit <= 0x007A
-  				) {
-  					// the character itself
-  					result += string.charAt(index);
-  					continue;
-  				}
-
-  				// Otherwise, the escaped character.
-  				// https://drafts.csswg.org/cssom/#escape-a-character
-  				result += '\\' + string.charAt(index);
-
-  			}
-  			return result;
-  		};
-
-  		if (!root.CSS) {
-  			root.CSS = {};
-  		}
-
-  		root.CSS.escape = cssEscape;
-  		return cssEscape;
-
-  	}));
-  } (css_escape));
+  /**
+   * @param {string} str
+   * @returns {string}
+   */
 
   var HTML_ESCAPE_MAP = {
     '&': '&amp;',
@@ -9066,6 +9066,11 @@
     return value;
   }
 
+  /**
+   * @typedef {import('../core/EventBus').default} EventBus
+   * @typedef {import('./Styles').default} Styles
+   */
+
   // apply default renderer with lowest possible priority
   // so that it only kicks in if noone else could render
   var DEFAULT_RENDER_PRIORITY = 1;
@@ -9183,9 +9188,9 @@
     /**
      * Builds a style definition from a className, a list of traits and an object of additional attributes.
      *
-     * @param  {string} className
-     * @param  {Array<string>} traits
-     * @param  {Object} additionalAttrs
+     * @param {string} className
+     * @param {Array<string>} traits
+     * @param {Object} additionalAttrs
      *
      * @return {Object} the style defintion
      */
@@ -9198,8 +9203,8 @@
     /**
      * Builds a style definition from a list of traits and an object of additional attributes.
      *
-     * @param  {Array<string>} traits
-     * @param  {Object} additionalAttrs
+     * @param {Array<string>} traits
+     * @param {Object} additionalAttrs
      *
      * @return {Object} the style defintion
      */
@@ -9236,8 +9241,8 @@
   /**
    * Failsafe remove an element from a collection
    *
-   * @param  {Array<Object>} [collection]
-   * @param  {Object} [element]
+   * @param {Array<Object>} [collection]
+   * @param {Object} [element]
    *
    * @return {number} the previous index of the element
    */
@@ -9307,6 +9312,27 @@
     }
   }
 
+  /**
+   * @typedef {import('.').ConnectionLike} ConnectionLike
+   * @typedef {import('.').RootLike} RootLike
+   * @typedef {import('.').ShapeLike} ShapeLike
+   *
+   * @typedef {import('./Canvas').CanvasConfig} CanvasConfig
+   * @typedef {import('./Canvas').CanvasLayer} CanvasLayer
+   * @typedef {import('./Canvas').CanvasLayers} CanvasLayers
+   * @typedef {import('./Canvas').CanvasPlane} CanvasPlane
+   * @typedef {import('./Canvas').CanvasViewbox} CanvasViewbox
+   *
+   * @typedef {import('./ElementRegistry').default} ElementRegistry
+   * @typedef {import('./EventBus').default} EventBus
+   * @typedef {import('./GraphicsFactory').default} GraphicsFactory
+   *
+   * @typedef {import('../util/Types').Dimensions} Dimensions
+   * @typedef {import('../util/Types').Point} Point
+   * @typedef {import('../util/Types').Rect} Rect
+   * @typedef {import('../util/Types').RectTRBL} RectTRBL
+   */
+
   function round(number, resolution) {
     return Math.round(number * resolution) / resolution;
   }
@@ -9327,7 +9353,8 @@
    * Creates a HTML container element for a SVG element with
    * the given configuration
    *
-   * @param  {Object} options
+   * @param {CanvasConfig} options
+   *
    * @return {HTMLElement} the container element
    */
   function createContainer(options) {
@@ -9387,21 +9414,34 @@
    *
    * @emits Canvas#canvas.init
    *
-   * @param {Object} config
+   * @param {CanvasConfig|null} config
    * @param {EventBus} eventBus
    * @param {GraphicsFactory} graphicsFactory
    * @param {ElementRegistry} elementRegistry
    */
   function Canvas(config, eventBus, graphicsFactory, elementRegistry) {
-
     this._eventBus = eventBus;
     this._elementRegistry = elementRegistry;
     this._graphicsFactory = graphicsFactory;
 
+    /**
+     * @type {number}
+     */
     this._rootsIdx = 0;
 
+    /**
+     * @type {CanvasLayers}
+     */
     this._layers = {};
+
+    /**
+     * @type {CanvasPlane[]}
+     */
     this._planes = [];
+
+    /**
+     * @type {RootLike|null}
+     */
     this._rootElement = null;
 
     this._init(config || {});
@@ -9426,6 +9466,8 @@
    *    ...
    *   </svg>
    * </div>
+   *
+   * @param {CanvasConfig} config
    */
   Canvas.prototype._init = function(config) {
 
@@ -9447,7 +9489,7 @@
       this._viewboxChanged = debounce(bind$2(this._viewboxChanged, this), 300);
     }
 
-    eventBus.on('diagram.init', function() {
+    eventBus.on('diagram.init', () => {
 
       /**
        * An event indicating that the canvas is ready to be drawn on.
@@ -9465,7 +9507,7 @@
         viewport: viewport
       });
 
-    }, this);
+    });
 
     // reset viewbox on shape changes to
     // recompute the viewbox
@@ -9476,15 +9518,15 @@
       'connection.removed',
       'elements.changed',
       'root.set'
-    ], function() {
+    ], () => {
       delete this._cachedViewbox;
-    }, this);
+    });
 
     eventBus.on('diagram.destroy', 500, this._destroy, this);
     eventBus.on('diagram.clear', 500, this._clear, this);
   };
 
-  Canvas.prototype._destroy = function(emit) {
+  Canvas.prototype._destroy = function() {
     this._eventBus.fire('canvas.destroy', {
       svg: this._svg,
       viewport: this._viewport
@@ -9531,7 +9573,7 @@
    * Returns the default layer on which
    * all elements are drawn.
    *
-   * @returns {SVGElement}
+   * @return {SVGElement}  The SVG element of the layer.
    */
   Canvas.prototype.getDefaultLayer = function() {
     return this.getLayer(BASE_LAYER, PLANE_LAYER_INDEX);
@@ -9547,10 +9589,10 @@
    * A layer with a certain index is always created above all
    * existing layers with the same index.
    *
-   * @param {string} name
-   * @param {number} index
+   * @param {string} name The name of the layer.
+   * @param {number} [index] The index of the layer.
    *
-   * @returns {SVGElement}
+   * @return {SVGElement} The SVG element of the layer.
    */
   Canvas.prototype.getLayer = function(name, index) {
 
@@ -9579,8 +9621,9 @@
    *
    * This is used to determine the node a layer should be inserted at.
    *
-   * @param {Number} index
-   * @returns {Number}
+   * @param {number} index
+   *
+   * @return {number}
    */
   Canvas.prototype._getChildIndex = function(index) {
     return reduce(this._layers, function(childIndex, layer) {
@@ -9598,7 +9641,7 @@
    * @param {string} name
    * @param {number} [index=0]
    *
-   * @return {Object} layer descriptor with { index, group: SVGGroup }
+   * @return {CanvasLayer}
    */
   Canvas.prototype._createLayer = function(name, index) {
 
@@ -9619,8 +9662,9 @@
   /**
    * Shows a given layer.
    *
-   * @param {String} layer
-   * @returns {SVGElement}
+   * @param {string} layer The name of the layer.
+   *
+   * @return {SVGElement} The SVG element of the layer.
    */
   Canvas.prototype.showLayer = function(name) {
 
@@ -9654,8 +9698,9 @@
   /**
    * Hides a given layer.
    *
-   * @param {String} layer
-   * @returns {SVGElement}
+   * @param {string} layer The name of the layer.
+   *
+   * @return {SVGElement} The SVG element of the layer.
    */
   Canvas.prototype.hideLayer = function(name) {
 
@@ -9697,7 +9742,7 @@
   /**
    * Returns the currently active layer. Can be null.
    *
-   * @returns {SVGElement|null}
+   * @return {CanvasLayer|null} The active layer of `null`.
    */
   Canvas.prototype.getActiveLayer = function() {
     const plane = this._findPlaneForRoot(this.getRootElement());
@@ -9713,9 +9758,9 @@
   /**
    * Returns the plane which contains the given element.
    *
-   * @param {string|djs.model.Base} element
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
    *
-   * @return {djs.model.Base} root for element
+   * @return {RootLike|undefined} The root of the element.
    */
   Canvas.prototype.findRoot = function(element) {
     if (typeof element === 'string') {
@@ -9736,7 +9781,7 @@
   /**
    * Return a list of all root elements on the diagram.
    *
-   * @return {djs.model.Root[]}
+   * @return {(RootLike)[]} The list of root elements.
    */
   Canvas.prototype.getRootElements = function() {
     return this._planes.map(function(plane) {
@@ -9755,7 +9800,7 @@
    * Returns the html element that encloses the
    * drawing canvas.
    *
-   * @return {DOMNode}
+   * @return {HTMLElement} The HTML element of the container.
    */
   Canvas.prototype.getContainer = function() {
     return this._container;
@@ -9795,8 +9840,8 @@
      *
      * @event element.marker.update
      * @type {Object}
-     * @property {djs.model.Element} element the shape
-     * @property {Object} gfx the graphical representation of the shape
+     * @property {Base} element the shape
+     * @property {SVGElement} gfx the graphical representation of the shape
      * @property {string} marker
      * @property {boolean} add true if the marker was added, false if it got removed
      */
@@ -9811,14 +9856,15 @@
    * integrate extension into the marker life-cycle, too.
    *
    * @example
+   *
    * canvas.addMarker('foo', 'some-marker');
    *
    * const fooGfx = canvas.getGraphics('foo');
    *
    * fooGfx; // <g class="... some-marker"> ... </g>
    *
-   * @param {string|djs.model.Base} element
-   * @param {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.addMarker = function(element, marker) {
     this._updateMarker(element, marker, true);
@@ -9831,18 +9877,18 @@
    * Fires the element.marker.update event, making it possible to
    * integrate extension into the marker life-cycle, too.
    *
-   * @param  {string|djs.model.Base} element
-   * @param  {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.removeMarker = function(element, marker) {
     this._updateMarker(element, marker, false);
   };
 
   /**
-   * Check the existence of a marker on element.
+   * Check whether an element has a given marker.
    *
-   * @param  {string|djs.model.Base} element
-   * @param  {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.hasMarker = function(element, marker) {
     if (!element.id) {
@@ -9860,8 +9906,8 @@
    * Fires the element.marker.update event, making it possible to
    * integrate extension into the marker life-cycle, too.
    *
-   * @param  {string|djs.model.Base} element
-   * @param  {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.toggleMarker = function(element, marker) {
     if (this.hasMarker(element, marker)) {
@@ -9884,7 +9930,7 @@
    * root elements can be null. This is used for applications that want to manage
    * root elements themselves.
    *
-   * @returns {Object|djs.model.Root|null} rootElement.
+   * @return {RootLike} The current root element.
    */
   Canvas.prototype.getRootElement = function() {
     const rootElement = this._rootElement;
@@ -9900,11 +9946,10 @@
   /**
    * Adds a given root element and returns it.
    *
-   * @param {Object|djs.model.Root} rootElement
+   * @param {ShapeLike} [rootElement] The root element to be added.
    *
-   * @return {Object|djs.model.Root} rootElement
+   * @return {RootLike} The added root element or an implicit root element.
    */
-
   Canvas.prototype.addRootElement = function(rootElement) {
     const idx = this._rootsIdx++;
 
@@ -9935,11 +9980,11 @@
   };
 
   /**
-   * Removes a given rootElement and returns it.
+   * Removes a given root element and returns it.
    *
-   * @param {djs.model.Root|String} rootElement
+   * @param {ShapeLike|string} rootElement The root element or its ID.
    *
-   * @return {Object|djs.model.Root} rootElement
+   * @return {ShapeLike|undefined} The removed root element.
    */
   Canvas.prototype.removeRootElement = function(rootElement) {
 
@@ -9973,15 +10018,13 @@
   };
 
 
-  // root element handling //////////////////////
-
   /**
    * Sets a given element as the new root element for the canvas
    * and returns the new root element.
    *
-   * @param {Object|djs.model.Root} rootElement
+   * @param {RootLike} rootElement The root element to be set.
    *
-   * @return {Object|djs.model.Root} new root element
+   * @return {RootLike} The set root element.
    */
   Canvas.prototype.setRootElement = function(rootElement, override) {
 
@@ -10068,8 +10111,6 @@
     this._eventBus.fire('root.set', { element: rootElement });
   };
 
-  // add functionality //////////////////////
-
   Canvas.prototype._ensureValid = function(type, element) {
     if (!element.id) {
       throw new Error('element must have an id');
@@ -10110,11 +10151,11 @@
    * Extensions may hook into these events to perform their magic.
    *
    * @param {string} type
-   * @param {Object|djs.model.Base} element
-   * @param {Object|djs.model.Base} [parent]
+   * @param {ConnectionLike|ShapeLike} element
+   * @param {ShapeLike} [parent]
    * @param {number} [parentIndex]
    *
-   * @return {Object|djs.model.Base} the added element
+   * @return {ConnectionLike|ShapeLike} The added element.
    */
   Canvas.prototype._addElement = function(type, element, parent, parentIndex) {
 
@@ -10143,26 +10184,26 @@
   };
 
   /**
-   * Adds a shape to the canvas
+   * Adds a shape to the canvas.
    *
-   * @param {Object|djs.model.Shape} shape to add to the diagram
-   * @param {djs.model.Base} [parent]
-   * @param {number} [parentIndex]
+   * @param {ShapeLike} shape The shape to be added
+   * @param {ShapeLike} [parent] The shape's parent.
+   * @param {number} [parentIndex] The index at which to add the shape to the parent's children.
    *
-   * @return {djs.model.Shape} the added shape
+   * @return {ShapeLike} The added shape.
    */
   Canvas.prototype.addShape = function(shape, parent, parentIndex) {
     return this._addElement('shape', shape, parent, parentIndex);
   };
 
   /**
-   * Adds a connection to the canvas
+   * Adds a connection to the canvas.
    *
-   * @param {Object|djs.model.Connection} connection to add to the diagram
-   * @param {djs.model.Base} [parent]
-   * @param {number} [parentIndex]
+   * @param {ConnectionLike} connection The connection to be added.
+   * @param {ShapeLike} [parent] The connection's parent.
+   * @param {number} [parentIndex] The index at which to add the connection to the parent's children.
    *
-   * @return {djs.model.Connection} the added connection
+   * @return {ConnectionLike} The added connection.
    */
   Canvas.prototype.addConnection = function(connection, parent, parentIndex) {
     return this._addElement('connection', connection, parent, parentIndex);
@@ -10203,11 +10244,14 @@
 
 
   /**
-   * Removes a shape from the canvas
+   * Removes a shape from the canvas.
    *
-   * @param {string|djs.model.Shape} shape or shape id to be removed
+   * @fires ShapeRemoveEvent
+   * @fires ShapeRemovedEvent
    *
-   * @return {djs.model.Shape} the removed shape
+   * @param {ShapeLike|string} shape The shape or its ID.
+   *
+   * @return {ShapeLike} The removed shape.
    */
   Canvas.prototype.removeShape = function(shape) {
 
@@ -10216,10 +10260,10 @@
      *
      * @memberOf Canvas
      *
-     * @event shape.remove
+     * @event ShapeRemoveEvent
      * @type {Object}
-     * @property {djs.model.Shape} element the shape descriptor
-     * @property {Object} gfx the graphical representation of the shape
+     * @property {ShapeLike} element The shape.
+     * @property {SVGElement} gfx The graphical element.
      */
 
     /**
@@ -10227,21 +10271,24 @@
      *
      * @memberOf Canvas
      *
-     * @event shape.removed
+     * @event ShapeRemoved
      * @type {Object}
-     * @property {djs.model.Shape} element the shape descriptor
-     * @property {Object} gfx the graphical representation of the shape
+     * @property {ShapeLike} element The shape.
+     * @property {SVGElement} gfx The graphical element.
      */
     return this._removeElement(shape, 'shape');
   };
 
 
   /**
-   * Removes a connection from the canvas
+   * Removes a connection from the canvas.
+   *
+   * @fires ConnectionRemoveEvent
+   * @fires ConnectionRemovedEvent
    *
-   * @param {string|djs.model.Connection} connection or connection id to be removed
+   * @param {ConnectionLike|string} connection The connection or its ID.
    *
-   * @return {djs.model.Connection} the removed connection
+   * @return {ConnectionLike} The removed connection.
    */
   Canvas.prototype.removeConnection = function(connection) {
 
@@ -10250,10 +10297,10 @@
      *
      * @memberOf Canvas
      *
-     * @event connection.remove
+     * @event ConnectionRemoveEvent
      * @type {Object}
-     * @property {djs.model.Connection} element the connection descriptor
-     * @property {Object} gfx the graphical representation of the connection
+     * @property {ConnectionLike} element The connection.
+     * @property {SVGElement} gfx The graphical element.
      */
 
     /**
@@ -10263,20 +10310,20 @@
      *
      * @event connection.removed
      * @type {Object}
-     * @property {djs.model.Connection} element the connection descriptor
-     * @property {Object} gfx the graphical representation of the connection
+     * @property {ConnectionLike} element The connection.
+     * @property {SVGElement} gfx The graphical element.
      */
     return this._removeElement(connection, 'connection');
   };
 
 
   /**
-   * Return the graphical object underlaying a certain diagram element
+   * Returns the graphical element of an element.
    *
-   * @param {string|djs.model.Base} element descriptor of the element
-   * @param {boolean} [secondary=false] whether to return the secondary connected element
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {boolean} [secondary=false] Whether to return the secondary graphical element.
    *
-   * @return {SVGElement}
+   * @return {SVGElement} The graphical element.
    */
   Canvas.prototype.getGraphics = function(element, secondary) {
     return this._elementRegistry.getGraphics(element, secondary);
@@ -10348,13 +10395,9 @@
    *   height: zoomedAndScrolledViewbox.outer.height
    * });
    *
-   * @param  {Object} [box] the new view box to set
-   * @param  {number} box.x the top left X coordinate of the canvas visible in view box
-   * @param  {number} box.y the top left Y coordinate of the canvas visible in view box
-   * @param  {number} box.width the visible width
-   * @param  {number} box.height
+   * @param {Rect} [box] The viewbox to be set.
    *
-   * @return {Object} the current view box
+   * @return {CanvasViewbox} The set viewbox.
    */
   Canvas.prototype.viewbox = function(box) {
 
@@ -10423,10 +10466,9 @@
   /**
    * Gets or sets the scroll of the canvas.
    *
-   * @param {Object} [delta] the new scroll to apply.
+   * @param {Point} [delta] The scroll to be set.
    *
-   * @param {number} [delta.dx]
-   * @param {number} [delta.dy]
+   * @return {Point}
    */
   Canvas.prototype.scroll = function(delta) {
 
@@ -10450,9 +10492,8 @@
    * Scrolls the viewbox to contain the given element.
    * Optionally specify a padding to be applied to the edges.
    *
-   * @param {Object|String} [element] the element to scroll to.
-   * @param {Object|Number} [padding=100] the padding to be applied. Can also specify top, bottom, left and right.
-   *
+   * @param {ShapeLike|ConnectionLike|string} element The element to scroll to or its ID.
+   * @param {RectTRBL|number} [padding=100] The padding to be applied. Can also specify top, bottom, left and right.
    */
   Canvas.prototype.scrollToElement = function(element, padding) {
     let defaultPadding = 100;
@@ -10520,17 +10561,17 @@
   };
 
   /**
-   * Gets or sets the current zoom of the canvas, optionally zooming
-   * to the specified position.
+   * Gets or sets the current zoom of the canvas, optionally zooming to the
+   * specified position.
    *
-   * The getter may return a cached zoom level. Call it with `false` as
-   * the first argument to force recomputation of the current level.
+   * The getter may return a cached zoom level. Call it with `false` as the first
+   * argument to force recomputation of the current level.
    *
-   * @param {string|number} [newScale] the new zoom level, either a number, i.e. 0.9,
-   *                                   or `fit-viewport` to adjust the size to fit the current viewport
-   * @param {string|Point} [center] the reference point { x: .., y: ..} to zoom to, 'auto' to zoom into mid or null
+   * @param {number|string} [newScale] The new zoom level, either a number,
+   * i.e. 0.9, or `fit-viewport` to adjust the size to fit the current viewport.
+   * @param {Point} [center] The reference point { x: ..., y: ...} to zoom to.
    *
-   * @return {number} the current scale
+   * @return {number} The set zoom level.
    */
   Canvas.prototype.zoom = function(newScale, center) {
 
@@ -10653,9 +10694,9 @@
 
 
   /**
-   * Returns the size of the canvas
+   * Returns the size of the canvas.
    *
-   * @return {Dimensions}
+   * @return {Dimensions} The size of the canvas.
    */
   Canvas.prototype.getSize = function() {
     return {
@@ -10666,14 +10707,14 @@
 
 
   /**
-   * Return the absolute bounding box for the given element
+   * Returns the absolute bounding box of an element.
+   *
+   * The absolute bounding box may be used to display overlays in the callers
+   * (browser) coordinate system rather than the zoomed in/out canvas coordinates.
    *
-   * The absolute bounding box may be used to display overlays in the
-   * callers (browser) coordinate system rather than the zoomed in/out
-   * canvas coordinates.
+   * @param {ShapeLike|ConnectionLike} element The element.
    *
-   * @param  {ElementDescriptor} element
-   * @return {Bounds} the absolute bounding box
+   * @return {Rect} The element's absolute bounding box.
    */
   Canvas.prototype.getAbsoluteBBox = function(element) {
     const vbox = this.viewbox();
@@ -10708,8 +10749,7 @@
   };
 
   /**
-   * Fires an event in order other modules can react to the
-   * canvas resizing
+   * Fires an event so other modules can react to the canvas resizing.
    */
   Canvas.prototype.resized = function() {
 
@@ -10721,11 +10761,21 @@
 
   var ELEMENT_ID = 'data-element-id';
 
+  /**
+   * @typedef {import('.').ElementLike} ElementLike
+   *
+   * @typedef {import('./EventBus').default} EventBus
+   *
+   * @typedef {import('./ElementRegistry').ElementRegistryCallback} ElementRegistryCallback
+   */
 
   /**
+   * A registry that keeps track of all shapes in the diagram.
+   *
    * @class
+   * @constructor
    *
-   * A registry that keeps track of all shapes in the diagram.
+   * @param {EventBus} eventBus
    */
   function ElementRegistry(eventBus) {
     this._elements = {};
@@ -10736,11 +10786,11 @@
   ElementRegistry.$inject = [ 'eventBus' ];
 
   /**
-   * Register a pair of (element, gfx, (secondaryGfx)).
+   * Add an element and its graphical representation(s) to the registry.
    *
-   * @param {djs.model.Base} element
-   * @param {SVGElement} gfx
-   * @param {SVGElement} [secondaryGfx] optional other element to register, too
+   * @param {ElementLike} element The element to be added.
+   * @param {SVGElement} gfx The primary graphical representation.
+   * @param {SVGElement} [secondaryGfx] The secondary graphical representation.
    */
   ElementRegistry.prototype.add = function(element, gfx, secondaryGfx) {
 
@@ -10759,9 +10809,9 @@
   };
 
   /**
-   * Removes an element from the registry.
+   * Remove an element from the registry.
    *
-   * @param {string|djs.model.Base} element
+   * @param {ElementLike|string} element
    */
   ElementRegistry.prototype.remove = function(element) {
     var elements = this._elements,
@@ -10782,10 +10832,10 @@
   };
 
   /**
-   * Update the id of an element
+   * Update an elements ID.
    *
-   * @param {string|djs.model.Base} element
-   * @param {string} newId
+   * @param {ElementLike|string} element The element or its ID.
+   * @param {string} newId The new ID.
    */
   ElementRegistry.prototype.updateId = function(element, newId) {
 
@@ -10811,11 +10861,11 @@
   };
 
   /**
-   * Update the graphics of an element
+   * Update the graphical representation of an element.
    *
-   * @param {string|djs.model.Base} element
-   * @param {SVGElement} gfx
-   * @param {boolean} [secondary=false] whether to update the secondary connected element
+   * @param {ElementLike|string} element The element or its ID.
+   * @param {SVGElement} gfx The new graphical representation.
+   * @param {boolean} [secondary=false] Whether to update the secondary graphical representation.
    */
   ElementRegistry.prototype.updateGraphics = function(filter, gfx, secondary) {
     var id = filter.id || filter;
@@ -10836,17 +10886,17 @@
   };
 
   /**
-   * Return the model element for a given id or graphics.
+   * Get the element with the given ID or graphical representation.
    *
    * @example
    *
    * elementRegistry.get('SomeElementId_1');
-   * elementRegistry.get(gfx);
    *
+   * elementRegistry.get(gfx);
    *
-   * @param {string|SVGElement} filter for selecting the element
+   * @param {string|SVGElement} filter The elements ID or graphical representation.
    *
-   * @return {djs.model.Base}
+   * @return {ElementLike|undefined} The element.
    */
   ElementRegistry.prototype.get = function(filter) {
     var id;
@@ -10864,9 +10914,9 @@
   /**
    * Return all elements that match a given filter function.
    *
-   * @param {Function} fn
+   * @param {ElementRegistryCallback} fn The filter function.
    *
-   * @return {Array<djs.model.Base>}
+   * @return {ElementLike[]} The matching elements.
    */
   ElementRegistry.prototype.filter = function(fn) {
 
@@ -10882,11 +10932,11 @@
   };
 
   /**
-   * Return the first element that satisfies the provided testing function.
+   * Return the first element that matches the given filter function.
    *
-   * @param {Function} fn
+   * @param {Function} fn The filter function.
    *
-   * @return {djs.model.Base}
+   * @return {ElementLike|undefined} The matching element.
    */
   ElementRegistry.prototype.find = function(fn) {
     var map = this._elements,
@@ -10905,18 +10955,18 @@
   };
 
   /**
-   * Return all rendered model elements.
+   * Get all elements.
    *
-   * @return {Array<djs.model.Base>}
+   * @return {ElementLike[]} All elements.
    */
   ElementRegistry.prototype.getAll = function() {
     return this.filter(function(e) { return e; });
   };
 
   /**
-   * Iterate over all diagram elements.
+   * Execute a given function for each element.
    *
-   * @param {Function} fn
+   * @param {Function} fn The function to execute.
    */
   ElementRegistry.prototype.forEach = function(fn) {
 
@@ -10932,19 +10982,20 @@
   };
 
   /**
-   * Return the graphical representation of an element or its id.
+   * Return the graphical representation of an element.
    *
    * @example
+   *
    * elementRegistry.getGraphics('SomeElementId_1');
+   *
    * elementRegistry.getGraphics(rootElement); // <g ...>
    *
    * elementRegistry.getGraphics(rootElement, true); // <svg ...>
    *
+   * @param {ElementLike|string} filter The element or its ID.
+   * @param {boolean} [secondary=false] Whether to return the secondary graphical representation.
    *
-   * @param {string|djs.model.Base} filter
-   * @param {boolean} [secondary=false] whether to return the secondary connected element
-   *
-   * @return {SVGElement}
+   * @return {SVGElement} The graphical representation.
    */
   ElementRegistry.prototype.getGraphics = function(filter, secondary) {
     var id = filter.id || filter;
@@ -10954,12 +11005,11 @@
   };
 
   /**
-   * Validate the suitability of the given id and signals a problem
-   * with an exception.
+   * Validate an ID and throw an error if invalid.
    *
    * @param {string} id
    *
-   * @throws {Error} if id is empty or already assigned
+   * @throws {Error} Error indicating that the ID is invalid or already assigned.
    */
   ElementRegistry.prototype._validateId = function(id) {
     if (!id) {
@@ -11299,14 +11349,6 @@
       outgoingRefs = new Refs({ name: 'outgoing', collection: true }, { name: 'source' }),
       incomingRefs = new Refs({ name: 'incoming', collection: true }, { name: 'target' });
 
-  /**
-   * @namespace djs.model
-   */
-
-  /**
-   * @memberOf djs.model
-   */
-
   /**
    * The basic graphical representation
    *
@@ -11503,21 +11545,47 @@
   };
 
   /**
-   * Creates a new model element of the specified type
+   * Creates a model element of the given type.
    *
    * @method create
    *
    * @example
    *
-   * var shape1 = Model.create('shape', { x: 10, y: 10, width: 100, height: 100 });
-   * var shape2 = Model.create('shape', { x: 210, y: 210, width: 100, height: 100 });
+   * import * as Model from 'diagram-js/lib/model';
+   *
+   * const connection = Model.create('connection', {
+   *   waypoints: [
+   *     { x: 100, y: 100 },
+   *     { x: 200, y: 100 }
+   *   ]
+   * });
+   *
+   * const label = Model.create('label', {
+   *   x: 100,
+   *   y: 100,
+   *   width: 100,
+   *   height: 100,
+   *   labelTarget: shape
+   * });
+   *
+   * const root = Model.create('root', {
+   *   x: 100,
+   *   y: 100,
+   *   width: 100,
+   *   height: 100
+   * });
    *
-   * var connection = Model.create('connection', { waypoints: [ { x: 110, y: 55 }, {x: 210, y: 55 } ] });
+   * const shape = Model.create('shape', {
+   *   x: 100,
+   *   y: 100,
+   *   width: 100,
+   *   height: 100
+   * });
    *
-   * @param  {string} type lower-cased model name
-   * @param  {Object} attrs attributes to initialize the new model instance with
+   * @param {string} type The type of model element to be created.
+   * @param {Object} attrs Attributes to create the model element with.
    *
-   * @return {Base} the new model instance
+   * @return {Connection|Label|Root|Shape} The created model element.
    */
   function create(type, attrs) {
     var Type = types$7[type];
@@ -11528,36 +11596,78 @@
   }
 
   /**
-   * A factory for diagram-js shapes
+   * @typedef {import('../model/index').Base} Base
+   * @typedef {import('../model/index').Connection} Connection
+   * @typedef {import('../model/index').Label} Label
+   * @typedef {import('../model/index').Root} Root
+   * @typedef {import('../model/index').Shape} Shape
+   * @typedef {import('../model/index').ModelAttrsConnection} ModelAttrsConnection
+   * @typedef {import('../model/index').ModelAttrsLabel} ModelAttrsLabel
+   * @typedef {import('../model/index').ModelAttrsRoot} ModelAttrsRoot
+   * @typedef {import('../model/index').ModelAttrsShape} ModelAttrsShape
+   */
+
+  /**
+   * A factory for model elements.
+   *
+   * @class
+   * @constructor
    */
   function ElementFactory() {
     this._uid = 12;
   }
 
-
+  /**
+   * Create a root element.
+   *
+   * @param {ModelAttrsRoot} attrs The attributes of the root element to be created.
+   *
+   * @return {Root} The created root element.
+   */
   ElementFactory.prototype.createRoot = function(attrs) {
     return this.create('root', attrs);
   };
 
+  /**
+   * Create a label.
+   *
+   * @param {ModelAttrsLabel} attrs The attributes of the label to be created.
+   *
+   * @return {Label} The created label.
+   */
   ElementFactory.prototype.createLabel = function(attrs) {
     return this.create('label', attrs);
   };
 
+  /**
+   * Create a shape.
+   *
+   * @param {ModelAttrsShape} attrs The attributes of the shape to be created.
+   *
+   * @return {Shape} The created shape.
+   */
   ElementFactory.prototype.createShape = function(attrs) {
     return this.create('shape', attrs);
   };
 
+  /**
+   * Create a connection.
+   *
+   * @param {ModelAttrsConnection} attrs The attributes of the connection to be created.
+   *
+   * @return {Connection} The created connection.
+   */
   ElementFactory.prototype.createConnection = function(attrs) {
     return this.create('connection', attrs);
   };
 
   /**
-   * Create a model element with the given type and
-   * a number of pre-set attributes.
+   * Create a model element of the given type with the given attributes.
    *
-   * @param  {string} type
-   * @param  {Object} attrs
-   * @return {djs.model.Base} the newly created model instance
+   * @param {string} type The type of the model element.
+   * @param {Object} attrs The attributes of the model element.
+   *
+   * @return {Connection|Label|Root|Shape} The created model element.
    */
   ElementFactory.prototype.create = function(type, attrs) {
 
@@ -11576,6 +11686,16 @@
 
   var slice = Array.prototype.slice;
 
+  /**
+   * @typedef {import('./EventBus').Event} Event
+   * @typedef {import('./EventBus').EventCallback} EventCallback
+   *
+   * @typedef {Object} EventListener
+   * @property {Function} callback
+   * @property {EventListener|null} next
+   * @property {number} priority
+   */
+
   /**
    * A general purpose event bus.
    *
@@ -11680,10 +11800,10 @@
    *
    * Returning anything but `undefined` from a listener will stop the listener propagation.
    *
-   * @param {string|Array<string>} events
-   * @param {number} [priority=1000] the priority in which this listener is called, larger is higher
-   * @param {Function} callback
-   * @param {Object} [that] Pass context (`this`) to the callback
+   * @param {string|string[]} events The event(s) to listen to.
+   * @param {number} [priority=1000] The priority with which to listen.
+   * @param {EventCallback} callback The callback.
+   * @param {*} [that] Value of `this` the callback will be called with.
    */
   EventBus.prototype.on = function(events, priority, callback, that) {
 
@@ -11723,12 +11843,12 @@
 
 
   /**
-   * Register an event listener that is executed only once.
+   * Register an event listener that is called only once.
    *
-   * @param {string} event the event name to register for
-   * @param {number} [priority=1000] the priority in which this listener is called, larger is higher
-   * @param {Function} callback the callback to execute
-   * @param {Object} [that] Pass context (`this`) to the callback
+   * @param {string} event The event to listen to.
+   * @param {number} [priority=1000] The priority with which to listen.
+   * @param {EventCallback} callback The callback.
+   * @param {*} [that] Value of `this` the callback will be called with.
    */
   EventBus.prototype.once = function(event, priority, callback, that) {
     var self = this;
@@ -11767,8 +11887,8 @@
    *
    * If no callback is given, all listeners for a given event name are being removed.
    *
-   * @param {string|Array<string>} events
-   * @param {Function} [callback]
+   * @param {string|string[]} events The events.
+   * @param {EventCallback} [callback] The callback.
    */
   EventBus.prototype.off = function(events, callback) {
 
@@ -11784,11 +11904,11 @@
 
 
   /**
-   * Create an EventBus event.
+   * Create an event recognized be the event bus.
    *
-   * @param {Object} data
+   * @param {Object} data Event data.
    *
-   * @return {Object} event, recognized by the eventBus
+   * @return {Event} An event that will be recognized by the event bus.
    */
   EventBus.prototype.createEvent = function(data) {
     var event = new InternalEvent();
@@ -11800,7 +11920,7 @@
 
 
   /**
-   * Fires a named event.
+   * Fires an event.
    *
    * @example
    *
@@ -11822,12 +11942,11 @@
    *
    * events.fire({ type: 'foo' }, 'I am bar!');
    *
-   * @param {string} [name] the optional event name
-   * @param {Object} [event] the event object
-   * @param {...Object} additional arguments to be passed to the callback functions
+   * @param {string} [type] The event type.
+   * @param {Object} [data] The event or event data.
+   * @param {...*} additional Additional arguments the callback will be called with.
    *
-   * @return {boolean} the events return value, if specified or false if the
-   *                   default action was prevented by listeners
+   * @return {*} The return value. Will be set to `false` if the default was prevented.
    */
   EventBus.prototype.fire = function(type, data) {
     var event,
@@ -11892,7 +12011,13 @@
     return returnValue;
   };
 
-
+  /**
+   * Handle an error by firing an event.
+   *
+   * @param {Error} error The error to be handled.
+   *
+   * @return {boolean} Whether the error was handled.
+   */
   EventBus.prototype.handleError = function(error) {
     return this.fire('error', { error: error }) === false;
   };
@@ -11955,7 +12080,7 @@
     return returnValue;
   };
 
-  /*
+  /**
    * Add new listener with a certain priority to the list
    * of listeners (for the given event).
    *
@@ -11969,7 +12094,7 @@
    *    * after: [ 1500, 1500, (new=1300), 1000, 1000, (new=1000) ]
    *
    * @param {string} event
-   * @param {Object} listener { priority, callback }
+   * @param {EventListener} listener
    */
   EventBus.prototype._addListener = function(event, newListener) {
 
@@ -12075,9 +12200,9 @@
    * Invoke function. Be fast...
    *
    * @param {Function} fn
-   * @param {Array<Object>} args
+   * @param {*[]} args
    *
-   * @return {Any}
+   * @return {*}
    */
   function invokeFunction(fn, args) {
     return fn.apply(null, args);
@@ -12091,11 +12216,11 @@
    */
 
   /**
-   * Returns the visual part of a diagram element
+   * Returns the visual part of a diagram element.
    *
-   * @param {Snap<SVGElement>} gfx
+   * @param {SVGElement} gfx
    *
-   * @return {Snap<SVGElement>}
+   * @return {SVGElement}
    */
   function getVisual(gfx) {
     return gfx.childNodes[0];
@@ -12104,15 +12229,28 @@
   /**
    * Returns the children for a given diagram element.
    *
-   * @param {Snap<SVGElement>} gfx
-   * @return {Snap<SVGElement>}
+   * @param {SVGElement} gfx
+   * @return {SVGElement}
    */
   function getChildren(gfx) {
     return gfx.parentNode.childNodes[1];
   }
 
   /**
-   * A factory that creates graphical elements
+   * @typedef {import('../model').ModelType} ModelType
+   * @typedef {import('../model').ModelTypeConnection} ModelTypeConnection
+   * @typedef {import('../model').ModelTypeShape} ModelTypeShape
+   *
+   * @typedef {import('.').ConnectionLike} ConnectionLike
+   * @typedef {import('.').ElementLike} ElementLike
+   * @typedef {import('.').ShapeLike} ShapeLike
+   *
+   * @typedef {import('./ElementRegistry').default} ElementRegistry
+   * @typedef {import('./EventBus').default} EventBus
+   */
+
+  /**
+   * A factory that creates graphical elements.
    *
    * @param {EventBus} eventBus
    * @param {ElementRegistry} elementRegistry
@@ -12180,7 +12318,7 @@
    * </g>
    *
    * @param {string} type the type of the element, i.e. shape | connection
-   * @param {SVGElement} [childrenGfx]
+   * @param {SVGElement} childrenGfx
    * @param {number} [parentIndex] position to create container in parent
    * @param {boolean} [isFrame] is frame element
    *
@@ -12218,11 +12356,25 @@
     return gfx;
   };
 
+  /**
+   * Create a graphical element.
+   *
+   * @param {ModelType} type The type of the element.
+   * @param {ElementLike} element The element.
+   * @param {number} [parentIndex] The index at which to add the graphical element to its parent's children.
+   *
+   * @return {SVGElement} The graphical element.
+   */
   GraphicsFactory.prototype.create = function(type, element, parentIndex) {
     var childrenGfx = this._getChildrenContainer(element.parent);
     return this._createContainer(type, childrenGfx, parentIndex, isFrameElement(element));
   };
 
+  /**
+   * Update the containments of the given elements.
+   *
+   * @param {ElementLike[]} elements The elements.
+   */
   GraphicsFactory.prototype.updateContainments = function(elements) {
 
     var self = this,
@@ -12258,30 +12410,63 @@
     });
   };
 
+  /**
+   * Draw a shape.
+   *
+   * @param {SVGElement} visual The graphical element.
+   * @param {ShapeLike} element The shape.
+   */
   GraphicsFactory.prototype.drawShape = function(visual, element) {
     var eventBus = this._eventBus;
 
     return eventBus.fire('render.shape', { gfx: visual, element: element });
   };
 
+  /**
+   * Get the path of a shape.
+   *
+   * @param {ShapeLike} element The shape.
+   *
+   * @return {string} The path of the shape.
+   */
   GraphicsFactory.prototype.getShapePath = function(element) {
     var eventBus = this._eventBus;
 
     return eventBus.fire('render.getShapePath', element);
   };
 
+  /**
+   * Draw a connection.
+   *
+   * @param {SVGElement} visual The graphical element.
+   * @param {ConnectionLike} element The connection.
+   */
   GraphicsFactory.prototype.drawConnection = function(visual, element) {
     var eventBus = this._eventBus;
 
     return eventBus.fire('render.connection', { gfx: visual, element: element });
   };
 
-  GraphicsFactory.prototype.getConnectionPath = function(waypoints) {
+  /**
+   * Get the path of a connection.
+   *
+   * @param {ConnectionLike} element The connection.
+   *
+   * @return {string} The path of the connection.
+   */
+  GraphicsFactory.prototype.getConnectionPath = function(connection) {
     var eventBus = this._eventBus;
 
-    return eventBus.fire('render.getConnectionPath', waypoints);
+    return eventBus.fire('render.getConnectionPath', connection);
   };
 
+  /**
+   * Update an elements graphical representation.
+   *
+   * @param {ModelTypeShape|ModelTypeConnection} type The type of the element.
+   * @param {ElementLike} element The element.
+   * @param {SVGElement} gfx The graphical representation.
+   */
   GraphicsFactory.prototype.update = function(type, element, gfx) {
 
     // do NOT update root element
@@ -12311,6 +12496,11 @@
     }
   };
 
+  /**
+   * Remove a graphical element.
+   *
+   * @param {ElementLike} element The element.
+   */
   GraphicsFactory.prototype.remove = function(element) {
     var gfx = this._elementRegistry.getGraphics(element);
 
@@ -12344,13 +12534,17 @@
   };
 
   /**
-   * @typedef { import('didi').ModuleDeclaration } Module
+   * @typedef {import('didi').InjectionContext} InjectionContext
+   * @typedef {import('didi').LocalsMap} LocalsMap
+   * @typedef {import('didi').ModuleDeclaration} ModuleDeclaration
+   *
+   * @typedef {import('./Diagram').DiagramOptions} DiagramOptions
    */
 
   /**
    * Bootstrap an injector from a list of modules, instantiating a number of default components
    *
-   * @param {Array<Module>} modules
+   * @param {ModuleDeclaration[]} modules
    *
    * @return {Injector} a injector to use to access the components
    */
@@ -12365,7 +12559,8 @@
   /**
    * Creates an injector from passed options.
    *
-   * @param {Object} options
+   * @param {DiagramOptions} [options]
+   *
    * @return {Injector}
    */
   function createInjector(options) {
@@ -12388,8 +12583,7 @@
    *
    * To register extensions with the diagram, pass them as Array<Module> to the constructor.
    *
-   * @class djs.Diagram
-   * @memberOf djs
+   * @class
    * @constructor
    *
    * @example
@@ -12427,9 +12621,9 @@
    *
    * // 'shape ... was added to the diagram' logged to console
    *
-   * @param {Object} options
-   * @param {Array<Module>} [options.modules] external modules to instantiate with the diagram
-   * @param {Injector} [injector] an (optional) injector to bootstrap the diagram with
+   * @param {DiagramOptions} [options]
+   * @param {ModuleDeclaration[]} [options.modules] External modules to instantiate with the diagram.
+   * @param {Injector} [injector] An (optional) injector to bootstrap the diagram with.
    */
   function Diagram(options, injector) {
 
@@ -12439,22 +12633,23 @@
     // API
 
     /**
-     * Resolves a diagram service
+     * Resolves a diagram service.
      *
      * @method Diagram#get
      *
-     * @param {string} name the name of the diagram service to be retrieved
-     * @param {boolean} [strict=true] if false, resolve missing services to null
+     * @param {string} name The name of the service to get.
+     * @param {boolean} [strict=true] If false, resolve missing services to null.
      */
     this.get = injector.get;
 
     /**
-     * Executes a function into which diagram services are injected
+     * Executes a function with its dependencies injected.
      *
      * @method Diagram#invoke
      *
-     * @param {Function|Object[]} fn the function to resolve
-     * @param {Object} locals a number of locals to use to resolve certain dependencies
+     * @param {Function} fn The function to be executed.
+     * @param {InjectionContext} [context] The context.
+     * @param {LocalsMap} [locals] The locals.
      */
     this.invoke = injector.invoke;