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

[tbouffard]

We have several issues that requires to pass new options to the renderer.
To have something consistent, I suggest we review all requirements to propose a consistent Options definition.

Topics involved:

• [FEAT] Review Black Box Pool Rendering #718: finally not planned
• [FEAT] Provide a way to configure the defaults of the BPMN renderer #1993
• [FEAT] Provide an option to ignore BPMN LabelStyles #2468
• [FEAT] Provide an option to ignore BPMN Label Bounds of activities #2469
• [FEAT] General improvements for default styles management #2471 - not directly involved as it suggests to create a dedicated API
• feat: add support for 'BPMN in Color' #2614 - ignore colors defined in the BPMN diagram

Way of working

• starting from the initial proposal, let's discuss and comment this issue to amend the proposal
• keep track of the initial proposal to be able to see at a glance the diff between the current/final solution and the initial proposition
• during the design phase, the proposal will be updated until we converge

Final proposal

[UPDATE 2026-03-04] ignoreActivityLabelBounds, ignoreLabelStyles, ignoreTaskLabelBounds initially included bpmn in their name which has been removed as it was redundant: it is obvious that the properties apply to BPMN elements. See #3484

renderer: {
    /**
     * For #2469. We may need a `ignoreTaskLabelBounds` properties as well.
     * @default false
     */
    ignoreActivityLabelBounds?: boolean;
    /**
     * For #2614.
     * @default true
     */
    ignoreBpmnColors?: boolean;
    /**
     * For #2468.
     * @default false
     */
    ignoreLabelStyles?: boolean;
    /**
     * For #1993. Overlays configuration only.
     */
    overlayDefaults?: OverlayStyle;
};

Initial proposal

#718: I suggest to NOT make it an option. Decide whether to implement it or keep it as it is today. We could introduce the option later if someone request it and motivate their needs. Today I don't see the benefits of such an option.

