docs(components): update documentation on components #1583

matthieu-crouzet · 2024-04-03T16:28:52Z

Proposed change

Update documentation for components

nx-cloud · 2024-04-03T16:29:50Z

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 8e0a717. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

✅ Successfully ran 1 target

nx run-many --target=build --projects=eslint-plugin --parallel 3

Sent with 💌 from NxCloud.

docs/components/COMPONENT_REPLACEMENT.md

docs/localization/LOCALIZATION.md

docs/styling/THEME.md

docs/components/COMPONENT_REPLACEMENT.md

docs/components/INTRODUCTION.md

docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md

docs/configuration/OVERVIEW.md

docs/components/INTRODUCTION.md

cpaulve-1A · 2024-04-05T13:42:40Z

docs/components/COMPONENT_REPLACEMENT.md

 ````

-Are not possible through an ``ng-template`` and ``c11n`` combination.
-
 Though there is a solution for the first example in making the value an input, and bind it inside the component using


Maybe make it clear that the value we are talking about is the dynamicClass? I know that is the only value on the container, but using precise words may avoid confusion.

cpaulve-1A · 2024-04-05T13:43:25Z

docs/components/COMPONENT_REPLACEMENT.md

 ````

-Are not possible through an ``ng-template`` and ``c11n`` combination.
-
 Though there is a solution for the first example in making the value an input, and bind it inside the component using
 the [HostBinding](https://angular.io/api/core/HostBinding) decorator, there is no actual solution for applying directive.
 A [feature request](https://github.com/angular/angular/issues/8785) has been opened for a long time and finally made it


Now that the feature request finally made it, what is the next step ? :D

docs/configuration/OVERVIEW.md

docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md

cpaulve-1A · 2024-04-09T12:58:55Z

docs/core/OTTER_ANGULAR_TOOLS.md

-  
-Configration example:   
+
+Configration example:


Suggested change

Configration example:

Configuration example:

mrednic-1A · 2024-04-09T13:13:17Z

docs/components/COMPONENT_REPLACEMENT.md

+import {Context} from '@o3r/core';
+
+export interface DummyPresContextInput {
+  dummyInput: string;


please add a dummy doc ( as line 188 says) :)
same for output.

docs/forms/FORM_STRUCTURE.md

cpaulve-1A · 2024-04-09T13:30:42Z

docs/forms/FORM_STRUCTURE.md


 We prefer to use the __formControl__ rather than __ngModel__ because we can easily listen to the valueChanges or status changes of the presenter form.
-Another constraint is that it's easier to identify the container context for the CMS, with one implementation (See [Component Structure](../components/COMPONENT_STRUCTURE.md) for details about the component context).
+Another constraint is that it's easier to identify the container context for the CMS, with one implementation (See [Component Replacement](../components/COMPONENT_REPLACEMENT.md) for details about the component context).


What do you mean "with one implementation"?

docs/forms/FORM_STRUCTURE.md

cpaulve-1A · 2024-04-09T13:36:40Z

docs/forms/FORM_STRUCTURE.md

 In addition to the simple case, if we need an __error message__ panel, which can be displayed anywhere in the page,
-or we need  __form submission__, done from the page, we came up with the following implementation.   
+or we need  __form submission__, done from the page, we came up with the following implementation.



Suggested change

In addition to the simple case, if we need an __error message__ panel, which can be displayed anywhere in the page,

or we need __form submission__, done from the page, we came up with the following implementation.

or we need __form submission__, done from the page, we came up with the following implementation.

In addition to the simple case, if we need an __error message__ panel, which can be displayed anywhere in the page, or to __submit the form outside the component__, we follow the more complex implementation described below.

cpaulve-1A · 2024-04-09T13:40:24Z

docs/forms/FORM_STRUCTURE.md

-##### 1.Basic structure      
-The form created in the presenter and the default value should have the same contract. The contract of a form is an interface which defines the form controls names and the type of the value which should be handled by each control. See the example of a component creation. 
+##### 1.Basic structure
+The form created in the presenter and the default value should have the same contract. The contract of a form is an interface which defines the form controls names and the type of the value which should be handled by each control. See the example of a component creation.


Suggested change

The form created in the presenter and the default value should have the same contract. The contract of a form is an interface which defines the form controls names and the type of the value which should be handled by each control. See the example of a component creation.

The form created in the presenter and the default value should have the same contract. The contract of a form is an interface which defines the name of the form controls and the type of the value which should be handled by each control. See the example of a component creation.

docs/forms/FORM_STRUCTURE.md

pginoux-1A · 2024-04-09T13:44:29Z

docs/components/CONTAINER_PRESENTER.md

@@ -1,6 +1,6 @@
 # Container / Presenter

-We encourage developers to decouple components into containers and presenters. From a UI perspective it is a good practice to separate access of Data/ business logic form pure presentation, this allows developer to reuse presenters in other parts of the code with different data or having a container linked to multiple presenters, in case you want to display the same thing with a totally different user experience.
+We encourage developers to decouple components into containers and presenters. From a UI perspective it is a good practice to separate access of data/business logic form pure presentation. This allows developers to reuse presenters in other parts of the code with different data or having a container linked to multiple presenters, in case you want to display the same thing with a totally different user experience.


"We encourage developers to decouple components into containers and presenters." Not sure it's relevant for all the use cases, if you are building a library or if you want to split the work between container and presenters amongst developers, or for a product that is meant to be configured and customized yes, but that's about it I think.

pginoux-1A · 2024-04-09T14:00:50Z

docs/components/INTRODUCTION.md

+export class ComponentNameComponent {}
+```
+The object passed to the `@O3rComponent` decorator includes the component type, which can be:
+- `Block`: a component that handles a functional area


Add an example here

pginoux-1A · 2024-04-09T14:05:53Z

docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md


 First thing to do is to define your given filenames for the configuration in the _package.json_ of the library/app where you run the extractor.
 When running in a library it will use this configuration as the names for the metadata files.
 When running the extractor in an application, it will search for these filenames in each node_module (package.json file) of each library,
-in order to concat the metadata from the file with other libraries metadata and app metadata.
+in order to concat the file's metadata with the metadata of other libraries and the application's metadata.


The final metadata file generated for an application will be the concatenation of the ones provided by the library used (if available) and the one extracted from the application itself.

docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md

cpaulve-1A · 2024-04-09T14:15:46Z

docs/forms/FORM_STRUCTURE.md

@@ -15,25 +15,25 @@
            3. [Include Custom Validations](#custom-validators)
                1. [Validators definition](#custom-validators-definition)
                2. [Apply validators ](#custom-apply-validators)
-                3. [Validators translations](#custom-validators-translations) 
+                3. [Validators translations](#custom-validators-translations)


Structure is too complex for one page and causes issues in the structure

cpaulve-1A · 2024-04-09T14:16:09Z

docs/forms/FORM_STRUCTURE.md

 * __submit from presenter__ - the submit button is displayed
-  * __Presenter__ - click on submit btn and emits an event > __Container__ receives the signal and executes the submit logic. Emits an event when the submit logic is finished.  
-
+  * __Presenter__ - click on submit btn and emits an event > __Container__ receives the signal and executes the submit logic. Emits an event when the submit logic is finished.


Suggested change

* __Presenter__ - click on submit btn and emits an event > __Container__ receives the signal and executes the submit logic. Emits an event when the submit logic is finished.

* __Presenter__ - click on submit button and emits an event > __Container__ receives the signal and executes the submit logic. Emits an event when the submit logic is finished.

docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md

cpaulve-1A · 2024-04-09T14:27:03Z

docs/localization/LOCALIZATION.md

@@ -3,7 +3,7 @@

 Localization module is built on top of an open source [ngx-translate](https://github.com/ngx-translate/core) library.


Suggested change

Localization module is built on top of an open source [ngx-translate](https://github.com/ngx-translate/core) library.

The ``Localization`` module is built on top of an open source [ngx-translate](https://github.com/ngx-translate/core) library.

cpaulve-1A · 2024-04-09T14:29:50Z

docs/localization/LOCALIZATION.md

@@ -29,7 +29,7 @@ Localization module is built on top of an open source [ngx-translate](https://gi

 # How to use

-We provide in [library](https://github.com/AmadeusITGroup/otter/blob/main/packages/@o3r/localization/src/tools/localization.module.ts) an angular module called **LocalizationModule** which comes with translations loader.
+We provide in [library](https://github.com/AmadeusITGroup/otter/blob/main/packages/@o3r/localization/src/tools/localization.module.ts) an Angular module called **LocalizationModule** which comes with translations loader.

 - **In your AppModule** you need to **import** the **LocalizationModule** and **TranslateModule**. The LocalizationModule could be imported calling `forRoot` with a custom configuration **factory** to specify the language of the application. This configuration is of type **LocalizationConfiguration** and describes your endpoint URL, supported locales, list of RTL languages, the language of your application and your fallback language.


Suggested change

- **In your AppModule** you need to **import** the **LocalizationModule** and **TranslateModule**. The LocalizationModule could be imported calling `forRoot` with a custom configuration **factory** to specify the language of the application. This configuration is of type **LocalizationConfiguration** and describes your endpoint URL, supported locales, list of RTL languages, the language of your application and your fallback language.

- **In your AppModule** you need to **import** the ``LocalizationModule`` and ``TranslateModule``. The LocalizationModule could be imported calling `forRoot` with a custom configuration **factory** to specify the language of the application. This configuration is of type ``LocalizationConfiguration`` and describes your endpoint URL, supported locales, list of RTL languages, the language of your application and your fallback language.

Method names and functions should be between `` shouldn't they?
(Comment for other parts of the file)

docs/localization/LOCALIZATION.md

cpaulve-1A · 2024-04-09T14:35:52Z

docs/localization/LOCALIZATION.md

 ### How to localize a date, decimal and currency

-Use angular built-in [DatePipe](https://angular.io/api/common/DatePipe), [DecimalPipe](https://angular.io/api/common/DecimalPipe) and [CurrencyPipe](https://angular.io/api/common/CurrencyPipe) and pass it current locale as the last parameter. The locale is read from **this.localizationService.getCurrentLanguage()**. To be able to use translateService, your component container should take benefit of dependency injection to get LocalizationService as parameter of constructor as well.
+Use Angular built-in [DatePipe](https://angular.io/api/common/DatePipe), [DecimalPipe](https://angular.io/api/common/DecimalPipe) and [CurrencyPipe](https://angular.io/api/common/CurrencyPipe) and pass it current locale as the last parameter. The locale is read from **this.localizationService.getCurrentLanguage()**. To be able to use translateService, your component container should take benefit of dependency injection to get LocalizationService as parameter of constructor as well.

 For example if you want to localize simpleHeader component you will start by injecting TranslateService to the constructor of simple-header-pres.component.ts


Suggested change

For example if you want to localize simpleHeader component you will start by injecting TranslateService to the constructor of simple-header-pres.component.ts

For example if you want to localize the SimpleHeader component you will start by injecting TranslateService to the constructor of simple-header-pres.component.ts

cpaulve-1A · 2024-04-09T14:43:46Z

docs/styling/THEME.md


-### Generate the RefX theme variables
+### Generate your own theme variables


Note: there are other reference to refx and airlines in the examples and in this documentation.

cpaulve-1A · 2024-04-09T14:45:47Z

docs/styling/THEME.md

@@ -242,11 +239,11 @@ to style a material component with a new palette (e.g. highlight), you will need

 #### Process

-The process to customize the application theme is similar to the angular material one as describe in [Theming your
+The process to customize the application theme is similar to the Angular material one as describe in [Theming your


line 232: the four palettes material palettes - leftover duplicate

pginoux-1A · 2024-04-09T14:50:35Z

docs/configuration/OVERVIEW.md

@@ -1,31 +1,31 @@
 # Configuration mechanism

-The aim of this document is to help developers to implement configuration inside components, in order to be compliant
-with __cms architecture__. This will give the possibility to __Business Analyst__ to configure the
+The aim of this document is to help developers to implement `Configuration` inside components, in order to be compliant with the __CMS architecture__.


I think the first thing is not about the CMS, it's about making the application configurable dynamically. The CMS is a way to ease the creation of this configuration override, but that's not mandatory. It would be interesting to develop "When do I want to build configurability in my application and why" and then go on the How which is already part of this file

pginoux-1A · 2024-04-09T14:58:39Z

docs/configuration/OVERVIEW.md

+- Defined in one interface extending the __AppBuildConfiguration__ from __@o3r/core__ in order
+  to be identified by the extractor
+- PreBootstrap config object is used for configurations needed before loading the Angular app component, and it will be
+  injected by the CMS in the index.html body tag data-bootstrapconfig as a data attribute


It's not injected by the CMS, there is no runtime interactions with the CMS, it's used as an edition panel for the customization and the files are exported in the dynamic content folder afterwards. We should advertise that this part is linked to a piece of code server side that updates the index.html and what requires to be added with an example

docs/components/INTRODUCTION.md

kpanot · 2024-04-10T02:49:47Z

docs/components/INTRODUCTION.md

+To enable the communication between your application and the Chrome Extension you can follow this [documentation](../dev-tools/chrome-devtools.md).
+
+## Next steps
+


This session is missing references to features configuration, localization, styling and design that can affect the component architecture in term of files.

You should also provide a link to placeholder that is part of the component page.

You may also need to add a reference list to the module affecting directly the component code: (today only the eslint plugin/config would be part of this list)

kpanot · 2024-04-10T02:51:21Z

docs/components/CONTAINER_PRESENTER.md

 | **Template file name**      | *-cont.template.html |
 | **Unit test file name**      | *-cont.spec.ts |

-It has its own _index.ts_ file exporting:


Not sure you need to remove this part as the bundle still exist to export modules and component

It is pertinent in the documentation ?
What does it bring to the developer that we write it here ?

The fact that we export the different file of the components in a barrel, that does not include all of then per default, soon to be an information that is meaningful.

docs/components/CONTAINER_PRESENTER.md

kpanot · 2024-04-10T02:55:37Z

docs/components/CONTAINER_PRESENTER.md

+        container/
+        presenter/
+  elements/
+    my-element/
 ```


A section with links/references to the features extending the component capabilities should be provided to this file (equivalent to the next steps section from the introduction file)

docs/components/INTRODUCTION.md

docs/components/CONTAINER_PRESENTER.md

kpanot · 2024-04-10T04:45:10Z

docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md

+```json
+"cmsMetadata": {
+  "componentFilePath": "./component.class.metadata.json",
+  "configurationFilePath": "./component.config.metadata.json",


Suggested change

"configurationFilePath": "./component.config.metadata.json",

"configurationFilePath": "./component.config.metadata.json"

kpanot · 2024-04-10T04:47:33Z

docs/core/OTTER_ANGULAR_TOOLS.md

@@ -52,13 +52,13 @@ In angular.json file of your lib.
      "builder": "@o3r/core:lib-build", // wrapper builder


turn json to json5 to support comment in the rendered code block

kpanot · 2024-04-10T04:50:25Z

docs/testing/UNIT_TESTS_SETUP.md

@@ -1,9 +1,9 @@
 # Tests setup

-With the focus on simplicity, we chose to use [JEST](https://jestjs.io) as Testing Framework for our unit and integration tests, which aims to work with a minimum set of configurations, on most js projects.  
+With the focus on simplicity, we chose to use [JEST](https://jestjs.io) as Testing Framework for our unit and integration tests, which aims to work with a minimum set of configurations, on most js projects.


Suggested change

With the focus on simplicity, we chose to use [JEST](https://jestjs.io) as Testing Framework for our unit and integration tests, which aims to work with a minimum set of configurations, on most js projects.

With the focus on simplicity, we chose to use [Jest](https://jestjs.io) as Testing Framework for our unit and integration tests, which aims to work with a minimum set of configurations, on most js projects.

github-actions bot added documentation Improvements or additions to documentation project:@o3r/core labels Apr 3, 2024

matthieu-crouzet force-pushed the docs/components branch from 0f1188f to 272e3c2 Compare April 4, 2024 08:20

matthieu-crouzet marked this pull request as ready for review April 4, 2024 08:21

matthieu-crouzet requested a review from a team as a code owner April 4, 2024 08:21

matthieu-crouzet force-pushed the docs/components branch from 272e3c2 to 032954f Compare April 4, 2024 08:37

github-actions bot added the project:@o3r/components label Apr 4, 2024

sdo-1A reviewed Apr 4, 2024

View reviewed changes

matthieu-crouzet force-pushed the docs/components branch from 9d0d606 to 9af489a Compare April 4, 2024 12:19

sdo-1A reviewed Apr 4, 2024

View reviewed changes

docs/components/COMPONENT_REPLACEMENT.md Outdated Show resolved Hide resolved

docs/components/COMPONENT_REPLACEMENT.md Outdated Show resolved Hide resolved

docs/components/INTRODUCTION.md Outdated Show resolved Hide resolved

matthieu-crouzet force-pushed the docs/components branch from 9af489a to 1a76180 Compare April 4, 2024 12:38

sdo-1A previously approved these changes Apr 4, 2024

View reviewed changes

matthieu-crouzet dismissed sdo-1A’s stale review via 47db863 April 4, 2024 13:48

matthieu-crouzet force-pushed the docs/components branch from 1a76180 to 47db863 Compare April 4, 2024 13:48

sdo-1A reviewed Apr 4, 2024

View reviewed changes

sdo-1A reviewed Apr 5, 2024

View reviewed changes

cpaulve-1A reviewed Apr 5, 2024

View reviewed changes

docs/components/INTRODUCTION.md Outdated Show resolved Hide resolved

cpaulve-1A reviewed Apr 5, 2024

View reviewed changes

docs/components/INTRODUCTION.md Outdated Show resolved Hide resolved

cpaulve-1A reviewed Apr 5, 2024

View reviewed changes

docs/components/INTRODUCTION.md Outdated Show resolved Hide resolved

cpaulve-1A reviewed Apr 5, 2024

View reviewed changes

docs/configuration/OVERVIEW.md Show resolved Hide resolved

matthieu-crouzet commented Apr 5, 2024

View reviewed changes

docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md Outdated Show resolved Hide resolved

matthieu-crouzet force-pushed the docs/components branch from 8a14754 to 5ade442 Compare April 5, 2024 15:22

github-actions bot added project:@o3r/analytics project:@o3r/configuration project:@o3r/design project:@o3r/forms project:@o3r/localization labels Apr 5, 2024