[doc] Add shape about the filtering of tree based representations

Bug: #1918
Signed-off-by: Axel RICHARD <axel.richard@obeo.fr>

doc/iterations/2023.6/scopes/filterTreeBasedRepresentations.adoc

@@ -0,0 +1,16 @@
+= Scope
+
+== First task
+
+- [ ] Shape written, reviewed and merged
+- [ ] ADR written, reviewed and merged
+- [ ] Mock of the features done with Figma
+- [ ] First prototype of the user interface
+- [ ] First version of the user interface done with Cypress tests
+
+== Second task
+
+- [ ] Capture proper screenshots for the CHANGELOG and the documentation
+- [ ] User guide updated with screenshots
+
+

doc/iterations/2023.6/shapes/filterTreeBasedRepresentations.adoc

@@ -0,0 +1,92 @@
+:imagesdir: images/
+= (M) Filtering tree based representations
+
+== Problem
+
+It is quite difficult to search for/identify specific tree item(s) in a tree when this tree contains lots of tree items.
+
+== Key Result
+
+The solution should not slow-down the user interface. The user interface must remains as smooth as it was before the developments of this filter.
+The results displayed by the filter should be visible immediately, i.e. without any latency.
+Otherwise, if the solution can only be implemented with a latency, then during the computation time, a "busy" indicator should be displayed, informing the user his request is processing.
+
+== Solution
+
+Add a search capacity in the Explorer View and other tree based representations, by providing a textual filtering of the tree just like what is being done in VSCode using a simple textfield.
+
+=== Breadboarding
+
+See the following breadboarding for the search:
+image:filterTreeBasedRepresentations-01.png[Filter widget]
+
+A shortcut (most likely ctrl+f) will be available in the Explorer View, allowing to display a search bar under the toolbar at the top of the Explorer View.
+This search bar will be composed by a simple textfield, a filter button and a close button.
+When user type a value in the textfield of the search bar, the tree item(s) containing this value are highlighted (only the part corresponding to the value, not the whole tree item(s)).
+Each character added/removed in the search bar will update the result (i.e. the highlighted tree item(s)).
+The filter button allows to hide all visible leaf tree items that do not match the search.
+The close button close the search bar, the highlighted results are not highlighted anymore, and the filtered tree items are not filtered anymore.
+The up/down arrow keys allow to jump from an highlighted item to the next one/previous one.
+
+=== Scenario 1 - Search
+
+User want to search tree items containing a specific value as their label or part of their label.
+User type the shortcut to enable the search bar.
+User type the value to search in the search bar.
+The tree items containing the searched value are highlighted (only the part of the items containing the value).
+Each character added/removed in the search bar updates the highlighted tree items.
+User close the search bar with the close button.
+All highlighted items are not highlighted anymore.
+
+=== Scenario 2 - Filter
+
+User want to filter tree items containing a specific value as their label or part of their label.
+User type the shortcut to enable the search bar.
+User type the value to search in the search bar.
+The tree items containing the searched value are highlighted (only the part of the items containing the value).
+User push the filter button (to enable the filter) in the search bar.
+All visible leaf tree items that do not match the search are hidden.
+It will not concern collapsed root/intermediate tree items.
+When expanded, root/intermediate tree items may become hidden if they are now leaf tree items that do not match the search.
+User push again the filter button (to disable the filter) in the search bar.
+All filtered items are not filtered anymore.
+
+=== Scenario 3 - Navigate through results
+
+User want to navigate quickly through the highlighted tree items containing after a search.
+User type the shortcut to enable the search bar.
+User type the value to search in the search bar.
+The tree items containing the searched value are highlighted (only the part of the items containing the value).
+User type the down arrow key to select the next highlighted tree item.
+User type the up arrow key to select the previous highlighted tree item.
+When the last highlighted tree item is selected, the down arrow key has no effect.
+When the first highlighted tree item is selected, the up arrow key has no effect.
+
+=== Cutting backs
+
+Sort the things todo, define the nice-to-have. What could be removed if finally the feature does not fit the appetite.
+1) Search bar open/close
+2) Highlight tree items
+3) Filter tree items
+4) Navigate through highlighted tree items
+5) Display the number of highlighted tree items somewhere in the search bar.
+
+== Rabbit holes
+
+The navigation through up/down arrow keys could lead to some misunderstanding for the users.
+The keys are already used to navigate through the tree items in the Explorer View.
+When the search will be enabled, the up/down arrow keys won't have the same behavior than when the search is disabled.
+An alternate solution could be to have two buttons in the search bar, allowing to navigate through the highlighted tree items.
+
+Some results may not be highlighted because they are collapsed. With the proposed solution, there is no simple way to access to those tree items. This could not be the behavior wanted by some users.
+The documentation will have to explain that.
+
+The filtering could also be confusing for the users. Indeed, the filtering will not concern collapsed root/intermediate tree items. Only leaf tree items are concerned. This could not be the behavior wanted by some users.
+The documentation will have to explain that.
+
+For those two concerns, a solution could be to let users know that there is a match available under a parent item which is collapsed by showing in a tag the number of matches for instance.
+
+== No-gos
+
+The filtering will not concern collapsed root/intermediate tree items.
+The navigation through highlighted tree items will only concern visible tree items. If a tree item is concerned by the result of the search but is not visible because it is contained by another tree item that is collapsed, then it will not be highlighted.