[doc] Add support for styled labels in view model for trees

Signed-off-by: Jerome Gout <[email protected]>

CHANGELOG.adoc

@@ -7,6 +7,7 @@
 
 === Architectural decision records
 
+- [ADR-158] Add support for styled labels in view model for trees
 
 === Deprecation warning
 

doc/adrs/158_add_support_for_styled_labels_in_view_model_for_trees.adoc

@@ -0,0 +1,104 @@
+= ADR-158 - Add support for styled labels in view model for trees
+
+== Context
+
+Currently, the tree description supports the ``StyledString`` in tree item label but no styles are given through the view model definition of trees.
+
+== Decision
+
+We need to update the tree view DSL to allow specifier to express how labels should be stylized.
+We need also to enhance the way the italic and bold style is managed because it is suitable to be used in the view DSL.
+
+=== Tree view DSL
+
+Currently, the tree view DSL, ``TreeDescription`` only has the ``treeItemLabelExpression`` that returns the string to display regarding the given ``self`` element.
+In addition to that expression, we will add two new owned properties.
+
+```
+TreeDescription {
+  ...
+  stylePalette: StylePalette [1..1]
+  labelStyles: ConditionalStyledLabel [0..*]
+  ...
+}
+```
+The first additional owned property (``stylePalette``) holds all text styles that are defined in this tree specification. 
+This is a sort of catalog of all defined style that could be used (or not) for a particular tree item label (or one of its part).
+We do prefer wrap all text styles in a dedicated property to avoid to mix them with other part of the tree specification (such as menu actions in a further work).
+A similar approach has been followed for storing colors in a palette inside diagrams specification.
+This property will be automatically created for each tree specification.
+
+The second owned property (``labelStyles``) is the actual set of styles that are used for displaying labels in this tree specification.
+
+```
+StylePalette {
+  textStyles : TextStyleDescription [0..*]
+}
+
+TextStyleDescription {
+  name: Identifier
+  fontNameExpression: InterpretedExpression<string>
+  foregroundColorExpression: InterpretedExpression<string>
+  backgroundColorExpression: InterpretedExpression<string>
+  isUnderlineExpression: InterpretedExpression<boolean>
+  isBoldExpression: InterpretedExpression<boolean>
+  isItalicExpression: InterpretedExpression<boolean>
+}
+```
+
+The above style description allows to specify a set of text style details.
+Such a description is named for clarity sake and is referenced inside conditional styled labels via their fragments.
+The ``fontNameExpression`` should return the name of the font to use.
+The color of the label fragment is specified through both ``foregroundColorExpression`` and ``backgroundColorExpression``.
+The string returned by those expressions should be compliant with a CSS color (e.g. ``#rrggbb``).
+The ``isUnderlineExpression`` should return whether this fragment is underlined or not.
+By design, we narrow the expressivity of the underline style to a solid line with the same color as expressed by the ``foregroundColorExpression`` expression.
+The ``isBoldExpression`` and ``isItalicExpression`` expressions respectively control the bold and italic style of this fragment.
+Those three last expressions should be evaluated in a boolean.
+
+```
+ConditionalStyledLabel {
+  name: Identifier
+  conditionExpression: InterpretedExpression<boolean>
+  fragments: StyledLabelFragment [1..*]
+}
+
+StyledLabelFragment {
+  labelExpression: InterpretedExpression<string>
+  style: TextStyleDescription (reference)
+}
+```
+
+The styles applied to labels (or portions of label) are named and conditional and they hold an ordered list of styled label fragments.
+In case the evaluation of its ``conditionExpression`` returns ``false`` no one of embedded fragments will be considered and an unstyled label will be used using the ``treeItemLabelExpression`` result.
+If ``conditionExpression`` returns ``true``, fragments are considered in the specified order.
+Each of them specifies the style of a sub-part of the label. 
+The ``labelExpression`` of the fragment should return the string itself and the style to apply is given through the reference of an actual TextStyleDescription through the ``style`` property.
+
+=== Backend
+
+As far as ``isBoldExpression`` and ``isItalicExpression`` expressions are concerned, we need to add two boolean flags in the class ``StyledStringFragmentStyle`` to handle those style features.
+``org.eclipse.sirius.components.emf.services.StyledStringConverter`` should also be updated to set those flags to ``false`` as the default value since this features are not present in EMF edit styles.
+
+The graphQL type ``StyledStringFragmentStyle`` in trees/tree.graphqls should be updated with new flags to be able to retrieve those style features in the frontend code.
+
+``ViewTreeDescriptionConverter`` should be updated to take into account the ``treeItemStyledLabel`` property from the view description.
+The function passed to the ``treeItemLabelProvider`` of the tree description should be changed to return the correct ``StyledString`` according to the evaluation of the ``conditionExpression`` of the ``treeItemStyledLabel``. 
+If the condition is not valid, we need to build the StyledString from the ``treeItemLabelExpression`` evaluation, otherwise it is built using contained fragments.
+
+=== Frontend
+
+The type ``GQLStyledStringFragmentStyle`` should be updated to reflect the change in the graphQL type in the backend code.
+The StyledLabel react component should be updated to handle new bold and italic style contained in the fragments.
+
+== Status
+
+Work in progress
+
+== Consequences
+
+The ``org.eclipse.sirius.components.emf.services.StyledStringConverter`` class which is in charge of converting an EMF style into a Sirius web one might have to be updated in the future.
+We suspect that the URI of the font may contain flags for expressing the bold or italic style.
+If this is verified, extraction of that information from the URI to the new flags should have to be made.
+
+== References