// renderer is a new property in GlobalOptions
    renderer: {
        // in comments, the related name of entries currently in StyleDefault
        defaults: {
            // "general properties" - Do we introduce a "general" for the following properties?
            // TODO improve name, used in a lot of places
            margin?: number; //   DEFAULT_MARGIN = 0,
            // try to share with the Fill type used in the "Update Style" API
            fill?: {
                color?: string; //   DEFAULT_FILL_COLOR = 'White',
                opacity?: number;
            };
            // try to share with the Font type used in the "Update Style" API
            // I suggest we don't let set isBold, isXXX
            font?: {
                color?: string; //   DEFAULT_FONT_COLOR = 'Black',
                family?: string; //   DEFAULT_FONT_FAMILY = 'Arial, Helvetica, sans-serif', // define our own to not depend on eventual mxGraph default change
                opacity?: number;
                size?: number; //   DEFAULT_FONT_SIZE = 11,
            };
            // try to share with the Stroke type used in the "Update Style" API
            stroke: {
                color: string; //   DEFAULT_STROKE_COLOR = 'Black',
                opacity: number;
                width?: number;
            };
            // END of "general properties"
            // specific to BPMN shapes and edges
            bpmn: {
                activity: {
                    marginBottom?: number; //   SHAPE_ACTIVITY_BOTTOM_MARGIN = 7
                    marginFromCenter?: number;//   SHAPE_ACTIVITY_FROM_CENTER_MARGIN = 7, --> find a better name
                    marginLeft?: number;//   SHAPE_ACTIVITY_LEFT_MARGIN = 7,
                    marginTop?: number;//   SHAPE_ACTIVITY_TOP_MARGIN = 7,
                    markerIconMargin?: number;//   SHAPE_ACTIVITY_MARKER_ICON_MARGIN = 5,
                    markerIconSize?: number;//   SHAPE_ACTIVITY_MARKER_ICON_SIZE = 20,
                }

                groupFillColor?: string; //   GROUP_FILL_COLOR = 'none',
                laneLabelFillColor?: string; //   LANE_LABEL_FILL_COLOR = 'none',
                laneLabelSize?: number; //   LANE_LABEL_SIZE = 30, // most of BPMN lane are ok when setting it to 30
                poolLabelFillColor?: string; //   POOL_LABEL_FILL_COLOR = 'none',
                poolLabelSize?: number; //   POOL_LABEL_SIZE = 30, // most of BPMN pool are ok when setting it to 30
                subProcessTransactionInnerRectangleArcSize?: number; //   SUB_PROCESS_TRANSACTION_INNER_RECT_ARC_SIZE = 6,
                subProcessTransactionInnerRectangleOffset?: number; //   SUB_PROCESS_TRANSACTION_INNER_RECT_OFFSET = 4,
                textAnnotationBorderLength?: number; //   TEXT_ANNOTATION_BORDER_LENGTH = 10,
                textAnnotationFillColor?: string; //   TEXT_ANNOTATION_FILL_COLOR = 'none',
                // Do we create an intermediate property for "shapes"?
                shapes?: {
                    arcSize?: number; //   SHAPE_ARC_SIZE = 20,
                    strokeWidthThick?: number; //   STROKE_WIDTH_THICK = 5,
                    strokeWidthThin?: number; //   STROKE_WIDTH_THIN = 2,
                };
                // Do we create an intermediate property for "edges"?
                edges?: {
                    arcSize?: number; // currently, not configurable
                    messageFlowMarkerEndFillColor?: string; //   MESSAGE_FLOW_MARKER_END_FILL_COLOR = 'White',
                    messageFlowMarkerStartFillColor?: string; //   MESSAGE_FLOW_MARKER_START_FILL_COLOR = 'White',
                    sequenceFlowConditionalMarkerFillColor?: string; //   SEQUENCE_FLOW_CONDITIONAL_FROM_ACTIVITY_MARKER_FILL_COLOR = 'White',
                };
            };
            overlays: {
                // use fill, stroke and font structure as everywhere else?
                fillColor?: string; //   DEFAULT_OVERLAY_FILL_COLOR = DEFAULT_FILL_COLOR,
                fillOpacity?: string; //   DEFAULT_OVERLAY_FILL_OPACITY = 100,
                fontColor?: string; //   DEFAULT_OVERLAY_FONT_COLOR = DEFAULT_FONT_COLOR,
                fontSize?: number; //   DEFAULT_OVERLAY_FONT_SIZE = DEFAULT_FONT_SIZE,
                strokeColor?: string; //   DEFAULT_OVERLAY_STROKE_COLOR = DEFAULT_STROKE_COLOR,
                strokeWidth?: number; //   DEFAULT_OVERLAY_STROKE_WIDTH = 1,
            }
        };
        /**
         * For #2469. We may need a `ignoreActivitiesLabelBounds` properties as well.
         * @default false
         */
        ignoreBpmnActivityLabelBounds?: boolean;
        /**
         * For #2614.
         * @default false
         */
        ignoreBpmnColors?: boolean;
        /**
         * For #2468.
         * @default false
         */
        ignoreBpmnLabelStyles?: boolean;
    };

The most urgent decision must be taken to finalize the implementation of #2614

Guidelines

• use plural for properties
• for all properties related to ignoring data from the BPMN source, start with ignoreBpmn

Questions

• for the defaults property
  • the fill, font, stroke types may be shared with the types used in the "Update Style" API. However, this involves accepting the "default" value. What would that means here? the default value provided by the lib? This is the same issue as for [REFACTOR] Mutualize the programatic styling APIs of Shapes/Edges with that of Overlays #2457. We didn't see benefits for overlays, to be investigated for the default renderer options.
  • do we separate "general"/"shared" properties from the properties specific to dedicated BPMN elements?
  • do we really the "opacity" properties?

We may introduce a bpmnIgnores that holds all "ignored" properties. This seems overkill for 3 properties

// new property in GlobalOptions
  renderer: {
    bpmnIgnores: {
      activityLabelBounds
      colors: ....
      labelStyles: ....
    }
  }

past proposed names for #718

• forceHorizontalBlackBoxPool

past proposed names for #2614

• ignoreBpmnColors - singular or plural?
• ignoreModelColors
• ignoreBpmnInColor - name of the specification
• ignoreBpmnModelColor(s) - do we really need to mention BPMN here as we manipulate BPMN model only?
  Le