[818] Contribute the ADR about a more structured selection

Bug: #818
Signed-off-by: Guillaume Coutable <[email protected]>

doc/adrs/036_structured-selection.adoc

@@ -0,0 +1,91 @@
+= ADR-036 - Adopt more structured selection
+
+== Context
+
+The selection is one of the core element of our workbench. The selection can handle elements with different natures, which need to be handled in specific ways: semantic elements, documents, representations, or others.
+This "nature" is encoded in the `Selection.kind` field, which is a string.
+Currently every part of the code which has to deal with the selection must be aware of what kind of selection can occur and the corresponding format of the `Selection.kind` field:
+* `Document` represents a top-level element (mapped into an EMF `Resource`);
+* `Diagram` or `Form` indicate a representation;
+* anything else is assumed to represent a semantic element and to be in the format `domain::Type`.
+* soon enough, the selection will have to deal with graphical elements.
+The selection can handle elements with different natures, but it can handle one entry at a time.
+
+A lot of our comming features especially https://github.com/eclipse-sirius/sirius-components/issues/692[issue #692] or Sirius Components extensions/applications, will leverage on more generic implementation of the Selection, and thus, suppose it can no longer have hard-coded knowledge of the ad-hoc values and format we currently use for `Selection.kind` as well as, the selection must support multiple selection.
+We need a well-defined format for this field which will scale as more kinds of selection are added, including by Sirius Components extensions/applications which do not know about each others (without creating conflicts).
+
+== Decision
+
+=== URI for selection kind
+
+We will standardise on a more structured and extensible format for selection kinds, which will be _extensible_ with their own types by Sirius Component-based applications and be more structured/parseable.
+The syntax is inspired by URIs (which makes them parseable with standard APIs):
+
+[]
+----
+source://type?attribute1=value1&attribute2=value2
+----
+
+Where:
+* `source` is a unique identifier of the application which defines this particular kind of selection. The source value `sirius` is reserved for selection kinds defined in Sirius Web (or Sirius Components) itself.
+* `type` indicates what type of element is represented by the selection, for example, `diagram`.
+* additional key/value pairs can be added as needed to provide more details depending on the type of element.
+
+With this syntax, the selection item kinds would become:
+
+[Attributes]
+|===
+|Previous syntax | New syntax
+
+|`Document`
+|`sirius://document`
+
+|`Diagram`
+|`sirius://representation?type=diagram`
+
+|`Form`
+|`sirius://representation?type=form`
+
+|`flow::System`
+|`sirius://semantic?domain=flow&type=System`
+
+|===
+
+It will also be possible to define new kinds of selection, for example to support the graphical selection :
+`sirius://graphical?representationId=[id]&nodeId=[id]`
+
+A Sirius-based application which provides its own kind of items unknown to Sirius itself will use its own prefix.
+For example: `myapp://user?accessLevel=admin`, `otherapp://requirement?priority=1`.
+
+Sirius-based applications which contribute new kind of representations *MUST* use the `sirius://representation` kind, with their of custom value for `type`.
+
+=== Add the support for multi-selection
+
+The structure of the selection will support selection entries:
+[]
+----
+export type Selection = {
+  entries: SelectionEntry[];
+}
+
+export type SelectionEntry = {
+  id: string;
+  label: string;
+  kind: string;
+}
+----
+
+With this structure, it will be possible to select many semantic elements, many representations or even, a mix of both element kinds.
+
+Each workbench components is independent and will handle by themselves how they deal with the multiple selection. For example, when many semantic elements are selected, the detail view will display properties of the first selected semantic element. The selection could also be made of many representations, in such case, representations will be opened as they were added to the selection.
+
+In a near future, once the selection of graphical elements will be supported, we could consider that selecting a graphical element will also select its associated semantic element. It will let the semantic properties as well as the graphical properties be displayed at the same time.
+
+== Consequences
+
+We need to update all the existing code (both on the frontend and backend) which uses the previous syntax to match the new one.
+Some of the most important change are:
+- when an element is selected after it has been created (CreateObjectModal);
+- when a subscription is base on the selection (PropertiesWebsocketContainer);
+- or when the user want to select an element in the explorer (TreeItem).
+