feat: add support for 'BPMN in Color' by tbouffard · Pull Request #2614 · process-analytics/bpmn-visualization-js

tbouffard · 2023-04-09T19:22:20Z

Support the 'BPMN in Color' and use bpmn.io colors as fallback.
The BPMN parser always extract the colors, but by default, they are ignored by the Renderer. It is possible to enable the support in the Renderer by setting an options at the library initialization.

This introduces internal management of BPMN extensions for BPMNShape, BPMNEdge and BPMNLabel.

The parsing tests are using diagrams taken from the 'BPMN in Color' specification sample (this ensure that the implementation is compliant with the specification) and from the original issue requesting support for modeling colors as an example of bpmn.io colors.

closes #2588

Tasks

e2e tests thresholds
disable by default
add new tests to handle the new option: StyleComputer and e2e tests
DiagramConverter.deserializeShape: "Refactor this function to reduce its Cognitive Complexity from 16 to the 15 allowed." (feedback from SonarCloud)
update the Internal Model schema
update the documentation: create a dedicated section (after the BPMN theme paragraph for instance) mentioning that it supports the spec (including links to the spec) + fallback bpmn.io.
update JSDoc of the types of the "Update Style" API parameters: warn about resetting using "default". This overrides the initial colors value set in the BPMN model.
introduce a ignoreBpmnColors option to enable/disable the rendering support

Decision about support by default of "BPMN in Color"

Decision with @csouchet on 2023-04-12

BPMN in Color support is disabled by default. We want to support it but we want to keep execution highlight easy to see. Adding colors to non highlighted elements defeat this purpose (as colors highlight the elements). See C.1.1 that has a lot of colors and that we used in several examples.
to enable it, pass an option to the a lib at initialization
the option will be ignoreBpmnColors which is true by default. The new option involves the "BPMN renderer", so it must be consistent with the new options we plan to introduce in the future. See [FEAT] Define the options that will be used to configure the Renderer #2659.

Screenshots

sample from the "BPMN in Color" Specification

Available in https://github.com/bpmn-miwg/bpmn-in-color, also stored for use in XML parsing unit tests

adapted from the diagram provided in #2588

Also used in XML parsing unit tests

e2e test diagram, including message flow icons that are also colored

Files from miwg-test-suite

File	without color	with color
A.2.1
A.4.1
C.1.0
C.1.1
C.3.0
C.8.0

Support the 'BPMN in Color' and use bpmn.io colors as fallback. This introduces internal management of BPMN extensions for BPMNShape, BPMNEdge and BPMNLabel. The parsing tests are using diagrams taken from the 'BPMN in Color' specification sample and from the original issue requesting support for modeling colors (#2588) as an example of bpmn.io colors.

github-actions · 2023-04-09T19:23:26Z

♻️ PR Preview 4ee509e has been successfully destroyed since this PR has been closed.

_{🤖 By surge-preview}

github-actions · 2023-04-09T19:23:46Z

♻️ PR Preview 4ee509e has been successfully destroyed since this PR has been closed.

_{🤖 By surge-preview}

…fault in StyleComputer

# Conflicts: # src/component/parser/json/converter/DiagramConverter.ts # test/unit/component/mxgraph/renderer/StyleComputer.test.ts # test/unit/component/parser/BpmnParser.test.ts # test/unit/helpers/JsonTestUtils.ts # test/unit/helpers/bpmn-model-expect.ts

…c method to handle extensions)

This proves the need for optional chaining for font management

# Conflicts: # src/component/BpmnVisualization.ts # src/component/options.ts # test/unit/component/mxgraph/renderer/StyleComputer.test.ts

…apeExtensions

csouchet · 2023-05-25T12:51:34Z

