[3220] Add documentation for Deck

Bug: #3220
Signed-off-by: Laurent Fasani <laurent.fasani@obeo.fr>
Signed-off-by: Florian ROUËNÉ <florian.rouene@obeosoft.com>

CHANGELOG.adoc

@@ -182,6 +182,7 @@ In other scenarios, the default creation position border remains the eastern one
 - https://github.com/eclipse-sirius/sirius-web/issues/2785[#2785] [gantt] Add cypress tests
 - https://github.com/eclipse-sirius/sirius-web/issues/3225[#3225] [sirius-web] The confirmation dialog on delete does not propose anymore the option allowing to "Disable this confirmation dialog" when the local storage is not available.
 - https://github.com/eclipse-sirius/sirius-web/issues/3246[#3246] [view] Make the `ViewRepresentationDescriptionSearchService` independent from specific representations
+- https://github.com/eclipse-sirius/sirius-web/issues/3220[#3220] [deck] Add documentation
 
 == v2024.1.0
 

doc/specifier/representation-deck.adoc

@@ -0,0 +1,132 @@
+# Deck representation description
+
+This chapter explains how to configure a `Deck` representation in the `View` model.
+
+A `Deck` representation is composed with many `Lanes` containing many `Cards`.
+Each `Lane` and `Card` is associated with a semantic element that is an object of the model represented by a `Deck` representation.
+
+image::images/deck-overview.png[Deck representation overview]
+
+## Deck description
+
+To define how your model is represented with a `Deck` representation, the specifier needs to create a `DeckDescription` in the `View` model.
+
+image::images/deck-description-overview.png[Deck description overview]
+
+* `Name` : A name that helps the specifier to know what the DeckDescription is about
+* `Domain Type`: Type of the object on which it is possible to create the representation 
+* `Precondition Expression`: An expression that determine if it is possible to create the representation
+* `Title Expression`: The initial name of the representation once created
+
+### Deck style
+
+It is possible to define the *background color* of the `Deck` representation by adding a `StyleDescription` in the `DeckDescription`.
+
+In addition, adding a `ConditionalStyleDescription` allows to override the style if the `Condition` expression returns `true`.
+You may add multiple `ConditionalStyleDescription`.
+
+## Lane description
+
+The `LaneDescription` is used to define the lanes.
+
+image::images/deck-lane.png[Deck lane]
+
+* `Semantic Candidates Expression`: An expression that returns one or more semantic elements.
+Each semantic element will be represented by a lane.
+** `self` variable is the semantic element associated with the `Deck`.
+* `Title Expression`: An expression that defines the title of the lane
+** `self` variable is a semantic element among the list returned by the `Semantic Candidates Expression`
+* `Label Expression`: An expression that defines the label of the lane
+* `Is Collapsible Expression`: An boolean expression.
+If true, it is possible to collapse the lane hence hiding all the contained cards.
+
+### Lane style
+
+It is possible to define the style of the lane by adding a `StyleDescription` in the `LaneDescription`.
+The customizable attributes are
+
+* Font Size
+* Italic, Bold, Underline and Strike Through
+* The text color
+* The background color of the lane
+
+In addition, adding a `ConditionalStyleDescription` allows to override the style if the `Condition` expression returns `true`.
+You may add multiple `ConditionalStyleDescription`
+
+## Card description
+
+The `CardDescription` is used to define the card inside a lane.
+
+image::images/deck-card.png[Deck card]
+
+* `Semantic Candidates Expression`: An expression that returns one or more semantic elements.
+Each semantic element will be represented by a `Card`.
+** `self` variable is the semantic element associated with the `Lane`
+* `Title Expression`: An expression that defines the title of the card 
+** `self` variable is a semantic element among the list returned by the `Semantic Candidates Expression`.
+* `Label Expression`: An expression that defines the label of the card
+* `Description Expression`: An expression that defines the description of the card
+
+### Card style
+
+As for `LaneDescription`, it is possible to define the style of the card by adding a `StyleDescription` or one or more `ConditionalStyleDescription` in the `CardDescription`.
+
+## Tools
+
+Many tools can be configured for `Lane` and `Card`.
+By default, a tool does nothing.
+A tool provides access to variables useful in the context of the tool and executes the operations associated with the tool.
+Typical operation:
+
+* `Change Context`: It allows to change the `self` value.
+But typically this operation is useful if you just want to call a java service that will implement the tool behavior.
+* `Create Instance`: Creates a semantic object and add it in the defined feature of the `self` semantic element
+* `Set Value`: Sets the value on a given feature on `self` semantic element
+* `Delete Element`
+* etc
+
+### Lane tools
+
+* `Lane Drop Tool`:
+This tool defines the behavior when dragging and dropping a lane before or after another lane.
+Available variables:
+** `self`: The semantic element associated with the dropped lane
+** `index`: The new index of the dropped lane.
+First position corresponds to zero and last position corresponds to the number of lanes.
+
+
+* `Edit Lane Tool`: This tool defines the behavior when the title of a lane is changed.
+Available variables:
+** `self`: The semantic element associated with the dropped lane
+** `newTitle`: The new value of the title.  
+
+### Card tools
+
+* `Create Card Tool`: This tool defines the behavior for the button to add a card.
+Available variables:
+** `self`: The semantic element associated with the lane
+** `title`: The value of the title.  
+** `description`: The value of the description.  
+** `label`: The value of the label.  
+
+* `Edit Card Tool`: This tool defines the behavior when the title, description or label of a card is changed.
+Available variables:
+** `self`: The semantic element associated with the dropped lane.
+** `newTitle`: The new value of the title.  
+** `newDescription`: The new value of the description.  
+** `newLabel`: The new value of the label.  
+
+* `Delete Card Tool`: This tool defines the behavior for the delete button on a card.
+Available variables:
+** `self`: The semantic element associated with the card
+
+* `Card Drop Tool`: This tool defines the behavior when dragging and dropping a card among cards of the same or other lane.
+Available variables:
+** `self`: The semantic object associated with the card
+** `oldLane`: The initial lane from which the card is dragged
+** `oldLaneTarget`: The semantic object associated with the initial lane
+** `newLane`: The lane where the card is dropped
+** `newLaneTarget`: The semantic object associated with the new lane
+** `index`: Index of the card among the cards of the new lane.
+First position corresponds to zero and last position corresponds to the number of cards in the lane.  
+

