From 4cbaabd9fca26ef4ee6c188923bc87b92b9ea329 Mon Sep 17 00:00:00 2001 From: Jerome Gout Date: Tue, 10 Sep 2024 15:05:50 +0200 Subject: [PATCH] [doc] Add support for styled labels in view model for trees Signed-off-by: Jerome Gout --- CHANGELOG.adoc | 1 + ...styled_labels_in_view_model_for_trees.adoc | 104 ++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 doc/adrs/158_add_support_for_styled_labels_in_view_model_for_trees.adoc diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 0eb5c676a1b..0d19295e217 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -7,6 +7,7 @@ === Architectural decision records +- [ADR-158] Add support for styled labels in view model for trees === Deprecation warning diff --git a/doc/adrs/158_add_support_for_styled_labels_in_view_model_for_trees.adoc b/doc/adrs/158_add_support_for_styled_labels_in_view_model_for_trees.adoc new file mode 100644 index 00000000000..039abf5c35f --- /dev/null +++ b/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 + foregroundColorExpression: InterpretedExpression + backgroundColorExpression: InterpretedExpression + isUnderlineExpression: InterpretedExpression + isBoldExpression: InterpretedExpression + isItalicExpression: InterpretedExpression +} +``` + +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 + fragments: StyledLabelFragment [1..*] +} + +StyledLabelFragment { + labelExpression: InterpretedExpression + 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