[FEAT] Add a plugin that provides an API to translate/scroll a BPMN element

[tbouffard]

Is your feature request related to a problem? Please describe.

A BPMN element may require special attention, so it may be required to position/scroll it at a specific location in the BPMN container.

Describe the solution you'd like

Implement a ScrollElementsApiPlugin plugin that provides an API to scroll an BPMN element given its id. This will be a generalization of #165. This should work when the BPMN container has scrollbars.

API proposal

type ScrollElementOptions = {
  // same as bpmn-visualization OverlayShapePosition + 'center' and 'visible'
  position?: 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center' | 'middle-left' | 'middle-right' | 'center' |  'visible' , // default 'top-left'
  margin-bottom?: number, // default 0
  margin-left?: number, // default 0
  margin-right?: number, // default 0
  margin-top?: number, // default 0
}

scrollElement(bpmnId: string, options?: {}): void

The margin properties don't always apply. For example:

• for the top-left position, only the margin-left and margin-top apply
• for the center position, no margin applies
• for the visible position, some margin may apply depending on the chosen implementation

Negative values for margins could be accepted.

Disclaimer: this will probably only work with a BPMN container that have a "fixed computed size" (as for the fit feature).

Name of the plugin. Be consistent with:

• 164

• 167

• 168

Future implementation: we may provide another plugin that takes the name of the BPMN element instead of its id, as we do in #75 or #76.

Screenshots

Positions and margins

Scrolling an hidden elements to make it visible

Additional context

A POC has been done for the top-left and center position in https://github.com/process-analytics/bpmn-visualization-js/pull/2885

Implementation of visible/center

• use mxGraph.scrollToVisible
• see " Centers the graph in the container" https://github.com/jgraph/mxgraph/blob/ff141aab158417bd866e2dfebd06c61d40773cd2/javascript/src/js/view/mxGraph.js#L7987
• see mxUtils.getScrollOrigin(this.graph.container);
• see the "additional context" paragraph of #165