[FEAT] API should return BPMN Semantic data about nodes/flows links

[tbouffard]

Is your feature request related to a problem? Please describe.
#2503 will store the information in the internal model.
Then, we can help navigating into the BPMN Model when a user retrieves an BPMN element with getElementsById and the getElementsByKind API.
This could be a first step to implement graph related use cases, like these involving paths like described in #930.

Describe the solution you'd like
Update the object returns by the API mentioned here and include

• for shapes: incoming and outgoing edges (ids) [FEAT] BpmnElementsRegistry API returns shape incoming/outgoing #2523
• for edges: source and terminal shapes (ids) [FEAT] BpmnElementsRegistry API returns source/target for edges #2522

Additional context
This is a sub-task of #929

The API definition (i.e. the BpmnSemantic type changes) is defined in #2504 (comment)

[tbouffard]

Here are some proposals for the structure of the BpmnSemantic

Proposal 1

All new properties directly available in BpmnSemantic.
Cons

• no distinction between flows and flownodes

export interface BpmnSemantic {
  // existing properties
  id: string;
  name: string;
  isShape: boolean;
  kind: BpmnElementKind;

  // new properties
  sourceRefId?: string;
  targetRefId?: string;

  incomingIds?: string[];
  outgoingIds?: string[];
}

Proposal 2

Dedicated sub-structure for flownode and flows data.
pros:

• only set when related BPMN element is a flownode or a flow
• we can have mandatory properties
• ready for the future when more properties will be available ([FEAT] Provide BPMN Semantic data in addition to HTML elements #929)
  cons:
• current proposal use visual wording (edge and shape) for the main property name whereas BPMN semantic is involved --> find a better name. Note that there is already a isShape property using the visual wording (not good).

export interface BpmnSemantic {
  // existing properties
  id: string;
  name: string;
  isShape: boolean;
  kind: BpmnElementKind;

  // new properties
  edgeInfo?: {
    sourceRefId: string;
    targetRefId: string;
  };
  shapeInfo?: {
    incomingIds: string[];
    outgoingIds: string[];
  };
}

[csouchet]

Proposal 3

export interface BpmnSemantic {
  // existing properties
  id: string;
  name: string;
  isShape: boolean;
  kind: BpmnElementKind;
}

export interface ShapeBpmnSemantic extends BpmnSemantic {
  // new properties
  incomingIds: string[];
  outgoingIds: string[];
}

export interface EdgeBpmnSemantic extends BpmnSemantic {
  // new properties
  sourceRefId: string;
  targetRefId: string;
}

[tbouffard]

After discussion with @csouchet, we decided to go with the Proposal 3.
Proposal 2 introduces an extra indirection with the shapeInfo/edgeInfo properties.
The new interface will use the rendering wording (shape and edge): if we find a better wording later, we will be able to provide a new type and keep the previous name (with a type alias) to keep the compatibility (at least for several releases).