From 64bea30487553ccd8b253ddbf5dc03578690e86a Mon Sep 17 00:00:00 2001 From: Pierre-Charles David Date: Wed, 13 Apr 2022 09:02:19 +0200 Subject: [PATCH] [1139] Add ADR for the new tree widget in forms Bug: https://github.com/eclipse-sirius/sirius-components/issues/1139 Signed-off-by: Pierre-Charles David --- CHANGELOG.adoc | 10 ++- doc/adrs/052_add_tree_widget_in_forms.adoc | 92 ++++++++++++++++++++++ 2 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 doc/adrs/052_add_tree_widget_in_forms.adoc diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 1e0e5ecc6b..3af86ebe8e 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -6,12 +6,14 @@ - [ADR-50] Add support for multiple selection entries in the details view - [ADR-51] Add support for form descriptions in the View DSL +- [ADR-52] Add support for a tree widget in forms === Deprecation warning === Breaking changes -- https://github.com/eclipse-sirius/sirius-components/issues/1088[#1088] [core] Change the type of `IRepresentationDescription#id` from UUID to String. This will allow us, when we will receive an operation to perform with a given representation description identifier, to determine if this operation should be handled by the Sirius Desktop compatibility layer, the View support or by a programmatic API +- https://github.com/eclipse-sirius/sirius-components/issues/1088[#1088] [core] Change the type of `IRepresentationDescription#id` from UUID to String. +This will allow us, when we will receive an operation to perform with a given representation description identifier, to determine if this operation should be handled by the Sirius Desktop compatibility layer, the View support or by a programmatic API === Dependency update @@ -27,7 +29,11 @@ - https://github.com/eclipse-sirius/sirius-components/issues/1112[#1112] [explorer] Add support for Ctrl+click or ⌘+click to select multiple elements in the explorer - https://github.com/eclipse-sirius/sirius-components/issues/1116[#1116] [form] Add support for multiple selection entries in the details view -- https://github.com/eclipse-sirius/sirius-components/issues/1117[#1117] [diagram] Add support for multiple selections in a diagram. This work only display the various selection entries in the diagram. It does not support Ctrl+click or ⌘+click in a diagram. Support for this feature would require additional work with major improvements in the lifecycle of the `DiagramServer`` +- https://github.com/eclipse-sirius/sirius-components/issues/1117[#1117] [diagram] Add support for multiple selections in a diagram. +This work only display the various selection entries in the diagram. +It does not support Ctrl+click or ⌘+click in a diagram. +Support for this feature would require additional work with major improvements in the lifecycle of the `DiagramServer`` +- https://github.com/eclipse-sirius/sirius-components/issues/1139[#1139] [form] Added support for a new Tree widget == v2022.3.0 diff --git a/doc/adrs/052_add_tree_widget_in_forms.adoc b/doc/adrs/052_add_tree_widget_in_forms.adoc new file mode 100644 index 0000000000..3298de8f8d --- /dev/null +++ b/doc/adrs/052_add_tree_widget_in_forms.adoc @@ -0,0 +1,92 @@ += ADR-052 - Add support for a tree widget in forms + +== Context + +The forms DSL currently supports a variety of widgets, but none which can represent hierarchical content. + +== Decision + +We will add support for a new `Tree` widget +This first version will only support displaying elements, with no edition capabilities. + +=== GraphQL Schema + +The `forms.graphqs` part of our schema will be extended with the following types: + +``` +type TreeWidget implements Widget { + id: ID! + diagnostics: [Diagnostic!]! + label: String! + children: [TreeNode!]! + expanded: [ID!]! +} + +type TreeNode { + id: ID! + label: String! + kind: String! + imageURL: String! + selectable: boolean! + children: [TreeNode!]! +} +``` + +The widget will be named `TreeWidget` instead of the more natural `Tree` as we already have a type with that name for the tree representations. +We can not easily reuse the same type as the existing `Tree` is a `Representation` (with metadata, etc.) and not a `Widget`. + +Similarly, we will not reuse the existing `TreeItem` used for the `Tree` representation as it includes attributes like `editable` and `deletable` which do not make sense in the context of a read-only widget. + +The `selectable` flag on `TreeNode` will be used to allow the creation of "folder" nodes inside the tree, which only exist for the purpose of organizing nodes in categories. +A selectable node (e.g. one which represents a semantic element or representation) will change the workbench's selection when clicked on (using its `id`, `label` and `kind` attributes as `SelectionEntry`). +Clicking on a non-selectable node will have no effect on the selection; in the UI the only effect will be to hightlight it. + +The existing `Tree` *representation* is designed to be used directly through a subscription and manages its "expanded" state accordingly, with each change in the expansion depth creating a new representation and a new subscription. +The new `TreeWidget` will be embedded in an enclosing `Form` representation. +We do not want to invalidate and recompute the whole form when the user expands or collapses tree nodes. +The `TreeWidget` will thus send its full content to the frontend, with the ids of the elements to expand for the initial presentation (the `expanded` attribute above). +Subsequent changes in the collapse/expand state of the nodes will be done purely on the client. +If the underlying model changes, the frontend will receive a new state for the whole enclosing form, including the tree widget(s) anyway. + +=== Backend + +The backend API to describe a tree widget will follow the same pattern as the existing `ListDescription`, except that items can be recursive. +For that part, we will use the same approach as for the tree _representation_: `childrenProvider` and `hasChildrenProvider`. + +```java +package org.eclipse.sirius.components.forms.description; + +@Immutable +public final class TreeDescription extends AbstractWidgetDescription { + private Function idProvider; + + private Function labelProvider; + + private Function> childrenProvider; + + private Function hasChildrenProvider; + + private Function itemIdProvider; + + private Function itemLabelProvider; + + private Function itemKindProvider; + + private Function itemImageURLProvider; + + private Function itemSelectableProvider; + + // with the corresponding getters and builder +} +``` + +=== Frontend + +On the frontend, we will use Material UI's [`TreeView`](https://v4.mui.com/components/tree-view/) component. +It is part of Materal UI's lab in the version we use (v4), but is still available (also in the lab) in v5 when we migrate to that. + +TODO: who controls the size/scrolling/layout of the widget, and how? + +== Status + +WIP