[3653] Add documentation for Gantt

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

CHANGELOG.adoc

@@ -5,6 +5,7 @@
 === Shapes
 
 - Add support for text alignment on labels
+- Add support for gantt representation
 
 === Architectural decision records
 
@@ -102,6 +103,7 @@ image:doc/screenshots/insideLabelPositions.png[Inside label positions, 70%]
 - https://github.com/eclipse-sirius/sirius-web/issues/3606[#3606] [test] Improve error handling in ExecuteEditingContextFunctionRunner and ExecuteEditingContextFunctionEventHandler
 - https://github.com/eclipse-sirius/sirius-web/issues/3561[#3561] [diagram] Add support for background and border on diagram labels
 - https://github.com/eclipse-sirius/sirius-web/issues/3604[#3604] [diagram] Make node overlap resolution faster during "Arrange All"
+- https://github.com/eclipse-sirius/sirius-web/issues/3653[#3653] [gantt] Add documentation for gantt representation
 
 == v2024.5.0
 

doc/specifier/representation-gantt.adoc

@@ -0,0 +1,127 @@
+# Gantt representation description
+
+This chapter explains how to configure a `Gantt` representation in the `View` model.
+
+A `Gantt` representation is made of a hierarchy tasks.
+
+* A task can contain sub-tasks.
+* A task can be linked to another task with a dependency relation.
+
+Each `Task` is associated with a semantic element that is an object of the model.
+
+image::images/gantt-overview.png[Gantt representation overview]
+
+## Gantt description
+
+To define how your model is represented with a `Gantt` representation, the specifier needs to create a `GanttDescription` in the `View` model.
+
+image::images/gantt-description-overview.png[Gantt description overview]
+
+* `Name`: A name that helps the specifier to know what the GanttDescription is about
+* `Domain Type`: Type of the object on which it is possible to create the representation 
+* `Precondition Expression`: An expression that determines if it is possible to create the representation
+** `self` variable is the semantic element associated with the `Gantt`.
+* `Title Expression`: The initial name of the representation once created
+** `self` variable is the semantic element associated with the `Gantt`.
+* `Date Rounding Expression`: An expression that returns a string that is a time duration that will define how the date is rounded when changing the date from the Gantt representation.
+The string contains 
+** an integer which is the number of time unit.
+** a character among {D,H,m} corresponding to a Day, Hour or minute time unit.
+Example: to round to half a day, the expression must returns `12H`
+
+## Task description
+
+The `TaskDescription` is used to define the direct tasks of its parent in the tasks hierarchy.
+It can be the root tasks in the Gantt or the sub-tasks in a task.
+
+* `Name`: A name that helps the specifier to know what the TaskDescription is about
+* `Semantic Candidates Expression`: An expression that returns one or more semantic elements.
+Each semantic element will be represented by a task.
+** `self` variable is the semantic element associated with the `Gantt`.
+* `Domain Type`: Type of the object used to filter the semantic object represented by a task 
+
+All the following expressions are called as many times as the number of semantic elements returned by the `Semantic Candidates Expression`.
+`self` variable is the current semantic element.
+
+* `Name Expression`: An expression that defines the name of the task
+* `Description Expression`: An expression that defines the description of the task
+* `Start Time Expression`: An expression that returns a `java.time.Instant` to define the start date of the task.
+* `End Time Expression`: An expression that returns a `java.time.Instant` to define the end date of the task.
+* `Progress Expression`: An expression that returns an integer between 0 and 100 to define the percentage progress of the task.
+* `Compute Start End Dynamically Expression`: An expression that returns a boolean.
+If true and if the task contains sub-tasks, the start and end dates displayed in the Gantt are computed from the sub-tasks.
+The start date(respectively the end date) is the lower(respectively upper) date of the sub-tasks dates.
+* `Task Dependencies Expression`: An expression that returns a list of semantic elements to define dependency relations between the current task and the tasks associated the returned semantic elements.
+
+### Task description as sub task
+
+To define tasks as the second level of the tasks hierarchy, create a `TaskDescription` in the `TaskDescription`.
+
+It is also possible to reuse `TaskDescription` so that it is possible to define a recursive definition.
+Use `Reused Task Element Descriptions` field to select existing `TaskDescription`. 
+
+## Tools
+
+Many tools can be configured for `Task`.
+All the tools are created under `GanttDescription`.
+Note that, by default, a tool does nothing.
+You need to add operations in the tool to make changes in the semantic model.
+Typical operations:
+
+* `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
+
+Each tool gives access to variables that can be used in the expression of the tools.
+When the tool is executed, the system will set the variables(that depends on the execution context of the tool) and executes the operations associated with the tool.
+
+image::images/gantt-tools.png[Gantt tools]
+
+### Task tools
+
+* `Create Task Tool`: This tool defines the behavior when the user creates a task using the button in the task contextual palette in Gantt.
+Available variables:
+** `self`: The semantic element associated with the selected Task
+* `Delete Task Tool`: This tool defines the behavior when the user deletes a task using the button in the task contextual palette in Gantt. 
+Available variables:
+** `self`: The semantic element associated with the selected Task
+
+image::images/gantt-task-tools.png[Task palette tools]
+
+
+* `Edit Task Tool`: This tool defines the behavior when the user uses the handles to change start or end dates or the progress.
+Available variables:
+** `self`: The semantic element associated with the selected task.
+** `newName`: The new value of the name.  
+** `newStartTime`: The new value of the start time.  
+** `newEndTime`: The new value of the end time.  
+** `newDescription`: The new value of the description.  
+** `newProgress`: The new value of the progress.  
+
+image::images/gantt-task-handlers.png[Task handlers]
+
+
+* `Drop Task Tool`:
+This tool defines the behavior when dragging and dropping, in the table part of Gantt, a task before, after or inside another task.
+Available variables:
+** `sourceObject`: The semantic element associated with the dragged task
+** `targetObject`: The semantic element associated with the target task where the task is dropped.
+** `sourceTask`: The dragged `Task`.
+** `targetTaskOrGantt`: The target where the task is dropped.
+It can be `Gantt` or another `Task`.
+** `indexInTarget`: The index of the dropped task inside the new list of tasks where it is dropped.
+index=0 means first position.
+
+### Dependency tools
+
+* `Create Task Dependency Tool`:
+This tool defines the behavior when creating a task dependency by dragging the dependency handler from one task to another.
+Available variables:
+** `sourceObject`: The semantic element associated with the task from which the dependency link is initiated.
+** `targetObject`: The semantic element associated with the target task where the dependency finishes.
+
+image::images/gantt-task-relation-tool.png[Create Task Dependency Tool]
+

doc/user/representation-gantt.adoc

@@ -0,0 +1,108 @@
+# Gantt representation
+
+A `Gantt` representation is made of a hierarchy tasks.
+Each task can contain sub-tasks.
+
+The left part is a table.
+Each row represents a task.
+The columns of the table provide information about the task.
+
+The right part is the Gantt itself.
+Each row displays a task.
+A task can be linked to another task with an arrow to represent a dependency relation.
+
+image::images/gantt-overview.png[Gantt representation overview]
+
+## Gantt display
+
+There are 3 types of task:
+
+* The basic task
+
+image::images/gantt-task.png[Gantt task]
+A color shows the progress value of the task.
+Fully colored mean 100%.
+
+* The group task that is a task which contains sub-tasks
+
+image::images/gantt-task-group.png[Gantt group]
+A color shows the progress value of the task in the bottom part.
+Depending on how the `TaskDescription` is configured in the `View` model, the task group may be either *computed from its sub-tasks* or defined independently as a basic task.
+In the former case, the start(respectively end) date is the minimal start(respectively maximal end) date of the sub-tasks and the progress is a weighted average of the sub-tasks progress.
+
+* The milestone represents a date. 
+
+image::images/gantt-task-milestone.png[Gantt milestone]
+
+A task can have a list of dependencies to other tasks.
+The dependencies are represented by an arrow between two tasks oriented from the dependency to the dependant task.
+
+image:images/gantt-task-dependencies.png[Task Dependencies]
+
+## Gantt Toolbar
+
+image::images/gantt-toolbar.png[Gantt Toolbar]
+
+* `Toggle full screen mode`: It allows to display the representation in full screen
+* `Zoom level`: Choose the time unit in the Gantt (Hour, Half Day, Day, Two Days, Week, Month, Year)
+* `Zoom in`
+* `Zoom out`
+* `Fit to screen`: Set the zoom level that allows to display all the tasks
+* `Display columns`: Allow to hide all the columns in a click.
+Using the drop down combo, the user chooses the displayed columns.
+The displayed columns are persisted in the Gantt representation.
+* `Share`: Provide an URL that reaches directly the current Gantt representation
+
+## Selection
+
+When selecting a `Task` in Gantt or in the Table, the associated semantic element is selected in the `Explorer` and its properties are displayed in `Details`.
+
+## Edition
+
+### Task attributes
+
+Using handlers on the task, it is possible to change the start/end dates and the progress.
+Clicking on the task and moving it left or right, allows to shift the date keeping the same duration.
+
+image:images/gantt-task-handlers.png[Show/Hide Cards]
+
+When changing a date, the date is rounded accordingly to the `Date Rounding Expression` define in the `GanttDescription`.
+Holiday is set as Saturday and Sunday. If the rounded date is part of the holiday, it is moved to the next or previous working date.
+Note that a date rounded greater than two days is not adjusted to the working days.
+
+### Task dependency relation
+
+Using the round handler next the task allows to create a dependency relation.
+
+image:images/gantt-task-dependency-tool.png[Task Dependency Tool]
+image:images/gantt-task-dependency.png[Task Dependency]
+
+
+### Task reordering
+
+From the table, it is possible to drag and drop a Task to reorder the task or change its container.
+
+image:images/gantt-task-dragdrop.png[Task Drag and Drop]
+
+* To reorder, drop the task before or after another.
+* To change its container, drop the task on another task.
+
+Note that it is not possible to drop a task in its own children hierarchy.
+
+
+## Table
+
+The table is made of rows and columns.
+There is one row per task.
+
+The first column presents the hierarchy of tasks. 
+It shows the name of the task and optionally an icon to expand/collapse the sub-tasks.
+The *expand status is persisted* in the Gantt representation.
+
+The other columns display the start/end dates and the progress.
+
+The columns can be resized and *the column width is persisted* in the Gantt representation.
+From the Gantt toolbar, the columns can be hidden (See 'Gantt toolbar' section).
+
+
+