doc/user/representation-deck.adoc

@@ -0,0 +1,46 @@
+# Deck representation
+
+A `Deck` representation is composed with many `Lanes` containing many `Cards`
+Each `Lane` and `Card` is associated to a semantic element that is an object of the model represented by a `Deck` representation.
+
+image::images/deck-overview.png[Deck representation overview]
+
+## Deck Toolbar
+
+image::images/deck-toolbar.png[Deck Toolbar]
+
+* `Toggle full screen mode` : It allows to display the representation in full screen
+* `Fit to screen`: Adjust the zoom level to the size of the editor
+* `Zoom in`
+* `Zoom out`
+* `Reset zoom`: Set the zoom level to default
+* `Share`: Provide an URL that reaches directly the current Deck representation
+
+## Selection
+
+When selecting a `Lane` or a `Card`, the associated semantic element is selected in the `Explorer` and its properties are displayed in `Details`.
+
+## Edition
+
+To edit text area of a `Lane` or a `Card` first select and then click in the text area.
+You can also press `F2` to edit the title. Then you can press `Tab` key to edit next fields.
+
+The `Lane` editable attributes:
+
+* `Title`
+
+The `Card` editable attributes:
+
+* `Title`
+* `Description`
+* `Label`
+
+## Show/Hide cards
+
+image:images/deck-show-hide.png[Show/Hide Cards]
+
+You have the ability to show/hide individual cards or hide the whole cards of a lane using the expand button.
+
+## Moving lanes and cards
+
+According to how the `View` model has been configured, you can update the model by *dragging and dropping* Lane or Cards.

integration-tests/cypress/workbench/Deck.ts