+  }
+
+  // 'BPMN in Color' extensions with fallback to bpmn.io colors
+  private static setColorExtensionsOnShape(shape: Shape, bpmnShape: BPMNShape): void {


suggestion:

I think we don't need to check if background-color, fill, border-color and stroke are in bpmnShape, because even if there are undefined, with this implementation or the suggested implementation, the attributes of shape.extensions will be undefined.

Suggested change

private static setColorExtensionsOnShape(shape: Shape, bpmnShape: BPMNShape): void {

private static setColorExtensionsOnShape(shape: Shape, bpmnShape: BPMNShape): void {

shape.extensions.fillColor = <string>bpmnShape['background-color'] ?? <string>bpmnShape['fill'];

shape.extensions.strokeColor = <string>bpmnShape['border-color'] ?? <string>bpmnShape['stroke'];

}

The usage of the color extensions is very rare, so the idea was to not have properties with undefined values but to have no property in this case.
The model is not stored internally, so I will give it a try to your proposal to simplify the code here and for Edge.

@csouchet the proposal cannot be implemented out of the box

const backgroundColor = bpmnShape['background-color'];

generates a TS error TS7053: Element implicitly has an 'any' type because expression of type '"background-color"' can't be used to index type 'BPMNShape'. Property 'background-color' does not exist on type 'BPMNShape'.

I can ignore the error but the resulting code is less lisible and ignoring error is misleading

// eslint-disable-next-line @typescript-eslint/ban-ts-comment -- explain why! // @ts-ignore shape.extensions.fillColor = <string>bpmnShape['background-color'] ?? <string>bpmnShape['fill']; // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- explain why! // @ts-ignore shape.extensions.strokeColor = <string>bpmnShape['border-color'] ?? <string>bpmnShape['stroke'];

csouchet · 2023-05-25T12:52:18Z


-        return new Edge(edge.id, flow, waypoints, label, messageVisibleKind);
+        const edge = new Edge(bpmnEdge.id, flow, waypoints, label, messageVisibleKind);
+        DiagramConverter.setColorExtensionsOnEdge(edge, bpmnEdge);


question:
Same as for Shape

csouchet · 2023-05-25T12:52:57Z


+  // 'BPMN in Color' extensions  with fallback to bpmn.io colors
+  private static setColorExtensionsOnEdge(edge: Edge, bpmnEdge: BPMNEdge): void {
+    if ('border-color' in bpmnEdge) {


suggestion:

Suggested change

if ('border-color' in bpmnEdge) {

edge.extensions.strokeColor = <string>bpmnEdge['border-color'] ?? <string>bpmnEdge['stroke'];

}

csouchet · 2023-05-25T12:55:08Z

-
+      const label = new Label(font, bounds);
+      if ('color' in bpmnLabel) {
+        label.extensions.color = <string>bpmnLabel.color;


question:

Same as for Shape & Edge

Here this would change the behavior.
We return a Label instance only if properties are set (previously only font and bounds.
If I change the implementation as for shape and edge, we will always have an instance even when the label color is undefined.
So, I prefer not to change it.

sonarqubecloud · 2023-05-25T15:17:07Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

100.0% Coverage
0.0% Duplication

tbouffard added enhancement New feature or request WIP 🚧 Pull request in progress and/or not ready for review. Used in addition to marking it as draft BPMN diagram styling Change the standard rendering: stroke color, thickness labels Apr 9, 2023

e2e test: remove unused import

44563ff

tbouffard mentioned this pull request Apr 11, 2023

[FEAT] Add fill and stroke attributes in xml to draw colors per bpmn element #2588

Closed

tbouffard added 2 commits April 12, 2023 12:06

e2e: configure thresholds

94db78b

e2e: configure thresholds

3a8f874

tbouffard mentioned this pull request Apr 24, 2023

[FEAT] miwg-test-suite - enable "BPMN in color" support process-analytics/bpmn-visualization-tools#19

Closed

tbouffard added BPMN support Something about the BPMN specification that the lib is already supporting or will support and removed BPMN diagram styling Change the standard rendering: stroke color, thickness labels Apr 25, 2023

tbouffard mentioned this pull request Apr 28, 2023

[FEAT] Define the options that will be used to configure the Renderer #2659

Closed

tbouffard added 12 commits May 9, 2023 16:21

introduce RendererOptions: "bpmn in color" optional and ignored by de…

aa7080d

…fault in StyleComputer

Add integration test: check no "model colors" support by default

7606577

StyleComputer: no color support by default

7b03ac6

lib: options to enable support for colors from BPMN model

00eb1ea

e2e tests: check when model colors are ignored or not

5d965d0

tests: fix bad import after merge + reorg imports

e0660fe

JSDoc: RendererOptions

0f255fa

fix unit and integration tests after merge

04afe69

refactor parser: reduce the "Cognitive Complexity" (introduce specifi…

3902d44

…c method to handle extensions)

e2e tests: set thresholds

b832d6d

StyleComputer: add test when there is no extension

3513199

This proves the need for optional chaining for font management

tbouffard mentioned this pull request May 11, 2023

feat: use colors defined in the BPMN diagrams in some examples process-analytics/bpmn-visualization-examples#494

Merged

tbouffard added 2 commits May 11, 2023 11:30

docs: mention the "BPMN in Color" support in the users documentation

80aacb8

docs: update the schema of the internal model (add extensions)

921ce1c

tbouffard added the decision record Track project and architectural decisions label May 11, 2023

tbouffard added 4 commits May 16, 2023 07:19

API docs: warn usage of "default" value in StyleUpdate types

f838422

API docs: fix typo

57af8c9

StyleComputer.ts make field reaonly

7f1407e

Rename option ignoreModelColors into ignoreBpmnColors

f5ec16f

tbouffard marked this pull request as ready for review May 16, 2023 05:36

tbouffard removed the WIP 🚧 Pull request in progress and/or not ready for review. Used in addition to marking it as draft label May 16, 2023

tbouffard requested a review from csouchet May 16, 2023 05:36

csouchet suggested changes May 22, 2023

View reviewed changes

Comment thread src/model/bpmn/internal/types.ts Outdated

Comment thread src/component/parser/json/converter/DiagramConverter.ts Outdated

Comment thread src/model/bpmn/internal/types.ts Outdated

tbouffard added 4 commits May 25, 2023 13:25

Merge branch 'master' into feat/bpmn-in-color

f9bd177

# Conflicts: # src/component/BpmnVisualization.ts # src/component/options.ts # test/unit/component/mxgraph/renderer/StyleComputer.test.ts

refactor: use named properties in EdgeExtensions, LabelExtensions, Sh…

d957d43

…apeExtensions

restore

04052da

restore

be6e750

tbouffard requested a review from csouchet May 25, 2023 12:30

csouchet reviewed May 25, 2023

View reviewed changes

tbouffard added 2 commits May 25, 2023 17:07

refactor(StyleComputer): simplify passing arrays

4d2cc3d

refactor(StyleComputer): simplify final style computation

4ee509e

csouchet approved these changes May 25, 2023

View reviewed changes

tbouffard merged commit d340bae into master May 25, 2023

tbouffard deleted the feat/bpmn-in-color branch May 25, 2023 15:48

	if ('border-color' in bpmnEdge) {
	edge.extensions.strokeColor = <string>bpmnEdge['border-color'] ?? <string>bpmnEdge['stroke'];
	}

Conversation

tbouffard commented Apr 9, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tasks

Decision about support by default of "BPMN in Color"

Screenshots

sample from the "BPMN in Color" Specification

adapted from the diagram provided in #2588

e2e test diagram, including message flow icons that are also colored

Files from miwg-test-suite

Uh oh!

github-actions Bot commented Apr 9, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 9, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

csouchet May 25, 2023

Choose a reason for hiding this comment

Uh oh!

tbouffard May 25, 2023

Choose a reason for hiding this comment

Uh oh!

tbouffard May 25, 2023

Choose a reason for hiding this comment

Uh oh!

csouchet May 25, 2023

Choose a reason for hiding this comment

Uh oh!

csouchet May 25, 2023

Choose a reason for hiding this comment

Uh oh!

csouchet May 25, 2023

Choose a reason for hiding this comment

Uh oh!

tbouffard May 25, 2023

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented May 25, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tbouffard commented Apr 9, 2023 •

edited

Loading

github-actions Bot commented Apr 9, 2023 •

edited

Loading

github-actions Bot commented Apr 9, 2023 •

edited

Loading