[FEAT] Study "having a way to add overlays to the BPMN Diagram"

[tbouffard]

Is your feature request related to a problem? Please describe.
Overlays are required to cover a large amount of use case to enrich the BPMN diagram with runtime and execution data

• badges (see [FEAT] Provide a way to display process execution information in badges #429)
• statistics display: on gateway outgoing edge for branch
• highlight elements in monitoring scenario: comments, warn late activities

Describe the solution you'd like
We could provide a flexible way for integration to configure the overlays

• html content as string or html object reference (to be able to register interactivity on the overlay prior adding it or modify it dynamically)
• positioning: we could provide options like https://popper.js.org/ does. Placement (top, right, ...) and offset for easy control

We may need

• a way to add and remove overlays
• (may) to let integration add a category to the overlay (badge, statistic, comment) and provide search capabilities
• decide how the overlays will react to Bpmn Diagram navigation: hide during navigation (pan and zoom)? change dimension on zoom?

[aibcmars]

We have decided with @csouchet and @tbouffard to use mxCellOverlay for badges / overlays

	mxCellOverlay	SVG.JS	popperJS (lite)
POC	#1112	#1118 #1140	#1098
size	0 KB	192 KB	68 KB
decoupling	coupled	decoupled	decoupled
possibility of adding / removing badge/overlay	yes	yes	yes
categories of overlays / badges	yes , deferrent types possible	yes	yes
behaviour of badges (pan zoom of diagram)	it zooms along with diagram	doable / we need to recalculate the size	panning yes, zoom - perhaps / to checkby default it follows the diagram behaviour
interactivity	yes, native with mxEvent	yes	yes
positioning	9 positions by default (can be customized by type)	custom	default and customizable offset
flexibility of customization (appearance)	predefined appearanceSVG customizable to be checked with foreignObject if not Shapes like for BPMN elements	predefined appearanceSVG customizable	fully flexible
performance	seems aligned with general mxGraph performance	hard to compare due tu differences in integration
DECISION:	based on above comparison
	mxCellOverlay

Prerequisites

• enrich the POC to ensure we can easily add mxCellOverlay on Edge and check if we can reuse the same position values as for shape. See [POC] add mxgraph overlay badges #1112
• it works already - see [POC] add mxgraph overlay badges #1112 (comment)

[tbouffard]

Decisions after Team review

General

• we will have a quite low level API, not domain oriented for now as we currently don't know which form it should take nor if it will land in bpmn-visualization or in another lib
• naming: we will use the overlay wording. Badges is too restrictive and we want a more generic word here
• we are not going to provide an API that let the integration pass the overlays as HTML:
  • we want something more related to our domain
  • HTML overlays allow a great level of flexibility (shape, rendering, ...) but with the cost of forcing the integration to provide implementation details
  • it requires extra management to deal with zoom and panning both in the implementation (our side) and in the configuration (integration side). For the user, this means that in some case, overlays clipping would occur
• so we will provide
  • an implementation at SVG stage and it will follow the BPMN diagram navigation rendering
  • a predefined set of overlays to simplify the configuration by integrations.
• this let cover all use-cases we currently know
• overlay customization: kind, size, colors, ....
• overlay extensibility: when the API will be fully implemented (after the mvp), it will provide a certain level of extensibility
  • allow to define new overlay kinds and register them
  • new options for the new overlay kinds

Parts of the MVP

• initial implementation: let add an overlay ([FEAT] Add overlays on Shape #1162).
  • The integration provides a mandatory position (in a list of available position like top-left, center-right, ....) and an optional text.
  • This will produce an rectangle badge with white/transparent background and black border using the already used default text settings
• for a given BPMN element, if a overlay already exists at the position, the new one override the existing one. Rationale: several overlays would overlap, only the latest one would be correctly displayed, having extra overlays could produce performance issues
• let remove all overlays of a given BPMN element
• ensure the overlays on edge are displayed at the right position
• ensure the overlay is displayed when the label is not provided (minimal size)?
• provide an initial set of overlays type: rectangle, circle, hexagon, star (cf [POC] Add/Remove badge with svg.js & a registry #1118), ... (to be precised later)
  • add dedicated css class on overlays depending on the type
• let provide styling options (to be precised later):
  • overlay size (relative to the shape? absolute?)
  • color (border, background)
  • border width
  • txt color,size, ...
• add user document with concept and global covered topics
• add examples and demo (to be precised)

To implement later as improvements

• overlay removal: let remove one or several (not only all)
  • this requires to let the integration identify the overlay
  • by its position
  • by providing an id or retrieving an id we have generated internally
  • by another method
• register interaction on overlays (for a single or several overlays). For instance, on click, see POC [POC] add mxgraph overlay badges #1112
• provide an 'auto' position and bpmn-visualization appends overlays at a position depending on the already existing overlays

[tbouffard]

Decisions taken and issues created, so closing this issue.