[doc] Add shape for supporting selections in URLs

Bug: eclipse-sirius#4376
Signed-off-by: Florent Latombe <[email protected]>

CHANGELOG.adoc

@@ -12,6 +12,7 @@
 - Add impact analysis before tool execution
 - Add support for artifact publication from a project
 - Improve image export
+- Add project elements selection to URLs
 
 
 === Architectural decision records

doc/iterations/2025.2/add_project_elements_selection_to_urls.adoc

@@ -0,0 +1,89 @@
+= (M) Add project elements selection to URLs
+
+== Problem
+
+Currently, Sirius Web has URLs for projects `+https://example.org/projects/project-id/edit+` and their representations `+https://example.org/projects/project-id/edit/representation-id+`.
+
+But there are no URLs that can be used to designate a selection of *project elements* (_models_ and/or _representations_ and/or _semantic elements_).
+This possibility would be useful for documentation and collaboration purposes.
+
+== Key Result
+
+End users shall be able to create links that include a selection of project elements.
+
+=== Acceptance Criteria
+
+- End users can easily obtain a URL from their current selection of project elements in the workbench.
+- When resolving a URL that specifies a selection, the specified project elements automatically get selected in the workbench.
+
+== Solution
+
+- The current URL will change based on the selection made in the workbench.
+- The identifiers of the selected project elements will be stored in the URL in parameter _selection_.
+- The order of the project element identifiers in the URL reflects the order of the project elements in the selection.
+- A project element may appear several times in the selection.
+  This is for instance the case if several different graphical elements in a representation represent the same semantic element.
+- Upon resolving a URL with parameter _selection_, the workbench selection is set to the specified project elements.
+The resulting behavior may depend largely on how the workbench and its sections decide to implement this behavior.
+- In the default workbench, the selection will be dispatched to the _Representation Editor_ (if opened), or otherwise to the _Explorer_ view.
+- In both the _Explorer_ view and the _Representation Editor_, selecting a semantic element means selecting all the graphical elements whose _target_ is that semantic element.
+In particular, this means there may be a lot of graphical elements that end up selected, because representations may include any number of graphical elements to represent a single semantic element.
+
+=== Scenario 1 : Obtaining the URL from a workbench selection
+
+- The end user is in a project.
+- If no representation is opened, the URL looks like `+https://example.org/projects/project-id/edit+`.
+- If a representation is opened, the URL looks like `+https://example.org/projects/project-id/edit/representation-id+`.
+
+The following behavior is the same in both cases.
+
+- The end user selects project elements.
+This can be done through any section of the workbench that supports selections: _Explorer_ view, _Representation Editor_, _Related Elements_ view, etc.
+
+- The selected elements can be:
+-- _Models_, e.g. the root elements in the _Explorer_ view.
+-- _Representations_, e.g. the _Explorer_ view displays them below their target element.
+-- _Semantic elements_, contained by a _model_ or a _semantic element_.
+-- _Graphical elements_, i.e. part of a representation.
+In that case, the intention is to capture in the selection their target semantic elements.
+
+- Upon selecting an element in the workbench, its corresponding project element identifier is retrieved, e.g. `+id_1+`.
+- The URL gets updated automatically in order to reflect the selection change, into either: 
+-- `+https://example.org/projects/project-id/edit?selection=id_1+`
+-- `+https://example.org/projects/project-id/edit/representation-id?selection=id_1+`
+- Upon selecting another element in the workbench, its corresponding project element identifier is retrieved and appended to the _selection_ parameter, which means the URL is updated to either:
+-- `+https://example.org/projects/project-id/edit?selection=id_1&id_2+`
+-- `+https://example.org/projects/project-id/edit/representation-id?selection=id_1&id_2+`
+- If selecting two graphical elements representing the same target semantic element, the following URLs are also possible:
+-- `+https://example.org/projects/project-id/edit?selection=id_1&id_1+`
+-- `+https://example.org/projects/project-id/edit/representation-id?selection=id_1&id_1+`
+
+=== Scenario 2 : Resolution of a URL containing the selection parameter
+
+- The URL path, whether it is a project or representation URL, is resolved as usual.
+  This means the specified project is opened, and if a representation is specified, it is opened in the representation editor.
+
+- The identifiers specified in the _selection_ parameter of the URL query are retrieved.
+  Based on these identifiers, we are able to retrieve the project elements that are meant to be selected.
+
+- The workbench selection is set to those elements.
+
+- The selection is revealed in the workbench.
+
+=== Breadboarding
+
+N/A
+
+=== Cutting backs
+
+N/A
+
+== Rabbit holes
+
+- When setting up the workbench selection programmatically, we have to make sure that as a result of the selection changing, the URL does not get updated automatically.
+We do not want the selection and/or the URL to flicker.
+- Project element identifiers are rather long so our URLs might end up being very long. We may need to encode the selection in order to make it shorter.
+
+== No-gos
+
+N/A