feat: add support for 'BPMN in Color'

dev/ts/main.ts

@@ -273,15 +273,23 @@ function configurePoolsFilteringFromParameters(parameters: URLSearchParams): Mod
 export function startBpmnVisualization(config: BpmnVisualizationDemoConfiguration): void {
   const log = logStartup;
   log(`Initializing BpmnVisualization with container '${config.globalOptions.container}'...`);
+
+  const parameters = new URLSearchParams(window.location.search);
+  const rendererIgnoreBpmnColors = parameters.get('renderer.ignore.bpmn.colors');
+  if (rendererIgnoreBpmnColors) {
+    const ignoreBpmnColors = rendererIgnoreBpmnColors === 'true';
+    log('Ignore support for "BPMN in Color"?', ignoreBpmnColors);
+    !config.globalOptions.renderer && (config.globalOptions.renderer = {});
+    config.globalOptions.renderer.ignoreBpmnColors = ignoreBpmnColors;
+  }
+
   bpmnVisualization = new ThemedBpmnVisualization(config.globalOptions);
   log('Initialization completed');
   new DropFileUserInterface(window, 'drop-container', bpmnVisualization.graph.container, readAndLoadFile);
   log('Drag&Drop support initialized');
 
   statusKoNotifier = config.statusKoNotifier ?? logOnlyStatusKoNotifier;
 
-  const parameters = new URLSearchParams(window.location.search);
-
   log('Configuring Load Options');
   loadOptions = config.loadOptions || {};
   loadOptions.fit = getFitOptionsFromParameters(config, parameters);

docs/users/overview.adoc

@@ -129,6 +129,18 @@ image::images/bpmn-theme-custom-colors.png[Custom BPMN Theme]
 _Custom BPMN Theme_
 
 
+==== `BPMN in Color` Support
+
+As of version 0.35.0, `bpmn-visualization` supports the https://github.com/bpmn-miwg/bpmn-in-color[BPMN in Color Specification] with a fallback to the
+https://github.com/bpmn-io/bpmn-moddle/blob/ea7fa6a94c55f49fe1da1f019dc9a40d62967252/resources/bpmn-io/json/bioc.json[bpmn.io specific BPMN extensions for colors] (a.k.a `bioc`).
+
+This support is disabled by default, and it can be enabled at the library initialization.
+
+image::images/bpmn-in-color-C.1.0.png[C.1.0 with "BPMN in Color"]
+
+_miwg-test-suite C.1.0 reference diagram using "BPMN in Color"_
+
+
 [[diagram-navigation]]
 === Diagram Navigation
 

src/component/BpmnVisualization.ts

@@ -18,7 +18,7 @@ import GraphConfigurator from './mxgraph/GraphConfigurator';
 import { newBpmnRenderer } from './mxgraph/BpmnRenderer';
 import { newBpmnParser } from './parser/BpmnParser';
 import type { BpmnGraph } from './mxgraph/BpmnGraph';
-import type { GlobalOptions, LoadOptions, ParserOptions } from './options';
+import type { GlobalOptions, LoadOptions, ParserOptions, RendererOptions } from './options';
 import type { BpmnElementsRegistry } from './registry';
 import { newBpmnElementsRegistry } from './registry/bpmn-elements-registry';
 import { BpmnModelRegistry } from './registry/bpmn-model-registry';
@@ -69,7 +69,10 @@ export class BpmnVisualization {
 
   private readonly parserOptions: ParserOptions;
 
+  private readonly rendererOptions: RendererOptions;
+
   constructor(options: GlobalOptions) {
+    this.rendererOptions = options?.renderer;
     // mxgraph configuration
     const configurator = new GraphConfigurator(htmlElement(options?.container));
     this.graph = configurator.configure(options);
@@ -89,7 +92,7 @@ export class BpmnVisualization {
   load(xml: string, options?: LoadOptions): void {
     const bpmnModel = newBpmnParser(this.parserOptions).parse(xml);
     const renderedModel = this.bpmnModelRegistry.load(bpmnModel, options?.modelFilter);
-    newBpmnRenderer(this.graph).render(renderedModel, options?.fit);
+    newBpmnRenderer(this.graph, this.rendererOptions).render(renderedModel, options?.fit);
   }
 
   getVersion(): Version {

src/component/mxgraph/BpmnRenderer.ts

@@ -23,7 +23,7 @@ import { MessageVisibleKind, ShapeUtil } from '../../model/bpmn/internal';
 import CoordinatesTranslator from './renderer/CoordinatesTranslator';
 import StyleComputer from './renderer/StyleComputer';
 import type { BpmnGraph } from './BpmnGraph';
-import type { FitOptions } from '../options';
+import type { FitOptions, RendererOptions } from '../options';
 import type { RenderedModel } from '../registry/bpmn-model-registry';
 import { mxgraph } from './initializer';
 import type { mxCell } from 'mxgraph';
@@ -139,8 +139,8 @@ export class BpmnRenderer {
 /**
  * @internal
  */
-export function newBpmnRenderer(graph: BpmnGraph): BpmnRenderer {
-  return new BpmnRenderer(graph, new CoordinatesTranslator(graph), new StyleComputer());
+export function newBpmnRenderer(graph: BpmnGraph, options: RendererOptions): BpmnRenderer {
+  return new BpmnRenderer(graph, new CoordinatesTranslator(graph), new StyleComputer(options));
 }
 
 /**

src/component/mxgraph/renderer/StyleComputer.ts

@@ -31,39 +31,46 @@ import { BpmnStyleIdentifier } from '../style';
 import { MessageVisibleKind, ShapeBpmnCallActivityKind, ShapeBpmnElementKind, ShapeBpmnMarkerKind, ShapeUtil } from '../../../model/bpmn/internal';
 import { AssociationFlow, SequenceFlow } from '../../../model/bpmn/internal/edge/flows';
 import type { Font } from '../../../model/bpmn/internal/Label';
+import type { RendererOptions } from '../../options';
 
 /**
  * @internal
  */
 export default class StyleComputer {
+  private readonly ignoreBpmnColors: boolean;
+
+  constructor(options?: RendererOptions) {
+    this.ignoreBpmnColors = options?.ignoreBpmnColors ?? true;
+  }
+
   computeStyle(bpmnCell: Shape | Edge, labelBounds: Bounds): string {
     const styles: string[] = [bpmnCell.bpmnElement.kind as string];
 
-    let shapeStyleValues;
+    let mainStyleValues;
     if (bpmnCell instanceof Shape) {
-      shapeStyleValues = StyleComputer.computeShapeStyle(bpmnCell);
+      mainStyleValues = this.computeShapeStyleValues(bpmnCell);
     } else {
-      styles.push(...StyleComputer.computeEdgeStyle(bpmnCell));
-      shapeStyleValues = new Map<string, string | number>();
+      styles.push(...StyleComputer.computeEdgeBaseStyles(bpmnCell));
+      mainStyleValues = this.computeEdgeStyleValues(bpmnCell);
     }
 
-    const fontStyleValues = StyleComputer.computeFontStyleValues(bpmnCell);
+    const fontStyleValues = this.computeFontStyleValues(bpmnCell);
     const labelStyleValues = StyleComputer.computeLabelStyleValues(bpmnCell, labelBounds);
 
     return [] //
       .concat([...styles])
-      .concat([...shapeStyleValues, ...fontStyleValues, ...labelStyleValues].filter(([, v]) => v && v != 'undefined').map(([key, value]) => key + '=' + value))
+      .concat(toArrayOfMxGraphStyleEntries([...mainStyleValues, ...fontStyleValues, ...labelStyleValues]))
       .join(';');
   }
 
-  private static computeShapeStyle(shape: Shape): Map<string, string | number> {
+  private computeShapeStyleValues(shape: Shape): Map<string, string | number> {
     const styleValues = new Map<string, string | number>();
     const bpmnElement = shape.bpmnElement;
 
     if (bpmnElement instanceof ShapeBpmnEvent) {
-      this.computeEventShapeStyle(bpmnElement, styleValues);
+      StyleComputer.computeEventShapeStyle(bpmnElement, styleValues);
     } else if (bpmnElement instanceof ShapeBpmnActivity) {
-      this.computeActivityShapeStyle(bpmnElement, styleValues);
+      StyleComputer.computeActivityShapeStyle(bpmnElement, styleValues);
     } else if (ShapeUtil.isPoolOrLane(bpmnElement.kind)) {
       // mxgraph.mxConstants.STYLE_HORIZONTAL is for the label
       // In BPMN, isHorizontal is for the Shape
@@ -74,6 +81,18 @@ export default class StyleComputer {
       styleValues.set(BpmnStyleIdentifier.EVENT_BASED_GATEWAY_KIND, String(bpmnElement.gatewayKind));
     }
 
+    if (!this.ignoreBpmnColors) {
+      const extensions = shape.extensions;
+      const fillColor = extensions.fillColor;
+      if (fillColor) {
+        styleValues.set(mxgraph.mxConstants.STYLE_FILLCOLOR, fillColor);
+        if (ShapeUtil.isPoolOrLane(bpmnElement.kind)) {
+          styleValues.set(mxgraph.mxConstants.STYLE_SWIMLANE_FILLCOLOR, fillColor);
+        }
+      }
+      extensions.strokeColor && styleValues.set(mxgraph.mxConstants.STYLE_STROKECOLOR, extensions.strokeColor);
+    }
+
     return styleValues;
   }
 
@@ -100,7 +119,7 @@ export default class StyleComputer {
     }
   }
 
-  private static computeEdgeStyle(edge: Edge): string[] {
+  private static computeEdgeBaseStyles(edge: Edge): string[] {
     const styles: string[] = [];
 
     const bpmnElement = edge.bpmnElement;
@@ -114,7 +133,18 @@ export default class StyleComputer {
     return styles;
   }
 
-  private static computeFontStyleValues(bpmnCell: Shape | Edge): Map<string, string | number> {
+  private computeEdgeStyleValues(edge: Edge): Map<string, string | number> {
+    const styleValues = new Map<string, string | number>();
+
+    if (!this.ignoreBpmnColors) {
+      const extensions = edge.extensions;
+      extensions.strokeColor && styleValues.set(mxgraph.mxConstants.STYLE_STROKECOLOR, extensions.strokeColor);
+    }
+
+    return styleValues;
+  }
+
+  private computeFontStyleValues(bpmnCell: Shape | Edge): Map<string, string | number> {
     const styleValues = new Map<string, string | number>();
 
     const font = bpmnCell.label?.font;
@@ -124,6 +154,11 @@ export default class StyleComputer {
       styleValues.set(mxgraph.mxConstants.STYLE_FONTSTYLE, getFontStyleValue(font));
     }
 
+    if (!this.ignoreBpmnColors) {
+      const extensions = bpmnCell.label?.extensions;
+      extensions?.color && styleValues.set(mxgraph.mxConstants.STYLE_FONTCOLOR, extensions.color);
+    }
+
     return styleValues;
   }
 
@@ -162,7 +197,14 @@ export default class StyleComputer {
   }
 
   computeMessageFlowIconStyle(edge: Edge): string {
-    return `shape=${BpmnStyleIdentifier.MESSAGE_FLOW_ICON};${BpmnStyleIdentifier.IS_INITIATING}=${edge.messageVisibleKind === MessageVisibleKind.INITIATING}`;
+    const styleValues: Array<[string, string]> = [];
+    styleValues.push(['shape', BpmnStyleIdentifier.MESSAGE_FLOW_ICON]);
+    styleValues.push([BpmnStyleIdentifier.IS_INITIATING, String(edge.messageVisibleKind === MessageVisibleKind.INITIATING)]);
+    if (!this.ignoreBpmnColors) {
+      edge.extensions.strokeColor && styleValues.push([mxgraph.mxConstants.STYLE_STROKECOLOR, edge.extensions.strokeColor]);
+    }
+
+    return toArrayOfMxGraphStyleEntries([...styleValues]).join(';');
   }
 }
 
@@ -186,3 +228,7 @@ export function getFontStyleValue(font: Font): number {
   }
   return value;
 }
+
+function toArrayOfMxGraphStyleEntries(styleValues: Array<[string, string | number]>): string[] {
+  return styleValues.filter(([, v]) => v && v != 'undefined').map(([key, value]) => `${key}=${value}`);
+}

src/component/options.ts

@@ -25,6 +25,8 @@ export interface GlobalOptions {
   navigation?: NavigationConfiguration;
   /** Configure the BPMN parser. */
   parser?: ParserOptions;
+  /** Configure how the BPMN diagram and its elements are rendered. */
+  renderer?: RendererOptions;
 }
 
 /**
@@ -180,3 +182,21 @@ export type ParserOptions = {
    */
   additionalXmlAttributeProcessor?: (val: string) => string;
 };
+
+/**
+ * Global configuration for the rendering of the BPMN elements.
+ *
+ * @category Initialization & Configuration
+ * @since 0.35.0
+ */
+export type RendererOptions = {
+  /**
+   * If set to `false`, support the "BPMN in Color" specification with a fallback with bpmn.io colors. For more details about the support, see
+   * {@link https://github.com/process-analytics/bpmn-visualization-js/pull/2614}.
+   *
+   * Otherwise, disable the support.
+   *
+   * @default true
+   */
+  ignoreBpmnColors?: boolean;
+};

src/component/parser/json/converter/DiagramConverter.ts

@@ -22,11 +22,10 @@ import { Edge, Waypoint } from '../../../../model/bpmn/internal/edge/edge';
 import type { Shapes } from '../../../../model/bpmn/internal/BpmnModel';
 import type BpmnModel from '../../../../model/bpmn/internal/BpmnModel';
 import Label, { Font } from '../../../../model/bpmn/internal/Label';
-import { MessageVisibleKind } from '../../../../model/bpmn/internal/edge/kinds';
+import { MessageVisibleKind, ShapeBpmnCallActivityKind, ShapeBpmnMarkerKind, ShapeUtil } from '../../../../model/bpmn/internal';
 import type { BPMNDiagram, BPMNEdge, BPMNLabel, BPMNLabelStyle, BPMNShape } from '../../../../model/bpmn/json/BPMNDI';
 import type { Point } from '../../../../model/bpmn/json/DC';
 import type { ConvertedElements } from './utils';
-import { ShapeBpmnCallActivityKind, ShapeBpmnMarkerKind, ShapeUtil } from '../../../../model/bpmn/internal';
 import { ensureIsArray } from '../../../helpers/array-utils';
 import type { ParsingMessageCollector } from '../../parsing-messages';
 import { EdgeUnknownBpmnElementWarning, LabelStyleMissingFontWarning, ShapeUnknownBpmnElementWarning } from '../warnings';
@@ -104,26 +103,44 @@ export default class DiagramConverter {
     return false;
   }
 
-  private deserializeShape(shape: BPMNShape, findShapeElement: (bpmnElement: string) => ShapeBpmnElement): Shape | undefined {
-    const bpmnElement = findShapeElement(shape.bpmnElement);
+  private deserializeShape(bpmnShape: BPMNShape, findShapeElement: (bpmnElement: string) => ShapeBpmnElement): Shape | undefined {
+    const bpmnElement = findShapeElement(bpmnShape.bpmnElement);
     if (bpmnElement) {
-      const bounds = DiagramConverter.deserializeBounds(shape);
+      const bounds = DiagramConverter.deserializeBounds(bpmnShape);
 
       if (
         (bpmnElement instanceof ShapeBpmnSubProcess ||
           (bpmnElement instanceof ShapeBpmnCallActivity && bpmnElement.callActivityKind === ShapeBpmnCallActivityKind.CALLING_PROCESS)) &&
-        !shape.isExpanded
+        !bpmnShape.isExpanded
       ) {
         bpmnElement.markers.push(ShapeBpmnMarkerKind.EXPAND);
       }
 
       let isHorizontal;
       if (ShapeUtil.isPoolOrLane(bpmnElement.kind)) {
-        isHorizontal = shape.isHorizontal ?? true;
+        isHorizontal = bpmnShape.isHorizontal ?? true;
       }
 
-      const label = this.deserializeLabel(shape.BPMNLabel, shape.id);
-      return new Shape(shape.id, bpmnElement, bounds, label, isHorizontal);
+      const bpmnLabel = bpmnShape.BPMNLabel;
+      const label = this.deserializeLabel(bpmnLabel, bpmnShape.id);
+      const shape = new Shape(bpmnShape.id, bpmnElement, bounds, label, isHorizontal);
+      DiagramConverter.setColorExtensionsOnShape(shape, bpmnShape);
+
+      return shape;
+    }
+  }
+
+  // 'BPMN in Color' extensions with fallback to bpmn.io colors
+  private static setColorExtensionsOnShape(shape: Shape, bpmnShape: BPMNShape): void {
+    if ('background-color' in bpmnShape) {
+      shape.extensions.fillColor = <string>bpmnShape['background-color'];
+    } else if ('fill' in bpmnShape) {
+      shape.extensions.fillColor = <string>bpmnShape['fill'];
+    }
+    if ('border-color' in bpmnShape) {
+      shape.extensions.strokeColor = <string>bpmnShape['border-color'];
+    } else if ('stroke' in bpmnShape) {
+      shape.extensions.strokeColor = <string>bpmnShape['stroke'];
     }
   }
 
@@ -136,26 +153,37 @@ export default class DiagramConverter {
 
   private deserializeEdges(edges: BPMNEdge | BPMNEdge[]): Edge[] {
     return ensureIsArray(edges)
-      .map(edge => {
+      .map(bpmnEdge => {
         const flow =
-          this.convertedElements.findSequenceFlow(edge.bpmnElement) ||
-          this.convertedElements.findMessageFlow(edge.bpmnElement) ||
-          this.convertedElements.findAssociationFlow(edge.bpmnElement);
+          this.convertedElements.findSequenceFlow(bpmnEdge.bpmnElement) ||
+          this.convertedElements.findMessageFlow(bpmnEdge.bpmnElement) ||
+          this.convertedElements.findAssociationFlow(bpmnEdge.bpmnElement);
 
         if (!flow) {
-          this.parsingMessageCollector.warning(new EdgeUnknownBpmnElementWarning(edge.bpmnElement));
+          this.parsingMessageCollector.warning(new EdgeUnknownBpmnElementWarning(bpmnEdge.bpmnElement));
           return;
         }
 
-        const waypoints = this.deserializeWaypoints(edge.waypoint);
-        const label = this.deserializeLabel(edge.BPMNLabel, edge.id);
-        const messageVisibleKind = edge.messageVisibleKind ? (edge.messageVisibleKind as unknown as MessageVisibleKind) : MessageVisibleKind.NONE;
+        const waypoints = this.deserializeWaypoints(bpmnEdge.waypoint);
+        const label = this.deserializeLabel(bpmnEdge.BPMNLabel, bpmnEdge.id);
+        const messageVisibleKind = bpmnEdge.messageVisibleKind ? (bpmnEdge.messageVisibleKind as unknown as MessageVisibleKind) : MessageVisibleKind.NONE;
 
-        return new Edge(edge.id, flow, waypoints, label, messageVisibleKind);
+        const edge = new Edge(bpmnEdge.id, flow, waypoints, label, messageVisibleKind);
+        DiagramConverter.setColorExtensionsOnEdge(edge, bpmnEdge);
+        return edge;
       })
       .filter(Boolean);
   }
 
+  // 'BPMN in Color' extensions  with fallback to bpmn.io colors
+  private static setColorExtensionsOnEdge(edge: Edge, bpmnEdge: BPMNEdge): void {
+    if ('border-color' in bpmnEdge) {
+      edge.extensions.strokeColor = <string>bpmnEdge['border-color'];
+    } else if ('stroke' in bpmnEdge) {
+      edge.extensions.strokeColor = <string>bpmnEdge['stroke'];
+    }
+  }
+
   private deserializeWaypoints(waypoints: Point[]): Waypoint[] {
     return ensureIsArray(waypoints).map(waypoint => new Waypoint(waypoint.x, waypoint.y));
   }
@@ -164,9 +192,13 @@ export default class DiagramConverter {
     if (bpmnLabel && typeof bpmnLabel === 'object') {
       const font = this.findFont(bpmnLabel.labelStyle, id);
       const bounds = DiagramConverter.deserializeBounds(bpmnLabel);
-
+      const label = new Label(font, bounds);
+      if ('color' in bpmnLabel) {
+        label.extensions.color = <string>bpmnLabel.color;
+        return label;
+      }
       if (font || bounds) {
-        return new Label(font, bounds);
+        return label;
       }
     }
   }