@@ -140,7 +140,7 @@ export class Deck {
     { condition, backgroundColor, color, italic, bold, underline, strikeThrough, fontSize }: ElementStyleProps
   ) {
     const details = new Details();
-    const objectName = `${condition ? 'Conditional Styles Conditional Deck' : 'Style'} Element Description Style`;
+    const objectName = `${condition ? 'Conditional Style' : 'Style'} Description`;
     cy.createChildObject(elementName, objectName);
     details.openReferenceWidgetOptions('Background Color');
     details.selectReferenceWidgetOption(backgroundColor);
@@ -162,7 +162,7 @@ export class Deck {
 
   public createDeckRepresentationtyle(elementName: string, backgroundColor: string, condition?: string) {
     const details = new Details();
-    const objectName = `${condition ? 'Conditional Styles Conditional Deck' : 'Style'} Description Style`;
+    const objectName = `${condition ? 'Conditional Style' : 'Style'} Description`;
     cy.createChildObject(elementName, objectName);
     details.openReferenceWidgetOptions('Background Color');
     details.selectReferenceWidgetOption(backgroundColor);

integration-tests/cypress/workbench/Gantt.ts

@@ -80,7 +80,7 @@ export class GanttTestHelper {
   }
 
   /**
-   * Creates the Deck Task Sample view from the stereotype.
+   * Creates the Gantt Task Sample view from the stereotype.
    * @returns the created studio project id.
    */
   public initGanttView(): Cypress.Chainable<string> {

packages/deck/backend/sirius-components-deck/src/main/java/org/eclipse/sirius/components/deck/renderer/component/CardComponent.java

@@ -71,7 +71,7 @@ private Element doRender(VariableManager childVariableManager) {
         DeckElementStyle style = cardDescription.styleProvider().apply(childVariableManager);
 
         Optional<Card> optionalPreviousCard = this.props.previousCards().stream()
-                .filter(card -> card.targetObjectId().equals(targetObjectId))
+                .filter(card -> card.descriptionId().equals(cardDescription.id()) && card.targetObjectId().equals(targetObjectId))
                 .findFirst();
         String cardId = optionalPreviousCard.map(Card::id).orElse(UUID.randomUUID().toString());
         boolean visible = optionalPreviousCard.map(this::computeVisibility).orElse(true);

packages/deck/backend/sirius-components-deck/src/main/java/org/eclipse/sirius/components/deck/renderer/component/LaneComponent.java

@@ -71,7 +71,9 @@ private Element doRender(VariableManager childVariableManager) {
         String title = laneDescription.titleProvider().apply(childVariableManager);
         String label = laneDescription.labelProvider().apply(childVariableManager);
 
-        Optional<Lane> optionalPreviousLane = this.props.previousLanes().stream().filter(lane -> lane.targetObjectId().equals(targetObjectId)).findFirst();
+        Optional<Lane> optionalPreviousLane = this.props.previousLanes().stream()
+            .filter(lane -> lane.descriptionId().equals(laneDescription.id()) && lane.targetObjectId().equals(targetObjectId))
+            .findFirst();
         String laneId = optionalPreviousLane.map(Lane::id).orElse(UUID.randomUUID().toString());
         List<Card> previousCards = optionalPreviousLane.map(Lane::cards).orElse(List.of());
         List<Element> childrenElements = this.getChildren(childVariableManager, laneDescription, laneId, previousCards);

packages/starters/backend/sirius-components-task-starter/src/main/java/org/eclipse/sirius/components/task/starter/configuration/TaskExampleBuilder.java

@@ -21,6 +21,8 @@
 
 import org.eclipse.emf.ecore.EObject;
 import org.eclipse.sirius.components.task.Company;
+import org.eclipse.sirius.components.task.KeyResult;
+import org.eclipse.sirius.components.task.Objective;
 import org.eclipse.sirius.components.task.Person;
 import org.eclipse.sirius.components.task.Project;
 import org.eclipse.sirius.components.task.Task;
@@ -253,53 +255,60 @@ private Project createOKRProject(Person paul, Person peter) {
         Project okrProject = TaskFactory.eINSTANCE.createProject();
         okrProject.setName("OKR Project Dev");
 
-        List<TaskTag> okrTags = this.createOKRTags();
-        okrProject.getOwnedTags().addAll(okrTags);
+        Objective objectiveAppicationRunning = TaskFactory.eINSTANCE.createObjective();
+        objectiveAppicationRunning.setName("Have the application running");
+
+        KeyResult keyResultDevCompleted = TaskFactory.eINSTANCE.createKeyResult();
+        keyResultDevCompleted.setName("Dev completed");
+        keyResultDevCompleted.setDescription("The development is completed");
 
         Task idea = TaskFactory.eINSTANCE.createTask();
         idea.setName(IDEA);
         idea.setStartTime(Instant.parse(DATE_2023_12_10T08_30_00Z));
         idea.setEndTime(Instant.parse(DATE_2023_12_11T17_30_00Z));
         idea.setProgress(50);
-        idea.getTags().add(okrTags.get(0));
         Task spec = TaskFactory.eINSTANCE.createTask();
         spec.setName(SPECIFICATION);
         spec.setStartTime(Instant.parse(DATE_2023_12_11T08_30_00Z));
         spec.setEndTime(Instant.parse(DATE_2023_12_12T17_30_00Z));
         spec.setProgress(50);
         spec.getDependencies().add(idea);
-        spec.getTags().add(okrTags.get(0));
 
         Task development = TaskFactory.eINSTANCE.createTask();
         development.setName(DEVELOPMENT);
         development.setStartTime(Instant.parse(DATE_2023_12_13T08_30_00Z));
         development.setEndTime(Instant.parse(DATE_2023_12_16T17_30_00Z));
         development.getDependencies().add(spec);
-        development.getTags().add(okrTags.get(1));
 
         Task codeDev = TaskFactory.eINSTANCE.createTask();
         codeDev.setName(CODE_DEVELOPMENT);
         codeDev.setStartTime(Instant.parse(DATE_2023_12_13T08_30_00Z));
         codeDev.setEndTime(Instant.parse(DATE_2023_12_15T17_30_00Z));
         codeDev.getAssignedPersons().add(peter);
-        codeDev.getTags().add(okrTags.get(2));
 
         Task review = TaskFactory.eINSTANCE.createTask();
         review.setName(REVIEW);
         review.setStartTime(Instant.parse(DATE_2023_12_16T08_30_00Z));
         review.setEndTime(Instant.parse(DATE_2023_12_16T17_30_00Z));
         development.getSubTasks().addAll(List.of(codeDev, review));
         codeDev.getAssignedPersons().add(paul);
-        review.getTags().add(okrTags.get(3));
 
-        Task release = TaskFactory.eINSTANCE.createTask();
-        release.setName(RELEASE);
-        release.setStartTime(Instant.parse(DATE_2023_12_18T08_30_00Z));
-        release.setEndTime(Instant.parse(DATE_2023_12_18T08_30_00Z));
-        release.getTags().add(okrTags.get(3));
+        keyResultDevCompleted.getSubTasks().addAll(List.of(idea, spec, development));
+
+        KeyResult keyResultTestsOK = TaskFactory.eINSTANCE.createKeyResult();
+        keyResultTestsOK.setName("Tests passed");
+        keyResultTestsOK.setDescription("The tests are all passed");
+
+        Task manualsTest = TaskFactory.eINSTANCE.createTask();
+        manualsTest.setName("Manual Test Campaign");
+        Task automaticTests = TaskFactory.eINSTANCE.createTask();
+        manualsTest.setName("Automatic Test Checks");
+
+        keyResultTestsOK.getSubTasks().addAll(List.of(manualsTest, automaticTests));
 
+        objectiveAppicationRunning.getOwnedKeyResults().addAll(List.of(keyResultDevCompleted, keyResultTestsOK));
+        okrProject.getOwnedObjectives().addAll(List.of(objectiveAppicationRunning));
 
-        okrProject.getOwnedTasks().addAll(List.of(idea, spec, development, release));
         return okrProject;
     }
 
@@ -314,17 +323,6 @@ private List<TaskTag> createDailyTags() {
         return tags;
     }
 
-    private List<TaskTag> createOKRTags() {
-        List<TaskTag> tags = new ArrayList<>();
-        for (int i = 0; i <= 4; i++) {
-            TaskTag tag = TaskFactory.eINSTANCE.createTaskTag();
-            tag.setPrefix("OKR");
-            tag.setSuffix(String.format("Objective #%s", i));
-            tags.add(tag);
-        }
-        return tags;
-    }
-
     private List<TaskTag> createKanbanTags() {
         List<TaskTag> tags = new ArrayList<>();
         TaskTag tag = TaskFactory.eINSTANCE.createTaskTag();

packages/starters/backend/sirius-components-task-starter/src/main/java/org/eclipse/sirius/components/task/starter/configuration/TaskStereotypeDescriptionRegistryConfigurer.java

@@ -33,7 +33,7 @@ public class TaskStereotypeDescriptionRegistryConfigurer implements IStereotypeD
 
     private static final UUID TASK_EXAMPLE_ID = UUID.nameUUIDFromBytes("task_example".getBytes());
 
-    private static final String TASK_EXAMPLE_LABEL = "Task model example";
+    private static final String TASK_EXAMPLE_LABEL = "Task Model Sample";
 
     private static final String TIMER_NAME = "siriusweb_stereotype_load";