[FEAT] Reset style per property with the "Update Style" API

[tbouffard]

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

#1030 introduces the "Update Style" API, which lets modify/update the style of a BPMN element by passing one or several properties.
#2458 lets reset the whole style of the BPMN element i.e. all properties of the style of the element are reset to their initial value.

However, there are some use cases were users would like to reset only one or a subset of the properties.
For example:

• 1st change the stroke width, stroke color and the fill color for a first scenario
• then we want to apply a gradient with a new fill color but restore the stroke width and change the stroke color

Describe the solution you'd like

Let pass a special string keyword as value of the StyleUpdate properties to reset one or several properties to the initial value.

My suggestion is to use our own keyword and not use the mxGraph keyword ('none') to better express the intent of this value.
Possible values (non exhaustive list, to be discussed prior starting the implementation): 'reset', 'default', 'unset'.

Tasks

Documentation and tests

Preview Give feedback

1. Choose which string keyword that the "Update Style"" API will support to reset a style property. Decision: default
2. JSDoc about how to reset the value on all properties that support it
3. JSDoc special information for gradient. Fill color must be set for activation otherwise acts like unset. Will be done in [FEAT] Add support for fill color gradient in the Update Style API #2559
4. JSDoc warning for the font property that cannot be reset
5. Add tests: only integration tests (update some styles, check update in mxGraph model, reset some style properties, check mxGraph model)

Notes: how mxGraph style properties can be reset?

First, here is how mxGraph styles are configured and resolved

• StyleConfigurator: default style properties by BPMN kind to follow the BPMN specification
• Specific style properties depending on Layout/View/ BPMNDI information the BPMN diagram
• Resolution initial/reference: merge defaults + specific with priority to the specific properties

Update style API: set specific style properties

mxGraph style property reset: set it to null, undefined or 'none'. In this case, the style resolution only use the property from the referenced default styles.
Regarding the properties that can be updated with the "Update Style" API, most of them are initially set in the the BPMN kind default styles.

Fonts style

Only the style properties related to the font (coming for the LabelStyle data in the BPMNDI) are initially set. This is because they are specific to the element.
This means that if we use the "mxGraph style property reset", we will remove the initial font style. So, we cannot use it for fonts.
However, this would work for use cases where the LabelStyle of the BPMN diagram is ignored, see #2468.
This could be done by restoring a stored value in cache like what we consider for the global reset, see #2558.

This seems to complicated for now. We won't support reset for the font property for now.

Gradient

The gradient property will be supported with #2559.
The gradient is enabled if the fill color and the gradient properties are set (not null, nor equal to 'none'). See the mxShape code.

This should be explain in the JSDoc, in particular, some BPMN elements doesn't define a fill color by default, so reset the fill color will also remove the gradient.

How-to reset the mxGraph style properties

The style properties are stored as a concatenated string. Changing the properties means parsing and updating this string.

If we want to implement parsing ourselves, filtering consists in removing the part of the style string that begins with style_key=. It could be implemented with the following function:

const removeStyleKey = (style: string, key: string): string =>
  style
    ?.split(';')
    .filter(value => !value.startsWith(`${key}=`))
    .join(';');

The above implementation is inspired from mxUtils.removeStylename and mxUtils.removeStylenames.

However, the mxUtils.reset function can already handles this for us. To reset the property, we can pass 'none' or null for the value parameter. '' (empty string) could also be passed.
See the mxUtils.setStyle documentation.

This is typically what we avoid to do when the StyleUpdate object doesn't contains a property. We don't call the setStyle function, otherwise it would have unset/reset the style property.

bpmn-visualization-js/src/component/mxgraph/GraphCellUpdater.ts

Lines 90 to 92 in 94cef15

	// Only set the style when the key is set. Otherwise, mxGraph removes the related setting from the cellStyle which is equivalent to a reset of the style property
	styleUpdate?.stroke?.color && (cellStyle = mxgraph.mxUtils.setStyle(cellStyle, mxgraph.mxConstants.STYLE_STROKECOLOR, styleUpdate.stroke.color));
	this.graph.model.setStyle(cell, cellStyle);

So, instead of passing the StyleUpdate value, we could call a function that transform the value if it is equal to the 'default' keyword value (and left it unchanged otherwise) and pass the result to the mxUtils.setStyle function. This will be very easy to implement.

Notice that we already rely on this mxUtils.setStyle behavior in the bpmn-visualization-pm4py demo. See https://github.com/process-analytics/bpmn-visualization-pm4py/blob/74a248d432c21bb4a1e6a8caeed77d0af5b07f74/frontend/src/conformance.js#L33-L39

Calling mxUtils.setStyle with null or 'none' value could be temporary used in the demo until we have the global reset API. See #2558.