[doc] Contribute a shape for the filtering/ordering pages API

Signed-off-by: Florian ROUËNÉ <florian.rouene@obeosoft.com>

CHANGELOG.adoc

@@ -7,6 +7,7 @@
 - Add disable / enable concept for widgets
 - Add new custom widget to edit single and multi-valued references
 - Add support for Help Expressions in Form widgets
+- Add an API for filtering and ordering view properties pages
 
 === Architectural decision records
 
@@ -61,7 +62,8 @@ Widgets which define such a help text have a new "?" icon next to their labels;
 For View-based widgets, this materializes as an AQL `helpExpression`.
 The help text can include multiple lines (separated by `\n`), but no text formatting.
 :image:doc/images/Widget_Help_Tooltip.png[Example of a help tooltip on a widget]
-- https://github.com/eclipse-sirius/sirius-components/issues/2048[#2048] [diagram] Add a basic support for the resize. It is possible to reduce the size of a node less than the space needed to display all children.
+- https://github.com/eclipse-sirius/sirius-components/issues/2048[#2048] [diagram] Add a basic support for the resize.
+It is possible to reduce the size of a node less than the space needed to display all children.
 - https://github.com/eclipse-sirius/sirius-components/issues/2064[#2064] [forms] Make the `IWidgetDescriptor` API more flexible.
 - https://github.com/eclipse-sirius/sirius-components/issues/1618[#1618] [view] Split the view metamodel into dedicated subpackages.
 - https://github.com/eclipse-sirius/sirius-components/issues/2083[#2083] [diagram] Add support for edge markers
@@ -147,14 +149,15 @@ image:doc/screenshots/filterBarFilterButton.png[Filter Bar Filter Button,30%,30%
 - https://github.com/eclipse-sirius/sirius-components/issues/1914[#1914] [form] It is now possible for applications to provide their own custom widgets without forking Sirius Components.
 See link:doc/how-to/contribute-custom-widget.adoc[the documentation] for more details.
 
-- https://github.com/eclipse-sirius/sirius-components/issues/1830[#1830] [layout] This feature is experimental and can be activated on a diagram by adding "__EXPERIMENTAL" to its name. The new algorithm does the minimum possible to place node without overlap.
+- https://github.com/eclipse-sirius/sirius-components/issues/1830[#1830] [layout] This feature is experimental and can be activated on a diagram by adding "__EXPERIMENTAL" to its name.
+The new algorithm does the minimum possible to place node without overlap.
 - https://github.com/eclipse-sirius/sirius-components/issues/1985[|#1985] [sirius-web] It is now possible to use in-memory View-based representations by registering them in the new `InMemoryViewRegistry`.
 These representations can be created programmatically or loaded from `.view` EMF models on startup, and do not need to be stored as documents inside a project in the database.
 - https://github.com/eclipse-sirius/sirius-components/issues/1921[#1921] [view] Added a project sirius-components-view-builder.
 +
 Introducing providers interfaces to help creating view programmatically.
 +
-Introducing a generator of builders aimed to help creating view programmatically, the generation makes use of emf-merge and modifications to these builders can be annotated to live during future regeneration. 
+Introducing a generator of builders aimed to help creating view programmatically, the generation makes use of emf-merge and modifications to these builders can be annotated to live during future regeneration.
 
 - https://github.com/eclipse-sirius/sirius-components/issues/1912[#1912] [core] Add the possibility to send feedback messages to the frontend after an action.
 - https://github.com/eclipse-sirius/sirius-components/issues/1989[#1989] [diagram] Contribute a new way to render diagrams to evaluate an alternate layouting strategy
@@ -212,7 +215,6 @@ Such calls will not work anymore since `null` will not be an acceptable value an
 +
 Removing dependencies from sirius-components-compatibility-emf in the canHandle methods of sirius-components-view-emf services
 
-
 === Dependency update
 
 - [form] Switch to lexical 0.8.1

doc/iterations/2023.8/shapes/order_and_filter_from_pages.adoc

@@ -0,0 +1,40 @@
+= (S) Add an API for filtering and ordering view properties pages
+
+== Problem
+
+A form in view properties can be composed of several pages from various contributions.
+A specifier should be able to order and filter these pages to control the form representation.
+
+== Key Result
+
+Offer the specifier the ability to programmatically order and filter the pages of a form.
+
+== Solution
+
+Add a new API with in entry the list of the pageDescription which can be applied on an item.
+This API should return the list of the pages to display in the form.
+
+[source,java]
+----
+public interface IPropertiesPageDescriptionPostProcessFiltering {
+    List<String> postProcessFiltering(List<PageDescription> pageDescriptions, PropertiesConfiguration propertiesConfiguration, IEditingContext editingContext);
+}
+----
+
+The API must return the ordered ids only of the pages to be displayed.
+
+=== Scenario
+
+* Contributors add a list of pages matching an element.
+* Specifier declares through the API a new filter and changes pages order.
+* On the form representation, only the pages filtered by the API are displayed and in the specified order.
+
+=== Cutting backs
+
+== Rabbit holes
+
+* This filter only concerns the view properties, for the form editor the specifier already controls the order and content.
+* The API return page's id and no directly the page, in order to not offer the ability to add page through this API.
+There is already an API for contributing new pages.
+
+== No-gos